Skip to content

Commit

Permalink
Merge pull request #7955 from peterbell10/alias-deprecation-message
Browse files Browse the repository at this point in the history 
Improve warning message from deprecated_alias
  • Loading branch information
@tk0miya
tk0miya committed Jul 16, 2020
2 parents aadb14b + 0000239 commit d7d14f2
Show file tree
Hide file tree
Showing 14 changed files with 133 additions and 26 deletions.
9 changes: 8 additions & 1 deletion sphinx/builders/applehelp.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,14 @@
'AppleHelpIndexerFailed': AppleHelpIndexerFailed,
'AppleHelpBuilder': AppleHelpBuilder,
},
RemovedInSphinx40Warning)
RemovedInSphinx40Warning,
{
'AppleHelpCodeSigningFailed':
'sphinxcontrib.applehelp.AppleHelpCodeSigningFailed',
'AppleHelpIndexerFailed':
'sphinxcontrib.applehelp.AppleHelpIndexerFailed',
'AppleHelpBuilder': 'sphinxcontrib.applehelp.AppleHelpBuilder',
})


def setup(app: Sphinx) -> Dict[str, Any]:
Expand Down
5 changes: 4 additions & 1 deletion sphinx/builders/devhelp.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,10 @@
{
'DevhelpBuilder': DevhelpBuilder,
},
RemovedInSphinx40Warning)
RemovedInSphinx40Warning,
{
'DevhelpBuilder': 'sphinxcontrib.devhelp.DevhelpBuilder'
})


def setup(app: Sphinx) -> Dict[str, Any]:
Expand Down
7 changes: 5 additions & 2 deletions sphinx/builders/dirhtml.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -49,9 +49,12 @@ def get_outfilename(self, pagename: str) -> str:
# for compatibility
deprecated_alias('sphinx.builders.html',
{
'DirectoryHTMLBuilder': DirectoryHTMLBuilder,
'DirectoryHTMLBuilder': DirectoryHTMLBuilder,
},
RemovedInSphinx40Warning)
RemovedInSphinx40Warning,
{
'DirectoryHTMLBuilder': 'sphinx.builders.dirhtml.DirectoryHTMLBuilder',
})


def setup(app: Sphinx) -> Dict[str, Any]:
Expand Down
11 changes: 9 additions & 2 deletions sphinx/builders/htmlhelp.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,10 +24,17 @@
{
'chm_locales': chm_locales,
'chm_htmlescape': chm_htmlescape,
'HTMLHelpBuilder': HTMLHelpBuilder,
'HTMLHelpBuilder': HTMLHelpBuilder,
'default_htmlhelp_basename': default_htmlhelp_basename,
},
RemovedInSphinx40Warning)
RemovedInSphinx40Warning,
{
'chm_locales': 'sphinxcontrib.htmlhelp.chm_locales',
'chm_htmlescape': 'sphinxcontrib.htmlhelp.chm_htmlescape',
'HTMLHelpBuilder': 'sphinxcontrib.htmlhelp.HTMLHelpBuilder',
'default_htmlhelp_basename':
'sphinxcontrib.htmlhelp.default_htmlhelp_basename',
})


def setup(app: Sphinx) -> Dict[str, Any]:
Expand Down
6 changes: 5 additions & 1 deletion sphinx/builders/qthelp.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,11 @@
'render_file': render_file,
'QtHelpBuilder': QtHelpBuilder,
},
RemovedInSphinx40Warning)
RemovedInSphinx40Warning,
{
'render_file': 'sphinxcontrib.qthelp.render_file',
'QtHelpBuilder': 'sphinxcontrib.qthelp.QtHelpBuilder',
})


def setup(app: Sphinx) -> Dict[str, Any]:
Expand Down
6 changes: 5 additions & 1 deletion sphinx/builders/singlehtml.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -193,7 +193,11 @@ def write_additional_files(self) -> None:
{
'SingleFileHTMLBuilder': SingleFileHTMLBuilder,
},
RemovedInSphinx40Warning)
RemovedInSphinx40Warning,
{
'SingleFileHTMLBuilder':
'sphinx.builders.singlehtml.SingleFileHTMLBuilder',
})


