IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

refactor: Use PEP-526 based variable annotation (sphinx.environment)

Browse Source
This commit is contained in:
Takeshi KOMIYA 2021-03-25 00:09:21 +09:00
parent 6e4df0a419
commit 000ae2e500
6 changed files with 78 additions and 81 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

91
sphinx/environment/__init__.py
View File

@ -42,7 +42,7 @@ if TYPE_CHECKING:
logger = logging.getLogger(__name__)
default_settings = {
default_settings: Dict[str, Any] = {
'embed_stylesheet': False,
'cloak_email_addresses': True,
'pep_base_url': 'https://www.python.org/dev/peps/',
@ -55,7 +55,7 @@ default_settings = {
'halt_level': 5,
'file_insertion_enabled': True,
'smartquotes_locales': [],
} # type: Dict[str, Any]
}
# This is increased every time an environment attribute is added
# or changed to properly invalidate pickle files.
@ -74,10 +74,10 @@ CONFIG_CHANGED_REASON = {
}
versioning_conditions = {
versioning_conditions: Dict[str, Union[bool, Callable]] = {
'none': False,
'text': is_translatable,
} # type: Dict[str, Union[bool, Callable]]
}
class BuildEnvironment:
@ -87,24 +87,24 @@ class BuildEnvironment:
transformations to resolve links to them.
"""
domains = None # type: Dict[str, Domain]
domains: Dict[str, Domain] = None
# --------- ENVIRONMENT INITIALIZATION -------------------------------------
def __init__(self, app: "Sphinx" = None):
self.app = None # type: Sphinx
self.doctreedir = None # type: str
self.srcdir = None # type: str
self.config = None # type: Config
self.config_status = None # type: int
self.config_status_extra = None # type: str
self.events = None # type: EventManager
self.project = None # type: Project
self.version = None # type: Dict[str, str]
self.app: Sphinx = None
self.doctreedir: str = None
self.srcdir: str = None
self.config: Config = None
self.config_status: int = None
self.config_status_extra: str = None
self.events: EventManager = None
self.project: Project = None
self.version: Dict[str, str] = None
# the method of doctree versioning; see set_versioning_method
self.versioning_condition = None # type: Union[bool, Callable]
self.versioning_compare = None # type: bool
self.versioning_condition: Union[bool, Callable] = None
self.versioning_compare: bool = None
# all the registered domains, set by the application
self.domains = {}
@ -116,70 +116,67 @@ class BuildEnvironment:
# All "docnames" here are /-separated and relative and exclude
# the source suffix.
self.all_docs = {} # type: Dict[str, float]
# docname -> mtime at the time of reading
# contains all read docnames
self.dependencies = defaultdict(set) # type: Dict[str, Set[str]]
self.all_docs: Dict[str, float] = {}
# docname -> set of dependent file
# names, relative to documentation root
self.included = defaultdict(set) # type: Dict[str, Set[str]]
self.dependencies: Dict[str, Set[str]] = defaultdict(set)
# docname -> set of included file
# docnames included from other documents
self.reread_always = set() # type: Set[str]
# docnames to re-read unconditionally on
# next build
self.included: Dict[str, Set[str]] = defaultdict(set)
# docnames to re-read unconditionally on next build
self.reread_always: Set[str] = set()
# File metadata
self.metadata = defaultdict(dict) # type: Dict[str, Dict[str, Any]]
# docname -> dict of metadata items
self.metadata: Dict[str, Dict[str, Any]] = defaultdict(dict)
# TOC inventory
self.titles = {} # type: Dict[str, nodes.title]
# docname -> title node
self.longtitles = {} # type: Dict[str, nodes.title]
self.titles: Dict[str, nodes.title] = {}
# docname -> title node; only different if
# set differently with title directive
self.tocs = {} # type: Dict[str, nodes.bullet_list]
self.longtitles: Dict[str, nodes.title] = {}
# docname -> table of contents nodetree
self.toc_num_entries = {} # type: Dict[str, int]
self.tocs: Dict[str, nodes.bullet_list] = {}
# docname -> number of real entries
self.toc_num_entries: Dict[str, int] = {}
# used to determine when to show the TOC
# in a sidebar (don't show if it's only one item)
self.toc_secnumbers = {} # type: Dict[str, Dict[str, Tuple[int, ...]]]
# docname -> dict of sectionid -> number
self.toc_fignumbers = {} # type: Dict[str, Dict[str, Dict[str, Tuple[int, ...]]]]
# docname -> dict of figtype ->
# dict of figureid -> number
self.toc_secnumbers: Dict[str, Dict[str, Tuple[int, ...]]] = {}
# docname -> dict of figtype -> dict of figureid -> number
self.toc_fignumbers: Dict[str, Dict[str, Dict[str, Tuple[int, ...]]]] = {}
self.toctree_includes = {} # type: Dict[str, List[str]]
# docname -> list of toctree includefiles
self.files_to_rebuild = {} # type: Dict[str, Set[str]]
# docname -> set of files
# (containing its TOCs) to rebuild too
self.glob_toctrees = set() # type: Set[str]
self.toctree_includes: Dict[str, List[str]] = {}
# docname -> set of files (containing its TOCs) to rebuild too
self.files_to_rebuild: Dict[str, Set[str]] = {}
# docnames that have :glob: toctrees
self.numbered_toctrees = set() # type: Set[str]
self.glob_toctrees: Set[str] = set()
# docnames that have :numbered: toctrees
self.numbered_toctrees: Set[str] = set()
# domain-specific inventories, here to be pickled
self.domaindata = {} # type: Dict[str, Dict]
# domainname -> domain-specific dict
self.domaindata: Dict[str, Dict] = {}
# these map absolute path -> (docnames, unique filename)
self.images = FilenameUniqDict() # type: FilenameUniqDict
self.dlfiles = DownloadFiles() # type: DownloadFiles
self.images: FilenameUniqDict = FilenameUniqDict()
# filename -> (set of docnames, destination)
self.dlfiles: DownloadFiles = DownloadFiles()
# the original URI for images
self.original_image_uri = {} # type: Dict[str, str]
self.original_image_uri: Dict[str, str] = {}
# temporary data storage while reading a document
self.temp_data = {} # type: Dict[str, Any]
self.temp_data: Dict[str, Any] = {}
# context for cross-references (e.g. current module or class)
# this is similar to temp_data, but will for example be copied to
# attributes of "any" cross references
self.ref_context = {} # type: Dict[str, Any]
self.ref_context: Dict[str, Any] = {}
# set up environment
if app:
@ -269,7 +266,7 @@ class BuildEnvironment:
raise an exception if the user tries to use an environment with an
incompatible versioning method.
"""
condition = None # type: Union[bool, Callable]
condition: Union[bool, Callable] = None
if callable(method):
condition = method
else:
@ -385,8 +382,8 @@ class BuildEnvironment:
# clear all files no longer present
removed = set(self.all_docs) - self.found_docs
added = set() # type: Set[str]
changed = set() # type: Set[str]
added: Set[str] = set()
changed: Set[str] = set()
if config_changed:
# config values affect e.g. substitutions
@ -438,7 +435,7 @@ class BuildEnvironment:
return added, changed, removed
def check_dependents(self, app: "Sphinx", already: Set[str]) -> Generator[str, None, None]:
to_rewrite = [] # type: List[str]
to_rewrite: List[str] = []
for docnames in self.events.emit('env-get-updated', self):
to_rewrite.extend(docnames)
for docname in set(to_rewrite):

4
sphinx/environment/adapters/indexentries.py
View File

@ -31,7 +31,7 @@ class IndexEntries:
_fixre: Pattern = re.compile(r'(.*) ([(][^()]*[)])')
) -> List[Tuple[str, List[Tuple[str, Any]]]]:
"""Create the real index from the collected index entries."""
new = {} # type: Dict[str, List]
new: Dict[str, List] = {}
def add_entry(word: str, subword: str, main: str, link: bool = True,
dic: Dict = new, key: str = None) -> None:
@ -126,7 +126,7 @@ class IndexEntries:
# (in module foo)
# (in module bar)
oldkey = ''
oldsubitems = None # type: Dict[str, List]
oldsubitems: Dict[str, List] = None
i = 0
while i < len(newlist):
key, (targets, subitems, _key) = newlist[i]

