diff --git a/doc/en/changelog.rst b/doc/en/changelog.rst index 65b160d2b..c5ccc75e3 100644 --- a/doc/en/changelog.rst +++ b/doc/en/changelog.rst @@ -156,7 +156,7 @@ Deprecations See :ref:`the deprecation note ` for full details. -- `#8592 `_: :func:`pytest_cmdline_preparse <_pytest.hookspec.pytest_cmdline_preparse>` has been officially deprecated. It will be removed in a future release. Use :func:`pytest_load_initial_conftests <_pytest.hookspec.pytest_load_initial_conftests>` instead. +- `#8592 `_: :hook:`pytest_cmdline_preparse` has been officially deprecated. It will be removed in a future release. Use :hook:`pytest_load_initial_conftests` instead. See :ref:`the deprecation note ` for full details. @@ -203,11 +203,11 @@ Features - ``pytest.Mark`` for :class:`marks `. - ``pytest.MarkDecorator`` for :class:`mark decorators `. - ``pytest.MarkGenerator`` for the :class:`pytest.mark ` singleton. - - ``pytest.Metafunc`` for the :class:`metafunc ` argument to the :func:`pytest_generate_tests ` hook. + - ``pytest.Metafunc`` for the :class:`metafunc ` argument to the :hook:`pytest_generate_tests` hook. - ``pytest.CallInfo`` for the :class:`CallInfo ` type passed to various hooks. - ``pytest.PytestPluginManager`` for :class:`PytestPluginManager `. - ``pytest.ExceptionInfo`` for the :class:`ExceptionInfo ` type returned from :func:`pytest.raises` and passed to various hooks. - - ``pytest.Parser`` for the :class:`Parser ` type passed to the :func:`pytest_addoption ` hook. + - ``pytest.Parser`` for the :class:`Parser ` type passed to the :hook:`pytest_addoption` hook. - ``pytest.OptionGroup`` for the :class:`OptionGroup ` type returned from the :func:`parser.addgroup ` method. - ``pytest.HookRecorder`` for the :class:`HookRecorder ` type returned from :class:`~pytest.Pytester`. - ``pytest.RecordedHookCall`` for the :class:`RecordedHookCall ` type returned from :class:`~pytest.HookRecorder`. @@ -228,11 +228,11 @@ Features - `#8144 `_: The following hooks now receive an additional ``pathlib.Path`` argument, equivalent to an existing ``py.path.local`` argument: - - :func:`pytest_ignore_collect <_pytest.hookspec.pytest_ignore_collect>` - The ``collection_path`` parameter (equivalent to existing ``path`` parameter). - - :func:`pytest_collect_file <_pytest.hookspec.pytest_collect_file>` - The ``file_path`` parameter (equivalent to existing ``path`` parameter). - - :func:`pytest_pycollect_makemodule <_pytest.hookspec.pytest_pycollect_makemodule>` - The ``module_path`` parameter (equivalent to existing ``path`` parameter). - - :func:`pytest_report_header <_pytest.hookspec.pytest_report_header>` - The ``start_path`` parameter (equivalent to existing ``startdir`` parameter). - - :func:`pytest_report_collectionfinish <_pytest.hookspec.pytest_report_collectionfinish>` - The ``start_path`` parameter (equivalent to existing ``startdir`` parameter). + - :hook:`pytest_ignore_collect` - The ``collection_path`` parameter (equivalent to existing ``path`` parameter). + - :hook:`pytest_collect_file` - The ``file_path`` parameter (equivalent to existing ``path`` parameter). + - :hook:`pytest_pycollect_makemodule` - The ``module_path`` parameter (equivalent to existing ``path`` parameter). + - :hook:`pytest_report_header` - The ``start_path`` parameter (equivalent to existing ``startdir`` parameter). + - :hook:`pytest_report_collectionfinish` - The ``start_path`` parameter (equivalent to existing ``startdir`` parameter). .. note:: The name of the :class:`~_pytest.nodes.Node` arguments and attributes (the @@ -491,7 +491,7 @@ Trivial/Internal Changes - `#8913 `_: The private ``CallSpec2._arg2scopenum`` attribute has been removed after an internal refactoring. -- `#8967 `_: :func:`pytest_assertion_pass <_pytest.hookspec.pytest_assertion_pass>` is no longer considered experimental and +- `#8967 `_: :hook:`pytest_assertion_pass` is no longer considered experimental and future changes to it will be considered more carefully. @@ -853,8 +853,8 @@ Deprecations if you use this and want a replacement. -- :issue:`7255`: The :func:`pytest_warning_captured <_pytest.hookspec.pytest_warning_captured>` hook is deprecated in favor - of :func:`pytest_warning_recorded <_pytest.hookspec.pytest_warning_recorded>`, and will be removed in a future version. +- :issue:`7255`: The :hook:`pytest_warning_captured` hook is deprecated in favor + of :hook:`pytest_warning_recorded`, and will be removed in a future version. - :issue:`7648`: The ``gethookproxy()`` and ``isinitpath()`` methods of ``FSCollector`` and ``Package`` are deprecated; @@ -962,7 +962,7 @@ Trivial/Internal Changes process, pytest now ignores builtin attributes (like ``__class__``, ``__delattr__`` and ``__new__``) without consulting the :confval:`python_classes` and :confval:`python_functions` configuration options and without passing them to plugins - using the :func:`pytest_pycollect_makeitem <_pytest.hookspec.pytest_pycollect_makeitem>` hook. + using the :hook:`pytest_pycollect_makeitem` hook. pytest 6.0.2 (2020-09-04) @@ -1751,7 +1751,7 @@ Bug Fixes - :issue:`6646`: Assertion rewriting hooks are (re)stored for the current item, which fixes them being still used after e.g. pytester's :func:`testdir.runpytest <_pytest.pytester.Testdir.runpytest>` etc. -- :issue:`6660`: :py:func:`pytest.exit` is handled when emitted from the :func:`pytest_sessionfinish <_pytest.hookspec.pytest_sessionfinish>` hook. This includes quitting from a debugger. +- :issue:`6660`: :py:func:`pytest.exit` is handled when emitted from the :hook:`pytest_sessionfinish` hook. This includes quitting from a debugger. - :issue:`6752`: When :py:func:`pytest.raises` is used as a function (as opposed to a context manager), @@ -1863,7 +1863,7 @@ Improvements - :issue:`6231`: Improve check for misspelling of :ref:`pytest.mark.parametrize ref`. -- :issue:`6257`: Handle :py:func:`pytest.exit` being used via :py:func:`~_pytest.hookspec.pytest_internalerror`, e.g. when quitting pdb from post mortem. +- :issue:`6257`: Handle :func:`pytest.exit` being used via :hook:`pytest_internalerror`, e.g. when quitting pdb from post mortem. @@ -2497,7 +2497,7 @@ Deprecations Features -------- -- :issue:`3457`: New :func:`~_pytest.hookspec.pytest_assertion_pass` +- :issue:`3457`: New :hook:`pytest_assertion_pass` hook, called with context information when an assertion *passes*. This hook is still **experimental** so use it with caution. @@ -5017,9 +5017,9 @@ Features - Console output falls back to "classic" mode when capturing is disabled (``-s``), otherwise the output gets garbled to the point of being useless. (:issue:`3038`) -- New :func:`~_pytest.hookspec.pytest_runtest_logfinish` +- New :hook:`pytest_runtest_logfinish` hook which is called when a test item has finished executing, analogous to - :func:`~_pytest.hookspec.pytest_runtest_logstart`. + :hook:`pytest_runtest_logstart`. (:issue:`3101`) - Improve performance when collecting tests using many fixtures. (:issue:`3107`) diff --git a/doc/en/conf.py b/doc/en/conf.py index bcf01aa47..b31616353 100644 --- a/doc/en/conf.py +++ b/doc/en/conf.py @@ -445,6 +445,13 @@ def setup(app: "sphinx.application.Sphinx") -> None: indextemplate="pair: %s; global variable interpreted by pytest", ) + app.add_crossref_type( + directivename="hook", + rolename="hook", + objname="pytest hook", + indextemplate="pair: %s; hook", + ) + configure_logging(app) # Make Sphinx mark classes with "final" when decorated with @final. diff --git a/doc/en/deprecations.rst b/doc/en/deprecations.rst index c748316cb..6351d1f6e 100644 --- a/doc/en/deprecations.rst +++ b/doc/en/deprecations.rst @@ -81,11 +81,11 @@ no matter what argument was used in the constructor. We expect to deprecate the In order to support the transition from ``py.path.local`` to :mod:`pathlib`, the following hooks now receive additional arguments: -* :func:`pytest_ignore_collect(collection_path: pathlib.Path) <_pytest.hookspec.pytest_ignore_collect>` as equivalent to ``path`` -* :func:`pytest_collect_file(file_path: pathlib.Path) <_pytest.hookspec.pytest_collect_file>` as equivalent to ``path`` -* :func:`pytest_pycollect_makemodule(module_path: pathlib.Path) <_pytest.hookspec.pytest_pycollect_makemodule>` as equivalent to ``path`` -* :func:`pytest_report_header(start_path: pathlib.Path) <_pytest.hookspec.pytest_report_header>` as equivalent to ``startdir`` -* :func:`pytest_report_collectionfinish(start_path: pathlib.Path) <_pytest.hookspec.pytest_report_collectionfinish>` as equivalent to ``startdir`` +* :hook:`pytest_ignore_collect(collection_path: pathlib.Path) ` as equivalent to ``path`` +* :hook:`pytest_collect_file(file_path: pathlib.Path) ` as equivalent to ``path`` +* :hook:`pytest_pycollect_makemodule(module_path: pathlib.Path) ` as equivalent to ``path`` +* :hook:`pytest_report_header(start_path: pathlib.Path) ` as equivalent to ``startdir`` +* :hook:`pytest_report_collectionfinish(start_path: pathlib.Path) ` as equivalent to ``startdir`` The accompanying ``py.path.local`` based paths have been deprecated: plugins which manually invoke those hooks should only pass the new ``pathlib.Path`` arguments, and users should change their hook implementations to use the new ``pathlib.Path`` arguments. @@ -157,8 +157,8 @@ Implementing the ``pytest_cmdline_preparse`` hook .. deprecated:: 7.0 -Implementing the :func:`pytest_cmdline_preparse <_pytest.hookspec.pytest_cmdline_preparse>` hook has been officially deprecated. -Implement the :func:`pytest_load_initial_conftests <_pytest.hookspec.pytest_load_initial_conftests>` hook instead. +Implementing the :hook:`pytest_cmdline_preparse` hook has been officially deprecated. +Implement the :hook:`pytest_load_initial_conftests` hook instead. .. code-block:: python @@ -331,8 +331,8 @@ at some point, depending on the plans for the plugins and number of users using .. versionremoved:: 6.0 -The ``pytest_collect_directory`` has not worked properly for years (it was called -but the results were ignored). Users may consider using :func:`pytest_collection_modifyitems <_pytest.hookspec.pytest_collection_modifyitems>` instead. +The ``pytest_collect_directory`` hook has not worked properly for years (it was called +but the results were ignored). Users may consider using :hook:`pytest_collection_modifyitems` instead. TerminalReporter.writer ~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/en/reference/reference.rst b/doc/en/reference/reference.rst index c132ae6d3..d4cbcbac0 100644 --- a/doc/en/reference/reference.rst +++ b/doc/en/reference/reference.rst @@ -671,9 +671,13 @@ Bootstrapping hooks Bootstrapping hooks called for plugins registered early enough (internal and setuptools plugins). +.. hook:: pytest_load_initial_conftests .. autofunction:: pytest_load_initial_conftests +.. hook:: pytest_cmdline_preparse .. autofunction:: pytest_cmdline_preparse +.. hook:: pytest_cmdline_parse .. autofunction:: pytest_cmdline_parse +.. hook:: pytest_cmdline_main .. autofunction:: pytest_cmdline_main .. _`initialization-hooks`: @@ -683,13 +687,20 @@ Initialization hooks Initialization hooks called for plugins and ``conftest.py`` files. +.. hook:: pytest_addoption .. autofunction:: pytest_addoption +.. hook:: pytest_addhooks .. autofunction:: pytest_addhooks +.. hook:: pytest_configure .. autofunction:: pytest_configure +.. hook:: pytest_unconfigure .. autofunction:: pytest_unconfigure +.. hook:: pytest_sessionstart .. autofunction:: pytest_sessionstart +.. hook:: pytest_sessionfinish .. autofunction:: pytest_sessionfinish +.. hook:: pytest_plugin_registered .. autofunction:: pytest_plugin_registered Collection hooks @@ -697,21 +708,29 @@ Collection hooks ``pytest`` calls the following hooks for collecting files and directories: +.. hook:: pytest_collection .. autofunction:: pytest_collection +.. hook:: pytest_ignore_collect .. autofunction:: pytest_ignore_collect +.. hook:: pytest_collect_file .. autofunction:: pytest_collect_file +.. hook:: pytest_pycollect_makemodule .. autofunction:: pytest_pycollect_makemodule For influencing the collection of objects in Python modules you can use the following hook: +.. hook:: pytest_pycollect_makeitem .. autofunction:: pytest_pycollect_makeitem +.. hook:: pytest_generate_tests .. autofunction:: pytest_generate_tests +.. hook:: pytest_make_parametrize_id .. autofunction:: pytest_make_parametrize_id After collection is complete, you can modify the order of items, delete or otherwise amend the test items: +.. hook:: pytest_collection_modifyitems .. autofunction:: pytest_collection_modifyitems .. note:: @@ -725,13 +744,21 @@ Test running (runtest) hooks All runtest related hooks receive a :py:class:`pytest.Item ` object. +.. hook:: pytest_runtestloop .. autofunction:: pytest_runtestloop +.. hook:: pytest_runtest_protocol .. autofunction:: pytest_runtest_protocol +.. hook:: pytest_runtest_logstart .. autofunction:: pytest_runtest_logstart +.. hook:: pytest_runtest_logfinish .. autofunction:: pytest_runtest_logfinish +.. hook:: pytest_runtest_setup .. autofunction:: pytest_runtest_setup +.. hook:: pytest_runtest_call .. autofunction:: pytest_runtest_call +.. hook:: pytest_runtest_teardown .. autofunction:: pytest_runtest_teardown +.. hook:: pytest_runtest_makereport .. autofunction:: pytest_runtest_makereport For deeper understanding you may look at the default implementation of @@ -740,6 +767,7 @@ in ``_pytest.pdb`` which interacts with ``_pytest.capture`` and its input/output capturing in order to immediately drop into interactive debugging when a test failure occurs. +.. hook:: pytest_pyfunc_call .. autofunction:: pytest_pyfunc_call Reporting hooks @@ -747,26 +775,41 @@ Reporting hooks Session related reporting hooks: +.. hook:: pytest_collectstart .. autofunction:: pytest_collectstart +.. hook:: pytest_make_collect_report .. autofunction:: pytest_make_collect_report +.. hook:: pytest_itemcollected .. autofunction:: pytest_itemcollected +.. hook:: pytest_collectreport .. autofunction:: pytest_collectreport +.. hook:: pytest_deselected .. autofunction:: pytest_deselected +.. hook:: pytest_report_header .. autofunction:: pytest_report_header +.. hook:: pytest_report_collectionfinish .. autofunction:: pytest_report_collectionfinish +.. hook:: pytest_report_teststatus .. autofunction:: pytest_report_teststatus +.. hook:: pytest_terminal_summary .. autofunction:: pytest_terminal_summary +.. hook:: pytest_fixture_setup .. autofunction:: pytest_fixture_setup +.. hook:: pytest_fixture_post_finalizer .. autofunction:: pytest_fixture_post_finalizer +.. hook:: pytest_warning_recorded .. autofunction:: pytest_warning_recorded Central hook for reporting about test execution: +.. hook:: pytest_runtest_logreport .. autofunction:: pytest_runtest_logreport Assertion related hooks: +.. hook:: pytest_assertrepr_compare .. autofunction:: pytest_assertrepr_compare +.. hook:: pytest_assertion_pass .. autofunction:: pytest_assertion_pass @@ -776,9 +819,13 @@ Debugging/Interaction hooks There are few hooks which can be used for special reporting or interaction with exceptions: +.. hook:: pytest_internalerror .. autofunction:: pytest_internalerror +.. hook:: pytest_keyboard_interrupt .. autofunction:: pytest_keyboard_interrupt +.. hook:: pytest_exception_interact .. autofunction:: pytest_exception_interact +.. hook:: pytest_enter_pdb .. autofunction:: pytest_enter_pdb diff --git a/src/_pytest/hookspec.py b/src/_pytest/hookspec.py index bbb6f5e96..a03c0e9ab 100644 --- a/src/_pytest/hookspec.py +++ b/src/_pytest/hookspec.py @@ -162,7 +162,7 @@ def pytest_cmdline_preparse(config: "Config", args: List[str]) -> None: """(**Deprecated**) modify command line arguments before option parsing. This hook is considered deprecated and will be removed in a future pytest version. Consider - using :func:`pytest_load_initial_conftests` instead. + using :hook:`pytest_load_initial_conftests` instead. .. note:: This hook will not be called for ``conftest.py`` files, only for setuptools plugins. @@ -466,7 +466,7 @@ def pytest_runtest_logstart( ) -> None: """Called at the start of running the runtest protocol for a single item. - See :func:`pytest_runtest_protocol` for a description of the runtest protocol. + See :hook:`pytest_runtest_protocol` for a description of the runtest protocol. :param str nodeid: Full node ID of the item. :param location: A tuple of ``(filename, lineno, testname)``. @@ -478,7 +478,7 @@ def pytest_runtest_logfinish( ) -> None: """Called at the end of running the runtest protocol for a single item. - See :func:`pytest_runtest_protocol` for a description of the runtest protocol. + See :hook:`pytest_runtest_protocol` for a description of the runtest protocol. :param str nodeid: Full node ID of the item. :param location: A tuple of ``(filename, lineno, testname)``. @@ -525,7 +525,7 @@ def pytest_runtest_makereport( """Called to create a :class:`~pytest.TestReport` for each of the setup, call and teardown runtest phases of a test item. - See :func:`pytest_runtest_protocol` for a description of the runtest protocol. + See :hook:`pytest_runtest_protocol` for a description of the runtest protocol. :param call: The :class:`~pytest.CallInfo` for the phase. @@ -537,7 +537,7 @@ def pytest_runtest_logreport(report: "TestReport") -> None: """Process the :class:`~pytest.TestReport` produced for each of the setup, call and teardown runtest phases of an item. - See :func:`pytest_runtest_protocol` for a description of the runtest protocol. + See :hook:`pytest_runtest_protocol` for a description of the runtest protocol. """ @@ -556,7 +556,7 @@ def pytest_report_from_serializable( data: Dict[str, Any], ) -> Optional[Union["CollectReport", "TestReport"]]: """Restore a report object previously serialized with - :func:`pytest_report_to_serializable`.""" + :hook:`pytest_report_to_serializable`.""" # ------------------------------------------------------------------------- @@ -859,10 +859,10 @@ def pytest_exception_interact( """Called when an exception was raised which can potentially be interactively handled. - May be called during collection (see :py:func:`pytest_make_collect_report`), + May be called during collection (see :hook:`pytest_make_collect_report`), in which case ``report`` is a :class:`CollectReport`. - May be called during runtest of an item (see :py:func:`pytest_runtest_protocol`), + May be called during runtest of an item (see :hook:`pytest_runtest_protocol`), in which case ``report`` is a :class:`TestReport`. This hook is not called if the exception that was raised is an internal diff --git a/src/_pytest/main.py b/src/_pytest/main.py index 57407fe54..952c70350 100644 --- a/src/_pytest/main.py +++ b/src/_pytest/main.py @@ -605,8 +605,7 @@ class Session(nodes.FSCollector): ) -> Sequence[Union[nodes.Item, nodes.Collector]]: """Perform the collection phase for this session. - This is called by the default - :func:`pytest_collection <_pytest.hookspec.pytest_collection>` hook + This is called by the default :hook:`pytest_collection` hook implementation; see the documentation of this hook for more details. For testing purposes, it may also be called directly on a fresh ``Session``. diff --git a/src/_pytest/python.py b/src/_pytest/python.py index b5e391fb2..aa49aa264 100644 --- a/src/_pytest/python.py +++ b/src/_pytest/python.py @@ -985,7 +985,7 @@ class CallSpec2: @final class Metafunc: - """Objects passed to the :func:`pytest_generate_tests <_pytest.hookspec.pytest_generate_tests>` hook. + """Objects passed to the :hook:`pytest_generate_tests` hook. They help to inspect a test function and to generate tests according to test configuration or values specified in the class or module where a