$g dZddlZddlZddlZddlZddlmZddlmZddl m Z ddl m Z ddl mZmZmZmZmZmZmZmZmZmZddlmZmZmZmZmZmZmZdd l m!Z!m"Z"m#Z#m$Z$dd l%m&Z&dd l'm(Z( dd lm)Z)n#e*$r dd l)m)Z)YnwxYwGd dZ+d de,de-de+fdZ.GddZ/de,de,de0de-fdZ1de,dee,ee,ffdZ2dddde,deee,efdee0dee,effdZ3dS)!zThis module is responsible for loading the documentation from Python objects. It uses [`inspect`](https://docs.python.org/3/library/inspect.html) for introspecting objects, iterating over their members, etc. N) lru_cache)chain) attrgetter)Path) AnyCallableDictListMappingOptionalSequenceSetTupleUnion) AttributeClassFunctionMethodModuleObjectSource)get_class_attributesget_instance_attributesget_module_attributesmerge)PARSERS) RE_SPECIAL)cached_propertyc eZdZdZddedededddfdZedefdZ edefd Z edd Z de fd Z de fd Zde fd Zde fdZde fdZde fdZde fdZde fdZde fdZde fdZde fdZdS) ObjectNodea)Helper class to represent an object tree. It's not really a tree but more a backward-linked list: each node has a reference to its parent, but not to its child (for simplicity purposes and to avoid bugs). Each node stores an object, its name, and a reference to its parent node. Nobjnameparentreturnc tj|}n#t$rYnwxYw||_ ||_ ||_dS)zInitialize the object. Arguments: obj: A Python object. name: The object's name. parent: The object's parent node. N)inspectunwrap Exceptionr!r"r#)selfr!r"r#s O/var/www/html/netbox-4.1.3/venv/lib/python3.11/site-packages/pytkdocs/loader.py__init__zObjectNode.__init__%s] .%%CC    D  ' ',2 s  $$c|jg}|j}|r#||j|j}|#dt |S)zyReturn the Python dotted path to the object. Returns: The Python dotted path to the object. .)r"r#appendjoinreversed)r)partscurrents r* dotted_pathzObjectNode.dotted_path?s[ + % LL & & &nG %xx(((c>tj|jjS)zkReturn the object's module file path. Returns: The object's module file path. )r& getabsfilerootr!r)s r* file_pathzObjectNode.file_pathMs!$)-000r4c,|j |jjS|S)zYReturn the root of the tree. Returns: The root of the tree. )r#r7r8s r*r7zObjectNode.rootVs ; ";# # r4c4tj|jS)zdTell if this node's object is a module. Returns: The root of the tree. )r&ismoduler!r8s r* is_modulezObjectNode.is_moduleas )))r4c4tj|jS)zoTell if this node's object is a class. Returns: If this node's object is a class. )r&isclassr!r8s r*is_classzObjectNode.is_classis tx(((r4c4tj|jS)zuTell if this node's object is a function. Returns: If this node's object is a function. )r& isfunctionr!r8s r* is_functionzObjectNode.is_functionqs !$(+++r4c4tj|jS)zwTell if this node's object is a coroutine. Returns: If this node's object is a coroutine. )r&iscoroutinefunctionr!r8s r*is_coroutine_functionz ObjectNode.is_coroutine_functionys *48444r4c^t|jtp|S)zuTell if this node's object is a property. Returns: If this node's object is a property. ) isinstancer!propertyis_cached_propertyr8s r* is_propertyzObjectNode.is_propertys' $(H--J1H1H1J1JJr4c6t|jtS)zTell if this node's object is a cached property. Returns: If this node's object is a cached property. )rHr!rr8s r*rJzObjectNode.is_cached_propertys $(O444r4c\t|jo|jS)zTell if the object of this node's parent is a class. Returns: If the object of this node's parent is a class. )boolr#r@r8s r*parent_is_classzObjectNode.parent_is_classs' DK:DK$8$8$:$:;;;r4cttd}|ot|j|S)zqTell if this node's object is a method. Returns: If this node's object is a method. cdSNrSr4r*z&ObjectNode.is_method..sTr4)typerOrHr!)r) function_types r* is_methodzObjectNode.is_methods6 \\** ##%%M*TX}*M*MMr4c4tj|jS)aTell if this node's object is a method descriptor. Built-in methods (e.g. those implemented in C/Rust) are often method descriptors, rather than normal methods. Returns: If this node's object is a method descriptor. )r&ismethoddescriptorr!r8s r*is_method_descriptorzObjectNode.is_method_descriptors)$(333r4c|jsdS|jjj|jd}|ot |tS)z}Tell if this node's object is a staticmethod. Returns: If this node's object is a staticmethod. FN)r#r!__dict__getr"rOrH staticmethodr)self_from_parents r*is_staticmethodzObjectNode.is_staticmethodsT { 5;?377 4HH##%%T*5E|*T*TTr4c|jsdS|jjj|jd}|ot |tS)z{Tell if this node's object is a classmethod. Returns: If this node's object is a classmethod. FN)r#r!r\r]r"rOrH classmethodr_s r*is_classmethodzObjectNode.is_classmethodsT { 5;?377 4HH##%%S*5E{*S*SSr4rR)r$r )__name__ __module__ __qualname____doc__rstrr r+rIr3r9r7rNr=r@rCrFrKrJrOrWrZrardrSr4r*r r sCsH\4JVZ4 )S ) ) )X )13111X1X*4****)$)))),T,,,,5t5555KTKKKK5D5555<<<<<N4NNNN 4d 4 4 4 4 U U U U U T T T T T T Tr4r Fpathnew_path_syntaxr$c|std|g}d|vs|rX |d\}}|d}n#t$r|g}}YnwxYwtj|}n|d} d|} tj|}nh#t $rZ}t |dkrt d|d||d|d Yd }~nd }~wwxYwt||j } |D]+} t| j | } t| | | } | } ,| } d }| j r|tj| j }tj| j j r+|(|| j j urt||j | _ n| j } | j r| S) a Transform a path into an actual Python object. The path can be arbitrary long. You can pass the path to a package, a module, a class, a function or a global variable, as deep as you want, as long as the deepest module is importable through `importlib.import_module` and each object is obtainable through the `getattr` method. It is not possible to load local objects. Args: path: The dot/colon-separated path of the object. new_path_syntax: Whether to use the "colon" syntax for the path. Raises: ValueError: When the path is not valid (evaluates to `False`). ImportError: When the object or its parent module could not be imported. Returns: The leaf node representing the object and its parents. z&path must be a valid Python path, not :r-Tz Importing 'zn' failed, possible causes are: - an exception happened while importing - an element in the path does not existrNr#) ValueErrorsplit importlib import_moduler/ ImportErrorleninsertpopr regetattrr!r#r& getmoduler<)rjrkobjects module_path object_path parent_moduleobj_parent_modulesparent_module_patherror current_nodeobj_namer!childleaf real_modules r*get_object_treersg( JH$HHIIIG d{{o{ -'+zz# $K"'',,GG , , ,#'KKK , "/ << "ZZ__ !$* > >)**a//%CdCCC! ! q"4"8"8"<"<======== > $m]-CDDLl&113>>> D K   )  !+L,<==K  L/3 4 4 &;l>Q>U+U+U&0k>R&S&S # #*    ) Ks*A AA!B66 DADDcZeZdZdZ d/deeededeeded ed df d Z d0d ed ee e eefd e fdZ d0dedee e eefd efdZeded efdZ d0dedee e eefd efdZdedeeded efdZdede ded eeefdee e eefdeded dfdZded efdZded efdZeded efdZ eded efd Z!eded efd!Z"ed0ded"eed efd#Z#ded e$fd$Z%ded e$fd%Z&ded e$fd&Z'd0ded'eeed e$fd(Z(ed0ded"eed efd)Z)d*ed+e ed efd,Z*e+d-d*ed efd.Z,dS)1LoaderzThis class contains the object documentation loading mechanisms. Any error that occurred during collection of the objects and their documentation is stored in the `errors` list. NgoogleFfiltersdocstring_styledocstring_optionsinherited_membersrkr$c|sg}d|D|_t|di|pi|_g|_||_||_dS)aInitialize the object. Arguments: filters: A list of regular expressions to fine-grain select members. It is applied recursively. docstring_style: The style to use when parsing docstrings. docstring_options: The options to pass to the docstrings parser. inherited_members: Whether to select inherited members for classes. new_path_syntax: Whether to use the "colon" syntax for the path. c`g|]+}|tj|df,S)!)recompilelstrip).0filtrs r* z#Loader.__init__..8s3TTT5 5<<+<+< = =>TTTr4NrS)rrdocstring_parsererrorsselect_inherited_membersrk)r)rrrrrks r*r+zLoader.__init__$se" GTTGTTT ' 8 U Us d??eeG{D,@AA >>   A77gFFKK ]]__ A66tWEEKK  ! ! # # A==dCCKK  " " A<???r4nodeselect_membersc|j}|j}|dd} tt j|d}ne#t $rX t|j }|rt|dnd}n#t tf$rd}YnwxYwYnwxYwt|||jt j ||}|dur|S|p t}t|} ||j| t j|D]&\} } || |r t'| | |} | rN|jjt j| jur)||| | rN|jjt j| jur)||| | | vr/||| | | (t9|d rrt;j|jD]X\} }} |||rOPZP^>_>_-_-_))$*F*Fz*R*RSSSS++--v$)-7CTU_UcCdCd2d2d))$*I*I**U*UVVVV O33))$*J*J:WfgrWs*t*tuuu 6: & & O!(!5fo!F!F O O 7A;;w77O*d+>+>W+>+>??D))$*G*G*M*MNNNs5"A B0&B?B0B*'B0)B**B0/B0clsc<|j}|j}|dkr|S|d|S)Nbuiltinsr-)rfrg)rmodqnames r* _class_pathzLoader._class_paths5n  *  Lr4c |j}tj|jpd}fd|jD} t tj|j}n#ttf$rd}YnwxYwt|j |j |j |||}i}t|jddD]} t|t!|  d|i} d|jvr\ |t'|jtj|j| d<n#tt,f$rYnwxYw|jjfi| |d ur|S|p t3}i} t3} |j} t5tj|}|D]]\}}||ur |t:usJ|t<usA||r+|| vr"j r|| |<| !|X|| |<^| D]@\}}tE||| }|#r$|}n|%r&|}n|'r(|}nw|)r*|}nM|+r,|}n#||vr-|||}n || vr|j./d |0|Bd d gj1fddgj2fddgj3fddgj4ffD]T\}}}5|| |r7|j.6|7|||||||nU|S)aGet the documentation for a class and its children. Arguments: node: The node representing the class and its parents. select_members: Explicit members to select. Returns: The documented class object. c:g|]}|SrS)r)rbr)s r*rz2Loader.get_class_documentation..s'???!!!$$???r4N)r"rjr9rbasesrrorr+ signatureFrp inherited __fields__zpydantic-model_declared_fieldszmarshmallow-modelz_meta.get_fieldsz django-model__dataclass_fields__ dataclass)8r!r&cleandocrh __bases__rgetsourcelinesr TypeErrorrr"r3r9r0__mro__rrr\updaterr+rrqrrrdictritemsrUobjectrraddr r@rrdrrarrWrrKrr propertiesr.r get_pydantic_field_documentation#get_marshmallow_field_documentationget_django_field_documentationget_annotated_dataclass_fielddetect_field_modelextend add_fields)r)rrclass_rrrrr parent_classcontextrrdirect_members all_membersrrrr attr_namer add_methods` r*rzLoader.get_class_documentations$V^%9r:: ????f.>??? W3DH==>FF#   FFF !n    68$V^CRC%899 G GL /#7 #E#E F F F F#/"A  ( ( &&'>v'O'OPPP'.'8'I'I $$z*    # #D$9EEWEEE U " " '0355EE 7-f5566 #.#4#4#6#6 2 2 KdNNf&6&6DKK Uc > J;;z>BBL-j)ZPPL >!> >l >'E 4PPP %%jj&<&<===  > >r4c |j} tj|}n#t$rd}YnwxYw t tj|}n#t $rd}YnwxYwg}|r|dt|j |j |j tj ||||S)zGet the documentation for a function. Arguments: node: The node representing the function and its parents. Returns: The documented function object. Nasync)r"rjr9rrrr)r!r&rrrrrrFr.rr"r3r9r)r)rfunctionrrrs r*rz!Loader.get_function_documentationPs8 )(33II   III  W3H==>FF   FFF !#  % % ' ' '   g & & &!nnX..!    s --A AAc |j}|j}dg}|r|ddg|j}n%||jdnd|j} tj |}|j }n#ttf$rd}YnwxYw ttj|}n#ttf$rd}YnwxYwt!|j||jtj||||S)zGet the documentation for a property. Arguments: node: The node representing the property and its parents. Returns: The documented attribute object (properties are considered attributes for now). rIwritablecachedNreadonly)r"rjr9r attr_typerr)r!r3rJrfuncr.fsetfgetr&rreturn_annotationrrqrrrrr"r9r) r)rproprjrsig_source_funcrrrs r*rz!Loader.get_property_documentationusCx \  " " $ $ (   z84 5 5 5"iOO   DI,=jj: N N N"iO 4)/::I"3II:&   III   W3ODDEFF#   FFF nnT**!    s$+BBB!B==CCc|j}|j}dg}|jr|dt |j||j|jj|j |S)zGet the documentation for a Pydantic Field. Arguments: node: The node representing the Field and its parents. Returns: The documented attribute object. zpydantic-fieldrequiredr"rjr9rrr) r!r3r r.rr"r9 field_info description outer_type_rrrjrs r*rz'Loader.get_pydantic_field_documentationsnx&' = *   j ) ) )no1&!     r4c4|j}|j}dg}|jr|d|jr|d|jr|jd|jnt|j}t|j ||j ||j |S)zGet the documentation for a Django Field. Arguments: node: The node representing the Field and its parents. Returns: The documented attribute object. z django-fieldnullableblankz: r ) r!r3nullr.r help_text verbose_namerirr"r9 __class__)rrrjrrs r*rz%Loader.get_django_field_documentationsx$% 9 *   j ) ) ) : '   g & & & AEjt(< /  /  / ////4%%C%(5QTUXQY[_Q_K`Ba%ms%%%%T;?===!s3x~!67=  ====~  #   \ ;?mmm!s3x~!67m  mmmm^C#]afj,>>> > c" > !s3x~!67 >>> >>>>># z# h# # # # J* z* i* * * * X z i   \ 0 Z I   \ @ *    \ 0  J QU bk   \ 2 D* D D D D D E: E& E E E EZF:. . Z. XdSViEX. dj. . . . `  * htn `i   \ ..3.s3x.D.... YtCDr4rr fields_namerc f|ttfd|jddDvS)aUCheck if a field with a certain name was inherited from parent classes. Arguments: field_name: The name of the field to check. fields_name: The name of the attribute in which the fields are stored. base_class: The base class in which the field appears. Returns: Whether the field was inherited. c3^K|]'}t|iV(dSrR)rykeys)rrr6s r* z%field_is_inherited..s; i i glK4499;; i i i i i ir4rnro)rrr)rr6rs ` r*rrsM  i i i iPZPbcdegcgPh i i i  r4rcT|dd^}}|r|dnd}||fS)aSplit an attribute name into a first-order attribute name and remainder. Args: attr_name: Attribute name (a) Returns: Tuple containing: first_order_attr_name: Name of the first order attribute (a) remainder: The remainder (b.c) r-rn)maxsplitrN)rr)rr remainingrs r*rrs<)2a(H(H%I )3 ! tI ) ++r4)r class_objrr>ct|t|z stdt|\}}|r||n/tt ||i}|rt ||}t|r |}t|ts d|D}n#t$ri}YnwxYw|S)Nz(Either members or class_obj is required.c ni|]2}t|ddt|dt||3S) auto_createdFr")ryri)rfs r* zget_fields..s@mmm7STVdfkKlKlmgaQ00!mmmr4) rNrqrrvarsr]rcallablerHr)rrr>rrrs r*rrs MMDOO +ECDDD'6y'A'A$9/6 pW* + +DirOs  \\\\\\\\\\\\\\\\\\\\\\\\WWWWWWWWWWWWWWWWWWssssssssssss//////******0)))))))000////////0eTeTeTeTeTeTeTeTZRR#RRRRRRjN N N N N N N N b3Sdt(,s,uS(3--?'@,,,,(,0 $ gc3h' (~   #s(^ s.A55 BB