diff --git a/doc/en/conf.py b/doc/en/conf.py index 3da401f89..e62bc157a 100644 --- a/doc/en/conf.py +++ b/doc/en/conf.py @@ -343,7 +343,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: diff --git a/doc/en/example/simple.rst b/doc/en/example/simple.rst index d149553c7..984afb152 100644 --- a/doc/en/example/simple.rst +++ b/doc/en/example/simple.rst @@ -222,8 +222,10 @@ Or run it including the ``slow`` marked test: ============================ 2 passed in 0.12s ============================= +.. _`__tracebackhide__`: + Writing well integrated assertion helpers --------------------------------------------------- +----------------------------------------- .. regendoc:wipe diff --git a/doc/en/reference.rst b/doc/en/reference.rst index 669b8272c..02b2f1815 100644 --- a/doc/en/reference.rst +++ b/doc/en/reference.rst @@ -881,13 +881,17 @@ TestReport .. autoclass:: _pytest.runner.TestReport() :members: + :show-inheritance: :inherited-members: _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/warnings.rst b/doc/en/warnings.rst index 17b244b7e..42c74ef36 100644 --- a/doc/en/warnings.rst +++ b/doc/en/warnings.rst @@ -418,19 +418,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/doc/en/writing_plugins.rst b/doc/en/writing_plugins.rst index 7040f2563..accda3634 100644 --- a/doc/en/writing_plugins.rst +++ b/doc/en/writing_plugins.rst @@ -513,6 +513,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 ------------------------------------------------- @@ -557,7 +558,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 diff --git a/src/_pytest/config/__init__.py b/src/_pytest/config/__init__.py index e21b9f1e2..6d18eeb65 100644 --- a/src/_pytest/config/__init__.py +++ b/src/_pytest/config/__init__.py @@ -731,26 +731,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:: @@ -762,10 +755,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: Optional[InvocationParams] = None + ) -> None: from .argparsing import Parser, FILE_OR_DIR if invocation_params is None: @@ -774,6 +775,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 @@ -782,6 +787,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] 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 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 ( diff --git a/src/_pytest/reports.py b/src/_pytest/reports.py index 25d8bf28b..dfda7f0e3 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:: diff --git a/src/_pytest/warning_types.py b/src/_pytest/warning_types.py index 2e03c578c..ee437cc97 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. """ @@ -117,9 +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. - Using this class avoids to keep all the warning types and messages in this module, avoiding misuse. + 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]")