3
T'íc{i ã
@ s¶ d Z ddlZddlZddlZddlZddlZddlZddlm Z ddl
m Z ddl m
Z
mZmZmZmZmZmZ ddlmZmZ ddlmZ ddlmZmZm Z m Z dd l m Z m Z ddl!Z!dd
l"m#Z# dd l$m%Z% dd l&m'Z' dd
l(m)Z) ddl*m+Z+ ddl,m-Z- ddl.m/Z/ ddl0m1Z1m2Z2 ddl3m4Z4 ddl5m6Z6m7Z7 ddl8m9Z9m:Z: ddl;m<Z< ddl=m>Z>m?Z?m@Z@ e6jAeBZCG dd dZDeEeEdddZFdYeEe)e
d d d ZGeEeEdd d ZHe%eEeed!d"d#ZIeEeEeeeeJeKd$d%d&ZLe%dd'd(d)ZMe+eeE e?e#e ed*d+d,ZNeeE e>e+eeE eEe#e ee d-d.d/ZOe-eeE e>eKe+eeE e#e ee d0 d1d2ZPe-eeE e>eKe#e ee d3d4d5ZQe-eEeKd6d7d8ZRe-eEe#e ee d9d:d;ZSe-eKe#e ee d<d=d>ZTe-e#e ee d?d@dAZUe%e-e#e ee dBdCdDZVG dEdF dFe9ZWG dGdH dHe:ZXG dIdJ dJe4ZYe%eEeeE ddKdLdMZZe%e)ddNdOdPZ[e%eeEef d'dQdRZ\eeE ddSdTdUZ]eBdVkr²ddl6Z^e^j_ e]ej`dWd
dX dS )Zaå Insert links to objects documented in remote Sphinx documentation.
This works as follows:
* Each Sphinx HTML build creates a file named "objects.inv" that contains a
mapping from object names to URIs relative to the HTML set's root.
* Projects using the Intersphinx extension can specify links to such mapping
files in the `intersphinx_mapping` config value. The mapping will then be
used to resolve otherwise missing references to objects into links to the
other documentation.
* By default, the mapping file is assumed to be at the same location as the
rest of the documentation; however, the location of the mapping file can
also be specified individually, e.g. if the docs should be buildable
without Internet access.
é N)Úpath)Ú
ModuleType)ÚIOÚAnyÚDictÚListÚOptionalÚTupleÚcast)ÚurlsplitÚ
urlunsplit)Únodes)ÚElementÚNodeÚ TextElementÚsystem_message)ÚReporterÚ
relative_path)Ú pending_xref)ÚSphinx)ÚINVENTORY_FILENAME)ÚConfig)ÚDomain)ÚBuildEnvironment)ÚExtensionError)Ú_Ú__)ÚReferencesResolver)ÚloggingÚrequests)ÚCustomReSTDispatcherÚ
SphinxRole)Ú
InventoryFile)Ú InventoryÚ
InventoryItemÚ RoleFunctionc @ s~ e Zd ZdZeddddZeeee ee
e f f dddZ ee dd d
Z
eeee f dd d Zddd
dZdS )ÚInventoryAdapterz!Inventory adapter for environmentN)ÚenvÚreturnc C s, || _ t|ds(i | j _i | j _i | j _d S )NÚintersphinx_cache)r' Úhasattrr) Úintersphinx_inventoryÚintersphinx_named_inventory)Úselfr' © r. ú8/tmp/pip-build-gk9425m9/sphinx/sphinx/ext/intersphinx.pyÚ__init__7 s
zInventoryAdapter.__init__)r( c C s | j jS )N)r' r) )r- r. r. r/ Úcache? s zInventoryAdapter.cachec C s | j jS )N)r' r+ )r- r. r. r/ Úmain_inventoryC s z InventoryAdapter.main_inventoryc C s | j jS )N)r' r, )r- r. r. r/ Únamed_inventoryG s z InventoryAdapter.named_inventoryc C s | j jj | j jj d S )N)r' r+ Úclearr, )r- r. r. r/ r4 K s zInventoryAdapter.clear)Ú__name__Ú
__module__Ú __qualname__Ú__doc__r r0 Úpropertyr Ústrr Úintr# r1 r2 r3 r4 r. r. r. r/ r& 4 s "r& )Úurlr( c C s6 t t| }d|d kr.|d jdd |d< t|S )a¨ Returns *url* with basic auth credentials removed. Also returns the
basic auth username and password if they're present in *url*.
E.g.: https://user:pass@example.com => https://example.com
*url* need not include basic auth credentials.
:param url: url which may or may not contain basic auth credentials
:type url: ``str``
:return: *url* with any basic auth creds removed
:rtype: ``str``
ú@é )Úlistr Úsplitr )r< Úfragsr. r. r/ Ú_strip_basic_authP s rB )r< Úconfigr( c C sB t j| d||jd}|j |j|j_tj|jjdd|j_|jS )u¢ Reads data from *url* with an HTTP *GET*.
This function supports fetching from resources which use basic HTTP auth as
laid out by RFC1738 § 3.1. See § 5 for grammar definitions for URLs.
.. seealso:
https://www.ietf.org/rfc/rfc1738.txt
:param url: URL of an HTTP resource
:type url: ``str``
:return: data read from resource described by *url*
:rtype: ``file``-like object
T)ÚstreamrC Útimeout)Údecode_content) r ÚgetÚintersphinx_timeoutÚraise_for_statusr< ÚrawÚ functoolsÚpartialÚread)r< rC Úrr. r. r/ Ú_read_from_urle s
rO c C s^ t | }|jdkr| S t|}|jr>dj|j|j|j|d< ndj|j|j|d< t|S dS )a5 Gets version of *url* with basic auth passwords obscured. This function
returns results suitable for printing and logging.
E.g.: https://user:12345@example.com => https://user@example.com
:param url: a url
:type url: ``str``
:return: *url* with password removed
:rtype: ``str``
Nz{}@{}:{}r> z{}@{})r Úusernamer? ÚportÚformatÚhostnamer )r< ÚpartsrA r. r. r/ Ú
_get_safe_url~ s
rU )ÚappÚuriÚinvr( c
+ C s d|k}|st |}y0d|kr.t|| jd}nttj| j|d}W n8 tk
r| } z d||jt |f|_
W Y dd}~X nX y¼t |drÒ|j }||krÒt
jtd|| ||tj|tj|d fkrÒtj|}|\ y"|rätjntj}tj|||}W n2 tk
r, } ztd | | W Y dd} ~ X nX W dQ R X W n< tk
rv } z d
||jjt |f|_
W Y dd}~X nX |S dS ) z6Fetch, parse and return an intersphinx inventory file.z://)rC Úrbz4intersphinx inventory %r not fetchable due to %s: %sNr< z)intersphinx inventory has moved: %s -> %sú/z,unknown or unsupported inventory version: %rz3intersphinx inventory %r not readable due to %s: %s)rB rO rC Úopenr ÚjoinÚsrcdirÚ ExceptionÚ __class__r: Úargsr* r< ÚloggerÚinfor ÚdirnameÚ posixpathr" ÚloadÚ
ValueErrorr5 )
rV rW rX ZlocaluriÚfÚerrZnewinvr\ ÚinvdataÚexcr. r. r/ Úfetch_inventory s:
.rk )ÚnamerW Úinvsr1 rV Únowr( c C s< ||j jd }g }z²x¬|D ]¤}|s0tj|t}d|ksP||ksP|| d |k r t|} tjtd| yt |||}
W n0 t
k
r¨ } z|j | j w W Y d d } ~ X nX |
r | ||
f||< dS q W dS |g krÒndt
|t
|k r tjtd xB|D ]} tj| qøW n*djd d
|D }
tjtd d |
X d S ) NiQ z://r> z(loading intersphinx inventory from %s...TFzXencountered some issues with some of the inventories, but they had working alternatives:Ú
c S s g | ]}|d |dd
qS )r r> Nr. )Ú.0rg r. r. r/ ú
<listcomp>Þ s z)fetch_inventory_group.<locals>.<listcomp>zAfailed to reach any of the inventories with the following issues:)rC Úintersphinx_cache_limitrd r\ r rU ra rb r rk r^ Úappendr` ÚlenÚwarning)rl rW rm r1 rV rn Z
cache_timeZfailuresrX Z safe_inv_urlri rh ZfailZissuesr. r. r/ Úfetch_inventory_group¾ s6
rv )rV r( c C s t tj }t| jj}tjj \}g }x:| jj j
D ]*\}\}}|j |j t
||||j| | q6W dd tjj|D }W dQ R X t|r|j t|jj
} tdd | D }
dd | D } xN|
| D ]B\}} }
|ræ|
|j|< x(|
j D ] \}}|jj|i j| qðW qÎW dS )z3Load all intersphinx mappings into the environment.c S s g | ] }|j qS r. )Úresult)rp rg r. r. r/ rq î s z!load_mappings.<locals>.<listcomp>Nc s s | ]}|d r|V qdS )r Nr. )rp Úvr. r. r/ ú <genexpr>û s z load_mappings.<locals>.<genexpr>c S s g | ]}|d s|qS )r r. )rp rx r. r. r/ rq ü s )r; Útimer& Zbuilderr' Ú
concurrentÚfuturesZThreadPoolExecutorrC Úintersphinx_mappingÚvaluesrs Zsubmitrv r1 Z as_completedÚanyr4 r? Úsortedr3 Úitemsr2 Ú
setdefaultÚupdate)rV rn Z inventoriesÚpoolr| rl rW rm ÚupdatedZ cached_valsZ
named_valsZ unnamed_valsÚ_xri ÚtypeZobjectsr. r. r/ Ú
load_mappingsã s$
r )ÚdomainÚinv_nameÚdataÚnodeÚcontnoder( c C s |\}}}}d|kr4|j dr4tjt|d d|}|rJtd||f } ntd|f } tjddd|| d}
|j d r|
j| n|d
ks | jd krþ|d d
krþ|j } |d k rò| j
|d rò|
j|j | t |d d
| t |d d
n
|
j| n|
j|j || |
S )Nz://ZrefdocÚ.z (in %s v%s)z(in %s)Ú F)ZinternalZrefuriÚreftitleZ refexplicitú-ÚstdÚreftypeÚkeywordú:r> )
rG r r\ r r r
Ú referencers rl ZastextÚ
startswithr_ rt ) r r r r r ÚprojÚversionrW Zdispnamer ÚnewnodeÚtitler. r. r/ Ú_create_element_from_result s$
r )r Ú inventoryr ÚobjtypesÚtargetr r r( c
s x|D ]}||krq||| kr.|| | }nJ|dkr|j tt fdd|| j } | r|| | d }qxqnqt|| |||S W d S )Nzstd:termc s | j kS )N)Úlower)Úk)Ú target_lowerr. r/ Ú<lambda>2 s z8_resolve_reference_in_domain_by_target.<locals>.<lambda>r )r r? ÚfilterÚkeysr )
r r r r r r r Zobjtyper Zinsensitive_matchesr. )r¢ r/ Ú&_resolve_reference_in_domain_by_target" s
r¦ ) r' r r Úhonor_disabled_refsr r r r r( c
s¶ j dkr d|kr |jd j dkr8d|kr8|jd fdd|D }|rh| jj fd d|D }t||||d
||}|d k r|S j|} | d kr¢d S t|||| ||S ) Nr Z cmdoptionÚoptionÚpyÚ attributeÚmethodc s g | ]}d j j|qS )z{}:{})rR rl )rp Út)r r. r/ rq Q s z0_resolve_reference_in_domain.<locals>.<listcomp>c s g | ]}| kr|qS r. r. )rp Úo)Údisabledr. r/ rq V s Ú reftarget)rl rs rC Ú intersphinx_disabled_reftypesr¦ Zget_full_qualified_name)
r' r r r§ r r r r ÚresZfull_qualified_namer. )r® r r/ Ú _resolve_reference_in_domainB s"
r² )r' r r r§ r r r( c
C sî |o
|d k}|r d| j jkr d S |d }|dkrxX| jj D ]J\}}|rZ|d | j jkrZq<t|j} t| ||||| ||}
|
d k r<|
S q<W d S |jd}|s d S |r¸|d | j jkr¸d S | j|}|j |} | sÔd S t| ||||| ||S d S )NÚ*r r z:*Ú refdomain)
rC r° Údomainsr r? Z object_typesr² rG Ú
get_domainZobjtypes_for_role) r' r r r§ r r ÚtypÚ domain_namer r r± r. r. r/ Ú_resolve_referencef s>
r¹ )r' r r( c C s |t | jkS )N)r& r3 )r' r r. r. r/ Úinventory_exists s rº )r' r r r r( c C s* t | |stt| |t| j| d||S )zÁAttempt to resolve a missing reference via intersphinx references.
Resolution is tried in the given inventory with the target as is.
Requires ``inventory_exists(env, inv_name)``.
F)rº ÚAssertionErrorr¹ r& r3 )r' r r r r. r. r/ Ú resolve_reference_in_inventory s
r¼ )r' r§ r r r( c C s t | dt| j|||S )zAttempt to resolve a missing reference via intersphinx references.
Resolution is tried with the target as is in any inventory.
N)r¹ r& r2 )r' r§ r r r. r. r/ Ú resolve_reference_any_inventory¢ s r½ )r' r r r( c C sn t | d||}|dk r|S |d }d|kr.dS |jdd\}}t| |sLdS ||d< t| |||}||d< |S )ag Attempt to resolve a missing reference via intersphinx references.
Resolution is tried first with the target as is in any inventory.
If this does not succeed, then the target is split by the first ``:``,
to form ``inv_name:newtarget``. If ``inv_name`` is a named inventory, then resolution
is tried in that inventory with the new target.
TNr¯ r r> )r½ r@ rº r¼ )r' r r r± r r Z newtargetZres_invr. r. r/ Ú"resolve_reference_detect_inventory¯ s
r¾ )rV r' r r r( c C s t |||S )zBAttempt to resolve a missing reference via intersphinx references.)r¾ )rV r' r r r. r. r/ Úmissing_referenceÌ s r¿ c s: e Zd ZdZeeeeee e
e f d fdd Z Z
S )ÚIntersphinxDispatcherzyCustom dispatcher for external role.
This enables :external:***:/:external+***: roles on parsing reST document.
)Ú role_nameÚlanguage_moduleÚlinenoÚreporterr( c s8 t |dkr"|jdr"t|g fS t j||||S d S )Né ú external:ú external+)rÆ rÇ )rt r ÚIntersphinxRoleÚsuperÚrole)r- rÁ r rà rÄ )r_ r. r/ rÊ Ù s zIntersphinxDispatcher.role)r5 r6 r7 r8 r: r r; r r r% r r rÊ Ú
__classcell__r. r. )r_ r/ rÀ Ó s rÀ c @ s¶ e Zd ZejdZeddddZee e
e e f dddZ eee
e ef d d
d Zee
eeef d d d
ZeeedddZeeef ee e
e e f dddZdS )rÈ z(\+([^:]+))?:(.*)N)Ú orig_namer( c C s
|| _ d S )N)rÌ )r- rÌ r. r. r/ r0 ç s zIntersphinxRole.__init__)r( c C sÒ | j | jj kst| j| j\}}|r\t| j| r\tjt d|| jj
| j fd g g fS | j |}|d krtjt d|| jj
| j fd g g fS | j
|\}}x&|D ] }t|tr¨d|d< ||d< q¨W ||fS )Nz4inventory for external cross-reference not found: %s)Úlocationz/role for external cross-reference not found: %sTÚ intersphinxr )rl rÌ r r» Ú get_inventory_and_name_suffixrº r' ra ru r Údocnamerà Ú
get_role_nameÚ invoke_roleÚ
isinstancer )r- r Z name_suffixrÁ rw Úmessagesr r. r. r/ Úrunê s"
zIntersphinxRole.run)rl r( c C sH |j dst||d dks&t|tjj|djdd\}}||fS )NZexternalé z:+é é )r r» rÈ Ú _re_inv_refÚ fullmatchÚgroup)r- rl rX Úsuffixr. r. r/ rÏ s z-IntersphinxRole.get_inventory_and_name_suffixc C s |j d}t|dkr<| jjjd}|r.|jnd }|d }n"t|dkrZ|d }|d }nd S |rv| j||rv||fS | jd|rd|fS d S d S )Nr r> Údefault_domainr r× r )r@ rt r' Z temp_datarG rl Úis_existent_role)r- rl ÚnamesrÝ r rÊ r. r. r/ rÑ s
z IntersphinxRole.get_role_name)r¸ rÁ r( c C s< y"| j j|}||jkr dS dS W n tk
r6 dS X d S )NTF)r' r¶ Zrolesr )r- r¸ rÁ r r. r. r/ rÞ ! s
z IntersphinxRole.is_existent_role)rÊ r( c C sT | j j|d }|rH|j|d }|dj|| j| j| j| j| j| j S g g fS d S )Nr r> r )
r' r¶ rÊ r\ ZrawtextÚtextrà ZinlinerÚoptionsÚcontent)r- rÊ r Z role_funcr. r. r/ rÒ + s zIntersphinxRole.invoke_role)r5 r6 r7 ÚreÚcompilerÙ r: r0 r r r r rÕ r rÏ rÑ ÚboolrÞ rÒ r. r. r. r/ rÈ á s
rÈ c @ s* e Zd ZdZejd ZeddddZdS )ÚIntersphinxRoleResolverzpending_xref node resolver for intersphinx role.
This resolves pending_xref nodes generated by :intersphinx:***: role.
r> N)Úkwargsr( c K sÌ xÆ| j jtD ]¶}d|kr qttj|d j }|d }|d k rbt| j|sPt t
| j|||}nt | jd||}|d krº|d }t d|d ||d f }t
j||d |d
|j| q|j| qW d S ) NrÎ r r Fr z-external %s:%s reference target not found: %sr´ r¯ Úref)rÍ r Úsubtype)ÚdocumentZtraverser r
r
r Údeepcopyrº r' r» r¼ r½ r ra ru Z replace_self)r- rç r r r r r· Úmsgr. r. r/ rÕ > s zIntersphinxRoleResolver.run)r5 r6 r7 r8 r Zdefault_priorityr rÕ r. r. r. r/ ræ 6 s
ræ )rV rÐ Úsourcer( c C s t }|j dS )zEnable IntersphinxDispatcher.
.. note:: The installed dispatcher will uninstalled on disabling sphinx_domain
automatically.
N)rÀ Úenable)rV rÐ rí Z
dispatcherr. r. r/ Úinstall_dispatcherS s rï )rV rC r( c C sî xè|j j j D ]Ö\}}yt|ttfr`|| }\}}t|tsptjt d| |j j
| wnd || }}}t|ts|||fff|j |< n|||ff|j |< W q t k
rä } z$tjt d|| |j j
| W Y d d }~X qX qW d S )Nz0intersphinx identifier %r is not string. Ignoredz3Failed to read intersphinx_mapping[%s], ignored: %r) r} Úcopyr rÓ r? Útupler: ra ru r Úpopr^ )rV rC ÚkeyÚvaluerl rW rX rj r. r. r/ Ú normalize_intersphinx_mapping] s
rõ c C s | j di d | j ddd | j dd d | j dg d | jdtd d
| jd t | jd t | jd
t | jt tj dddS )Nr} Trr é FrH r° z
config-initedi )Úpriorityzbuilder-initedz source-readzmissing-referencer> )r Z env_versionZparallel_read_safe)
Zadd_config_valueÚconnectrõ r rï r¿ Zadd_post_transformræ ÚsphinxZ__display_version__)rV r. r. r/ Úsetupu s
rú )Úargvr( c s< t | dk r$tdtjd tjd G dd d G fddd}y| d }t| d |}xht|pfi D ]X}t| xJt|| j D ]6\}}td
||d d kr®d
|d nd |d f qW qjW W nn tk
r } z"t|j d |j dd
W Y dd}~X n0 t
k
r6 } ztd| W Y dd}~X nX dS )z-Debug functionality to print out an inventoryr> zXPrint out an inventory file.
Error: must specify local path or URL to an inventory file.)Úfilec @ s e Zd ZU dZedZdZdS )z inspect_main.<locals>.MockConfigNF)r5 r6 r7 rH r; Z
tls_verifyÚ
user_agentr. r. r. r/ Ú
MockConfig s
rþ c s& e Zd ZdZ ZeddddZdS )z inspect_main.<locals>.MockAppr N)rì r( c S s t |tjd d S )N)rü )ÚprintÚsysÚstderr)r- rì r. r. r/ Úwarn s z"inspect_main.<locals>.MockApp.warn)r5 r6 r7 r] rC r: r r. )rþ r. r/ ÚMockApp s r r r z %-40s %s%srØ r z%-40s: r× NzUnknown error: %r) rt rÿ r r Úexitrk r r rf r` r^ )rû r Úfilenameri ró ÚentryZeinforj r. )rþ r/ Ú inspect_main s&
,r Ú__main__r> )rû )N)ar8 Úconcurrent.futuresr{ rK rd rã r rz Úosr Útypesr Útypingr r r r r r r
Ú urllib.parser r Zdocutilsr
Zdocutils.nodesr r r r Zdocutils.utilsr r rù Zsphinx.addnodesr Zsphinx.applicationr Zsphinx.builders.htmlr Z
sphinx.configr Zsphinx.domainsr Zsphinx.environmentr Z
sphinx.errorsr Z
sphinx.localer r Z!sphinx.transforms.post_transformsr Z sphinx.utilr r Zsphinx.util.docutilsr r! Zsphinx.util.inventoryr" Zsphinx.util.typingr# r$ r% Ú getLoggerr5 ra r& r: rB rO rU rk Úfloatrå rv r r r¦ r² r¹ rº r¼ r½ r¾ r¿ rÀ rÈ ræ rï rõ rú r Z_loggingÚ basicConfigrû r. r. r. r/ Ú<module> s $
( #!
'
U
#