From 620d457756b519ba6b6c52c10412b84ea7c46ceb Mon Sep 17 00:00:00 2001 From: Daniel Hahler Date: Mon, 2 Mar 2020 17:08:37 +0100 Subject: [PATCH 01/12] doc: add __tracebackhide__ label --- doc/en/example/simple.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/en/example/simple.rst b/doc/en/example/simple.rst index 1a5c5b444..c25f4d53b 100644 --- a/doc/en/example/simple.rst +++ b/doc/en/example/simple.rst @@ -218,8 +218,10 @@ Or run it including the ``slow`` marked test: ============================ 2 passed in 0.12s ============================= +.. _`__tracebackhide__`: + Writing well integrated assertion helpers --------------------------------------------------- +----------------------------------------- .. regendoc:wipe From a42e85ed54804bc86ae1a65eeb91a6746b23f6a9 Mon Sep 17 00:00:00 2001 From: Daniel Hahler Date: Tue, 3 Mar 2020 18:12:12 +0100 Subject: [PATCH 02/12] Fix documentation for _pytest.pytester.RunResult When using `(i)var` in the class docstring it would link `duration` to `_pytest.runner.TestReport.duration`. This moves the docstrings to the attributes properly. --- src/_pytest/pytester.py | 24 +++++++++++------------- 1 file changed, 11 insertions(+), 13 deletions(-) diff --git a/src/_pytest/pytester.py b/src/_pytest/pytester.py index 9df3ed779..f25f8e10c 100644 --- a/src/_pytest/pytester.py +++ b/src/_pytest/pytester.py @@ -395,19 +395,7 @@ rex_outcome = re.compile(r"(\d+) (\w+)") class RunResult: - """The result of running a command. - - Attributes: - - :ivar ret: the return value - :ivar outlines: list of lines captured from stdout - :ivar errlines: list of lines captured from stderr - :ivar stdout: :py:class:`LineMatcher` of stdout, use ``stdout.str()`` to - reconstruct stdout or the commonly used ``stdout.fnmatch_lines()`` - method - :ivar stderr: :py:class:`LineMatcher` of stderr - :ivar duration: duration in seconds - """ + """The result of running a command.""" def __init__( self, @@ -418,13 +406,23 @@ class RunResult: ) -> None: try: self.ret = pytest.ExitCode(ret) # type: Union[int, ExitCode] + """the return value""" except ValueError: self.ret = ret self.outlines = outlines + """list of lines captured from stdout""" self.errlines = errlines + """list of lines captured from stderr""" self.stdout = LineMatcher(outlines) + """:class:`LineMatcher` of stdout. + + Use e.g. :func:`stdout.str() ` to reconstruct stdout, or the commonly used + :func:`stdout.fnmatch_lines() ` method. + """ self.stderr = LineMatcher(errlines) + """:class:`LineMatcher` of stderr""" self.duration = duration + """duration in seconds""" def __repr__(self) -> str: return ( From dc5219a9c008b3b77dfebd55b9924605c3a9a354 Mon Sep 17 00:00:00 2001 From: Daniel Hahler Date: Tue, 3 Mar 2020 21:15:06 +0100 Subject: [PATCH 03/12] Fix documentation for Config/InvocationParams --- src/_pytest/config/__init__.py | 33 +++++++++++++++++++++------------ 1 file changed, 21 insertions(+), 12 deletions(-) diff --git a/src/_pytest/config/__init__.py b/src/_pytest/config/__init__.py index f499a349a..ec3fc6afe 100644 --- a/src/_pytest/config/__init__.py +++ b/src/_pytest/config/__init__.py @@ -735,26 +735,19 @@ class Config: """ Access to configuration values, pluginmanager and plugin hooks. - :ivar PytestPluginManager pluginmanager: the plugin manager handles plugin registration and hook invocation. - - :ivar argparse.Namespace option: access to command line option as attributes. - - :ivar InvocationParams invocation_params: + :param PytestPluginManager pluginmanager: + :param InvocationParams invocation_params: Object containing the parameters regarding the ``pytest.main`` invocation. - - Contains the following read-only attributes: - - * ``args``: tuple of command-line arguments as passed to ``pytest.main()``. - * ``plugins``: list of extra plugins, might be None. - * ``dir``: directory where ``pytest.main()`` was invoked from. """ @attr.s(frozen=True) class InvocationParams: """Holds parameters passed during ``pytest.main()`` + The object attributes are read-only. + .. versionadded:: 5.1 .. note:: @@ -766,10 +759,18 @@ class Config: """ args = attr.ib(converter=tuple) + """tuple of command-line arguments as passed to ``pytest.main()``.""" plugins = attr.ib() + """list of extra plugins, might be `None`.""" dir = attr.ib(type=Path) + """directory where ``pytest.main()`` was invoked from.""" - def __init__(self, pluginmanager, *, invocation_params=None) -> None: + def __init__( + self, + pluginmanager: PytestPluginManager, + *, + invocation_params: InvocationParams = None + ) -> None: from .argparsing import Parser, FILE_OR_DIR if invocation_params is None: @@ -778,6 +779,10 @@ class Config: ) self.option = argparse.Namespace() + """access to command line option as attributes. + + :type: argparse.Namespace""" + self.invocation_params = invocation_params _a = FILE_OR_DIR @@ -786,6 +791,10 @@ class Config: processopt=self._processopt, ) self.pluginmanager = pluginmanager + """the plugin manager handles plugin registration and hook invocation. + + :type: PytestPluginManager""" + self.trace = self.pluginmanager.trace.root.get("config") self.hook = self.pluginmanager.hook self._inicache = {} # type: Dict[str, Any] From 1a8d427e983270f5a865845628bb1dd2876bd6ad Mon Sep 17 00:00:00 2001 From: Daniel Hahler Date: Thu, 5 Mar 2020 02:47:21 +0100 Subject: [PATCH 04/12] doc: src/_pytest/deprecated.py: links --- src/_pytest/deprecated.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/_pytest/deprecated.py b/src/_pytest/deprecated.py index 7e241ae1b..28ca02550 100644 --- a/src/_pytest/deprecated.py +++ b/src/_pytest/deprecated.py @@ -5,7 +5,8 @@ that is planned to be removed in the next pytest release. Keeping it in a central location makes it easy to track what is deprecated and should be removed when the time comes. -All constants defined in this module should be either PytestWarning instances or UnformattedWarning +All constants defined in this module should be either instances of +:class:`PytestWarning`, or :class:`UnformattedWarning` in case of warnings which need to format their messages. """ from _pytest.warning_types import PytestDeprecationWarning From 77adb33ec613bb64e0a68d4bc9c9393c2dab08f5 Mon Sep 17 00:00:00 2001 From: Daniel Hahler Date: Thu, 5 Mar 2020 02:56:18 +0100 Subject: [PATCH 05/12] doc: use show-inheritance with warnings, revisit docstrings Revisits the docstring for `PytestExperimentalApiWarning` and `PytestUnhandledCoroutineWarning`. --- doc/en/warnings.rst | 9 ++++++ src/_pytest/warning_types.py | 56 +++++++++--------------------------- 2 files changed, 23 insertions(+), 42 deletions(-) diff --git a/doc/en/warnings.rst b/doc/en/warnings.rst index 013564c2d..550e294ef 100644 --- a/doc/en/warnings.rst +++ b/doc/en/warnings.rst @@ -416,19 +416,28 @@ features. The following warning types are used by pytest and are part of the public API: .. autoclass:: pytest.PytestWarning + :show-inheritance: .. autoclass:: pytest.PytestAssertRewriteWarning + :show-inheritance: .. autoclass:: pytest.PytestCacheWarning + :show-inheritance: .. autoclass:: pytest.PytestCollectionWarning + :show-inheritance: .. autoclass:: pytest.PytestConfigWarning + :show-inheritance: .. autoclass:: pytest.PytestDeprecationWarning + :show-inheritance: .. autoclass:: pytest.PytestExperimentalApiWarning + :show-inheritance: .. autoclass:: pytest.PytestUnhandledCoroutineWarning + :show-inheritance: .. autoclass:: pytest.PytestUnknownMarkWarning + :show-inheritance: diff --git a/src/_pytest/warning_types.py b/src/_pytest/warning_types.py index 2e03c578c..87ab72c2d 100644 --- a/src/_pytest/warning_types.py +++ b/src/_pytest/warning_types.py @@ -11,71 +11,46 @@ if TYPE_CHECKING: class PytestWarning(UserWarning): - """ - Bases: :class:`UserWarning`. - - Base class for all warnings emitted by pytest. - """ + """Base class for all warnings emitted by pytest.""" __module__ = "pytest" class PytestAssertRewriteWarning(PytestWarning): - """ - Bases: :class:`PytestWarning`. - - Warning emitted by the pytest assert rewrite module. - """ + """Warning emitted by the pytest assert rewrite module.""" __module__ = "pytest" class PytestCacheWarning(PytestWarning): - """ - Bases: :class:`PytestWarning`. - - Warning emitted by the cache plugin in various situations. - """ + """Warning emitted by the cache plugin in various situations.""" __module__ = "pytest" class PytestConfigWarning(PytestWarning): - """ - Bases: :class:`PytestWarning`. - - Warning emitted for configuration issues. - """ + """Warning emitted for configuration issues.""" __module__ = "pytest" class PytestCollectionWarning(PytestWarning): - """ - Bases: :class:`PytestWarning`. - - Warning emitted when pytest is not able to collect a file or symbol in a module. - """ + """Warning emitted when pytest is not able to collect a file or symbol in a module.""" __module__ = "pytest" class PytestDeprecationWarning(PytestWarning, DeprecationWarning): - """ - Bases: :class:`pytest.PytestWarning`, :class:`DeprecationWarning`. - - Warning class for features that will be removed in a future version. - """ + """Warning class for features that will be removed in a future version.""" __module__ = "pytest" class PytestExperimentalApiWarning(PytestWarning, FutureWarning): - """ - Bases: :class:`pytest.PytestWarning`, :class:`FutureWarning`. + """Warning category used to denote experiments in pytest. - Warning category used to denote experiments in pytest. Use sparingly as the API might change or even be - removed completely in future version + Use sparingly as the API might change or even be removed completely in a + future version. """ __module__ = "pytest" @@ -90,22 +65,19 @@ class PytestExperimentalApiWarning(PytestWarning, FutureWarning): class PytestUnhandledCoroutineWarning(PytestWarning): - """ - Bases: :class:`PytestWarning`. + """Warning emitted for an unhandled coroutine. - Warning emitted when pytest encounters a test function which is a coroutine, - but it was not handled by any async-aware plugin. Coroutine test functions - are not natively supported. + A coroutine was encountered when collecting test functions, but was not + handled by any async-aware plugin. + Coroutine test functions are not natively supported. """ __module__ = "pytest" class PytestUnknownMarkWarning(PytestWarning): - """ - Bases: :class:`PytestWarning`. + """Warning emitted on use of unknown markers. - Warning emitted on use of unknown markers. See https://docs.pytest.org/en/latest/mark.html for details. """ From b90f57d25c43f797f8afdb9f5a336dac5631c28a Mon Sep 17 00:00:00 2001 From: Daniel Hahler Date: Thu, 5 Mar 2020 03:13:28 +0100 Subject: [PATCH 06/12] Remove wrong/outdated doc with UnformattedWarning It was introduced in da6830f19 (added to `_pytest.deprecated`, but then moved to `_pytest.warning_types`). --- src/_pytest/warning_types.py | 2 -- 1 file changed, 2 deletions(-) diff --git a/src/_pytest/warning_types.py b/src/_pytest/warning_types.py index 87ab72c2d..e99de5c47 100644 --- a/src/_pytest/warning_types.py +++ b/src/_pytest/warning_types.py @@ -90,8 +90,6 @@ _W = TypeVar("_W", bound=PytestWarning) @attr.s class UnformattedWarning(Generic[_W]): """Used to hold warnings that need to format their message at runtime, as opposed to a direct message. - - Using this class avoids to keep all the warning types and messages in this module, avoiding misuse. """ category = attr.ib(type="Type[_W]") From c39a85e5f4efc9e8875802bb838f0ed91c6336ba Mon Sep 17 00:00:00 2001 From: Daniel Hahler Date: Thu, 5 Mar 2020 03:15:14 +0100 Subject: [PATCH 07/12] doc: revisit UnformattedWarning --- src/_pytest/warning_types.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/_pytest/warning_types.py b/src/_pytest/warning_types.py index e99de5c47..ee437cc97 100644 --- a/src/_pytest/warning_types.py +++ b/src/_pytest/warning_types.py @@ -89,7 +89,10 @@ _W = TypeVar("_W", bound=PytestWarning) @attr.s class UnformattedWarning(Generic[_W]): - """Used to hold warnings that need to format their message at runtime, as opposed to a direct message. + """A warning meant to be formatted during runtime. + + This is used to hold warnings that need to format their message at runtime, + as opposed to a direct message. """ category = attr.ib(type="Type[_W]") From 9b32794391ae1b494c5082999bb69ee1a5038bcb Mon Sep 17 00:00:00 2001 From: Daniel Hahler Date: Thu, 5 Mar 2020 05:53:42 +0100 Subject: [PATCH 08/12] intersphinx_mapping: add pluggy --- doc/en/conf.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/doc/en/conf.py b/doc/en/conf.py index 71f63712e..cb0e846ad 100644 --- a/doc/en/conf.py +++ b/doc/en/conf.py @@ -344,7 +344,10 @@ texinfo_documents = [ # Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {"python": ("https://docs.python.org/3", None)} +intersphinx_mapping = { + "pluggy": ("https://pluggy.readthedocs.io/en/latest", None), + "python": ("https://docs.python.org/3", None), +} def configure_logging(app: "sphinx.application.Sphinx") -> None: From a1ad6e31173b0e26dc68c5e90ce524ed209da312 Mon Sep 17 00:00:00 2001 From: Daniel Hahler Date: Thu, 5 Mar 2020 05:55:04 +0100 Subject: [PATCH 09/12] doc: fix/revisit _Result (hook wrappers) - it should not document the deprecated `result`; used the same as pluggy documents itself - add a "hookwrapper" label, that could be used by pluggy (currently it links to the section) - use pluggy's `hookwrappers` label for linking to its documentation --- doc/en/reference.rst | 5 ++++- doc/en/writing_plugins.rst | 4 +++- 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/doc/en/reference.rst b/doc/en/reference.rst index 16bf3cf79..b746172ea 100644 --- a/doc/en/reference.rst +++ b/doc/en/reference.rst @@ -886,8 +886,11 @@ TestReport _Result ~~~~~~~ +Result used within :ref:`hook wrappers `. + .. autoclass:: pluggy.callers._Result - :members: +.. automethod:: pluggy.callers._Result.get_result +.. automethod:: pluggy.callers._Result.force_result Special Variables ----------------- diff --git a/doc/en/writing_plugins.rst b/doc/en/writing_plugins.rst index e914af401..f590a1245 100644 --- a/doc/en/writing_plugins.rst +++ b/doc/en/writing_plugins.rst @@ -508,6 +508,7 @@ call only executes until the first of N registered functions returns a non-None result which is then taken as result of the overall hook call. The remaining hook functions will not be called in this case. +.. _`hookwrapper`: hookwrapper: executing around other hooks ------------------------------------------------- @@ -552,7 +553,8 @@ perform tracing or other side effects around the actual hook implementations. If the result of the underlying hook is a mutable object, they may modify that result but it's probably better to avoid it. -For more information, consult the `pluggy documentation `_. +For more information, consult the +:ref:`pluggy documentation about hookwrappers `. Hook function ordering / call example From ffa2658971e29536c759ca52bffb2a6040e74ac4 Mon Sep 17 00:00:00 2001 From: Daniel Hahler Date: Thu, 5 Mar 2020 05:57:43 +0100 Subject: [PATCH 10/12] doc: reports: count_towards_summary: is a property And therefore does not really `return`. It confused me that there was no `source` link in the docs, which is only there for functions. --- src/_pytest/reports.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/_pytest/reports.py b/src/_pytest/reports.py index 4fa465ea7..0cd838016 100644 --- a/src/_pytest/reports.py +++ b/src/_pytest/reports.py @@ -131,7 +131,7 @@ class BaseReport: """ **Experimental** - Returns True if this report should be counted towards the totals shown at the end of the + ``True`` if this report should be counted towards the totals shown at the end of the test session: "1 passed, 1 failure, etc". .. note:: From 3865f77de3f40fc035e6365bfcf28f600d29e5e9 Mon Sep 17 00:00:00 2001 From: Daniel Hahler Date: Thu, 5 Mar 2020 06:00:11 +0100 Subject: [PATCH 11/12] doc: TestReport: :show-inheritance: --- doc/en/reference.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/en/reference.rst b/doc/en/reference.rst index b746172ea..cc70a0ed5 100644 --- a/doc/en/reference.rst +++ b/doc/en/reference.rst @@ -881,6 +881,7 @@ TestReport .. autoclass:: _pytest.runner.TestReport() :members: + :show-inheritance: :inherited-members: _Result From d9a462694414ff62ed1605b139808531ee6a708d Mon Sep 17 00:00:00 2001 From: Daniel Hahler Date: Thu, 5 Mar 2020 06:38:44 +0100 Subject: [PATCH 12/12] fixup! Fix documentation for Config/InvocationParams --- src/_pytest/config/__init__.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/_pytest/config/__init__.py b/src/_pytest/config/__init__.py index ec3fc6afe..7468d2c31 100644 --- a/src/_pytest/config/__init__.py +++ b/src/_pytest/config/__init__.py @@ -769,7 +769,7 @@ class Config: self, pluginmanager: PytestPluginManager, *, - invocation_params: InvocationParams = None + invocation_params: Optional[InvocationParams] = None ) -> None: from .argparsing import Parser, FILE_OR_DIR