File: //usr/lib/python3/dist-packages/sphinx/environment/__pycache__/__init__.cpython-310.pyc
o
o�aRe � @ s( U d Z ddlZddlZddlZddlmZ ddlmZ ddlmZ ddlmZ ddl m
Z
m Z m Z m
Z
mZmZmZmZmZmZmZ ddlmZ dd lmZ dd
lmZ dd lm Z dd l m Z dd
l m Z ddl!m"Z" ddl#m$Z$m%Z%m&Z&m'Z' ddl(m)Z) ddl*m+Z+ ddl,m-Z- ddl.m/Z/ ddl0m1Z1m2Z2m3Z3 ddl4m5Z5 ddl6m7Z7m8Z8 ddl9m:Z: ddl;m<Z<m=Z= e
r�ddl>m?Z? ddl@mAZA e3�BeC�ZDdd d d d dd dd d d d d!d g d"�ZEe
eFe f eGd#< d$ZHd%ZId&ZJd'ZKd(ZLeJe+d)�eKe+d*�eLe+d+�iZMd e:d,�ZNe
eFeeOe f f eGd-< G d.d/� d/�ZPdS )0z�
sphinx.environment
~~~~~~~~~~~~~~~~~~
Global creation environment.
:copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
� N)� defaultdict)�copy)�datetime)�path) �
TYPE_CHECKING�Any�Callable�Dict� Generator�Iterator�List�Optional�Set�Tuple�Union)�nodes)�Node)�addnodes)�Config)�RemovedInSphinx60Warning)�Domain)�TocTree)�BuildEnvironmentError�
DocumentError�ExtensionError� SphinxError)� EventManager)�__)�Project)�SphinxTransformer)�
DownloadFiles�FilenameUniqDict�logging)�LoggingReporter)�CatalogRepository�docname_to_domain)�is_translatable)�
canon_path�os_path)�Sphinx)�Builder�idFTz https://www.python.org/dev/peps/z https://tools.ietf.org/html/z utf-8-sig� )�auto_id_prefix� embed_images�embed_stylesheet�cloak_email_addresses� pep_base_url�pep_references� rfc_base_url�rfc_references�input_encoding�doctitle_xform�sectsubtitle_xform�section_self_link�
halt_level�file_insertion_enabled�smartquotes_locales�default_settings�8 � � � � z
new configzconfig changedzextensions changed)�none�text�versioning_conditionsc @ s� e Zd ZU dZeeef ed< d_d`dd�Zdefd d
�Z d eddfd d
�Z
dadd�Z de ddfdd�Z
de ddfdd�Zdeeef deddfdd�Zdeddfdd�Zd ee d d ddddfd d �Zd edee fd!d"�Zdbded$edefd%d&�Zd_d ededeeef fd'd(�Zede e fd)d*��Z de d+d,ddfd-d.�Z d/edee e e e e e f fd0d1�Z ddd2e e de eddf fd3d4�Z!deddfd5d6�Z"edefd7d8��Z#dcd:ede$fd;d<�Z%d eddfd=d>�Z&d eddfd?d@�Z'dddAdB�Z(dCedefdDdE�Z)dede*j+fdFdG�Z, # Hdeded+d,dIe*j+dJedKede*j+f dLdM�Z- H Hdfded+d,dOe.j/dPedQe$dRedSedKede0fdTdU�Z1dIe*j+dVed+d,ddfdWdX�Z2dIe*j+deddfdYdZ�Z3deeeee f fd[d\�Z4ddd]d^�Z5dS )g�BuildEnvironmentz�
The environment in which the ReST files are translated.
Stores an inventory of cross-file targets and provides doctree
transformations to resolve links to them.
�domainsN�appr) c C s d | _ d | _d | _d | _d | _d | _d | _d | _d | _d | _ d | _
i | _ t �
� | _| | jd< i | _tt�| _tt�| _t� | _tt�| _i | _i | _i | _i | _i | _i | _ i | _ i | _ t� | _ t� | _ i | _!t"� | _#t$� | _%i | _&i | _'i | _(|r�| �)|� d S t*j+dt,dd� d S )N�envz?The 'app' argument for BuildEnvironment() becomes required now.r? )�
stacklevel)-rG �
doctreedir�srcdir�config�
config_status�config_status_extra�events�project�version�versioning_condition�versioning_comparerF r< r �settings�all_docsr �set� dependencies�included�
reread_always�dict�metadata�titles�
longtitles�tocs�toc_num_entries�toc_secnumbers�toc_fignumbers�toctree_includes�files_to_rebuild�
glob_toctrees�numbered_toctrees�
domaindatar! �imagesr �dlfiles�original_image_uri� temp_data� ref_context�setup�warnings�warnr )�selfrG � rp �=/usr/lib/python3/dist-packages/sphinx/environment/__init__.py�__init__c sP
�zBuildEnvironment.__init__�returnc C s | j �� }|jdi dd� |S )z'Obtains serializable data for pickling.N)rG rF rO )�__dict__r �update)ro rt rp rp rq � __getstate__� s
z BuildEnvironment.__getstate__�statec C s | j �|� d S �N)rt ru )ro rw rp rp rq � __setstate__� s z BuildEnvironment.__setstate__c C s� | j r| j |j�|�krttd���| jr!| j|jkr!ttd���| jr+|j�| j� || _|j | _ |j
| _
|j| _|j| _|j�|�| _ i | _ |j� | �D ]}|| j |j
< qN| j �� D ]}|�� q\| �|j� | �|j� dS )z Set up BuildEnvironment object.z%build environment version not currentz source directory has changedN)rQ �registry�get_envversionr r rK rP �restorerG rJ rO rF �create_domains�name�valuesrl �_update_configrL �_update_settings)ro rG �domainrp rp rq rl � s&
zBuildEnvironment.setuprL c C s� t | _d| _| jdu rt| _nM| jj|jkr?t| _tt| jj�t|j�A �}t |�dkr1|d }ndt |�f }d|f | _n |�
d�D ]}| j|j |j kr[t
| _d|j f | _ nqD|| _dS )z!Update configurations by new one.� Nr> r z%dz (%r)rH )� CONFIG_OKrM rN rL �
CONFIG_NEW�
extensions�CONFIG_EXTENSIONS_CHANGED�sortedrV �len�filterr~ �value�CONFIG_CHANGED)ro rL r� � extension�itemrp rp rq r� � s(
�
�
z BuildEnvironment._update_configc C s: |j | jd< |j| jd< |jpd| jd< | j�dd� dS )z Update settings by new config.r5 � trim_footnote_reference_space�en�
language_code� smart_quotesTN)�source_encodingrT r� �language�
setdefault)ro rL rp rp rq r� s z!BuildEnvironment._update_settings�method�comparec C sT t |�r|}n|tvrtd| ��t| }| jd|fvr"ttd���|| _|| _dS )aX This sets the doctree versioning method for this environment.
Versioning methods are a builder property; only builders with the same
versioning method can share the same doctree directory. Therefore, we
raise an exception if the user tries to use an environment with an
incompatible versioning method.
z invalid versioning method: %rNzdThis environment is incompatible with the selected builder, please choose another doctree directory.)�callablerD �
ValueErrorrR r r rS )ro r� r� � conditionrp rp rq �set_versioning_method
s
z&BuildEnvironment.set_versioning_method�docnamec C sP || j v r| j �|d� | j�|d� | j�|� | j�� D ]}|�|� q dS )z4Remove all traces of a source file in the inventory.N)rU �poprX rY �discardrF r � clear_doc)ro r� r� rp rp rq r� $ s
�zBuildEnvironment.clear_doc�docnames�otherc C s� t |�}|D ] }|j| | j|< |j| | j|< ||jv r#| j�|� q| j�� D ]
\}}|�||j| � q)| j �
d| ||� dS )z�Merge global information gathered about *docnames* while reading them
from the *other* environment.
This possibly comes from a parallel build process.
zenv-merge-infoN) rV rU rX rY �addrF �items�merge_domaindatarf rO �emit)ro r� r� rG r� �
domainnamer� rp rp rq �merge_info_from. s
�z BuildEnvironment.merge_info_from�filenamec C s | j �|�S )z�Return the docname for the filename if the file is document.
*filename* should be absolute or relative to the source directory.
)rP �path2doc�ro r� rp rp rq r� @ s zBuildEnvironment.path2docT�basec C s | j �||�S )z�Return the filename for the document name.
If *base* is True, return absolute path under self.srcdir.
If *base* is False, return relative path to self.srcdir.
)rP �doc2path)ro r� r� rp rp rq r� G s zBuildEnvironment.doc2pathc C st t |�}|�d�s|�tj�r|dd� }nt�| j|p | jdd��}t�||�}t t�
|��t�
t�| j |��fS )a+ Return paths to a file referenced from a document, relative to
documentation root and absolute.
In the input "filename", absolute filenames are taken as relative to the
source dir, while relative filenames are relative to the dir of the
containing document.
�/r> N)r� ) r( �
startswith�os�sepr �dirnamer� r� �joinr' �normpathrK )ro r� r� �rel_fn�docdirrp rp rq �
relfn2pathO s � �zBuildEnvironment.relfn2pathc C s | j jS )z contains all existing docnames.)rP r� �ro rp rp rq �
found_docsb s zBuildEnvironment.found_docs�builderr* c
C s� zL| j j| j j |�� }| j�|� |jrGt| j| j j | j j
| j j �}dd� |j D �}| j
D ]}t|| j j�}||v rF| j| �|| � q/W dS W dS tyd } z ttd�| j|f �|�d}~ww )zYFind all source files in the source dir and put them in
self.found_docs.
c S s i | ]}|j |j�qS rp )r� �mo_path)�.0�crp rp rq �
<dictcomp>{ s z/BuildEnvironment.find_files.<locals>.<dictcomp>z"Failed to scan documents in %s: %rN)rL �exclude_patterns�templates_path�get_asset_pathsrP �discover�use_message_catalogr$ rK � locale_dirsr� r� �catalogsr� r% �gettext_compactrW r� �OSErrorr r ) ro rL r� �
exclude_paths�repo�mo_pathsr� r� �excrp rp rq �
find_filesg s6 �� �
������zBuildEnvironment.find_files�config_changedc
C s| t | j�| j }t � }t � }|r| j}n�| jD ]�}|| jvr*t�d|� |�|� qt�| j|d �}t� |�sDt�d|� |�|� q|| j
v rUt�d|� |�|� q| j| }t� | � |��}||krzt�d|t
�|�t
�|�� |�|� q| j| D ]8} z't�| j| �}
t� |
�s�|�|� W n"t� |
�} | |kr�|�|� W nW q ty� |�|� Y nw q|||fS )z&Return (added, changed, removed) sets.z[build target] added %r�.doctreez[build target] changed %rz$[build target] outdated %r: %s -> %s)rV rU r� �logger�debugr� r r� rJ �isfilerY �getmtimer� r �utcfromtimestamprW rK r� ) ro r� �removed�added�changedr� r� �mtime�newmtime�dep�deppath�depmtimerp rp rq �get_outdated_files� s\
�
�
��
z#BuildEnvironment.get_outdated_files�alreadyc c sD � g }| j �d| �D ]}|�|� q
t|�D ] }||vr |V qd S )Nzenv-get-updated)rO r� �extendrV )ro rG r� �
to_rewriter� r� rp rp rq �check_dependents� s � ��z!BuildEnvironment.check_dependentsc C s2 || j d< | jj| j d< | j�| jj�| j d< dS )z*Prepare to set up environment for reading.r� � default_role�default_domainN)rj rL r� rF �get�primary_domain)ro r� rp rp rq �prepare_settings� s
�z!BuildEnvironment.prepare_settingsc C s
| j d S )z;Returns the docname of the document currently being parsed.r� )rj r� rp rp rq r� � s
zBuildEnvironment.docnamer� �categoryc C s( |d }| j �|d�}|d | j |< |S )z�Return a serial number, e.g. for index entry targets.
The number is guaranteed to be unique in the current document.
�serialnor r> )rj r� )ro r� �key�currp rp rq � new_serialno� s z BuildEnvironment.new_serialnoc C s | j | j �|� dS )z�Add *filename* as a dependency of the current document.
This means that the document will be rebuilt if this file changes.
*filename* should be absolute or relative to the source directory.
N)rW r� r� r� rp rp rq �note_dependency� s z BuildEnvironment.note_dependencyc C s | j | j �| �|�� dS )z�Add *filename* as a included from other document.
This means the document is not orphaned.
*filename* should be absolute or relative to the source directory.
N)rX r� r� r� r� rp rp rq �
note_included� s z BuildEnvironment.note_includedc C s | j �| j� dS )zxAdd the current document to the list of documents that will
automatically be re-read at the next build.
N)rY r� r� r� rp rp rq � note_reread� s z BuildEnvironment.note_rereadr� c
C s8 z| j | W S ty } z ttd�| �|�d}~ww )zReturn the domain instance with the specified name.
Raises an ExtensionError if the domain is not registered.
zDomain %r is not registeredN)rF �KeyErrorr r )ro r� r� rp rp rq �
get_domain� s ��zBuildEnvironment.get_domainc C sb t �| j|d �}t|d��
}t�|�}W d � n1 s w Y | |j_t| � |��|_
|S )z:Read the doctree for a file from the pickle and return it.r� �rbN) r r� rJ �open�pickle�loadrT rH r# r� �reporter)ro r� r� �f�doctreerp rp rq � get_doctree s �z BuildEnvironment.get_doctreeFr� �prune_toctrees�
includehiddenc C sj |du r | � |�}| �||� |�tj�D ] }t| �j|||||d�}|du r-|�g � q|�|� q|S )zgRead the doctree from the pickle, resolve cross-references and
toctrees and return it.
N)�pruner� )r� �apply_post_transforms�traverser �toctreer �resolve� replace_self)ro r� r� r� r� r� � toctreenode�resultrp rp rq �get_and_resolve_doctree
s
� z(BuildEnvironment.get_and_resolve_doctreer r� r� �maxdepth� titles_only�collapsec
C s t | ��||||||||�S )a Resolve a *toctree* node into individual bullet lists with titles
as items, returning None (if no containing titles are found) or
a new node.
If *prune* is True, the tree is pruned to *maxdepth*, or if that is 0,
to the value of the *maxdepth* option on the *toctree* node.
If *titles_only* is True, only toplevel document titles will be in the
resulting tree.
If *collapse* is True, all branches not containing docname will
be collapsed.
)r r� ) ro r� r� r� r� r r r r� rp rp rq �resolve_toctree% s �z BuildEnvironment.resolve_toctree� fromdocnamec C s | � ||� d S rx )r� )ro r� r r� rp rp rq �resolve_references7 s z#BuildEnvironment.resolve_referencesc C sh z%t | j�}|| jd< t|�}|�| � |�| jj�� � |�� W || _n|| _w | j �
d||� dS )zApply all post-transforms.r� zdoctree-resolvedN) r rj r �set_environment�add_transformsrG rz �get_post_transforms�apply_transformsrO r� )ro r� r� �backup� transformerrp rp rq r� ; s
z&BuildEnvironment.apply_post_transformsc s� t � �dtdtdttttf f� ��fdd� �i }�d � jj�}d }t|�\}}|D ]\}}|||g||< |}|}|}q+||d g||< |S )N�parentr� rs c 3 s� � | |krt jtd�|ddd� d S | |fV ��|� � j�|�p#g D ]}�||�D ]\}}|�vr=||fV ��|� q+q$d S )Nz'self referenced toctree found. Ignored.�toc�circular)�location�type�subtype)r� �warningr r� rb r� )r r� �child� subparent�
subdocname�ro �traverse_toctree� traversedrp rq r O s" �
�
���z<BuildEnvironment.collect_relations.<locals>.traverse_toctree)rV �strr r rL �root_doc�next)ro � relationsr� �prevdocr r� �
nextparent�nextdocrp r rq �collect_relationsL s * z"BuildEnvironment.collect_relationsc C s� t � j| j�� � }t| j�D ]$}|| jvr2|| jjkr q||v r!qd| j | v r)qt
j t d�|d� q| j
�� D ]}|�� q8| j�d| � dS )zDo consistency checks.�orphanz&document isn't included in any toctree)r zenv-check-consistencyN)rV �unionrX r r� rU rc rL r r[ r� r r rF �check_consistencyrO r� )ro rX r� r� rp rp rq r% n s
��
z"BuildEnvironment.check_consistencyrx )rG r) )rG r) rs N)T)r� )rs N)NTF)Tr FFF)6�__name__�
__module__� __qualname__�__doc__r r r �__annotations__rr rv ry rl r r� r� r r �boolr� r� r r� r
r� r� r r� �propertyr r� r� r� r
r� r� r� �intr� r� r� r� r� r �documentr� r r r� r r r r� r" r% rp rp rp rq rE X s�
^
�
� ( $9
����
�������
� �
� "rE )Qr) r� r� rm � collectionsr r r r �typingr r r r r
r r r
r r r �docutilsr �docutils.nodesr �sphinxr �
sphinx.configr �sphinx.deprecationr �sphinx.domainsr �#sphinx.environment.adapters.toctreer �
sphinx.errorsr r r r �
sphinx.eventsr �
sphinx.localer �sphinx.projectr �sphinx.transformsr � sphinx.utilr r! r" �sphinx.util.docutilsr# �sphinx.util.i18nr$ r% �sphinx.util.nodesr& �sphinx.util.osutilr' r( �sphinx.applicationr) �sphinx.buildersr* � getLoggerr& r� r< r r* � ENV_VERSIONr� r� r� r� �CONFIG_CHANGED_REASONrD r+ rE rp rp rp rq �<module> sv
4
�� �