def setup(app: Sphinx) -> Dict[str, Any]:
Expand Down
32 changes: 22 additions & 10 deletions sphinx/deprecation.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,27 +29,39 @@ class RemovedInSphinx50Warning(PendingDeprecationWarning):
RemovedInNextVersionWarning = RemovedInSphinx40Warning


def deprecated_alias(modname: str, objects: Dict, warning: "Type[Warning]") -> None:
def deprecated_alias(modname: str, objects: Dict[str, object],
warning: "Type[Warning]", names: Dict[str, str] = None) -> None:
module = import_module(modname)
sys.modules[modname] = _ModuleWrapper(module, modname, objects, warning) # type: ignore
sys.modules[modname] = _ModuleWrapper( # type: ignore
module, modname, objects, warning, names)


class _ModuleWrapper:
def __init__(self, module: Any, modname: str, objects: Dict, warning: "Type[Warning]"
) -> None:
def __init__(self, module: Any, modname: str,
objects: Dict[str, object],
warning: "Type[Warning]",
names: Dict[str, str]) -> None:
self._module = module
self._modname = modname
self._objects = objects
self._warning = warning
self._names = names

def __getattr__(self, name: str) -> Any:
if name in self._objects:
warnings.warn("%s.%s is deprecated. Check CHANGES for Sphinx "
"API modifications." % (self._modname, name),
if name not in self._objects:
return getattr(self._module, name)

canonical_name = self._names.get(name, None)
if canonical_name is not None:
warnings.warn(
"The alias '{}.{}' is deprecated, use '{}' instead. Check CHANGES for "
"Sphinx API modifications.".format(self._modname, name, canonical_name),
self._warning, stacklevel=3)
else:
warnings.warn("{}.{} is deprecated. Check CHANGES for Sphinx "
"API modifications.".format(self._modname, name),
self._warning, stacklevel=3)
return self._objects[name]

return getattr(self._module, name)
return self._objects[name]


class DeprecatedDict(dict):
Expand Down
26 changes: 24 additions & 2 deletions sphinx/directives/__init__.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -298,13 +298,35 @@ def run(self) -> List[Node]:
'Figure': Figure,
'Meta': Meta,
},
RemovedInSphinx40Warning)
RemovedInSphinx40Warning,
{
'Highlight': 'sphinx.directives.code.Highlight',
'CodeBlock': 'sphinx.directives.code.CodeBlock',
'LiteralInclude': 'sphinx.directives.code.LiteralInclude',
'TocTree': 'sphinx.directives.other.TocTree',
'Author': 'sphinx.directives.other.Author',
'Index': 'sphinx.directives.other.IndexDirective',
'VersionChange': 'sphinx.directives.other.VersionChange',
'SeeAlso': 'sphinx.directives.other.SeeAlso',
'TabularColumns': 'sphinx.directives.other.TabularColumns',
'Centered': 'sphinx.directives.other.Centered',
'Acks': 'sphinx.directives.other.Acks',
'HList': 'sphinx.directives.other.HList',
'Only': 'sphinx.directives.other.Only',
'Include': 'sphinx.directives.other.Include',
'Class': 'sphinx.directives.other.Class',
'Figure': 'sphinx.directives.patches.Figure',
'Meta': 'sphinx.directives.patches.Meta',
})

deprecated_alias('sphinx.directives',
{
'DescDirective': ObjectDescription,
},
RemovedInSphinx50Warning)
RemovedInSphinx50Warning,
{
'DescDirective': 'sphinx.directives.ObjectDescription',
})


def setup(app: "Sphinx") -> Dict[str, Any]:
Expand Down
5 changes: 4 additions & 1 deletion sphinx/directives/other.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -368,7 +368,10 @@ def run(self) -> List[Node]:
{
'Index': IndexDirective,
},
RemovedInSphinx40Warning)
RemovedInSphinx40Warning,
{
'Index': 'sphinx.domains.index.IndexDirective',
})