8
sphinx/environment/adapters/toctree.py
View File

@ -102,7 +102,7 @@ class TocTree:
if not subnode['anchorname']:
# give the whole branch a 'current' class
# (useful for styling it differently)
branchnode = subnode # type: Element
branchnode: Element = subnode
while branchnode:
branchnode['classes'].append('current')
branchnode = branchnode.parent
@ -119,7 +119,7 @@ class TocTree:
) -> List[Element]:
"""Return TOC entries for a toctree node."""
refs = [(e[0], e[1]) for e in toctreenode['entries']]
entries = [] # type: List[Element]
entries: List[Element] = []
for (title, ref) in refs:
try:
refdoc = None
@ -268,7 +268,7 @@ class TocTree:
for p, children in self.env.toctree_includes.items():
for child in children:
parent[child] = p
ancestors = [] # type: List[str]
ancestors: List[str] = []
d = docname
while d in parent and d not in ancestors:
ancestors.append(d)
@ -316,7 +316,7 @@ class TocTree:
**kwargs: Any) -> Element:
"""Return the global TOC nodetree."""
doctree = self.env.get_doctree(self.env.config.root_doc)
toctrees = [] # type: List[Element]
toctrees: List[Element] = []
if 'includehidden' not in kwargs:
kwargs['includehidden'] = True
if 'maxdepth' not in kwargs or not kwargs['maxdepth']:

