Skip to content

Commit

Permalink
Merge branch '3.4.x' into 8602_process-docstring_for_nondatadescriptors
Browse files Browse the repository at this point in the history
  • Loading branch information
tk0miya authored Dec 31, 2020
2 parents 97f36a2 + 3f560cd commit e3b1fde
Show file tree
Hide file tree
Showing 10 changed files with 95 additions and 4 deletions.
1 change: 1 addition & 0 deletions CHANGES
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ Features added
Bugs fixed
----------

* #8164: autodoc: Classes that inherit mocked class are not documented
* #8602: autodoc: The ``autodoc-process-docstring`` event is emitted to the
non-datadescriptors unexpectedly

Expand Down
1 change: 1 addition & 0 deletions setup.cfg
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,7 @@ filterwarnings =
all
ignore::DeprecationWarning:docutils.io
ignore::DeprecationWarning:pyximport.pyximport
ignore::ImportWarning:importlib._bootstrap
ignore::PendingDeprecationWarning:sphinx.util.pycompat
markers =
apidoc
Expand Down
4 changes: 2 additions & 2 deletions sphinx/ext/autodoc/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@
from sphinx.environment import BuildEnvironment
from sphinx.ext.autodoc.importer import (get_class_members, get_module_members,
get_object_members, import_object)
from sphinx.ext.autodoc.mock import mock
from sphinx.ext.autodoc.mock import ismock, mock
from sphinx.locale import _, __
from sphinx.pycode import ModuleAnalyzer, PycodeError
from sphinx.util import inspect, logging
Expand Down Expand Up @@ -731,7 +731,7 @@ def is_filtered_inherited_member(name: str) -> bool:
isprivate = membername.startswith('_')

keep = False
if safe_getattr(member, '__sphinx_mock__', None) is not None:
if ismock(member):
# mocked module or object
pass
elif self.options.exclude_members and membername in self.options.exclude_members:
Expand Down
22 changes: 22 additions & 0 deletions sphinx/ext/autodoc/mock.py
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@
from typing import Any, Generator, Iterator, List, Sequence, Tuple, Union

from sphinx.util import logging
from sphinx.util.inspect import safe_getattr

logger = logging.getLogger(__name__)

Expand Down Expand Up @@ -147,3 +148,24 @@ def mock(modnames: List[str]) -> Generator[None, None, None]:
finally:
sys.meta_path.remove(finder)
finder.invalidate_caches()


def ismock(subject: Any) -> bool:
"""Check if the object is mocked."""
# check the object has '__sphinx_mock__' attribute
if not hasattr(subject, '__sphinx_mock__'):
return False

# check the object is mocked module
if isinstance(subject, _MockModule):
return True

try:
# check the object is mocked object
__mro__ = safe_getattr(type(subject), '__mro__', [])
if len(__mro__) > 2 and __mro__[1] is _MockObject:
return True
except AttributeError:
pass

return False
12 changes: 12 additions & 0 deletions sphinx/testing/fixtures.py
Original file line number Diff line number Diff line change
Expand Up @@ -250,3 +250,15 @@ def tempdir(tmpdir: str) -> "util.path":
this fixture is for compat with old test implementation.
"""
return util.path(tmpdir)


@pytest.fixture
def rollback_sysmodules():
"""Rollback sys.modules to before testing to unload modules during tests."""
try:
sysmodules = list(sys.modules)
yield
finally:
for modname in list(sys.modules):
if modname not in sysmodules:
sys.modules.pop(modname)
5 changes: 5 additions & 0 deletions tests/roots/test-ext-autodoc/target/need_mocks.py
Original file line number Diff line number Diff line change
Expand Up @@ -28,4 +28,9 @@ def decoratedMethod(self):
return None


class Inherited(missing_module.Class):
"""docstring"""
pass


sphinx.missing_module4.missing_function(len(missing_name2))
31 changes: 31 additions & 0 deletions tests/test_ext_autodoc_automodule.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
"""
test_ext_autodoc_autocmodule
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Test the autodoc extension. This tests mainly the Documenters; the auto
directives are tested in a test source file translated by test_build.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

import sys

import pytest

from .test_ext_autodoc import do_autodoc


@pytest.mark.sphinx('html', testroot='ext-autodoc',
confoverrides={'autodoc_mock_imports': ['missing_module',
'missing_package1',
'missing_package2',
'missing_package3',
'sphinx.missing_module4']})
@pytest.mark.usefixtures("rollback_sysmodules")
def test_subclass_of_mocked_object(app):
sys.modules.pop('target', None) # unload target module to clear the module cache

options = {'members': True}
actual = do_autodoc(app, 'module', 'target.need_mocks', options)
assert '.. py:class:: Inherited(*args: Any, **kwargs: Any)' in actual
3 changes: 3 additions & 0 deletions tests/test_ext_autodoc_configs.py
Original file line number Diff line number Diff line change
Expand Up @@ -429,7 +429,10 @@ def test_autoclass_content_and_docstring_signature_both(app):


@pytest.mark.sphinx('html', testroot='ext-autodoc')
@pytest.mark.usefixtures("rollback_sysmodules")
def test_mocked_module_imports(app, warning):
sys.modules.pop('target', None) # unload target module to clear the module cache

# no autodoc_mock_imports
options = {"members": 'TestAutodoc,decoratedFunction,func'}
actual = do_autodoc(app, 'module', 'target.need_mocks', options)
Expand Down
18 changes: 17 additions & 1 deletion tests/test_ext_autodoc_mock.py
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@

import pytest

from sphinx.ext.autodoc.mock import _MockModule, _MockObject, mock
from sphinx.ext.autodoc.mock import _MockModule, _MockObject, ismock, mock


def test_MockModule():
Expand Down Expand Up @@ -129,3 +129,19 @@ class Bar:
assert func.__doc__ == "docstring"
assert Foo.meth.__doc__ == "docstring"
assert Bar.__doc__ == "docstring"


def test_ismock():
with mock(['sphinx.unknown']):
mod1 = import_module('sphinx.unknown')
mod2 = import_module('sphinx.application')

class Inherited(mod1.Class):
pass

assert ismock(mod1) is True
assert ismock(mod1.Class) is True
assert ismock(Inherited) is False

assert ismock(mod2) is False
assert ismock(mod2.Sphinx) is False
2 changes: 1 addition & 1 deletion tox.ini
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ deps =
extras =
test
setenv =
PYTHONWARNINGS = all,ignore::ImportWarning:importlib._bootstrap_external,ignore::DeprecationWarning:site,ignore::DeprecationWarning:distutils
PYTHONWARNINGS = all,ignore::ImportWarning:importlib._bootstrap_external,ignore::DeprecationWarning:site,ignore::DeprecationWarning:distutils,ignore::DeprecationWarning:pip._vendor.packaging.version
PYTEST_ADDOPTS = {env:PYTEST_ADDOPTS:} --color yes
commands=
python -X dev -m pytest --durations 25 {posargs}
Expand Down

0 comments on commit e3b1fde

Please sign in to comment.