Skip to content

Commit b6fd89e

Browse files
authored
Merge pull request #7370 from bluetech/typing3
Some type annotations, doc improvements
2 parents db00612 + 33804fd commit b6fd89e

File tree

7 files changed

+166
-82
lines changed

7 files changed

+166
-82
lines changed

doc/en/changelog.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -287,7 +287,7 @@ Bug Fixes
287287
- `#6646 <https://github.com/pytest-dev/pytest/issues/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.
288288

289289

290-
- `#6660 <https://github.com/pytest-dev/pytest/issues/6660>`_: :func:`pytest.exit() <_pytest.outcomes.exit>` is handled when emitted from the :func:`pytest_sessionfinish <_pytest.hookspec.pytest_sessionfinish>` hook. This includes quitting from a debugger.
290+
- `#6660 <https://github.com/pytest-dev/pytest/issues/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.
291291

292292

293293
- `#6752 <https://github.com/pytest-dev/pytest/issues/6752>`_: When :py:func:`pytest.raises` is used as a function (as opposed to a context manager),
@@ -399,7 +399,7 @@ Improvements
399399
- `#6231 <https://github.com/pytest-dev/pytest/issues/6231>`_: Improve check for misspelling of :ref:`pytest.mark.parametrize ref`.
400400

401401

402-
- `#6257 <https://github.com/pytest-dev/pytest/issues/6257>`_: Handle :py:func:`_pytest.outcomes.exit` being used via :py:func:`~_pytest.hookspec.pytest_internalerror`, e.g. when quitting pdb from post mortem.
402+
- `#6257 <https://github.com/pytest-dev/pytest/issues/6257>`_: Handle :py:func:`pytest.exit` being used via :py:func:`~_pytest.hookspec.pytest_internalerror`, e.g. when quitting pdb from post mortem.
403403

404404

405405

doc/en/reference.rst

Lines changed: 38 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -15,41 +15,41 @@ Functions
1515
pytest.approx
1616
~~~~~~~~~~~~~
1717

18-
.. autofunction:: _pytest.python_api.approx
18+
.. autofunction:: pytest.approx
1919

2020
pytest.fail
2121
~~~~~~~~~~~
2222

2323
**Tutorial**: :ref:`skipping`
2424

25-
.. autofunction:: _pytest.outcomes.fail
25+
.. autofunction:: pytest.fail
2626

2727
pytest.skip
2828
~~~~~~~~~~~
2929

30-
.. autofunction:: _pytest.outcomes.skip(msg, [allow_module_level=False])
30+
.. autofunction:: pytest.skip(msg, [allow_module_level=False])
3131

3232
.. _`pytest.importorskip ref`:
3333

3434
pytest.importorskip
3535
~~~~~~~~~~~~~~~~~~~
3636

37-
.. autofunction:: _pytest.outcomes.importorskip
37+
.. autofunction:: pytest.importorskip
3838

3939
pytest.xfail
4040
~~~~~~~~~~~~
4141

42-
.. autofunction:: _pytest.outcomes.xfail
42+
.. autofunction:: pytest.xfail
4343

4444
pytest.exit
4545
~~~~~~~~~~~
4646

47-
.. autofunction:: _pytest.outcomes.exit
47+
.. autofunction:: pytest.exit
4848

4949
pytest.main
5050
~~~~~~~~~~~
5151

52-
.. autofunction:: _pytest.config.main
52+
.. autofunction:: pytest.main
5353

5454
pytest.param
5555
~~~~~~~~~~~~
@@ -644,31 +644,6 @@ Initialization hooks called for plugins and ``conftest.py`` files.
644644

645645
.. autofunction:: pytest_plugin_registered
646646