2
sphinx/environment/collectors/__init__.py
View File

@ -27,7 +27,7 @@ class EnvironmentCollector:
entries and toctrees, etc.
"""
listener_ids = None # type: Dict[str, int]
listener_ids: Dict[str, int] = None
def enable(self, app: "Sphinx") -> None:
assert self.listener_ids is None

4
sphinx/environment/collectors/asset.py
View File

@ -48,7 +48,7 @@ class ImageCollector(EnvironmentCollector):
# choose the best image from these candidates. The special key * is
# set if there is only single candidate to be used by a writer.
# The special key ? is set for nonlocal URIs.
candidates = {} # type: Dict[str, str]
candidates: Dict[str, str] = {}
node['candidates'] = candidates
imguri = node['uri']
if imguri.startswith('data:'):
@ -94,7 +94,7 @@ class ImageCollector(EnvironmentCollector):
def collect_candidates(self, env: BuildEnvironment, imgpath: str,
candidates: Dict[str, str], node: Node) -> None:
globbed = {} # type: Dict[str, List[str]]
globbed: Dict[str, List[str]] = {}
for filename in glob(imgpath):
new_imgpath = relative_path(path.join(env.srcdir, 'dummy'),
filename)

14
sphinx/environment/collectors/toctree.py
View File

@ -64,7 +64,7 @@ class TocTreeCollector(EnvironmentCollector):
def traverse_in_section(node: Element, cls: "Type[N]") -> List[N]:
"""Like traverse(), but stay within the same section."""
result = [] # type: List[N]
result: List[N] = []
if isinstance(node, cls):
result.append(node)
for child in node.children:
@ -75,7 +75,7 @@ class TocTreeCollector(EnvironmentCollector):
return result
def build_toc(node: Element, depth: int = 1) -> nodes.bullet_list:
entries = [] # type: List[Element]
entries: List[Element] = []
for sectionnode in node:
# find all toctree nodes in this section and add them
# to the toc (just copying the toctree node which is then
@ -100,7 +100,7 @@ class TocTreeCollector(EnvironmentCollector):
'', '', internal=True, refuri=docname,
anchorname=anchorname, *nodetext)
para = addnodes.compact_paragraph('', '', reference)
item = nodes.list_item('', para) # type: Element
item: Element = nodes.list_item('', para)
sub_item = build_toc(sectionnode, depth + 1)
if sub_item:
item += sub_item
@ -136,7 +136,7 @@ class TocTreeCollector(EnvironmentCollector):
# a list of all docnames whose section numbers changed
rewrite_needed = []
assigned = set() # type: Set[str]
assigned: Set[str] = set()
old_secnumbers = env.toc_secnumbers
env.toc_secnumbers = {}
@ -186,7 +186,7 @@ class TocTreeCollector(EnvironmentCollector):
'(nested numbered toctree?)'), ref,
location=toctreenode, type='toc', subtype='secnum')
elif ref in env.tocs:
secnums = {} # type: Dict[str, Tuple[int, ...]]
secnums: Dict[str, Tuple[int, ...]] = {}
env.toc_secnumbers[ref] = secnums
assigned.add(ref)
_walk_toc(env.tocs[ref], secnums, depth, env.titles.get(ref))
@ -210,10 +210,10 @@ class TocTreeCollector(EnvironmentCollector):
rewrite_needed = []
assigned = set() # type: Set[str]
assigned: Set[str] = set()
old_fignumbers = env.toc_fignumbers
env.toc_fignumbers = {}
fignum_counter = {} # type: Dict[str, Dict[Tuple[int, ...], int]]
fignum_counter: Dict[str, Dict[Tuple[int, ...], int]] = {}
def get_figtype(node: Node) -> str:
for domain in env.domains.values():