U \Shp @sdZddlmZddlZddlZddlZddlZddlZddl Z ddl m Z ddl m Z mZmZmZmZddlmZmZddlmZddlmZddlZdd lmZdd lmZdd lmZdd l m!Z!m"Z"dd l#m$Z$ddl%m&Z&m'Z'ddl(m)Z)m*Z*ddl+m,Z,erddl-m.Z.ddl m/Z/m0Z0ddl1m2Z2m3Z3m4Z4ddlm5Z5ddl6m7Z7ddl8m9Z9ddl:m;Z;ddlm?Z?m@Z@mAZAe/e0eBdfeCe?fZDe&EeFZGGdddZHdddddZIdrdd d!d"d#d$ZJdddd%d&ZKd'ddd(d)d*d+ZLd,dd-d.d'd/d0d1d2d3ZMd'd4d5d6d7ZNd8d,d9d:d;dd?ZOd,d(d8d@dd:d;dAdBdCdDZPdEd,d(d0d8d@d:d;dAdF dGdHZQdEd,d(d0d:d;dAdIdJdKZRdEdd0dLdMdNZSdEdd:d;dAdOdPdQZTdEd0d:d;dAdRdSdTZUdEd:d;dAdUdVdWZVd'dEd:d;dAdXdYdZZWGd[d\d\e)ZXGd]d^d^e*ZYGd_d`d`e$ZZd'ddad4dbdcddZ[d'ded4dfdgdhZ\d'did5djdkZ]dad4dldmdnZ^eFdokrddl&Z_e_`e^ejadpddqdS)saInsert 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. ) annotationsN)path)IO TYPE_CHECKINGAnyIterablecast)urlsplit urlunsplit)nodes) relative_path) pending_xref)INVENTORY_FILENAME)ExtensionError)___)ReferencesResolver)loggingrequests)CustomReSTDispatcher SphinxRole) InventoryFile) ModuleType)TupleUnion)Node TextElementsystem_message)Reporter)Sphinx)Config)Domain)BuildEnvironment) Inventory InventoryItem RoleFunctionc@sdeZdZdZdddddZeddd d Zed dd d ZeddddZddddZ dS)InventoryAdapterz!Inventory adapter for environmentr"None)envreturncCs,||_t|ds(i|j_i|j_i|j_dS)Nintersphinx_cache)r(hasattrr*intersphinx_inventoryintersphinx_named_inventory)selfr(r/I/root/rtd-docs/venv/lib/python3.8/site-packages/sphinx/ext/intersphinx.py__init__As  zInventoryAdapter.__init__dict[str, InventoryCacheEntry]r)cCs|jjS)aAIntersphinx cache. - Key is the URI of the remote inventory - Element one is the key given in the Sphinx intersphinx_mapping configuration value - Element two is a time value for cache invalidation, a float - Element three is the loaded remote inventory, type Inventory )r(r*r.r/r/r0cacheKs zInventoryAdapter.cacher#cCs|jjSN)r(r,r4r/r/r0main_inventoryWszInventoryAdapter.main_inventoryzdict[str, Inventory]cCs|jjSr6)r(r-r4r/r/r0named_inventory[sz InventoryAdapter.named_inventorycCs|jj|jjdSr6)r(r,clearr-r4r/r/r0r9_s zInventoryAdapter.clearN) __name__ __module__ __qualname____doc__r1propertyr5r7r8r9r/r/r/r0r&>s  r&str)urlr)cCs6tt|}d|dkr.|ddd|d<t|S)aReturns *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/r0_strip_basic_authds  rFz Config | Noner)r@configr)cCsNtj|d|j|j|j|jfd}||j|j_t j |jj dd|j_ |jS)uReads 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)streamtimeoutZ _user_agentZ _tls_info)decode_content) rgetintersphinx_timeout user_agent tls_verify tls_cacertsraise_for_statusr@raw functoolspartialread)r@rGrr/r/r0_read_from_urlys   rVcCsft|}|jdkr|St|}|jrD|jd|jd|j|d<n|jd|j|d<t|SdS)a5Gets 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`` NrA:rB)r usernamerCporthostnamer )r@partsrEr/r/r0 _get_safe_urls   r\rr#)appuriinvr)c Csd|k}|st|}z0d|kr.t||jd}ntt|j|d}Wn8tk r|}zd||jt |f|_ W5d}~XYnXzt |dr|j }||krt td||||t|t|dfkrt|}|\z"|rtjntj}t|||}Wn2tk r,} ztd | | W5d} ~ XYnXW5QRXWn<tk rv}zd ||jjt |f|_ W5d}~XYnX|SdS) z6Fetch, parse and return an intersphinx inventory file.://)rGrbz4intersphinx 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)rFrVrGopenrjoinsrcdir Exception __class__r?argsr+r@loggerinfordirname posixpathrload ValueErrorr:) r]r^r_ZlocaluriferrZnewinvrdinvdataexcr/r/r0fetch_inventorysF  .rsz str | Noneztuple[str | None, ...]r2intbool)namer^invsr5r]nowr)c CsF||jjd}g}z|D]} | s.t|t } d| ksN||ksN||d|krt | } ttd | zt ||| } Wn6t k r} z| | jWYqW5d} ~ XYnX| r||| f||<Wd SqWd S|gkrnbt|t|krttd|D]}tj|qn*ddd|D} ttdd| XdS) NiQzXencountered some issues with some of the inventories, but they had working alternatives: cSs g|]}|d|ddqS)rrBNr/.0ror/r/r0 sz)fetch_inventory_group..zAfailed to reach any of the inventories with the following issues:r`rBz(loading intersphinx inventory from %s...TF)rGintersphinx_cache_limitlenrirjrrdwarningrlrr\rsrfappendrh)rvr^rwr5r]rxZ cache_timeZfailuresZfailZissuesr_Z safe_inv_urlrqrpr/r/r0fetch_inventory_groups<     rr')r]r)c Cs"tt}t|jj}|j}tjV}g}|j j D](\}\}}| | t||||||q:ddtj|D} W5QRXt| r|g} g} | D],\}} } |r| || fq| || fqt| | D]<\}} |r| |j|<| D]\}}|j|i|qqdS)z3Load all intersphinx mappings into the environment.cSsg|] }|qSr/)resultrzr/r/r0r| sz!load_mappings..N)rttimer&Zbuilderr(r5 concurrentfuturesZThreadPoolExecutorrGintersphinx_mappingvaluesrZsubmitrZ as_completedanyr9sortedr8itemsr7 setdefaultupdate)r]rxZ inventoriesr*poolrrvr^rwupdatedZ named_valsZ unnamed_valsZ_expiryrqtypeobjectsr/r/r0 load_mappingss:       rr!r$r rznodes.reference)domaininv_namedatanodecontnoder)c Cs|\}}}}d|kr4|dr4tt|dd|}|rJtd||f} ntd|f} tjddd|| d} |d r| |n|d ks|jd kr|d d kr| } |dk r| |dr| | | t |dd| t |ddn | |n| | ||| S)Nr`Zrefdoc.z (in %s v%s)z(in %s)F)ZinternalZrefurireftitleZ refexplicit-stdreftypekeywordrWrB) rKrrdr rr referencerrvZastext startswithrgr~) rrrrrZprojversionr^Zdispnamernewnodetitler/r/r0_create_element_from_result's,     rz Iterable[str]znodes.reference | None)r inventoryrobjtypestargetrrr)c s|D]}||krq|||kr,|||}nJ|dkr|ttfdd||} | r||| d}qvqnqt|||||SdS)Nzstd:termcs |kSr6)lower)kZ target_lowerr/r0Uz8_resolve_reference_in_domain_by_target..r)rrCfilterkeysr) rrrrrrrobjtyperZinsensitive_matchesr/rr0&_resolve_reference_in_domain_by_targetEs   rr") r(rrhonor_disabled_refsrrrrr)c si|}|jdkr$d|kr$d|d<|jdkr>d|kr>d|d<|jfdd|D}|rxt|jjfd d|D}|}t|||||d ||} | dk r| S||} | dkrdSt||||| ||S) NrZ cmdoptionoptionpy attributemethodcsi|]}d|dqS)rWNr/r{obj_type) domain_namer/r0 ws z0_resolve_reference_in_domain..csi|]}|kr|dqSr6r/r)disabledr/r0r|s reftarget)fromkeysrvsetrGintersphinx_disabled_reftypesrrZget_full_qualified_name) r(rrrrrrrZ obj_typesresZfull_qualified_namer/)rrr0_resolve_reference_in_domaines8       r)r(rrrrrr)c Cs|o |dk}|r d|jjkr dS|d}|dkr|jD]N\}}|rX|d|jjkrXq:|j} t|||||| ||} | dk r:| Sq:dS|d}|sdS|r|d|jjkrdS||}| |} | sdSt|||||| ||SdS)N*rrz:* refdomain) rGrdomainsrZ object_typesrrrK get_domainZobjtypes_for_role) r(rrrrrtyprrrrr/r/r0_resolve_referencesN      r)r(rr)cCs|t|jkSr6)r&r8)r(rr/r/r0inventory_existssr)r(rrrr)cCs*t||stt||t|j|d||S)zAttempt 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)rAssertionErrorrr&r8)r(rrrr/r/r0resolve_reference_in_inventorys r)r(rrrr)cCst|dt|j|||S)zAttempt to resolve a missing reference via intersphinx references. Resolution is tried with the target as is in any inventory. N)rr&r7)r(rrrr/r/r0resolve_reference_any_inventorys r)r(rrr)cCsnt|d||}|dk r|S|d}d|kr.dS|dd\}}t||sLdS||d<t||||}||d<|S)agAttempt 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. TNrrWrB)rrDrr)r(rrrrrZ newtargetZres_invr/r/r0"resolve_reference_detect_inventorys  r)r]r(rrr)cCs t|||S)zBAttempt to resolve a missing reference via intersphinx references.)r)r]r(rrr/r/r0missing_referencesrcs.eZdZdZddddddfdd ZZS) IntersphinxDispatcherzyCustom dispatcher for external role. This enables :external:***:/:external+***: roles on parsing reST document. r?rrtrz)tuple[RoleFunction, list[system_message]]) role_namelanguage_modulelinenoreporterr)cs8t|dkr"|dr"t|gfSt||||SdS)N )z external:z external+)r~rIntersphinxRolesuperrole)r.rrrrrgr/r0rs zIntersphinxDispatcher.role)r:r;r<r=r __classcell__r/r/rr0rsrc@sveZdZedZdddddZddd d Zdd d d dZddd ddZ ddddddZ dddddZ dS)rz(\+([^:]+))?:(.*)r?r') orig_namer)cCs ||_dSr6)r)r.rr/r/r0r1szIntersphinxRole.__init__z'tuple[list[Node], list[system_message]]r3cCs|j|jkst||j\}}|rZt|j|sZtjt d||jj |j fdggfS| |}|dkrtjt d||jj |j fdggfS| |\}}|D]}t|trd|d<||d<q||fS)Nz4inventory for external cross-reference not found: %s)locationz/role for external cross-reference not found: %sT intersphinxr)rvrrrget_inventory_and_name_suffixrr(rirrdocnamer get_role_name invoke_role isinstancer )r.rZ name_suffixrrmessagesrr/r/r0runs(       zIntersphinxRole.runztuple[str | None, str])rvr)cCsH|dst||ddks&t|tj|ddd\}}||fS)NZexternalz:+)rrr _re_inv_ref fullmatchgroup)r.rvr_suffixr/r/r0r+sz-IntersphinxRole.get_inventory_and_name_suffixztuple[str, str] | NonecCs|d}t|dkr<|jjd}|r.|jnd}|d}n"t|dkrZ|d}|d}ndS|rv|||rv||fS|d|rd|fSdSdS)NrWrBdefault_domainrrr)rDr~r(Z temp_datarKrvis_existent_role)r.rvnamesrrrr/r/r0r7s      zIntersphinxRole.get_role_nameru)rrr)cCs4z|j|}||jkWStk r.YdSXdS)NF)r(rZrolesr)r.rrrr/r/r0rLs   z IntersphinxRole.is_existent_roleztuple[str, str])rr)cCsT|j|d}|rH||d}|d||j|j|j|j|j|j SggfSdS)NrrBrW) r(rrrdZrawtexttextrZinlineroptionscontent)r.rrZ role_funcr/r/r0rSszIntersphinxRole.invoke_roleN) r:r;r<recompilerr1rrrrrr/r/r/r0r s  rc@s*eZdZdZejdZdddddZdS) IntersphinxRoleResolverzpending_xref node resolver for intersphinx role. This resolves pending_xref nodes generated by :intersphinx:***: role. rBrr')kwargsr)cKs|jtD]}d|krq ttj|d}|d}|dk r`t|j|sNt t |j|||}nt |jd||}|dkr|d}t d|d||df}t j||d |d ||q ||q dS) NrrrFrz-external %s:%s reference target not found: %srrref)rrsubtype)Zdocumentfindallr rr rdeepcopyrr(rrrrrirZ replace_self)r.rrrrrrmsgr/r/r0rfs" zIntersphinxRoleResolver.runN)r:r;r<r=rZdefault_priorityrr/r/r/r0r^s rz list[str])r]rsourcer)cCst}|dS)zEnable IntersphinxDispatcher. .. note:: The installed dispatcher will be uninstalled on disabling sphinx_domain automatically. N)renable)r]rr dispatcherr/r/r0install_dispatcher{srr )r]rGr)c Cs|jD]\}}zt|ttfr`||}\}}t|tstt d||j |Wqn*d||}}}d||fd}t|t|ts|||fff|j|<n|||ff|j|<Wqt k r}z"tt d|||j |W5d}~XYqXqdS)Nz0intersphinx identifier %r is not string. IgnoredzThe pre-Sphinx 1.0 'intersphinx_mapping' format is deprecated and will be removed in Sphinx 8. Update to the current format as described in the documentation. Hint: "intersphinx_mapping = {'': ze}".https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#confval-intersphinx_mappingz3Failed to read intersphinx_mapping[%s], ignored: %r) rcopyrrrCtupler?rirrpoprf) r]rGkeyvaluervr^r_rrrr/r/r0normalize_intersphinx_mappings(     rzdict[str, Any]cCs|did|ddd|ddd|ddgd|jd td d |d t|d t|dt|ttj dddS)NrTr}FrLrzstd:docz config-initedi )priorityzbuilder-initedz source-readzmissing-referencerB)rZ env_versionZparallel_read_safe) Zadd_config_valueconnectrrrrZadd_post_transformrsphinxZ__display_version__)r]r/r/r0setups    r)argvr)c s0t|dkr"tdtjdtdGdddGfddd}z||d}t|d |}t|pbiD]T}t|t||D]6\}}td ||d d krd |d nd |dfqqfWnltk r}z t|j d|j ddW5d}~XYn0t k r*}ztd|W5d}~XYnXdS)z-Debug functionality to print out an inventoryrBzXPrint out an inventory file. Error: must specify local path or URL to an inventory file.filec@s&eZdZUdZded<dZdZdZdS)z inspect_main..MockConfigNz int | NonerLF)r:r;r<rL__annotations__rNrOrMr/r/r/r0 MockConfigs  r cs&eZdZdZZdddddZdS)zinspect_main..MockApprr?r')rr)cSst|tjddS)Nr)printsysstderr)r.rr/r/r0warnsz"inspect_main..MockApp.warnN)r:r;r<rerGrr/r r/r0MockAppsrrrz %-40s %s%srrz%-40s: rNzUnknown error: %r) r~r r r  SystemExitrsrrrnrhrf)rrfilenamerqrentryZeinforrr/rr0 inspect_mains* ,r__main__rB)r)N)br= __future__rconcurrent.futuresrrRrlrr rosrtypingrrrrr urllib.parser r Zdocutilsr Zdocutils.utilsr rZsphinx.addnodesr Zsphinx.builders.htmlrZ sphinx.errorsrZ sphinx.localerrZ!sphinx.transforms.post_transformsrZ sphinx.utilrrZsphinx.util.docutilsrrZsphinx.util.inventoryrtypesrrrZdocutils.nodesrrrrZsphinx.applicationrZ sphinx.configr Zsphinx.domainsr!Zsphinx.environmentr"Zsphinx.util.typingr#r$r%r?rtZInventoryCacheEntry getLoggerr:rir&rFrVr\rsrrrrrrrrrrrrrrrrrrZ_logging basicConfigrr/r/r/r0sx                &'*) +) R !$