diff options
Diffstat (limited to 'sphinx/registry.py')
| -rw-r--r-- | sphinx/registry.py | 99 |
1 files changed, 51 insertions, 48 deletions
diff --git a/sphinx/registry.py b/sphinx/registry.py index c6a249e74..cdf77cb67 100644 --- a/sphinx/registry.py +++ b/sphinx/registry.py @@ -9,9 +9,11 @@ """ import traceback +import warnings from importlib import import_module from types import MethodType -from typing import Any, Callable, Dict, Iterator, List, Tuple, Union +from typing import (TYPE_CHECKING, Any, Callable, Dict, Iterator, List, Optional, Tuple, Type, + Union) from docutils import nodes from docutils.io import Input @@ -23,6 +25,7 @@ from pkg_resources import iter_entry_points from sphinx.builders import Builder from sphinx.config import Config +from sphinx.deprecation import RemovedInSphinx60Warning from sphinx.domains import Domain, Index, ObjType from sphinx.domains.std import GenericObject, Target from sphinx.environment import BuildEnvironment @@ -35,10 +38,7 @@ from sphinx.util import logging from sphinx.util.logging import prefixed_warnings from sphinx.util.typing import RoleFunction, TitleGetter -if False: - # For type annotation - from typing import Type # for python3.5.1 - +if TYPE_CHECKING: from sphinx.application import Sphinx from sphinx.ext.autodoc import Documenter @@ -54,76 +54,76 @@ EXTENSION_BLACKLIST = { class SphinxComponentRegistry: def __init__(self) -> None: #: special attrgetter for autodoc; class object -> attrgetter - self.autodoc_attrgettrs = {} # type: Dict[Type, Callable[[Any, str, Any], Any]] + self.autodoc_attrgettrs: Dict[Type, Callable[[Any, str, Any], Any]] = {} #: builders; a dict of builder name -> bulider class - self.builders = {} # type: Dict[str, Type[Builder]] + self.builders: Dict[str, Type[Builder]] = {} #: autodoc documenters; a dict of documenter name -> documenter class - self.documenters = {} # type: Dict[str, Type[Documenter]] + self.documenters: Dict[str, Type[Documenter]] = {} #: css_files; a list of tuple of filename and attributes - self.css_files = [] # type: List[Tuple[str, Dict[str, Any]]] + self.css_files: List[Tuple[str, Dict[str, Any]]] = [] #: domains; a dict of domain name -> domain class - self.domains = {} # type: Dict[str, Type[Domain]] + self.domains: Dict[str, Type[Domain]] = {} #: additional directives for domains #: a dict of domain name -> dict of directive name -> directive - self.domain_directives = {} # type: Dict[str, Dict[str, Any]] + self.domain_directives: Dict[str, Dict[str, Any]] = {} #: additional indices for domains #: a dict of domain name -> list of index class - self.domain_indices = {} # type: Dict[str, List[Type[Index]]] + self.domain_indices: Dict[str, List[Type[Index]]] = {} #: additional object types for domains #: a dict of domain name -> dict of objtype name -> objtype - self.domain_object_types = {} # type: Dict[str, Dict[str, ObjType]] + self.domain_object_types: Dict[str, Dict[str, ObjType]] = {} #: additional roles for domains #: a dict of domain name -> dict of role name -> role impl. - self.domain_roles = {} # type: Dict[str, Dict[str, Union[RoleFunction, XRefRole]]] # NOQA + self.domain_roles: Dict[str, Dict[str, Union[RoleFunction, XRefRole]]] = {} #: additional enumerable nodes #: a dict of node class -> tuple of figtype and title_getter function - self.enumerable_nodes = {} # type: Dict[Type[Node], Tuple[str, TitleGetter]] + self.enumerable_nodes: Dict[Type[Node], Tuple[str, TitleGetter]] = {} #: HTML inline and block math renderers #: a dict of name -> tuple of visit function and depart function - self.html_inline_math_renderers = {} # type: Dict[str, Tuple[Callable, Callable]] - self.html_block_math_renderers = {} # type: Dict[str, Tuple[Callable, Callable]] + self.html_inline_math_renderers: Dict[str, Tuple[Callable, Callable]] = {} + self.html_block_math_renderers: Dict[str, Tuple[Callable, Callable]] = {} #: js_files; list of JS paths or URLs - self.js_files = [] # type: List[Tuple[str, Dict[str, Any]]] + self.js_files: List[Tuple[str, Dict[str, Any]]] = [] #: LaTeX packages; list of package names and its options - self.latex_packages = [] # type: List[Tuple[str, str]] + self.latex_packages: List[Tuple[str, str]] = [] - self.latex_packages_after_hyperref = [] # type: List[Tuple[str, str]] + self.latex_packages_after_hyperref: List[Tuple[str, str]] = [] #: post transforms; list of transforms - self.post_transforms = [] # type: List[Type[Transform]] + self.post_transforms: List[Type[Transform]] = [] #: source paresrs; file type -> parser class - self.source_parsers = {} # type: Dict[str, Type[Parser]] + self.source_parsers: Dict[str, Type[Parser]] = {} #: source inputs; file type -> input class - self.source_inputs = {} # type: Dict[str, Type[Input]] + self.source_inputs: Dict[str, Type[Input]] = {} #: source suffix: suffix -> file type - self.source_suffix = {} # type: Dict[str, str] + self.source_suffix: Dict[str, str] = {} #: custom translators; builder name -> translator class - self.translators = {} # type: Dict[str, Type[nodes.NodeVisitor]] + self.translators: Dict[str, Type[nodes.NodeVisitor]] = {} #: custom handlers for translators #: a dict of builder name -> dict of node name -> visitor and departure functions - self.translation_handlers = {} # type: Dict[str, Dict[str, Tuple[Callable, Callable]]] + self.translation_handlers: Dict[str, Dict[str, Tuple[Callable, Callable]]] = {} #: additional transforms; list of transforms - self.transforms = [] # type: List[Type[Transform]] + self.transforms: List[Type[Transform]] = [] - def add_builder(self, builder: "Type[Builder]", override: bool = False) -> None: + def add_builder(self, builder: Type[Builder], override: bool = False) -> None: logger.debug('[app] adding builder: %r', builder) if not hasattr(builder, 'name'): raise ExtensionError(__('Builder class %s has no "name" attribute') % builder) @@ -152,7 +152,7 @@ class SphinxComponentRegistry: return self.builders[name](app) - def add_domain(self, domain: "Type[Domain]", override: bool = False) -> None: + def add_domain(self, domain: Type[Domain], override: bool = False) -> None: logger.debug('[app] adding domain: %r', domain) if domain.name in self.domains and not override: raise ExtensionError(__('domain %s already registered') % domain.name) @@ -175,7 +175,7 @@ class SphinxComponentRegistry: yield domain def add_directive_to_domain(self, domain: str, name: str, - cls: "Type[Directive]", override: bool = False) -> None: + cls: Type[Directive], override: bool = False) -> None: logger.debug('[app] adding directive to domain: %r', (domain, name, cls)) if domain not in self.domains: raise ExtensionError(__('domain %s not yet registered') % domain) @@ -198,7 +198,7 @@ class SphinxComponentRegistry: (name, domain)) roles[name] = role - def add_index_to_domain(self, domain: str, index: "Type[Index]", + def add_index_to_domain(self, domain: str, index: Type[Index], override: bool = False) -> None: logger.debug('[app] adding index to domain: %r', (domain, index)) if domain not in self.domains: @@ -210,7 +210,7 @@ class SphinxComponentRegistry: indices.append(index) def add_object_type(self, directivename: str, rolename: str, indextemplate: str = '', - parse_node: Callable = None, ref_nodeclass: "Type[TextElement]" = None, + parse_node: Callable = None, ref_nodeclass: Type[TextElement] = None, objname: str = '', doc_field_types: List = [], override: bool = False ) -> None: logger.debug('[app] adding object type: %r', @@ -234,7 +234,7 @@ class SphinxComponentRegistry: object_types[directivename] = ObjType(objname or directivename, rolename) def add_crossref_type(self, directivename: str, rolename: str, indextemplate: str = '', - ref_nodeclass: "Type[TextElement]" = None, objname: str = '', + ref_nodeclass: Type[TextElement] = None, objname: str = '', override: bool = False) -> None: logger.debug('[app] adding crossref type: %r', (directivename, rolename, indextemplate, ref_nodeclass, objname)) @@ -260,7 +260,7 @@ class SphinxComponentRegistry: else: self.source_suffix[suffix] = filetype - def add_source_parser(self, parser: "Type[Parser]", override: bool = False) -> None: + def add_source_parser(self, parser: Type[Parser], override: bool = False) -> None: logger.debug('[app] adding search source_parser: %r', parser) # create a map from filetype to parser @@ -271,13 +271,13 @@ class SphinxComponentRegistry: else: self.source_parsers[filetype] = parser - def get_source_parser(self, filetype: str) -> "Type[Parser]": + def get_source_parser(self, filetype: str) -> Type[Parser]: try: return self.source_parsers[filetype] except KeyError as exc: raise SphinxError(__('Source parser for %s not registered') % filetype) from exc - def get_source_parsers(self) -> Dict[str, "Type[Parser]"]: + def get_source_parsers(self) -> Dict[str, Type[Parser]]: return self.source_parsers def create_source_parser(self, app: "Sphinx", filename: str) -> Parser: @@ -287,7 +287,10 @@ class SphinxComponentRegistry: parser.set_application(app) return parser - def get_source_input(self, filetype: str) -> "Type[Input]": + def get_source_input(self, filetype: str) -> Optional[Type[Input]]: + warnings.warn('SphinxComponentRegistry.get_source_input() is deprecated.', + RemovedInSphinx60Warning) + try: return self.source_inputs[filetype] except KeyError: @@ -297,14 +300,14 @@ class SphinxComponentRegistry: except KeyError: return None - def add_translator(self, name: str, translator: "Type[nodes.NodeVisitor]", + def add_translator(self, name: str, translator: Type[nodes.NodeVisitor], override: bool = False) -> None: logger.debug('[app] Change of translator for the %s builder.', name) if name in self.translators and not override: raise ExtensionError(__('Translator for %r already exists') % name) self.translators[name] = translator - def add_translation_handlers(self, node: "Type[Element]", + def add_translation_handlers(self, node: Type[Element], **kwargs: Tuple[Callable, Callable]) -> None: logger.debug('[app] adding translation_handlers: %r, %r', node, kwargs) for builder_name, handlers in kwargs.items(): @@ -318,7 +321,7 @@ class SphinxComponentRegistry: 'function tuple: %r=%r') % (builder_name, handlers) ) from exc - def get_translator_class(self, builder: Builder) -> "Type[nodes.NodeVisitor]": + def get_translator_class(self, builder: Builder) -> Type[nodes.NodeVisitor]: return self.translators.get(builder.name, builder.default_translator_class) @@ -340,24 +343,24 @@ class SphinxComponentRegistry: return translator - def add_transform(self, transform: "Type[Transform]") -> None: + def add_transform(self, transform: Type[Transform]) -> None: logger.debug('[app] adding transform: %r', transform) self.transforms.append(transform) - def get_transforms(self) -> List["Type[Transform]"]: + def get_transforms(self) -> List[Type[Transform]]: return self.transforms - def add_post_transform(self, transform: "Type[Transform]") -> None: + def add_post_transform(self, transform: Type[Transform]) -> None: logger.debug('[app] adding post transform: %r', transform) self.post_transforms.append(transform) - def get_post_transforms(self) -> List["Type[Transform]"]: + def get_post_transforms(self) -> List[Type[Transform]]: return self.post_transforms - def add_documenter(self, objtype: str, documenter: "Type[Documenter]") -> None: + def add_documenter(self, objtype: str, documenter: Type["Documenter"]) -> None: self.documenters[objtype] = documenter - def add_autodoc_attrgetter(self, typ: "Type", + def add_autodoc_attrgetter(self, typ: Type, attrgetter: Callable[[Any, str, Any], Any]) -> None: self.autodoc_attrgettrs[typ] = attrgetter @@ -382,7 +385,7 @@ class SphinxComponentRegistry: else: self.latex_packages.append((name, options)) - def add_enumerable_node(self, node: "Type[Node]", figtype: str, + def add_enumerable_node(self, node: Type[Node], figtype: str, title_getter: TitleGetter = None, override: bool = False) -> None: logger.debug('[app] adding enumerable node: (%r, %r, %r)', node, figtype, title_getter) if node in self.enumerable_nodes and not override: @@ -424,7 +427,7 @@ class SphinxComponentRegistry: if setup is None: logger.warning(__('extension %r has no setup() function; is it really ' 'a Sphinx extension module?'), extname) - metadata = {} # type: Dict[str, Any] + metadata: Dict[str, Any] = {} else: try: metadata = setup(app) |