BendZddlZddlZddlZddlmZddlmZm Z ddl m Z ddl m Z ddlmZdd lmZd ZGd d eZGd deZdZGddZGddeZGddeZGddeZGddeZGddeZGddeZGddeZGd d!eZGd"d#eZ Gd$d%e!Z"d&Z#Gd'd(eZ$Gd)d*Z%Gd+d,e&Z'Gd-d.eZ(Gd/d0Z)y)1zPython code parser.N)StringIO)chain dropwhile)Path)compile)Tuple)log) Parser DefinitionModulePackageFunctionNestedFunctionMethodClass NestedClassAllErrorr ParseErrorceZdZdZdZy)rz+An error parsing contents of a Python file.cy)NzCannot parse file.selfs 1lib/python3.12/site-packages/pydocstyle/parser.py__str__zParseError.__str__!s#N)__name__ __module__ __qualname____doc__rrrrrrs 5$rrceZdZdZdZy)UnexpectedTokenErrorc ||_||_yNtoken expected_kind)rr'r(s r__init__zUnexpectedTokenError.__init__&s *rcNdj|j|jS)Nz Unexpected token {}, expected {})formatr'r(rs rrzUnexpectedTokenError.__str__*s$188 JJ**  rN)rrr r)rrrrr#r#%s + rr#cTtdjd|jS)Nz (.)([A-Z]+)z\1 \2)resublower)strings rhumanizer10s# n  ! !(F 3 9 9 ;;rc(eZdZdZdZdZdZdZy)Valuez.A generic object with a list of preset fields.cPt|jt|k7rWtdjt|t|j|jj |jt |jt|j|y)Nz)got {} arguments for {} fields for {}: {}) len_fields ValueErrorr+ __class__rvarsupdatezip)rargss rr)zValue.__init__7sx t|| D );BBI %NN++LL   T #dllD12rc*tt|Sr%)hashreprrs r__hash__zValue.__hash__CsDJrc8|xrt|t|k(Sr%)r9)rothers r__eq__z Value.__eq__Fs2dtE{22rcdjfdjD}jjd|dS)Nz, c3VK|] }dj|t|"yw)z{}={!r}N)r+getattr).0fieldrs r z!Value.__repr__..Js-    UGD%$8 9 s&)())joinr6r8r)rkwargss` r__repr__zValue.__repr__IsB   ..))*!F8155rN)rrr r!r)r@rCrNrrrr3r34s8 3 36rr3ceZdZdZdZedZedZedZedZ edZ dZ d Z ed Z ed Zed Zd Zy)r z@A Python source code definition (could be class, function, etc).) name_sourcestartend decorators docstringchildren callable_argsparentskipped_error_codesc>tt|jSr%)r1typerrs rzDefinition.as8DJ,?,?#@rc<|jjdS)N)_humansplitrs rr\zDefinition.bs!2!2!4R!8rc.|jjSr%)rXmodulers rr\zDefinition.cs4;;#5#5rc.|jjSr%)rb dunder_allrs rr\zDefinition.dst{{'='=rcHt|jdz |jS)Nr )slicerRrSrs rr\zDefinition.es5a#BrFc0t|gg|jSr%)rrVrs r__iter__zDefinition.__iter__hsdV,dmm,,rczt|jtr|jjS|jS)z4Get the line number with which to report violations.) isinstancerU DocstringrRrs r error_linenozDefinition.error_linenoks, dnni 0>>'' 'zzrc&ddd|jS)Npublicprivate)TF) is_publicrs r _publicityzDefinition._publicityrsy1$..AArc|j|j}d}t|t|}dj tt |S)z*Return the source code for the definition.cj|jdk(xs|jjdS)N#)strip startswith)lines ris_empty_or_commentz.Definition.source..is_empty_or_comment{s)::<2%E)@)@)E Errt)rQ_slicerreversedrLlist)rfull_srcry filtered_srcs rsourcezDefinition.sourcevsI<< , F!!4hx6HI wwx\ 2344rcd|jd|jd|jd}|jr|d|jdz }|S)Nzin  z ``z (skipping rK)rqr_rPrY)routs rrzDefinition.__str__sQDOO$Adkk]"TYYKqA  # # [!9!9 :!< J B CFH- BB55rr creZdZdZdZedZedZedZ edZ dZ dZ d Z d Zy ) r zA Python source code module.) rPrQrRrSrTrUrVrX _dunder_alldunder_all_errorfuture_importsrYc"ttd|SNdefclass)rrss rr\zModule.s8e#DQ#Grc|Sr%rrs rr\zModule.s4rc|jSr%)rrs rr\zModule.s t'7'7rct|jj}|j xr|j |S)zsReturn True iff the module is considered public. This helps determine if it requires a docstring. )rrPstem_is_inside_private_package_is_public_namer module_names rrpzModule.is_publics@ 499o** 2244 9M9M :  rc6t|jj}tjDcgc] }t|}}||jk7r@||vr<|j |jry|j}||jk7r||vrs.;?Brc|j|j|jvS|jjd S)z:Return True iff this function should be considered public.r)rdrPrwrs rrpzFunction.is_publics9 ?? &99/ /yy++C00 0rc:td|jDS)z3Return True iff the method decorated with overload.c3:K|]}|jdk(yw)overloadNrP)rG decorators rrIz'Function.is_overload..s -6INNj ( sanyrTrs r is_overloadzFunction.is_overloads" :>//   rc@tfd|jDS)zCReturn True if the method is decorated with any property decorator.c3:K|]}|jvywr%r)rGrproperty_decorator_namess rrIz'Function.is_property..s#  NN6 6 sr)rrs `r is_propertyzFunction.is_propertys! !__   rcZ|jjdxs|jdk(S)aReturn True if this function is a test function/method. We exclude tests from the imperative mood check, because to phrase their docstring in the imperative mood, they would have to start with a highly redundant "Test that ...". testrunTest)rPrwrs ris_testzFunction.is_tests'yy##F+EtyyI/EErc|jS)zReturn the parameter names.)rWrs r param_nameszFunction.param_namess!!!rN) rrr r!rrrrprrrrrrrrrsi( B E11   FF""rrceZdZdZdZy)rz%A Python source code nested function.FN)rrr r!rprrrrrs /IrrcPeZdZdZedZedZedZedZy)rzA Python source code method.c|jjdxr/|jjdxr|jtvS)z@Return True iff this method is a magic method (e.g., `__str__`).r)rPrwrVARIADIC_MAGIC_METHODSrs ris_magiczMethod.is_magicsD II  & 8 ""4( 8 !77 rc |jdk(S)z*Return True iff this method is `__init__`.r)rrs ris_initzMethod.is_initsyyJ&&rc<|jD]6}td|jdj|js6y|jj d xs |jt vxs |j }|jjxr|S)z8Return True iff this method should be considered public.^z\.Fr) rTr-rPmatchrwrrrXrp)rrname_is_publics rrpzMethod.is_public s IQtyyk$%++INN;   $$S) ) yy22 }}  {{$$77rcH|jD]}|jdk(syy)z%Return True iff the method is static.rTF)rTrP)rrs r is_staticzMethod.is_statics+ I~~/ rN) rrr r!rrrrprrrrrrsS&   '' 8 8rrc>eZdZdZedZejZdZy)rzA Python source code class.c"ttd|Sr)rrrs rr\zClass.'s6K#H#KrTN) rrr r!rrrrprrrrrr$s % K LE""IHrrc eZdZdZedZy)rz"A Python source code nested class.c|jjd xr.|jjxr|jjS)z7Return True iff this class should be considered public.r)rPrwrXrrprs rrpzNestedClass.is_public/sB $$S) ) & $$ & %% rN)rrr r!rrprrrrr,s,   rrc0eZdZdZdj Zy) Decoratorz*A decorator for function, method or class.zname argumentsN)rrr r!r`r6rrrrr9s4$$&GrrceZdZdZdZdZy)rkzRepresent a docstring. This is a string, but has additional start/end attributes representing the start and end of the token. c.tj||Sr%)str__new__)clsvrRrSs rrzDocstring.__new__Gs{{3""rc ||_||_yr%)rRrS)rrrRrSs rr)zDocstring.__init__Js rN)rrr r!rr)rrrrkrk?s#rrk)r)__call__rceZdZdZdZy)rz9Raised when there is a problem with __all__ when parsing.c\tj||tjdzy)z2Initialize the error with a more specific message.a] That means pydocstyle cannot decide which definitions are public. Variable __all__ should be present at most once in each file, in form `__all__ = ('a_public_function', 'APublicClass', ...)`. More info on __all__: http://stackoverflow.com/q/44834/. ') N) Exceptionr)textwrapdedent)rmessages rr)zAllError.__init__Us,  oo  rN)rrr r!r)rrrrrRs C rrcjeZdZejej ej hZdZdZ dZ dZ y) TokenStreamctj|j|_t t |jd|_|j jd|_t|_ d|_ y)NrT) tkgenerate_tokensreadline _generatorTokennextcurrentrRrxr got_logical_newline)rfilelikes rr)zTokenStream.__init__nsV,,X->->?d4??D9: LL&&q) #' rc|j}|j}|dnt||_|jr|jjdn |j|_|j t jt jfv}|j |jvxs|jxr||_ |S)Nr) r_next_from_generatorrrRrxrrNLCOMMENTLOGICAL_NEWLINESr)rpreviousris_logical_blanks rmovezTokenStream.moveus<<++-&tE7O -1\\DLL&&q)tyy #==RUUBJJ,?? MMT22 2 ?((=-=  rc t|jdS#ttjf$r |j j ddYywxYw)Nzerror generating tokensT)exc_info)rr SyntaxErrorr TokenErrorr warningrs rrz TokenStream._next_from_generatorsK . .R]]+  HH  6  F s6AAc#fK |j|jny|j-wr%)rrrs rrhzTokenStream.__iter__s.||'ll" IIK s/1N) rrr rNEWLINEINDENTDEDENTrr)rrrhrrrrrfs1  BIIryy9( rrceZdZdZy) TokenKindcFdjtj|S)Nztk.{})r+rtok_namers rrNzTokenKind.__repr__s~~bkk$/00rN)rrr rNrrrrrs1rrcDeZdZdjZfdZdZxZS)rzkind value start end sourcecRt||t|j|_yr%)superr)rr)rr<r8s rr)zToken.__init__s  $dii( rc:|jd|jdS)Nz (rK)rvaluers rrz Token.__str__s))b A..r)rrr r`r6r)r __classcell__)r8s@rrrs+113G)/rrceZdZdZdZdZedZedZdZ ddZ d Z d Z dd Z d Zd ZdZdZddZdZdZdZy)r zA Python source code parser.ctt|_|j|_dj|j} t ||dtt||_ ||_ d|_ d|_ t|_g|_|j!S#t $r}t |d}~wwxYw)z>Parse the given file-like object and return its Module object.rtexecN)r readlinesrrLrrrrrstreamfilenamerdrsetr_accumulated_decorators parse_module)rrr srcerrors rparsez Parser.parses((* ggdkk" * C6 *"(3-0    $!e')$  "" *,E ) *s B B7' B22B7c&|j|i|S)zCall the parse method.)r)rr<rMs rrzParser.__call__stzz4*6**rc.|jjSr%)r rrs rr\zParser.sDKK$7$7rc.|jjSr%)r rxrs rr\zParser.s!1!1rcp|jj}|j|k7r t||y)z8Consume one token and verify it is of the expected kind.r&N)r rrr#)rr next_tokens rconsumezParser.consumes2[[%%' ??d "&ZtL L #rNc|jn|jj|k(r-||jj|k(r|j|y|jj |jmyy)zSkip tokens in the stream until a certain token kind is reached. If `value` is specified, tokens whose values are different will also be skipped. N)rrrrr r)rrrs rleapfrogzParser.leapfrogsa ll&||  D( !3!3u!< T" KK    ll&rcH|jjd|j|jjtj tj tjfvr|jj|jjd|jj|jj|jjtj tj tjfvr|jjtjk(rkt|jj|jjd|jjd}|jj|Sy)z.Parse a single docstring and return its value.zparsing docstring, token is %sz#parsing docstring, token is %r (%s)rN)r debugrrrrrrr rrSTRINGrkrRrS)rrUs rparse_docstringzParser.parse_docstrings 7FllBJJ BEE#BB KK    HHNN5 !! "" llBJJ BEE#BB <<   )! ""DLL$6$6q$94<<;K;KA;NI KK    rcbg}g}d}|jY|jjd|jj|jj|jjt j k(r|jjdvrn|jjt jk(rd|jjdk(rK|jjtdj|dj|g}g}d}n |jjt jk(r|jjdk(rd}n|jjt jk(r|jjd k(rn|jjt jk(s'|jjt jk(rnM|s&|j|jjn%|j|jj|jj|jY|jjtdj|dj|y) zParse decorators into self._accumulated_decorators. Called after first @ is found. Continue to do so until encountering the 'def' or 'class' start token. FNz,parsing decorators, current token is %r (%s))asyncrr@rtrJTrK)rr rrrrNAMEOPr appendrrLrrr r)rrP arguments at_argumentss rparse_decoratorszParser.parse_decoratorss   ll& HHNN> !! ""  ||  BGG+ 0B0BG1 ""bee+ 0B0Bc0I,,33bggdmRWWY-?@ $ ""bee+ 0B0Bc0I# ""bee+ 0B0Bc0I""bjj0DLL4E4E4N$KK 2 23$$T\\%7%78 KK   Ill&N $$++ bggdmRWWY%7 8 rc#K|jr|jjd|jj|jj|jjd|j j |r+|jjdk(r|jn|jjtjk(r`|jjdk(rG|j j r1|jtj|jn:|jjdvr7|j|j|jjn|jjtjk(r9|jtj|j|Ed{n|jjtj k(r |jtj y|jjdk(r|j#n|j j%|jqyy7w)z*Parse multiple definitions and yield them.Nz1parsing definition list, current token is %r (%s)zgot_newline: %s__all__r rfrom)rr rrrr rparse_dunder_allrr"rr&parse_definitionrrparse_definitionsrparse_from_import_statementr)rclass_rds rr,zParser.parse_definitionssll& HHNNC !! ""  HHNN,dkk.M.M Ndll00I=%%' !!RUU*LL&&#-KK33 RUU#%%'##'77++FLL9K9K,LMM""bii/ RYY'11&999""bii/ RYY'##v-002   "7ll&(:sG J"J#BJJc|jjdk(sJ|jtj|j |j d|_d|_y|jjdk7rd|_y|jtjd}|jjdvr!d}|jtjd} |r|jjd vrn|jjtjtjfvrn|jjtjtjfvrnb|jjtjk(s|jjd k(r||jjz }nd |_y|jj|r|jtj|s/d |vr+d j!|jj|_y|d z } t#|i|_|jj|jj&vr|jjtjk7r|jjtjk7rd|_d|_y|jj|jj|jj&vr)|jjtjk7ryyyy#t$$r"}dj!|||_Yd}~!d}~wwxYw)z)Parse the __all__ definition in a module.r(Nz(Could not evaluate contents of __all__. =Fz([TrJz)],z'Could not evaluate contents of __all__.z(Unexpected token kind in __all__: {!r}. rKzOCould not evaluate contents of __all__.The value was {}. The exception was: {})rrrrr!rdrr"rr ENDMARKERrrrr rr+eval BaseExceptionr)r is_surroundeddunder_all_contentes rr*zParser.parse_dunder_all8s||!!Y.. RWW ?? &$*?*?*K"DO$ND !  <<   $$ND !  RUU <<   % M LL  !3!3t!;||  RZZ$>>||  RUUBJJ$77""bii/4<<3E3E3L"dll&8&88">% KK     LL ,>!>:AALL%%  ! c! "#5r:DO LL  T[[%A%A A !!R\\1||  BJJ."&>% KK    LL  T[[%A%A A !!R\\1 B1 B ==CV&>  ! ! s?M M6M11M6cr|jjd|j}|j}|j }t |j td}|jJ|j|j}t}|jjdrt}||j|j||g||d|j|jd| }|jD] }||_ |j"|_|jjd|S)z=Parse a module (and its children) and return a Module object.zparsing module.T)rdNz __init__.pyzfinished parsing module.)r rrxparse_skip_commentrr|r,r rr rrrrdrrVrXr) rrRrYrUrVrSrrbchilds rrzParser.parse_module|s () "557((* ..v$.GH||#1T\\1ii == ! !- 0C MM KK       OO  ! !    __ "E!EL " $ 3 3 12 rc |j}|jtj|jj }|j jd|j||jjg}|jjtjk(r|jj dk(rd}d} |jjtjk(r_|jj dk(r|dz }n|jj dk(r |dz}|dk(rrn|jj dk(rXd}nU|dk(rP|jjtjk(r)|s'|j|jj d}|jj|jjtjk7s|jj d k7r"|jtjd n|jtj|jjtjtj fvr|j#}|jtj$|jjtj$k7sJ|j'}|j(} |j jd | g|_|j jd t+|j-|} |j jd ||jdz } nnd}|j'}|j(} |j jd | g|_g} |j} |jtj|||j.|| | || |d| } | j0D] } | | _ |j jd|j||j| S)z=Parse a definition and return its value in a `class_` object.zparsing %s '%s'rJrFTr rKr1:rz"current accumulated decorators: %szparsing nested definitions.z,finished parsing nested definitions for '%s'rtNz*finished parsing %s '%s'. Next token is %r)rxrrr!rrr rrr rrr"r#rrrr9rrr r|r,rrVrX)rr.rRrPrWparenthesis_levelin_default_argrYrUrTrVrS definitionr:s rr+zParser.parse_definitionsB  RWW||!! (&//4@  <<   %$,,*<*<*C ! "N<<$$-||))S0)Q.)++s2)Q.),1!++s2).%* ))RWW4*!((););<%)N   "#$ <<   %););s)B MM"%%sM + LL  <<  RZZ 8 8"&"9"9";  MM")) $<<$$ 1 1,,.I55J HHNN? L+-D ( HHNN8 9D226:;H HHNN> ))a-C"$ ,,.I55J HHNN? L+-D (H))C MM"** %  KK           (( &E%EL &  8 OO  LL  rc(d}|jjtjtjtj fvrI|jjtjk(rwd|jj vr8dj|jj jddd}n'|jj jdrd}|jj|jjd|jj|jj |r |S|jjtjtjtj fvrI|S)z*Parse a definition comment for noqa skips.rtznoqa: r Nz# noqaallz3parsing comments before docstring, token is %r (%s))rrrrrrrrLr`rwr rr r)rrYs rr9zParser.parse_skip_comments llBJJ BEE#BB||  BJJ.t||111*,'' **00:12>+'\\''228<*/' KK    HHNNE !! ""  #""%llBJJ BEE#BB$#"rctjdj|}|r|jj|k(nd}|r|jj |k(nd}|r|sJ|y)z>Verify the current token is of type `kind` and equals `value`.z Unexpected token at line {self.line}: In file: {self.filename} Got kind {self.current.kind!r} Got value {self.current.value} rTN)rrr+rrr)rrrmsg kind_valid value_valids r check_currentzParser.check_currentsjoo  F    37T\\&&$.D 5:dll((E1 k.3.krc||jjd|j}|j|y)zeParse a 'from x import y' statement. The purpose is to find __future__ statements. zparsing from/import statement.N)r r_parse_from_import_source_parse_from_import_namesris_future_imports rr-z"Parser.parse_from_import_statements3 7899; %%&67rc|jjdk(sJ|jj|jj|jjdk(}|jj|j|jjt j t jt jfvr|jjdk7r|jj|j_|jjt j t jt jfvr|jjdk7r|j|jjdk7ry|jd|jjdk(sJ|jj|jj|S)zuParse the 'from x import' part in a 'from x import y' statement. Return true iff `x` is __future__. r) __future__importFr=) rrr rrrDOTr!r"rGrKs rrIz Parser._parse_from_import_sources\ ||!!V+?T\\-?-?? <<--=  LL $ !!bffbggruu%== ""h. KK    LL $ !!bffbggruu%== ""h. << 4<<#5#5#A *||!!X-At||/A/AA rc&|jjdk(r1|jtjtjf}n tj tj f}|jj|vr|jjtjk(r|jjdk(s|jjtjk7r|jj|jjd|jj|jj|r_|jjd|jj|jj|jj|jtj|jjd|jj|jj|jjtjk(r~|jjdk(re|jtj|jjtjk(r|jtj|jjdk(r|jtj|jjd|jj|jj|jj|vrE|jjtjk(s|jjdk(syyyy)z4Parse the 'y' part in a 'from x import y' statement.rJ;z parsing import, token is %r (%s)zfound future import: %sasr1N)rrrrr"rr2rr!r rr rradd)rrLexpected_end_kindss rrJzParser._parse_from_import_names3sG <<   $ LL "$%% "$**bll!; ll'99 LL   &4<<+=+=+D||  BGG+   " HHNN2 !! ""   8$,,:L:LM##'' (:(:; LL ! HHNN2 !! ""  ||  BGG+ 0B0Bd0J RWW%<<$$/LL)||!!S( RUU# HHNN2 !! "" 5ll'99 LL   &4<<+=+=+D:+D:rr%)F)NN)rrr r!rrrrrxrrrr&r,r*rr+r9rGr-rIrJrrrr r so&#$+78G 1 2DM $3 j#>BH@L\#./$8 ,%rr )*r!rrtokenizerior itertoolsrrpathlibrr-rtypingrutilsr r(rrr#r1r3r r rrrrrrrrrkrrrintrrr rrrr]s &  $$ : <66:44n8!Z8!v-f-+"z+"\X &X&RJ  %  ''   = y ())X11 /E/vvr