647-
Test running hooks
648-
~~~~~~~~~~~~~~~~~~
649-
650-
All runtest related hooks receive a :py:class:`pytest.Item <_pytest.main.Item>` object.
651-
652-
.. autofunction:: pytest_runtestloop
653-
.. autofunction:: pytest_runtest_protocol
654-
.. autofunction:: pytest_runtest_logstart
655-
.. autofunction:: pytest_runtest_logfinish
656-
.. autofunction:: pytest_runtest_setup
657-
.. autofunction:: pytest_runtest_call
658-
.. autofunction:: pytest_runtest_teardown
659-
.. autofunction:: pytest_runtest_makereport
660-
661-
For deeper understanding you may look at the default implementation of
662-
these hooks in :py:mod:`_pytest.runner` and maybe also
663-
in :py:mod:`_pytest.pdb` which interacts with :py:mod:`_pytest.capture`
664-
and its input/output capturing in order to immediately drop
665-
into interactive debugging when a test failure occurs.
666-
667-
The :py:mod:`_pytest.terminal` reported specifically uses
668-
the reporting hook to print information about a test run.
669-
670-
.. autofunction:: pytest_pyfunc_call
671-
672647
Collection hooks
673648
~~~~~~~~~~~~~~~~
674649

@@ -694,6 +669,28 @@ items, delete or otherwise amend the test items:
694669

695670
.. autofunction:: pytest_collection_finish
696671

672+
Test running (runtest) hooks
673+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
674+
675+
All runtest related hooks receive a :py:class:`pytest.Item <_pytest.main.Item>` object.
676+
677+
.. autofunction:: pytest_runtestloop
678+
.. autofunction:: pytest_runtest_protocol
679+
.. autofunction:: pytest_runtest_logstart
680+
.. autofunction:: pytest_runtest_logfinish
681+
.. autofunction:: pytest_runtest_setup
682+
.. autofunction:: pytest_runtest_call
683+
.. autofunction:: pytest_runtest_teardown
684+
.. autofunction:: pytest_runtest_makereport
685+
686+
For deeper understanding you may look at the default implementation of
687+
these hooks in :py:mod:`_pytest.runner` and maybe also
688+
in :py:mod:`_pytest.pdb` which interacts with :py:mod:`_pytest.capture`
689+
and its input/output capturing in order to immediately drop
690+
into interactive debugging when a test failure occurs.
691+
692+
.. autofunction:: pytest_pyfunc_call
693+
697694
Reporting hooks
698695
~~~~~~~~~~~~~~~
699696

@@ -762,6 +759,14 @@ Collector
762759
:members:
763760
:show-inheritance:
764761

762+
CollectReport
763+
~~~~~~~~~~~~~
764+
765+
.. autoclass:: _pytest.reports.CollectReport()
766+
:members:
767+
:show-inheritance:
768+
:inherited-members:
769+
765770
Config
766771
~~~~~~
767772

@@ -881,7 +886,7 @@ Session
881886
TestReport
882887
~~~~~~~~~~
883888

884-
.. autoclass:: _pytest.runner.TestReport()
889+
.. autoclass:: _pytest.reports.TestReport()
885890
:members:
886891
:show-inheritance:
887892
:inherited-members:

src/_pytest/hookspec.py

