diff options
Diffstat (limited to 'sphinx/registry.py')
| -rw-r--r-- | sphinx/registry.py | 182 |
1 files changed, 91 insertions, 91 deletions
diff --git a/sphinx/registry.py b/sphinx/registry.py index 4fd808f04..311270ccb 100644 --- a/sphinx/registry.py +++ b/sphinx/registry.py @@ -1,4 +1,3 @@ -# -*- coding: utf-8 -*- """ sphinx.registry ~~~~~~~~~~~~~~~ @@ -8,7 +7,6 @@ :copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS. :license: BSD, see LICENSE for details. """ -from __future__ import print_function import traceback import warnings @@ -17,7 +15,6 @@ from types import MethodType from docutils.parsers.rst import Directive from pkg_resources import iter_entry_points -from six import iteritems, itervalues from sphinx.deprecation import RemovedInSphinx30Warning from sphinx.domains import ObjType @@ -29,6 +26,7 @@ from sphinx.parsers import Parser as SphinxParser from sphinx.roles import XRefRole from sphinx.util import logging from sphinx.util.docutils import directive_helper +from sphinx.util.logging import prefixed_warnings if False: # For type annotation @@ -43,6 +41,7 @@ if False: from sphinx.domains import Domain, Index # NOQA from sphinx.environment import BuildEnvironment # NOQA from sphinx.ext.autodoc import Documenter # NOQA + from sphinx.io import SphinxFileInput # NOQA from sphinx.util.typing import RoleFunction, TitleGetter # NOQA logger = logging.getLogger(__name__) @@ -51,76 +50,76 @@ logger = logging.getLogger(__name__) # Values are Sphinx version that merge the extension. EXTENSION_BLACKLIST = { "sphinxjp.themecore": "1.2" -} # type: Dict[unicode, unicode] +} -class SphinxComponentRegistry(object): +class SphinxComponentRegistry: def __init__(self): # type: () -> None #: special attrgetter for autodoc; class object -> attrgetter - self.autodoc_attrgettrs = {} # type: Dict[Type, Callable[[Any, unicode, Any], Any]] + self.autodoc_attrgettrs = {} # type: Dict[Type, Callable[[Any, str, Any], Any]] #: builders; a dict of builder name -> bulider class - self.builders = {} # type: Dict[unicode, Type[Builder]] + self.builders = {} # type: Dict[str, Type[Builder]] #: autodoc documenters; a dict of documenter name -> documenter class - self.documenters = {} # type: Dict[unicode, Type[Documenter]] + self.documenters = {} # type: Dict[str, Type[Documenter]] #: css_files; a list of tuple of filename and attributes - self.css_files = [] # type: List[Tuple[unicode, Dict[unicode, unicode]]] + self.css_files = [] # type: List[Tuple[str, Dict[str, str]]] #: domains; a dict of domain name -> domain class - self.domains = {} # type: Dict[unicode, Type[Domain]] + self.domains = {} # type: Dict[str, Type[Domain]] #: additional directives for domains #: a dict of domain name -> dict of directive name -> directive - self.domain_directives = {} # type: Dict[unicode, Dict[unicode, Any]] + self.domain_directives = {} # type: Dict[str, Dict[str, Any]] #: additional indices for domains #: a dict of domain name -> list of index class - self.domain_indices = {} # type: Dict[unicode, List[Type[Index]]] + self.domain_indices = {} # type: 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[unicode, Dict[unicode, ObjType]] + self.domain_object_types = {} # type: 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[unicode, Dict[unicode, Union[RoleFunction, XRefRole]]] # NOQA + self.domain_roles = {} # type: Dict[str, Dict[str, Union[RoleFunction, XRefRole]]] # NOQA #: additional enumerable nodes #: a dict of node class -> tuple of figtype and title_getter function - self.enumerable_nodes = {} # type: Dict[nodes.Node, Tuple[unicode, TitleGetter]] + self.enumerable_nodes = {} # type: Dict[Type[nodes.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[unicode, Tuple[Callable, Callable]] # NOQA - self.html_block_math_renderers = {} # type: Dict[unicode, Tuple[Callable, Callable]] # NOQA + self.html_inline_math_renderers = {} # type: Dict[str, Tuple[Callable, Callable]] + self.html_block_math_renderers = {} # type: Dict[str, Tuple[Callable, Callable]] #: js_files; list of JS paths or URLs - self.js_files = [] # type: List[Tuple[unicode, Dict[unicode, unicode]]] + self.js_files = [] # type: List[Tuple[str, Dict[str, str]]] #: LaTeX packages; list of package names and its options - self.latex_packages = [] # type: List[Tuple[unicode, unicode]] + self.latex_packages = [] # type: List[Tuple[str, str]] #: post transforms; list of transforms self.post_transforms = [] # type: List[Type[Transform]] #: source paresrs; file type -> parser class - self.source_parsers = {} # type: Dict[unicode, Type[Parser]] + self.source_parsers = {} # type: Dict[str, Type[Parser]] #: source inputs; file type -> input class - self.source_inputs = {} # type: Dict[unicode, Input] + self.source_inputs = {} # type: Dict[str, Type[Input]] #: source suffix: suffix -> file type - self.source_suffix = {} # type: Dict[unicode, unicode] + self.source_suffix = {} # type: Dict[str, str] #: custom translators; builder name -> translator class - self.translators = {} # type: Dict[unicode, nodes.NodeVisitor] + self.translators = {} # type: 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[unicode, Dict[unicode, Tuple[Callable, Callable]]] # NOQA + self.translation_handlers = {} # type: Dict[str, Dict[str, Tuple[Callable, Callable]]] #: additional transforms; list of transforms self.transforms = [] # type: List[Type[Transform]] @@ -136,7 +135,7 @@ class SphinxComponentRegistry(object): self.builders[builder.name] = builder def preload_builder(self, app, name): - # type: (Sphinx, unicode) -> None + # type: (Sphinx, str) -> None if name is None: return @@ -151,7 +150,7 @@ class SphinxComponentRegistry(object): self.load_extension(app, entry_point.module_name) def create_builder(self, app, name): - # type: (Sphinx, unicode) -> Builder + # type: (Sphinx, str) -> Builder if name not in self.builders: raise SphinxError(__('Builder name %s not registered') % name) @@ -165,19 +164,19 @@ class SphinxComponentRegistry(object): self.domains[domain.name] = domain def has_domain(self, domain): - # type: (unicode) -> bool + # type: (str) -> bool return domain in self.domains def create_domains(self, env): # type: (BuildEnvironment) -> Iterator[Domain] - for DomainClass in itervalues(self.domains): + for DomainClass in self.domains.values(): domain = DomainClass(env) # transplant components added by extensions domain.directives.update(self.domain_directives.get(domain.name, {})) domain.roles.update(self.domain_roles.get(domain.name, {})) domain.indices.extend(self.domain_indices.get(domain.name, [])) - for name, objtype in iteritems(self.domain_object_types.get(domain.name, {})): + for name, objtype in self.domain_object_types.get(domain.name, {}).items(): domain.add_object_type(name, objtype) yield domain @@ -191,7 +190,7 @@ class SphinxComponentRegistry(object): def add_directive_to_domain(self, domain, name, obj, has_content=None, argument_spec=None, override=False, **option_spec): - # type: (unicode, unicode, Any, bool, Any, bool, Any) -> None + # type: (str, str, Any, bool, Any, bool, Any) -> None logger.debug('[app] adding directive to domain: %r', (domain, name, obj, has_content, argument_spec, option_spec)) if domain not in self.domains: @@ -207,7 +206,7 @@ class SphinxComponentRegistry(object): directives[name] = obj def add_role_to_domain(self, domain, name, role, override=False): - # type: (unicode, unicode, Union[RoleFunction, XRefRole], bool) -> None + # type: (str, str, Union[RoleFunction, XRefRole], bool) -> None logger.debug('[app] adding role to domain: %r', (domain, name, role)) if domain not in self.domains: raise ExtensionError(__('domain %s not yet registered') % domain) @@ -218,7 +217,7 @@ class SphinxComponentRegistry(object): roles[name] = role def add_index_to_domain(self, domain, index, override=False): - # type: (unicode, Type[Index], bool) -> None + # type: (str, Type[Index], bool) -> None logger.debug('[app] adding index to domain: %r', (domain, index)) if domain not in self.domains: raise ExtensionError(__('domain %s not yet registered') % domain) @@ -231,13 +230,13 @@ class SphinxComponentRegistry(object): def add_object_type(self, directivename, rolename, indextemplate='', parse_node=None, ref_nodeclass=None, objname='', doc_field_types=[], override=False): - # type: (unicode, unicode, unicode, Callable, nodes.Node, unicode, List, bool) -> None + # type: (str, str, str, Callable, Type[nodes.TextElement], str, List, bool) -> None logger.debug('[app] adding object type: %r', (directivename, rolename, indextemplate, parse_node, ref_nodeclass, objname, doc_field_types)) # create a subclass of GenericObject as the new directive - directive = type(directivename, # type: ignore + directive = type(directivename, (GenericObject, object), {'indextemplate': indextemplate, 'parse_node': staticmethod(parse_node), @@ -254,12 +253,12 @@ class SphinxComponentRegistry(object): def add_crossref_type(self, directivename, rolename, indextemplate='', ref_nodeclass=None, objname='', override=False): - # type: (unicode, unicode, unicode, nodes.Node, unicode, bool) -> None + # type: (str, str, str, Type[nodes.TextElement], str, bool) -> None logger.debug('[app] adding crossref type: %r', (directivename, rolename, indextemplate, ref_nodeclass, objname)) # create a subclass of Target as the new directive - directive = type(directivename, # type: ignore + directive = type(directivename, (Target, object), {'indextemplate': indextemplate}) @@ -273,7 +272,7 @@ class SphinxComponentRegistry(object): object_types[directivename] = ObjType(objname or directivename, rolename) def add_source_suffix(self, suffix, filetype, override=False): - # type: (unicode, unicode, bool) -> None + # type: (str, str, bool) -> None logger.debug('[app] adding source_suffix: %r, %r', suffix, filetype) if suffix in self.source_suffix and not override: raise ExtensionError(__('source_suffix %r is already registered') % suffix) @@ -285,7 +284,7 @@ class SphinxComponentRegistry(object): logger.debug('[app] adding search source_parser: %r', args) if len(args) == 1: # new sytle arguments: (source_parser) - suffix = None # type: unicode + suffix = None # type: str parser = args[0] # type: Type[Parser] else: # old style arguments: (suffix, source_parser) @@ -318,18 +317,18 @@ class SphinxComponentRegistry(object): self.source_parsers[suffix] = parser def get_source_parser(self, filetype): - # type: (unicode) -> Type[Parser] + # type: (str) -> Type[Parser] try: return self.source_parsers[filetype] except KeyError: raise SphinxError(__('Source parser for %s not registered') % filetype) def get_source_parsers(self): - # type: () -> Dict[unicode, Parser] + # type: () -> Dict[str, Type[Parser]] return self.source_parsers def create_source_parser(self, app, filename): - # type: (Sphinx, unicode) -> Parser + # type: (Sphinx, str) -> Parser parser_class = self.get_source_parser(filename) parser = parser_class() if isinstance(parser, SphinxParser): @@ -337,7 +336,9 @@ class SphinxComponentRegistry(object): return parser def add_source_input(self, input_class, override=False): - # type: (Type[Input], bool) -> None + # type: (Type[SphinxFileInput], bool) -> None + warnings.warn('registry.source_input() is deprecated.', + RemovedInSphinx30Warning, stacklevel=2) for filetype in input_class.supported: if filetype in self.source_inputs and not override: raise ExtensionError(__('source_input for %r is already registered') % @@ -345,7 +346,7 @@ class SphinxComponentRegistry(object): self.source_inputs[filetype] = input_class def get_source_input(self, filetype): - # type: (unicode) -> Type[Input] + # type: (str) -> Type[Input] try: return self.source_inputs[filetype] except KeyError: @@ -353,19 +354,19 @@ class SphinxComponentRegistry(object): # use special source_input for unknown filetype return self.source_inputs['*'] except KeyError: - raise SphinxError(__('source_input for %s not registered') % filetype) + return None def add_translator(self, name, translator, override=False): - # type: (unicode, Type[nodes.NodeVisitor], bool) -> None + # type: (str, Type[nodes.NodeVisitor], bool) -> 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, **kwargs): - # type: (nodes.Node, Any) -> None + # type: (Type[nodes.Element], Any) -> None logger.debug('[app] adding translation_handlers: %r, %r', node, kwargs) - for builder_name, handlers in iteritems(kwargs): + for builder_name, handlers in kwargs.items(): translation_handlers = self.translation_handlers.setdefault(builder_name, {}) try: visit, depart = handlers # unpack once for assertion @@ -391,7 +392,7 @@ class SphinxComponentRegistry(object): # retry with builder.format handlers = self.translation_handlers.get(builder.format, {}) - for name, (visit, depart) in iteritems(handlers): + for name, (visit, depart) in handlers.items(): setattr(translator, 'visit_' + name, MethodType(visit, translator)) if depart: setattr(translator, 'depart_' + name, MethodType(depart, translator)) @@ -417,35 +418,35 @@ class SphinxComponentRegistry(object): return self.post_transforms def add_documenter(self, objtype, documenter): - # type: (unicode, Type[Documenter]) -> None + # type: (str, Type[Documenter]) -> None self.documenters[objtype] = documenter def add_autodoc_attrgetter(self, typ, attrgetter): - # type: (Type, Callable[[Any, unicode, Any], Any]) -> None + # type: (Type, Callable[[Any, str, Any], Any]) -> None self.autodoc_attrgettrs[typ] = attrgetter def add_css_files(self, filename, **attributes): self.css_files.append((filename, attributes)) def add_js_file(self, filename, **attributes): - # type: (unicode, **unicode) -> None + # type: (str, **str) -> None logger.debug('[app] adding js_file: %r, %r', filename, attributes) - self.js_files.append((filename, attributes)) # type: ignore + self.js_files.append((filename, attributes)) def add_latex_package(self, name, options): - # type: (unicode, unicode) -> None + # type: (str, str) -> None logger.debug('[app] adding latex package: %r', name) self.latex_packages.append((name, options)) def add_enumerable_node(self, node, figtype, title_getter=None, override=False): - # type: (nodes.Node, unicode, TitleGetter, bool) -> None + # type: (Type[nodes.Node], str, TitleGetter, bool) -> None logger.debug('[app] adding enumerable node: (%r, %r, %r)', node, figtype, title_getter) if node in self.enumerable_nodes and not override: raise ExtensionError(__('enumerable_node %r already registered') % node) self.enumerable_nodes[node] = (figtype, title_getter) def add_html_math_renderer(self, name, inline_renderers, block_renderers): - # type: (unicode, Tuple[Callable, Callable], Tuple[Callable, Callable]) -> None + # type: (str, Tuple[Callable, Callable], Tuple[Callable, Callable]) -> None logger.debug('[app] adding html_math_renderer: %s, %r, %r', name, inline_renderers, block_renderers) if name in self.html_inline_math_renderers: @@ -455,7 +456,7 @@ class SphinxComponentRegistry(object): self.html_block_math_renderers[name] = block_renderers def load_extension(self, app, extname): - # type: (Sphinx, unicode) -> None + # type: (Sphinx, str) -> None """Load a Sphinx extension.""" if extname in app.extensions: # alread loaded return @@ -466,42 +467,41 @@ class SphinxComponentRegistry(object): return # update loading context - app._setting_up_extension.append(extname) - - try: - mod = __import__(extname, None, None, ['setup']) - except ImportError as err: - logger.verbose(__('Original exception:\n') + traceback.format_exc()) - raise ExtensionError(__('Could not import extension %s') % extname, err) - - if not hasattr(mod, 'setup'): - logger.warning(__('extension %r has no setup() function; is it really ' - 'a Sphinx extension module?'), extname) - metadata = {} # type: Dict[unicode, Any] - else: + prefix = __('while setting up extension %s:') % extname + with prefixed_warnings(prefix): try: - metadata = mod.setup(app) - except VersionRequirementError as err: - # add the extension name to the version required - raise VersionRequirementError( - __('The %s extension used by this project needs at least ' - 'Sphinx v%s; it therefore cannot be built with this ' - 'version.') % (extname, err) - ) - - if metadata is None: - metadata = {} - elif not isinstance(metadata, dict): - logger.warning(__('extension %r returned an unsupported object from ' - 'its setup() function; it should return None or a ' - 'metadata dictionary'), extname) - metadata = {} - - app.extensions[extname] = Extension(extname, mod, **metadata) - app._setting_up_extension.pop() + mod = __import__(extname, None, None, ['setup']) + except ImportError as err: + logger.verbose(__('Original exception:\n') + traceback.format_exc()) + raise ExtensionError(__('Could not import extension %s') % extname, err) + + if not hasattr(mod, 'setup'): + logger.warning(__('extension %r has no setup() function; is it really ' + 'a Sphinx extension module?'), extname) + metadata = {} # type: Dict[str, Any] + else: + try: + metadata = mod.setup(app) + except VersionRequirementError as err: + # add the extension name to the version required + raise VersionRequirementError( + __('The %s extension used by this project needs at least ' + 'Sphinx v%s; it therefore cannot be built with this ' + 'version.') % (extname, err) + ) + + if metadata is None: + metadata = {} + elif not isinstance(metadata, dict): + logger.warning(__('extension %r returned an unsupported object from ' + 'its setup() function; it should return None or a ' + 'metadata dictionary'), extname) + metadata = {} + + app.extensions[extname] = Extension(extname, mod, **metadata) def get_envversion(self, app): - # type: (Sphinx) -> Dict[unicode, unicode] + # type: (Sphinx) -> Dict[str, str] from sphinx.environment import ENV_VERSION envversion = {ext.name: ext.metadata['env_version'] for ext in app.extensions.values() if ext.metadata.get('env_version')} @@ -512,7 +512,7 @@ class SphinxComponentRegistry(object): def merge_source_suffix(app, config): # type: (Sphinx, Config) -> None """Merge source_suffix which specified by user and added by extensions.""" - for suffix, filetype in iteritems(app.registry.source_suffix): + for suffix, filetype in app.registry.source_suffix.items(): if suffix not in app.config.source_suffix: app.config.source_suffix[suffix] = filetype elif app.config.source_suffix[suffix] is None: @@ -525,7 +525,7 @@ def merge_source_suffix(app, config): def setup(app): - # type: (Sphinx) -> Dict[unicode, Any] + # type: (Sphinx) -> Dict[str, Any] app.connect('config-inited', merge_source_suffix) return { |