AQ;;% ( d Z ddlmZ ddlZddlZddlmZ ddlmZ ddlm Z d.d Z
d/dZ d0dZ d1dZ
d2dZd3dZd4d Z d5d6d#Z G d$ d" Z G d% d&e Z G d' d(e Z G d) d*e Z G d+ d,e Zeeeeed-ZdS )7z'Utility methods for docstring checking. ) annotationsN)nodes)UninferableBase)utilssstrreturnintc f t | t | d z
S )zThe number of leading spaces in a string.
:param str s: input string
:rtype: int
:return: number of leading spaces
)lenlstrip)r s u/builddir/build/BUILD/cloudlinux-venv-1.0.10/venv/lib/python3.11/site-packages/pylint/extensions/_check_docs_utils.pyspace_indentationr s' q66C
&& && nodenodes.FunctionDef
str | Nonec | j r | j j ng }|D ]T}t |t j r8|j dk r-t |j t j r|j j c S UdS )a Get the name of the property that the given node is a setter for.
:param node: The node to get the property name for.
:type node: str
:rtype: str or None
:returns: The name of the property that the node is a setter for,
or None if one could not be found.
setterN)
decoratorsr
isinstance AttributeattrnameexprNamename)r r decorators r get_setters_property_namer sz +//A &&rJ ' ' y%/ 2 2 '"h..9>5:66 / >& & & & 4r nodes.FunctionDef | Nonec d}t | }t j | }|r9|r7| | j }|D ]}t j | r|} n|S )a' Get the property node for the given setter node.
:param node: The node to get the property for.
:type node: nodes.FunctionDef
:rtype: nodes.FunctionDef or None
:returns: The node relating to the property of the given setter node,
or None if one could not be found.
N)r r node_frame_classgetattrr decorated_with_property)r property_
property_name
class_node class_attrsattrs r get_setters_propertyr* 2 s I-d33M'--J /9/A/A$)/L/L D,T22
r return_node nodes.Returnboolc ` | j }|dS t |t j o|j du S )a Check if a return node returns a value other than None.
:param return_node: The return node to check.
:type return_node: astroid.Return
:rtype: bool
:return: True if the return node returns a value other than None,
False otherwise.
NF)valuer r Const)r+ returnss r returns_somethingr2 J s7 Gu7EK00JW]d5J KKr nodes.NodeNG%nodes.NodeNG | UninferableBase | Nonec t | j t j rF| j j }t |t j t j f rt j | S d S N) r excr Callfuncr r r
safe_infer)r r9 s r _get_raise_targetr; \ sR $(EJ'' *x} dUZ 9 : : *#D)) ) 4r target list[str]c 0 d}t j || S )Nz (\s*,(?:\s*or\s)?\s*|\s+or\s+))resplit)r<
delimiterss r _split_multiple_exc_typesrB d s 2J
8J ' ''r set[nodes.ClassDef]c g }t j t j r t j j }|r|g}n j j }|r=t |t j s#|j }|rt |t j #|rf|j r_ t j
|j D ],}t |t s| | -nL# t j
$ r Y n:w xY wn4t }t |t j r|g}nt |t j r| t j D ]}|j
| d |k r%t j |j }|rt j | rxt |t j r| | t |t j r.| | d d fd|D S # t j
$ r t1 cY S w xY w)a Gets all the possible raised exception types for the given raise node.
.. note::
Caught exception types are ignored.
:param node: The raise node to find exception types for.
:returns: A list of exception types possibly raised by :param:`node`.
NT)future __class__r c H h | ] }t j |j | S )r node_ignores_exceptionr ).0r7 r s r z%possible_exc_types.. s>
/ch??
r )r r7 r r r r: parent
ExceptHandlertypeastroid unpack_inferr appendInferenceErrorr; ClassDef FunctionDefnodes_of_classReturnr/ frameinherit_from_std_exInstancer# set)r
exceptionsinferredhandler exceptionr< retvals ` r possible_exc_typesra i s J$(EJ'' !G#DH-- $"J
+ %j%2E F F % nG %j%2E F F % w|
!(!5gl!C!C 5 5I%i AA 5")))4445 )
#4(( fen - - G JJ
1
2
2
G ,,U\::
G
G9$ 99D9))V33 &sy11 G54S99 G!#u~66 G"))#....#C)9:: G"))#++k*B*B1*EFFF
!
! uu s% AC" "C54C5/
H= = I I default docstringnodes.Const | None default_type Docstringc dt |t | f}t t t
t fD ]1} || }| }||d k r||f}2|d S )Nr )DOCSTRING_TYPESgetrf SphinxDocstringEpytextDocstringGoogleDocstringNumpyDocstringmatching_sections)rc re
best_matchdocstring_typeinstancero s r docstringifyrs s _(( yAA)LLMJ 7 7 ">),, $ 6 6 8 8 z!} , ,+X6J a=r c e Zd ZU ej dej ej z ZdZde d< dd Z
d d Z d d
Z d dZ
d dZd dZd dZd dZd dZd dZd dZd dZd dZdS )!rf z=
For\s+the\s+(other)?\s*parameters\s*,\s+see
Fr- supports_yieldsdocrd r Nonec N |r|j nd}| | _ d S )N )r/
expandtabsrv )selfrv rc s r __init__zDocstring.__init__ s) &)1r ''))r r c 2 d| j j d| j dS )N)rF __name__rv r{ s r __repr__zDocstring.__repr__ s" >4>*>>>>>>r r
c dS )2Returns the number of matching docstring sections.r rH r s r ro zDocstring.matching_sections s qr set[str]c t S r6 rZ r s r r[ zDocstring.exceptions s uu r c dS NFrH r s r
has_paramszDocstring.has_params ur c dS r rH r s r has_returnszDocstring.has_returns r r c dS r rH r s r has_rtypezDocstring.has_rtype r r c dS r rH r s r has_property_returnsz Docstring.has_property_returns r r c dS r rH r s r has_property_typezDocstring.has_property_type r r c dS r rH r s r
has_yieldszDocstring.has_yields r r c dS r rH r s r has_yields_typezDocstring.has_yields_type r r tuple[set[str], set[str]]c : t t fS r6 r r s r match_param_docszDocstring.match_param_docs s uucee|r c D | j | j d uS r6 )re_for_parameters_seesearchrv r s r params_documented_elsewherez%Docstring.params_documented_elsewhere s )00::$FFr N)rv rd r rw r r r r
r r r r- r r )r
__module__ __qualname__r? compileXSr ru __annotations__r| r ro r[ r r r r r r r r r rH r r rf rf s^ &BJ rt "O!!!! * * * *? ? ? ? G G G G G Gr c e Zd ZdZde dZd ee Zde dZde d e d
Z e j
ee j e j z Z
d e d Z e j
ee j e j z Zd
e dZ e j
ee j e j z Zde dZ e j
ee j e j z Z e j
d Z e j
d ZdZd"dZd#dZd$dZd$dZd$d Zd$d Z d$d Z d%d Z d!S )&rk zt
[~!.]? # Optional link style prefix
\w(?:\w|\.[^\.])* # Valid python name
z
zw # a container type
[\(\[] [^\n\s]+ [\)\]] # with the contents of the container
zv
(?:{container_type}|{type})
(?:(?:\s+(?:of|or)\s+|\s*,\s*|\s+\|\s+)(?:{container_type}|{type}))*
)rN container_typez?
(?::\w+:)? # optional tag
`z0` # what to reference
a#
: # initial colon
(?: # Sphinx keywords
param|parameter|
arg|argument|
key|keyword
)
\s+ # whitespace
(?: # optional type declaration
(|z)
\s+
)?
((\\\*{0,2}\w+)|(\w+)) # Parameter name with potential asterisks
\s* # whitespace
: # final colon
zx
:type # Sphinx keyword
\s+ # whitespace
(z) # Parameter name
\s* # whitespace
: # final colon
zo
:type: # Sphinx keyword
\s+ # whitespace
z # type declaration
z
: # initial colon
(?: # Sphinx keyword
raises?|
except|exception
)
\s+ # whitespace
(z) # exception type
\s* # whitespace
: # final colon
z:rtype:z
:returns?:Fr r
c
` t d | j | j | j | j | j | j | j | j | j | j fD S )r c 3 4 K | ]}t | V d S r6 r- rJ is r z4SphinxDocstring.matching_sections..= <
GG
r )sumre_param_in_docstringr rv re_raise_in_docstringre_rtype_in_docstringre_returns_in_docstring re_property_type_in_docstringr s r ro z!SphinxDocstring.matching_sections; s
*11$(;;*11$(;;*11$(;;,33DH==299$(CC
r r c t }t j | j | j D ]9}| d }| t | :|S Nrh )rZ r? finditerr rv groupupdaterB )r{ typesmatch
raise_types r r[ zSphinxDocstring.exceptionsH s_ %%[!;TXFF @ @E Q J LL2:>> ? ? ? ? r r- c V | j sdS | j | j d uS r )rv r r r s r r zSphinxDocstring.has_paramsQ s/ x 5)00::$FFr c l | j sdS t | j | j S r )rv r- r r r s r r zSphinxDocstring.has_returnsW s2 x 5D077AABBBr c l | j sdS t | j | j S r )rv r- r r r s r r zSphinxDocstring.has_rtype] s2 x 5D.55dh??@@@r c n | j sdS | j d S )NF:)rv r
startswithr s r r z$SphinxDocstring.has_property_returnsc s6 x 5 8??$$//4444r c l | j sdS t | j | j S r )rv r- r r r s r r z!SphinxDocstring.has_property_typek s2 x 5D6==dhGGHHHr r c t }t }t j | j | j D ]n}| d }| dd }| | | d }|| | o| t j | j
| j ||fS )N \ry rh ) rZ r? r r rv r replaceaddr findallre_type_in_docstring)r{ params_with_docparams_with_typer r
param_types r r z SphinxDocstring.match_param_docsq s %% 55[!;TXFF + +E;;q>>D<<b))D % % % Q J% $$T***
4+Ddh O OPPP 000r Nr r r r ) r r r re_typere_simple_container_typeformatre_multiple_simple_typere_xref re_param_rawr? r r r r re_type_rawr re_property_type_rawr re_raise_rawr r r ru ro r[ r r r r r r rH r r rk rk sB G
%=
G
- L$ 'BJ|RTBD[ A A " K &2:k24"$;??
!
%/BJ/CRTBD[$Q$Q!
"
L 'BJ|RTBD[ A A &BJz 2 2 (bj 7 7O
G G G G C C C C A A A A 5 5 5 5I I I I 1 1 1 1 1 1r rk c 6 e Zd ZdZ ej ej ddd ej ej
z Z ej ej ddd ej ej
z Z
ej ej ddd ej ej
z Z ej ej ddd ej ej
z Z ej dej ej
z Z ej d Zd d Zd
S ) rl a Epytext is similar to Sphinx.
See the docs:
http://epydoc.sourceforge.net/epytext.html
http://epydoc.sourceforge.net/fields.html#fields
It's used in PyCharm:
https://www.jetbrains.com/help/pycharm/2016.1/creating-documentation-comments.html#d848203e314
https://www.jetbrains.com/help/pycharm/2016.1/using-docstrings-to-specify-types.html
r @rh z
@ # initial "at" symbol
(?: # Epytext keyword
rtype|returntype
)
: # final colon
z
@returns?:r r- c | j sdS | r-| j d S dS )NFr )rv r r r r s r r z%EpytextDocstring.has_property_returns sQ x 5 ! ! # # 9 x((33C888 8ur Nr )r r r __doc__r? r rk r r r r r r r r r r r r r r rH r r rl rl sN 'BJ$,,S#q9924"$; &2:#++Ca88"$+ %/BJ,44S#qAA24"$;% %! 'BJ$,,S#q9924"$; 'BJ rt )bj 7 7
r rl c e Zd Zej Zej Zde de dZd eee ZdZ e
j e d e
j e
j
z e
j z Z e
j e d e
j e
j
z e
j z Z e
j d e d
e
j e
j
z e
j z Z e
j e d e
j e
j
z e
j z Z e
j d e d
e
j e
j
z e
j z Z e
j e d e
j e
j
z e
j z Z e
j de de
j e
j
z e
j z Z e
j de de
j e
j
z e
j z Z e
j e d e
j e
j
z e
j z ZeZdZd0dZd1dZd1dZ d1dZ d1d Z d1d Z d1d Z d1d Z!d2d!Z"d3d#Z#d4d%Z$e%d5d( Z&e%d6d* Z'd7d.Z(d/S )8rm z
(?:r zj) # a container type
[\(\[] [^\n]+ [\)\]] # with the contents of the container
z
(?:{container_type}|{type}|{xref})
(?:(?:\s+(?:of|or)\s+|\s*,\s*|\s+\|\s+)(?:{container_type}|{type}|{xref}))*
)rN xrefr zy
^([ ]*) {0} \s*: \s*$ # Google parameter header
( .* ) # section
(?:Args|Arguments|Parameters)z&Keyword\s(?:Args|Arguments|Parameters)z}
\s* ((?:\\?\*{0,2})?[\w\\]+) # identifier potentially with asterisks or escaped `\`
\s* ( [(]
z
(?:,\s+optional)?
[)] )? \s* : # optional type declaration
\s* (.*) # beginning of optional description
Raisesz
\s* (zg) \s* : # identifier
\s* (.*) # beginning of optional description
Returns?
\s* (za:)? # identifier
\s* (.*) # beginning of description
z
^za: # identifier
\s* (.*) # Summary line / description
Yields?Tr r
c z t d | j | j | j | j | j | j | j | j | j | fD S )r c 3 4 K | ]}t | V d S r6 r r s r r z4GoogleDocstring.matching_sections.. r r ) r re_param_sectionr rv re_raise_sectionre_returns_sectionre_yields_sectionre_property_returns_line _first_liner s r ro z!GoogleDocstring.matching_sections s
%,,TX66%,,TX66'..tx88&--dh77-44T5E5E5G5GHH
r r- c V | j sdS | j | j d uS r )rv r r r s r r zGoogleDocstring.has_params s/ x 5$++DH55TAAr c | j sdS | | j }|D ]9}| j | }|s | d }|r dS :dS NFr Trv _parse_sectionr re_returns_liner r )r{ entriesentryr return_descs r r zGoogleDocstring.has_returns x 5%%d&=>> E(..u55E
++a..K
tt
ur c | j sdS | | j }|D ]9}| j | }|s | d }|r dS :dS NFrh Tr )r{ r r r return_types r r zGoogleDocstring.has_rtype/ r r c | }t | j | pM| j | p3| j | p| j | S r6 )r r- r r r r r )r{
first_lines r r z$GoogleDocstring.has_property_returns? s %%''
! ( ( 4 4
9$++J77
9&--j99
9 %,,Z88
r c | j sdS t | j | S r )rv r- r r r r s r r z!GoogleDocstring.has_property_typeJ s< x 5D1778H8H8J8JKKLLLr c | j sdS | | j }|D ]9}| j | }|s | d }|r dS :dS r rv r r re_yields_liner r )r{ r r r
yield_descs r r zGoogleDocstring.has_yieldsP x 5%%d&<== E'--e44E
Q J
tt
ur c | j sdS | | j }|D ]9}| j | }|s | d }|r dS :dS r r )r{ r r r
yield_types r r z GoogleDocstring.has_yields_type` r r r c 6 t }| | j }|D ]m}| j | }|s | d }| d }|r"| t | n|S )Nrh r )rZ r r
re_raise_liner r r rB )r{ r r r r exc_typeexc_descs r r[ zGoogleDocstring.exceptionsp s %%%%d&;<< B BE&,,U33E
{{1~~H {{1~~H
B 6x @ @AAA r r c t }t }| | j }| | | j |D ]}| j | }|s | d }| dd }| d }| d }|r| | |r| | ||fS )Nrh r ry r )
rZ r r extendre_keyword_param_section
re_param_liner r r r ) r{ r r r r r
param_namer
param_descs r r z GoogleDocstring.match_param_docs s $'EE%(UU%%d&;<<t**4+HIIJJJ 0 0E&,,U33E
Q J#++D"55J Q J Q J
1 $$Z000
0 ##J/// 000r r c h | j dd d S )N
rh r )rv r r@ r s r r zGoogleDocstring._first_line s) x &&tQ//22r
section_match
re.Match[str]c L t | d dz S r r
r r s r min_section_indentz"GoogleDocstring.min_section_indent s# =&&q))**Q..r _c dS r rH )r s r _is_section_headerz"GoogleDocstring._is_section_header s ur
section_rere.Pattern[str]r= c @ | | j }|g S | | }g }g }d}| d D ]}| st
| }||k r ne|r|}d}||k rC| | r nB|r*| d | g }| | |r(| d | |S )NTr Fr )
r rv r r
splitlinesstripr r rQ join) r{ r r min_indentationr r is_firstline indentations r r z GoogleDocstring._parse_section sD "))$(33
I 11-@@ !''**5577 D::<<
+D11K_,,
!"- o--**400 E NN499U#3#3444 E LL - NN499U++ , , ,r Nr r r r r r r r r
)r r r r- )r r r r= ))r r r rk r r re_container_typer re_multiple_type_re_section_templater? r r r Mr r r
r r r r r r r ru ro r r r r r r r r[ r r staticmethodr r r rH r r rm rm s %G %G
73D
"rz ##$DEE
rt bd
*rz ##$MNN
rt bd
BJ rt bd
M "rz ##I..rt bd0B BJ rt bd M $ ##K00"$+2D !bj rt bd O *rz
rt bd #
##J//rt1C %NO
B B B B
M M M M 1 1 1 143 3 3 3 / / / \/ \
% % % % % %r rm c . e Zd ZdZ ej e d ej ej z ej z Z
dZ ej de j
de dej ej z Z ej e d ej ej z ej z Z ej de j d ej ej z ej z Z ej e d
ej ej z ej z Z ej d e j
d ej ej z ej z Z ej e d
ej ej z ej z ZeZdZddZed d Zed d ZdS ) rn z
^([ ]*) {0} \s*?$ # Numpy parameters header
\s* [-=]+ \s*?$ # underline
( .* ) # section
r z.((['"]\w+\s*['"])|(\d+)|(True)|(False)|(None))z
\s* (?P\*{0,2}\w+)(\s?(:|\n)) # identifier with potential asterisks
\s*
(?P
(
(z) # default type declaration
(,\s+optional)? # optional 'optional' indication
)?
(
{(z,?\s*)+} # set of default values
)?
(?:$|\n)
)?
(
\s* (?P.*) # optional description
)?
r r z^)$ # type declaration
\s* (.*) # optional description
r z6
\s* (?:\w+\s+:\s+)? # optional name
(zc)$ # type declaration
\s* (.*) # optional description
r Tr r c t }t }| | j }| | | j |D ]}| j | }|s t j d| }|r-| d }| d }d} n^| d }| d } | d }| t j d| r|} |s| r| }| r| | |r| | ||fS )zIMatches parameter documentation section to parameter documentation rules.z \s*(\*{0,2}\w+)\s*:?\n\s*\w*$r r Nr z\s*(\*{0,2}\w+)\s*:.+$)
rZ r r r r r
r r? r r )
r{ r r r r r re_only_descr r r s
r r z NumpyDocstring.match_param_docs sp %% 55%%d&;<<t**4+HIIJJJ 0 0E&,,U33E
8$DeLLL
, "[[ 6 6
"[[ 6 6
!
"[[ 6 6
"[[ 6 6
"[[ 6 6
%"(3Le*T*T%!+J " ,j ,!+J
1 $$Z000
0 ##J/// 000r r r r
c F t | d S r r r s r r z!NumpyDocstring.min_section_indent= s =&&q))***r r# r r- c F t t j d| S )Nz\s*-+$)r- r? r )r# s r r z!NumpyDocstring._is_section_headerA s BHY--...r Nr r% )r# r r r- )r r r r( r? r r r r r) r re_default_valuerm r' r
r r r r r r r ru r r* r r rH r r rn rn s9 "rz ##$DEE
rt bd
M BJ
, " rt % M* "rz ##I..rt bd0B BJ % rt bd M $ ##K00"$+2D !bj
*
rt bd
O #
##J//rt1C %NO(1 (1 (1 (1T + + + \+ / / / \/ / /r rn )sphinxepytextgooglenumpyrb )r r r r
)r r r r )r r r r )r+ r, r r- )r r3 r r4 )r< r r r= )r r3 r rC )rb )rc rd re r r rf )r
__future__r r? rO r astroid.utilr pylint.checkersr r r r* r2 r; rB ra rs rf rk rl rm rn ri rH r r r8 s3
. - " " " " " " ( ( ( ( ( ( ! ! ! ! ! !' ' ' ' * 0L L L L$ ( ( ( (
6 6 6 6t 8A $6G 6G 6G 6G 6G 6G 6G 6GrR1 R1 R1 R1 R1i R1 R1 R1j3 3 3 3 3 3 3 3lT T T T Ti T T Tnt/ t/ t/ t/ t/_ t/ t/ t/p
r