3
T'íc ~ ã @ s¬ d Z ddlZddlZddlZddlZddlZddlZddlZddlZddl Z ddl
m Z m Z ddl
mZ ddlmZmZmZmZmZ ddlmZ ddlmZ ddlmZmZmZmZmZm Z m Z m Z m Z dd l m!Z! dd
l"m#Z# dd l"m$Z% dd l&m'Z' dd
l(m)Z) ddl(m*Z+ ej,d~kr2ddlm-Z-m.Z.m/Z/ n"e0e1j2Z-e0e3j4Z.e0e5j6d Z/e'j7e8Z9ej:dej;Z<eedddZ=eedddZ>ddeeedd d Z?eee e3 dd d Z@eee3ef dd d!ZAeee3ef dd"d#ZBee e d$f dd%d&ZCeee ed$f dd'd(ZDeee dd)d*ZEeeFdd+d,ZGeeFd-d.d/ZHeeFd-d0d1ZIeedd2d3ZJeeFdd4d5ZKdeee3eFd6d7d8ZLdeee3eFd6d9d:ZMeeFd-d;d<ZNeeFdd=d>ZOeeFdd?d@ZPeeFddAdBZQeeFddCdDZReeFddEdFZSeeFddGdHZTeeFddIdJZUeeFddKdLZVeeFddMdNZWeeFddOdPZXeeFddQdRZYeeFddSdTZZee3eedUdVdWZ[ee3dXdYdZZ\ee3eFd[d\d]Z]G d^d_ d_Z^G d`da daZ_G dbdc dcZ`G ddde deee3ef ZaeeFdfdgdhZbdidi feeFeFeejcdjdkdlZddejceeejcdmdndoZedejceFeFeFe3dqdrdsZfe3ejcdtdudvZgde#jhe3ejcdxdydzZie[diddfeeeFee3e3d{d|d}ZjdS )z&Helpers for inspecting Python modules.é N)ÚpartialÚ
partialmethod)Ú
import_module)Ú ParameterÚisclassÚismethodÚismethoddescriptorÚismodule)ÚStringIO)Ú
ModuleType) ÚAnyÚCallableÚDictÚMappingÚOptionalÚSequenceÚTupleÚTypeÚcast)ÚRemovedInSphinx50Warning)Úast)Úunparse)Úlogging)Ú
ForwardRef)Ú stringifyé é )ÚClassMethodDescriptorTypeÚMethodDescriptorTypeÚWrapperDescriptorTypeÚfromkeysz at 0x[0-9a-f]{8,16}(?=>))ÚfuncÚreturnc C s> t jdtdd tj| }g }d}d}g }f }i }f }i }|j|jk rP|j|d< xÂ|jj D ]´} | j }
| j
} |
t j kr|j
| nx|
t jkr°|j
| | j| jk rú|| jf7 }nJ|
t jkrÀ| }n:|
t jkrì|j
| | j| jk rú| j|| < n|
t jkrú| }| j| jk r\| j|| < q\W |s d}|s(d}tj|||||||S )zPLike inspect.getfullargspec but supports bound methods, and wrapped
methods.z-sphinx.ext.inspect.getargspec() is deprecatedé )Ú
stacklevelNr" )ÚwarningsÚwarnr ÚinspectÚ signatureÚreturn_annotationÚemptyÚ
parametersÚvaluesÚkindÚnamer ÚPOSITIONAL_ONLYÚappendÚPOSITIONAL_OR_KEYWORDÚdefaultÚVAR_POSITIONALÚ KEYWORD_ONLYÚ VAR_KEYWORDÚ
annotationÚ FullArgSpec) r! ÚsigÚargsÚvarargsÚvarkwÚ
kwonlyargsÚdefaultsÚ annotationsÚ
kwdefaultsÚparamr- r. © rA ú5/tmp/pip-build-gk9425m9/sphinx/sphinx/util/inspect.pyÚ
getargspec3 sL
rC )Úobjr" c C s6 y t | dr| S tj| S W n tk
r0 | S X dS )z?Get an original object from wrapped object (wrapped functions).Z__sphinx_mock__N)Úhasattrr' ÚunwrapÚ
ValueError)rD rA rA rB rF i s
rF )Ústop)rD rH r" c C sj xd|r|| r| S t | r"| j} qtj| r>t| dr>| j} qt| rN| j} qt| r^| j} q| S qW dS )zx
Get an original object from wrapped object (unwrapping partials, wrapped
functions, and other decorators).
Ú __wrapped__N) Ú ispartialr! r' Ú isroutinerE rI Ú
isclassmethodÚ__func__Úisstaticmethod)rD rH rA rA rB Ú
unwrap_allv s rO c C sH t | dd}|dkrdS t|ttfr<tdd |D r<|S t|dS )z£Get __all__ attribute of the module as dict.
Return None if given *obj* does not have __all__.
Raises ValueError if given *obj* have invalid __all__.
Ú__all__Nc s s | ]}t |tV qd S )N)Ú
isinstanceÚstr)Ú.0ÚerA rA rB ú <genexpr> s zgetall.<locals>.<genexpr>)Ú safe_getattrrQ ÚlistÚtupleÚallrG )rD rP rA rA rB Úgetall s rZ c C s" t | dd}t|tr|S i S dS )z,Get __annotations__ from given *obj* safely.Ú__annotations__N)rV rQ r )rD r[ rA rA rB Úgetannotations s
r\ c C s" t | dd}t|tr|S i S dS )z(Get __globals__ from given *obj* safely.Ú __globals__N)rV rQ r )rD r] rA rA rB Ú
getglobals£ s
r^ .c C s$ t | dd}t|tr|S t S dS )z$Get __mro__ from given *obj* safely.Ú__mro__N)rV rQ rX )rD r_ rA rA rB Úgetmro¬ s
r` c C sF t j| sdS t| di }|jd}t|tr>t|dkr>|S dS dS )z%Get __orig_bases__ from *obj* safely.NÚ__dict__Ú__orig_bases__r )r' r rV ÚgetrQ rX Úlen)rD ra rb rA rA rB Ú getorigbasesµ s
re c C sj t j| stt| dd}|dkr&dS t|tr4|S t|trF|diS t|ttfrbdd |D S t dS )zÜGet __slots__ attribute of the class as dict.
Return None if gienv *obj* does not have __slots__.
Raises TypeError if given *obj* is not a class.
Raises ValueError if given *obj* have invalid __slots__.
Ú __slots__Nc S s i | ]
}d |qS )NrA )rS rT rA rA rB ú
<dictcomp>Ö s z getslots.<locals>.<dictcomp>)
r' r Ú TypeErrorrV rQ ÚdictrR rW rX rG )rD rf rA rA rB ÚgetslotsÄ s
rj c C sJ t jd
krt| tjS t| dd}t| dd}|dkrB|dkrBdS d S dS ) z)Check the if object is a kind of NewType.r é
Ú
__module__NÚ __qualname__ÚtypingzNewType.<locals>.new_typeTF)r rk )ÚsysÚ version_inforQ rn ZNewTyperV )rD rl rm rA rA rB Ú isNewTypeÛ s
rq )Úxr" c C s t j| ot| tjS )z(Check if the object is subclass of enum.)r' r Ú
issubclassÚenumÚEnum)rr rA rA rB Ú isenumclassè s rv c C s t | tjS )z)Check if the object is attribute of enum.)rQ rt ru )rr rA rA rB Úisenumattributeí s rw c C s xt | r| j} qW | S )zfGet an original object from partial object.
This returns given object itself if not partial.
)rJ r! )rD rA rA rB Ú unpartialò s
rx c C s t | ttfS )z Check if the object is partial.)rQ r r )rD rA rA rB rJ ý s rJ )rD Úclsr. r" c C sr t | trdS tj| r0| jdk r0t| jr0dS |rn|rnt }x.t|D ]"}|jj ||}||k rHt
|S qHW dS )z#Check if the object is classmethod.TNF) rQ Ú classmethodr' r Ú__self__r Úobjectr` ra rc rL )rD ry r. Ú placeholderÚbaseclsÚmethrA rA rB rL s
rL c C sT t | trdS |rP|rPx8t|d|gD ]&}|jj|}|r&t |trHdS dS q&W dS )z$Check if the object is staticmethod.Tr_ F)rQ Ú staticmethodÚgetattrra rc )rD ry r. r~ r rA rA rB rN s
rN c C s& x dD ]}t t| |drdS qW dS )z/Check if the object is some kind of descriptor.Ú__get__Ú__set__Ú
__delete__NTF)r r r )ÚcallablerV )rr ÚitemrA rA rB Ú isdescriptor% s
r c C s t | dddkS )z)Check if the object is an abstractmethod.Ú__isabstractmethod__FT)rV )rD rA rA rB Úisabstractmethod- s r c C s& y | j jdkS tk
r dS X dS )z6Check if the object is a function or method in cython.Zcython_function_or_methodFN)Ú __class__Ú__name__ÚAttributeError)rD rA rA rB Ú is_cython_function_or_method2 s r c C s t j| rdS t| rt| }t|s8t|s8t j|r<dS t|rHdS t j|rVdS t |t
t t frjdS t
|jdkr|dS dS ndS dS )z4Check if the object is an attribute like descriptor.TFZinstancemethodN)r' Úisdatadescriptorr rF Ú
isfunctionÚ isbuiltinr r r rQ r r r Útyper )rD Z unwrappedrA rA rB Úisattributedescriptor: s$
r c C s6 t j| r.t| dr.t| dr.| jjdkr.dS dS dS )z/Check if the object is singledispatch function.ÚdispatchÚregisterÚ functoolsTFN)r' r rE r rl )rD rA rA rB Úis_singledispatch_functionY s
r c C s0 yddl m} t| |S tk
r* dS X dS )z-Check if the object is singledispatch method.r )ÚsingledispatchmethodFN)r r rQ Ú ImportError)rD r rA rA rB Úis_singledispatch_methodd s
r c C s t jt| S )z Check if the object is function.)r' r rO )rD rA rA rB r m s r c C s t jt| S )z Check if the object is builtin.)r' r rO )rD rA rA rB r r s r c C s t jt| S )z(Check is any kind of function or method.)r' rK rO )rD rA rA rB rK w s rK c C s< t tddd}t| |d} t| dr4tj| r4dS dS dS ) z*Check if the object is coroutine-function.)rD r" c S s2 t | st| st| r dS t| dr*dS dS dS )z2Check if the object is wrapped coroutine-function.FrI TN)rN rL rJ rE )rD rA rA rB Úiswrappedcoroutine~ s
z/iscoroutinefunction.<locals>.iswrappedcoroutine)rH Ú__code__TFN)r ÚboolrO rE r' Úiscoroutinefunction)rD r rA rA rB r | s
r c C s t | drtj| rdS dS dS )z*Check if the object is async-gen function.r TFN)rE r' Úisasyncgenfunction)rD rA rA rB r s r c C s. t jdkr$ddlm} t| |r$dS t| tS )z Check if the object is property.r é r )Úcached_propertyT)r r )ro rp r r rQ Úproperty)rD r rA rA rB Ú
isproperty s
r¢ c C sV t tdrt| tjrdS t tdr4t| tjr4dS t tdrNt| tjrNdS dS dS )z$Check if the object is GenericAlias.Ú
_GenericAliasTÚ GenericAliasÚ_SpecialGenericAliasFN)rE rn rQ r£ Útypesr¤ r¥ )rD rA rA rB Úisgenericalias¦ s
r§ )rD r. Údefargsr" c G sn yt | |f| S tk
rh } z<y
| j| S tk
r@ Y nX |rN|d S t||W Y dd}~X nX dS )z;A getattr() that turns all exceptions into AttributeErrors.r N)r Ú Exceptionra r )rD r. r¨ ÚexcrA rA rB rV µ s
rV )r| r" c sH t trNy t }W n tk
r* Y qøX fdd|D }ddj| S nªt try t }W n tk
rx Y qøX ddjdd |D S ndt trÚy t }W n tk
r¾ Y qøX ddjdd |D S n t tj rød j
j j f S y t
}W n* tk
r. } z t|W Y d d }~X nX tjd
|}|jd d S )
zFA repr() implementation that returns text safe to use in reST context.c 3 s& | ] }d t |t | f V qdS )z%s: %sN)Úobject_description)rS Úkey)r| rA rB rU Ó s z%object_description.<locals>.<genexpr>z{%s}z, c s s | ]}t |V qd S )N)r« )rS rr rA rA rB rU Ý s zfrozenset({%s})c s s | ]}t |V qd S )N)r« )rS rr rA rA rB rU ä s z%s.%sNÚ Ú
ú )rQ ri Úsortedr© ÚjoinÚsetrh Ú frozensetrt ru r r r. ÚreprrG Úmemory_address_reÚsubÚreplace)r| Z sorted_keysÚitemsZ
sorted_valuesÚsrª rA )r| rB r« Ë s:
r« )rD Ú attr_namer" c sl y"t | }t fdd|D }W n tk
r6 dS X yt|d}W n tk
rZ dS X tt|d|kS )zÿIf attr_name is implemented at builtin class, return True.
>>> is_builtin_class_method(int, '__init__')
True
Why this function needed? CPython implements int.__init__ by Descriptor
but PyPy implements it by pure Python code.
c 3 s" | ]} t |d i kr|V qdS )ra N)rV )rS Úc)rº rA rB rU þ s z*is_builtin_class_method.<locals>.<genexpr>Fr N)r` ÚnextÚ
StopIterationrV r r Úbuiltins)rD rº Úmrory r. rA )rº rB Úis_builtin_class_methodó s rÀ c @ s> e Zd ZdZeddddZeedddZed d
d Z dS ) Ú DefaultValuezKA simple wrapper for default value of the parameters of overload functions.N)Úvaluer" c C s
|| _ d S )N)r )Úselfr rA rA rB Ú__init__
s zDefaultValue.__init__)Úotherr" c C s
| j |kS )N)r )rà rÅ rA rA rB Ú__eq__ s zDefaultValue.__eq__)r" c C s | j S )N)r )rà rA rA rB Ú__repr__ s zDefaultValue.__repr__)
r rl rm Ú__doc__rR rÄ r| r rÆ rÇ rA rA rA rB rÁ
s rÁ c @ s> e Zd ZdZeddddZddddZeed d
d Z dS ) ÚTypeAliasForwardRefzPseudo typing class for autodoc_type_aliases.
This avoids the error on evaluating the type inside `get_type_hints()`.
N)r. r" c C s
|| _ d S )N)r. )rà r. rA rA rB rÄ s z TypeAliasForwardRef.__init__)r" c C s d S )NrA )rà rA rA rB Ú__call__ s z TypeAliasForwardRef.__call__)rÅ r" c C s
| j |kS )N)r. )rà rÅ rA rA rB rÆ # s zTypeAliasForwardRef.__eq__)
r rl rm rÈ rR rÄ rÊ r r rÆ rA rA rA rB rÉ s rÉ c @ s: e Zd ZdZeeeef ddddZeedddZdS ) ÚTypeAliasModulez-Pseudo module class for autodoc_type_aliases.N)ÚmodnameÚmappingr" c C s || _ || _d | _d S )N)Ú_TypeAliasModule__modnameÚ_TypeAliasModule__mappingÚ_TypeAliasModule__module)rà rÌ rÍ rA rA rB rÄ * s zTypeAliasModule.__init__)r. r" c s dj td | j|g}|| jkr.t| j| S |d fdd| jj D }|r\t||S yt|S tk
r | j d krt| j| _ t
| j |S X d S )NÚ.c s i | ]\}}|j r||qS rA )Ú
startswith)rS ÚkÚv)ÚprefixrA rB rg 7 s z/TypeAliasModule.__getattr__.<locals>.<dictcomp>) r± ÚfilterrÎ rÏ rÉ r¸ rË r r rÐ r )rà r. ÚfullnameÚnestedrA )rÕ rB Ú __getattr__0 s
zTypeAliasModule.__getattr__) r rl rm rÈ rR r rÄ r rÙ rA rA rA rB rË ' s rË c @ s8 e Zd ZdZeeef ddddZeedddZdS ) ÚTypeAliasNamespacez
Pseudo namespace class for autodoc_type_aliases.
This enables to look up nested modules and classes like `mod1.mod2.Class`.
N)rÍ r" c C s
|| _ d S )N)Ú _TypeAliasNamespace__mapping)rà rÍ rA rA rB rÄ N s zTypeAliasNamespace.__init__)r¬ r" c sN || j krt| j | S |d fdd| j j D }|rFt||S td S )NrÑ c s i | ]\}}|j r||qS rA )rÒ )rS rÓ rÔ )rÕ rA rB rg W s z2TypeAliasNamespace.__getitem__.<locals>.<dictcomp>)rÛ rÉ r¸ rË ÚKeyError)rà r¬ rØ rA )rÕ rB Ú __getitem__Q s
z TypeAliasNamespace.__getitem__) r rl rm rÈ r rR rÄ r rÝ rA rA rA rB rÚ H s rÚ )Úsubjectr" c C s. t | }|jddkr*|jdtjkr*dS dS )z<Check the function should be unwrapped on getting signature.r Ú
contextlibÚ__file__TF)r^ rc rß rà )rÞ r] rA rA rB Ú_should_unwrap_ s
rá F)rÞ Ú bound_methodÚfollow_wrappedÚ type_aliasesr" c C s |dkrd}nt jdtdd y^y&t| r6tj| }ntj| |d}W n tk
rd tj| }Y nX t|jj }|j
}W n, t k
r¨ t | dr¢g }t
j}n Y nX yt|}tj| d|}xHt|D ]<\} }
|
j|krÌ||
j } t| trø| j} |
j| d|| < qÌW d |kr:t|d tr2|d j}n|d }W n tk
rR Y nX |rtj| rhnt|d
kr|jd
tj||d d S )
z¸Return a Signature object for the given *subject*.
:param bound_method: Specify *subject* is a bound method or not
:param follow_wrapped: Same as ``inspect.signature()``.
NTzLThe follow_wrapped argument of sphinx.util.inspect.signature() is deprecatedr# )r$ )rã Ú_partialmethod)r6 r" r F)r) Ú__validate_parameters__) r% r& r rá r' r( rG rW r+ r, r) Ú
IndexErrorrE r r* rÚ rn Zget_type_hintsÚ enumerater. rQ rÉ r· r© r rd ÚpopÚ Signature) rÞ râ rã rä r( r+ r) Úlocalnsr> Úir@ r6 rA rA rB r( j sP
r( )r8 Úglobalnsrë r" c s° t tttddd ttttd fdd }|dkr8i }|dkrD|}t| jj }x8t|D ],\}}|jr\||j||}|j|d||< q\W | j }|r¢||||}| j||d S )
z;Evaluate unresolved type annotations in a signature object.)Úrefrí rë r" c S s* t jdkr| j||t S | j||S dS )z Evaluate a forward reference.r é N)r rï )ro rp Z _evaluater³ )rî rí rë rA rA rB Úevaluate_forwardref¶ s
z/evaluate_signature.<locals>.evaluate_forwardref)r6 rí rë r" c sz y\t | trZt| d} |||} t | tr: |||} n t | trZt| d} |||} W n ttfk
rt Y nX | S )z$Evaluate unresolved type annotation.T)rQ rR r Ú NameErrorrh )r6 rí rë rî )rð rA rB Úevaluate½ s
z$evaluate_signature.<locals>.evaluateN)r6 )r+ r) )
r r r rW r+ r, rè r6 r· r) ) r8 rí rë rò r+ rì r@ r6 r) rA )rð rB Úevaluate_signature³ s ró T)r8 Úshow_annotationÚshow_return_annotationÚunqualified_typehintsr" c
C s´ |r
d}nd}g }d}x2| j j D ]"}|j|jkrJ||jkrJ|jd |j|jkrr||j|jdfkrr|jd t }|j|jkr|j d|j
n*|j|j kr´|j d|j
n |j |j
|rì|j |j
k rì|j d |j t|j | |j|j
k r4|r|j |j
k r|j d n
|j d |j t|j |j|j |j}q$W |tjkrb|jd | jtj
ks|d
ks|d
krd d j| S t| j|} d
d j|| f S dS )aN Stringify a Signature object.
:param show_annotation: If enabled, show annotations on the signature
:param show_return_annotation: If enabled, show annotation of the return value
:param unqualified_typehints: If enabled, show annotations as unqualified
(ex. io.StringIO -> StringIO)
Zsmartzfully-qualifiedNú/Ú*z**z: z = ú=Fz(%s)z, z
(%s) -> %s)r+ r, r- r/ r0 r4 r1 r
r3 Úwriter. r5 r6 r* Ústringify_annotationr2 r« Úgetvaluer r) r± )
r8 rô rõ rö Úmoder9 Z last_kindr@ Úargr6 rA rA rB Ústringify_signatureâ sH
rÿ )r( r" c C s2 d| d }t j|}tt j|jd }t||S )z&Create a Signature object from string.zdef funcz: passr )r Úparser Ú FunctionDefÚbodyÚsignature_from_ast)r( ÚcodeÚmoduleÚfunctionrA rA rB Úsignature_from_str s
r r )Únoder r" c
C sL | j }t|j}g }t|dr8t|j}|t|j }nd}t|j }x$tt||D ]}|jdtj qVW t|drâxjt
|jD ]\\}} || tj kr tj }
nt t || |}
t | j
|pÂtj } |jt| jtj|
| d qW xvt
|j D ]h\}} ||| tj krtj }
nt t ||| |}
t | j
|p:tj } |jt| jtj|
| d qîW |jrt |jj
|pvtj } |jt|jjtj| d x^t
|jD ]P\}} t |j| |p¼tj }
t | j
|pÐtj } |jt| jtj|
| d qW |jr*t |jj
|ptj } |jt|jjtj| d t | j|p<tj } tj|| dS )z*Create a Signature object from AST *node*.Ú posonlyargsr )r2 r6 )r6 )r) ) r9 rW r= rE rd r ÚrangeÚinsertr r* rè rÁ Ú ast_unparser6 r0 rþ r/ r1 Úvarargr3 r< Ú kw_defaultsr4 Úkwargr5 Zreturnsr' rê )
r r r9 r= Úparamsr Ú positionalsÚ_rì rþ r2 r6 r) rA rA rB r ( sP
r )rD Ú
attrgetterÚallow_inheritedry r. r" c C sN t ftttt ddd}|rv|rvt| ||rvxFt|D ]:}|jj|}|r8t |dr8t
|j }|dk sn| r8|S q8W || }t | r|| j
jkrt
| jS |dko¦|rJ|o°|r6x6t|D ]*}t ||d}|dk r¾||}|dk r¾P q¾W |dkr6x>t|D ]2}t ||d}|dk r tj
|}|dk r P q W |dkrJtj
| }|S )zÊGet the docstring for the object.
This tries to obtain the docstring for some kind of objects additionally:
* partial functions
* inherited docstring
* inherited decorated methods
)rD r r" c S s" || dd }t |tr|S d S d S )NrÈ )rQ rR )rD r ÚdocrA rA rB Úgetdoc_internalk s
z getdoc.<locals>.getdoc_internalrM N)rV r r
r rR rL r` ra rc rE ÚgetdocrM rJ r rÈ r! r' ) rD r r ry r. r r~ r r rA rA rB r a s:
r )r r )NN)NN)NN)TTF)r )krÈ r¾ rß rt r' Úrero r¦ rn r% r r r Ú importlibr r r r r r Úior
r r r
r r r r r r r Zsphinx.deprecationr Zsphinx.pycode.astr r r Z sphinx.utilr Zsphinx.util.typingr r rû rp r r r r r| rÄ rR r± ri ra Ú getLoggerr ÚloggerÚcompileÚ
IGNORECASErµ rC rF rO rZ r\ r^ r` re rj r rq rv rw rx rJ rL rN r r r r r r r r rK r r r¢ r§ rV r« rÀ rÁ rÉ rË rÚ rá rê r( ró rÿ r r r r rA rA rA rB Ú<module> s ,
6
(
! H
. ; 9