def setup(app: "Sphinx") -> Dict[str, Any]:
Expand Down
9 changes: 8 additions & 1 deletion sphinx/ext/autodoc/importer.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -194,4 +194,11 @@ def get_object_members(subject: Any, objpath: List[str], attrgetter: Callable,
'MockLoader': MockLoader,
'mock': mock,
},
RemovedInSphinx40Warning)
RemovedInSphinx40Warning,
{
'_MockModule': 'sphinx.ext.autodoc.mock._MockModule',
'_MockObject': 'sphinx.ext.autodoc.mock._MockObject',
'MockFinder': 'sphinx.ext.autodoc.mock.MockFinder',
'MockLoader': 'sphinx.ext.autodoc.mock.MockLoader',
'mock': 'sphinx.ext.autodoc.mock.mock',
})
6 changes: 5 additions & 1 deletion sphinx/io.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -229,4 +229,8 @@ def read_doc(app: "Sphinx", env: BuildEnvironment, filename: str) -> nodes.docum
'FiletypeNotFoundError': FiletypeNotFoundError,
'get_filetype': get_filetype,
},
RemovedInSphinx40Warning)
RemovedInSphinx40Warning,
{
'FiletypeNotFoundError': 'sphinx.errors.FiletypeNotFoundError',
'get_filetype': 'sphinx.util.get_filetype',
})
8 changes: 7 additions & 1 deletion sphinx/transforms/__init__.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -410,7 +410,13 @@ def apply(self, **kwargs: Any) -> None:
'CitationReferences': CitationReferenceTransform,
'SmartQuotesSkipper': CitationDefinitionTransform,
},
RemovedInSphinx40Warning)
RemovedInSphinx40Warning,
{
'CitationReferences':
'sphinx.domains.citation.CitationReferenceTransform',
'SmartQuotesSkipper':
'sphinx.domains.citation.CitationDefinitionTransform',
})


def setup(app: "Sphinx") -> Dict[str, Any]:
Expand Down
10 changes: 9 additions & 1 deletion sphinx/util/pycompat.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -99,4 +99,12 @@ def execfile_(filepath: str, _globals: Any, open: Callable = open) -> None:
'sys_encoding': sys.getdefaultencoding(),
'u': '',
},
RemovedInSphinx40Warning)
RemovedInSphinx40Warning,
{
'NoneType': 'sphinx.util.typing.NoneType',
'TextIOWrapper': 'io.TextIOWrapper',
'htmlescape': 'html.escape',
'indent': 'textwrap.indent',
'terminal_safe': 'sphinx.util.console.terminal_safe',
'sys_encoding': 'sys.getdefaultencoding',
})
19 changes: 18 additions & 1 deletion sphinx/writers/latex.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2140,7 +2140,24 @@ def generate_numfig_format(self, builder: "LaTeXBuilder") -> str:
'XELATEX_GREEK_DEFAULT_FONTPKG': constants.XELATEX_GREEK_DEFAULT_FONTPKG,
'ExtBabel': ExtBabel,
},
RemovedInSphinx40Warning)
RemovedInSphinx40Warning,
{
'ADDITIONAL_SETTINGS':
'sphinx.builders.latex.constants.ADDITIONAL_SETTINGS',
'DEFAULT_SETTINGS':
'sphinx.builders.latex.constants.DEFAULT_SETTINGS',
'LUALATEX_DEFAULT_FONTPKG':
'sphinx.builders.latex.constants.LUALATEX_DEFAULT_FONTPKG',
'PDFLATEX_DEFAULT_FONTPKG':
'sphinx.builders.latex.constants.PDFLATEX_DEFAULT_FONTPKG',
'SHORTHANDOFF':
'sphinx.builders.latex.constants.SHORTHANDOFF',
'XELATEX_DEFAULT_FONTPKG':
'sphinx.builders.latex.constants.XELATEX_DEFAULT_FONTPKG',
'XELATEX_GREEK_DEFAULT_FONTPKG':
'sphinx.builders.latex.constants.XELATEX_GREEK_DEFAULT_FONTPKG',
'ExtBabel': 'sphinx.builders.latex.util.ExtBabel',
})

# FIXME: Workaround to avoid circular import
# refs: https://github.com/sphinx-doc/sphinx/issues/5433
Expand Down

0 comments on commit d7d14f2

Please sign in to comment.