Lines changed: 100 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -361,93 +361,147 @@ def pytest_make_parametrize_id(
361361

362362

363363
# -------------------------------------------------------------------------
364-
# generic runtest related hooks
364+
# runtest related hooks
365365
# -------------------------------------------------------------------------
366366

367367

368368
@hookspec(firstresult=True)
369369
def pytest_runtestloop(session: "Session") -> Optional[object]:
370-
""" called for performing the main runtest loop
371-
(after collection finished).
370+
"""Performs the main runtest loop (after collection finished).
372371
373-
Stops at first non-None result, see :ref:`firstresult`
372+
The default hook implementation performs the runtest protocol for all items
373+
collected in the session (``session.items``), unless the collection failed
374+
or the ``collectonly`` pytest option is set.
374375
375-
:param _pytest.main.Session session: the pytest session object
376+
If at any point :py:func:`pytest.exit` is called, the loop is
377+
terminated immediately.
378+
379+
If at any point ``session.shouldfail`` or ``session.shouldstop`` are set, the
380+
loop is terminated after the runtest protocol for the current item is finished.
381+
382+
:param _pytest.main.Session session: The pytest session object.
383+
384+
Stops at first non-None result, see :ref:`firstresult`.
385+
The return value is not used, but only stops further processing.
376386
"""
377387

378388

379389
@hookspec(firstresult=True)
380390
def pytest_runtest_protocol(
381391
item: "Item", nextitem: "Optional[Item]"
382392
) -> Optional[object]:
383-
""" implements the runtest_setup/call/teardown protocol for
384-
the given test item, including capturing exceptions and calling
385-
reporting hooks.
393+
"""Performs the runtest protocol for a single test item.
386394
387-
:arg item: test item for which the runtest protocol is performed.
395+
The default runtest protocol is this (see individual hooks for full details):
388396
389-
:arg nextitem: the scheduled-to-be-next test item (or None if this
390-
is the end my friend). This argument is passed on to
391-
:py:func:`pytest_runtest_teardown`.
397+
- ``pytest_runtest_logstart(nodeid, location)``
392398
393-
:return boolean: True if no further hook implementations should be invoked.
399+
- Setup phase:
400+
- ``call = pytest_runtest_setup(item)`` (wrapped in ``CallInfo(when="setup")``)
401+
- ``report = pytest_runtest_makereport(item, call)``
402+
- ``pytest_runtest_logreport(report)``
403+
- ``pytest_exception_interact(call, report)`` if an interactive exception occurred
394404
405+
- Call phase, if the the setup passed and the ``setuponly`` pytest option is not set:
406+
- ``call = pytest_runtest_call(item)`` (wrapped in ``CallInfo(when="call")``)
407+
- ``report = pytest_runtest_makereport(item, call)``
408+
- ``pytest_runtest_logreport(report)``
409+
- ``pytest_exception_interact(call, report)`` if an interactive exception occurred
395410
396-
Stops at first non-None result, see :ref:`firstresult` """
411+
- Teardown phase:
412+
- ``call = pytest_runtest_teardown(item, nextitem)`` (wrapped in ``CallInfo(when="teardown")``)
413+
- ``report = pytest_runtest_makereport(item, call)``
414+
- ``pytest_runtest_logreport(report)``
415+
- ``pytest_exception_interact(call, report)`` if an interactive exception occurred
397416
417+
- ``pytest_runtest_logfinish(nodeid, location)``
398418
399-
def pytest_runtest_logstart(nodeid, location):
400-
""" signal the start of running a single test item.
419+
:arg item: Test item for which the runtest protocol is performed.
401420
402-
This hook will be called **before** :func:`pytest_runtest_setup`, :func:`pytest_runtest_call` and
403-
:func:`pytest_runtest_teardown` hooks.
421+
:arg nextitem: The scheduled-to-be-next test item (or None if this is the end my friend).
404422
405-
:param str nodeid: full id of the item
406-
:param location: a triple of ``(filename, linenum, testname)``
423+
Stops at first non-None result, see :ref:`firstresult`.
424+
The return value is not used, but only stops further processing.
407425
"""
408426

409427

410-
def pytest_runtest_logfinish(nodeid, location):
411-
""" signal the complete finish of running a single test item.
428+
def pytest_runtest_logstart(
429+
nodeid: str, location: Tuple[str, Optional[int], str]
430+
) -> None:
431+
"""Called at the start of running the runtest protocol for a single item.
412432
413-
This hook will be called **after** :func:`pytest_runtest_setup`, :func:`pytest_runtest_call` and
414-
:func:`pytest_runtest_teardown` hooks.
433+
See :func:`pytest_runtest_protocol` for a description of the runtest protocol.
415434
416-
:param str nodeid: full id of the item
417-
:param location: a triple of ``(filename, linenum, testname)``
435+
:param str nodeid: Full node ID of the item.
436+
:param location: A triple of ``(filename, lineno, testname)``.
437+
"""
438+
439+
440+
def pytest_runtest_logfinish(
441+
nodeid: str, location: Tuple[str, Optional[int], str]
442+
) -> None:
443+
"""Called at the end of running the runtest protocol for a single item.
444+
445+
See :func:`pytest_runtest_protocol` for a description of the runtest protocol.
446+
447+
:param str nodeid: Full node ID of the item.
448+
:param location: A triple of ``(filename, lineno, testname)``.
418449
"""
419450

420451

421452
def pytest_runtest_setup(item: "Item") -> None:
422-
""" called before ``pytest_runtest_call(item)``. """
453+
"""Called to perform the setup phase for a test item.
454+
455+
The default implementation runs ``setup()`` on ``item`` and all of its
456+
parents (which haven't been setup yet). This includes obtaining the
457+
values of fixtures required by the item (which haven't been obtained
458+
yet).
459+
"""
423460

424461

425462
def pytest_runtest_call(item: "Item") -> None:
426-
""" called to execute the test ``item``. """
463+
"""Called to run the test for test item (the call phase).
464+
465+
The default implementation calls ``item.runtest()``.
466+
"""
427467

428468

429469
def pytest_runtest_teardown(item: "Item", nextitem: "Optional[Item]") -> None:
430-
""" called after ``pytest_runtest_call``.
470+
"""Called to perform the teardown phase for a test item.
431471
432-
:arg nextitem: the scheduled-to-be-next test item (None if no further
472+
The default implementation runs the finalizers and calls ``teardown()``
473+
on ``item`` and all of its parents (which need to be torn down). This
474+
includes running the teardown phase of fixtures required by the item (if
475+
they go out of scope).
476+
477+
:arg nextitem: The scheduled-to-be-next test item (None if no further
433478
test item is scheduled). This argument can be used to
434479
perform exact teardowns, i.e. calling just enough finalizers
435480
so that nextitem only needs to call setup-functions.
436481
"""
437482

438483

439484
@hookspec(firstresult=True)
440-
def pytest_runtest_makereport(item: "Item", call: "CallInfo[None]") -> Optional[object]:
441-
""" return a :py:class:`_pytest.runner.TestReport` object
442-
for the given :py:class:`pytest.Item <_pytest.main.Item>` and
443-
:py:class:`_pytest.runner.CallInfo`.
485+
def pytest_runtest_makereport(
486+
item: "Item", call: "CallInfo[None]"
487+
) -> Optional["TestReport"]:
488+
"""Called to create a :py:class:`_pytest.reports.TestReport` for each of
489+
the setup, call and teardown runtest phases of a test item.
444490
445-
Stops at first non-None result, see :ref:`firstresult` """
491+
See :func:`pytest_runtest_protocol` for a description of the runtest protocol.
492+
493+
:param CallInfo[None] call: The ``CallInfo`` for the phase.
494+
495+
Stops at first non-None result, see :ref:`firstresult`.
496+
"""
446497

447498

448499
def pytest_runtest_logreport(report: "TestReport") -> None:
449-
""" process a test setup/call/teardown report relating to
450-
the respective phase of executing a test. """
500+
"""Process the :py:class:`_pytest.reports.TestReport` produced for each
501+
of the setup, call and teardown runtest phases of an item.
502+
503+
See :func:`pytest_runtest_protocol` for a description of the runtest protocol.
504+
"""
451505

452506

453507
@hookspec(firstresult=True)
@@ -779,11 +833,17 @@ def pytest_keyboard_interrupt(
779833
def pytest_exception_interact(
780834
node: "Node", call: "CallInfo[object]", report: "Union[CollectReport, TestReport]"
781835
) -> None:
782-
"""called when an exception was raised which can potentially be
836+
"""Called when an exception was raised which can potentially be
783837
interactively handled.
784838
785-
This hook is only called if an exception was raised
786-
that is not an internal exception like ``skip.Exception``.
839+
May be called during collection (see :py:func:`pytest_make_collect_report`),
840+
in which case ``report`` is a :py:class:`_pytest.reports.CollectReport`.
841+
842+
May be called during runtest of an item (see :py:func:`pytest_runtest_protocol`),
843+
in which case ``report`` is a :py:class:`_pytest.reports.TestReport`.
844+
845+
This hook is not called if the exception that was raised is an internal
846+
exception like ``skip.Exception``.
787847
"""
788848

789849

src/_pytest/logging.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -653,12 +653,12 @@ def pytest_runtestloop(self, session: Session) -> Generator[None, None, None]:
653653
yield # run all the tests
654654

655655
@pytest.hookimpl
656-
def pytest_runtest_logstart(self):
656+
def pytest_runtest_logstart(self) -> None:
657657
self.log_cli_handler.reset()
658658
self.log_cli_handler.set_when("start")
659659

660660
@pytest.hookimpl
661-
def pytest_runtest_logreport(self):
661+
def pytest_runtest_logreport(self) -> None:
662662
self.log_cli_handler.set_when("logreport")
663663

664664
def _runtest_for(self, item: nodes.Item, when: str) -> Generator[None, None, None]:

0 commit comments

Comments
 (0)