diff --git a/doc/en/reference/reference.rst b/doc/en/reference/reference.rst index d5ab94bc3..cf83ae05f 100644 --- a/doc/en/reference/reference.rst +++ b/doc/en/reference/reference.rst @@ -783,18 +783,66 @@ reporting or interaction with exceptions: .. autofunction:: pytest_leave_pdb -Objects -------- +Collection tree objects +----------------------- -Full reference to objects accessible from :ref:`fixtures ` or :ref:`hooks `. +These are the collector and item classes (collectively called "nodes") which +make up the collection tree. +Node +~~~~ -CallInfo -~~~~~~~~ - -.. autoclass:: pytest.CallInfo() +.. autoclass:: _pytest.nodes.Node() :members: +Collector +~~~~~~~~~ + +.. autoclass:: pytest.Collector() + :members: + :show-inheritance: + +Item +~~~~ + +.. autoclass:: pytest.Item() + :members: + :show-inheritance: + +File +~~~~ + +.. autoclass:: pytest.File() + :members: + :show-inheritance: + +FSCollector +~~~~~~~~~~~ + +.. autoclass:: _pytest.nodes.FSCollector() + :members: + :show-inheritance: + +Session +~~~~~~~ + +.. autoclass:: pytest.Session() + :members: + :show-inheritance: + +Package +~~~~~~~ + +.. autoclass:: pytest.Package() + :members: + :show-inheritance: + +Module +~~~~~~ + +.. autoclass:: pytest.Module() + :members: + :show-inheritance: Class ~~~~~ @@ -803,13 +851,34 @@ Class :members: :show-inheritance: -Collector -~~~~~~~~~ +Function +~~~~~~~~ -.. autoclass:: pytest.Collector() +.. autoclass:: pytest.Function() :members: :show-inheritance: +FunctionDefinition +~~~~~~~~~~~~~~~~~~ + +.. autoclass:: _pytest.python.FunctionDefinition() + :members: + :show-inheritance: + + +Objects +------- + +Objects accessible from :ref:`fixtures ` or :ref:`hooks ` +or importable from ``pytest``. + + +CallInfo +~~~~~~~~ + +.. autoclass:: pytest.CallInfo() + :members: + CollectReport ~~~~~~~~~~~~~ @@ -837,13 +906,6 @@ ExitCode .. autoclass:: pytest.ExitCode :members: -File -~~~~ - -.. autoclass:: pytest.File() - :members: - :show-inheritance: - FixtureDef ~~~~~~~~~~ @@ -852,34 +914,6 @@ FixtureDef :members: :show-inheritance: -FSCollector -~~~~~~~~~~~ - -.. autoclass:: _pytest.nodes.FSCollector() - :members: - :show-inheritance: - -Function -~~~~~~~~ - -.. autoclass:: pytest.Function() - :members: - :show-inheritance: - -FunctionDefinition -~~~~~~~~~~~~~~~~~~ - -.. autoclass:: _pytest.python.FunctionDefinition() - :members: - :show-inheritance: - -Item -~~~~ - -.. autoclass:: pytest.Item() - :members: - :show-inheritance: - MarkDecorator ~~~~~~~~~~~~~ @@ -907,19 +941,6 @@ Metafunc .. autoclass:: pytest.Metafunc() :members: -Module -~~~~~~ - -.. autoclass:: pytest.Module() - :members: - :show-inheritance: - -Node -~~~~ - -.. autoclass:: _pytest.nodes.Node() - :members: - Parser ~~~~~~ @@ -941,13 +962,6 @@ PytestPluginManager :inherited-members: :show-inheritance: -Session -~~~~~~~ - -.. autoclass:: pytest.Session() - :members: - :show-inheritance: - TestReport ~~~~~~~~~~ diff --git a/src/_pytest/main.py b/src/_pytest/main.py index f2327ca68..67c52243e 100644 --- a/src/_pytest/main.py +++ b/src/_pytest/main.py @@ -462,6 +462,11 @@ class _bestrelpath_cache(Dict[Path, str]): @final class Session(nodes.FSCollector): + """The root of the collection tree. + + ``Session`` collects the initial paths given as arguments to pytest. + """ + Interrupted = Interrupted Failed = Failed # Set on the session by runner.pytest_sessionstart. diff --git a/src/_pytest/nodes.py b/src/_pytest/nodes.py index 83180c126..cb8907fe8 100644 --- a/src/_pytest/nodes.py +++ b/src/_pytest/nodes.py @@ -157,10 +157,11 @@ class NodeMeta(type): class Node(metaclass=NodeMeta): - """Base class for Collector and Item, the components of the test - collection tree. + r"""Base class of :class:`Collector` and :class:`Item`, the components of + the test collection tree. - Collector subclasses have children; Items are leaf nodes. + ``Collector``\'s are the internal nodes of the tree, and ``Item``\'s are the + leaf nodes. """ # Implemented in the legacypath plugin. @@ -525,15 +526,17 @@ def get_fslocation_from_item(node: "Node") -> Tuple[Union[str, Path], Optional[i class Collector(Node): - """Collector instances create children through collect() and thus - iteratively build a tree.""" + """Base class of all collectors. + + Collector create children through `collect()` and thus iteratively build + the collection tree. + """ class CollectError(Exception): """An error during collection, contains a custom message.""" def collect(self) -> Iterable[Union["Item", "Collector"]]: - """Return a list of children (items and collectors) for this - collection node.""" + """Collect children (items and collectors) for this collector.""" raise NotImplementedError("abstract") # TODO: This omits the style= parameter which breaks Liskov Substitution. @@ -577,6 +580,8 @@ def _check_initialpaths_for_relpath(session: "Session", path: Path) -> Optional[ class FSCollector(Collector): + """Base class for filesystem collectors.""" + def __init__( self, fspath: Optional[LEGACY_PATH] = None, @@ -660,7 +665,7 @@ class File(FSCollector): class Item(Node): - """A basic test invocation item. + """Base class of all test invocation items. Note that for a single function there might be multiple test invocation items. """ diff --git a/src/_pytest/python.py b/src/_pytest/python.py index 5f4ba3da6..77912b866 100644 --- a/src/_pytest/python.py +++ b/src/_pytest/python.py @@ -522,7 +522,7 @@ class PyCollector(PyobjMixin, nodes.Collector): class Module(nodes.File, PyCollector): - """Collector for test classes and functions.""" + """Collector for test classes and functions in a Python module.""" def _getobj(self): return self._importtestmodule() @@ -659,6 +659,9 @@ class Module(nodes.File, PyCollector): class Package(Module): + """Collector for files and directories in a Python packages -- directories + with an `__init__.py` file.""" + def __init__( self, fspath: Optional[LEGACY_PATH], @@ -790,7 +793,7 @@ def _get_first_non_fixture_func(obj: object, names: Iterable[str]) -> Optional[o class Class(PyCollector): - """Collector for test methods.""" + """Collector for test methods (and nested classes) in a Python class.""" @classmethod def from_parent(cls, parent, *, name, obj=None, **kw): @@ -1675,7 +1678,7 @@ def write_docstring(tw: TerminalWriter, doc: str, indent: str = " ") -> None: class Function(PyobjMixin, nodes.Item): - """An Item responsible for setting up and executing a Python test function. + """Item responsible for setting up and executing a Python test function. :param name: The full function name, including any decorations like those @@ -1832,10 +1835,8 @@ class Function(PyobjMixin, nodes.Item): class FunctionDefinition(Function): - """ - This class is a step gap solution until we evolve to have actual function definition nodes - and manage to get rid of ``metafunc``. - """ + """This class is a stop gap solution until we evolve to have actual function + definition nodes and manage to get rid of ``metafunc``.""" def runtest(self) -> None: raise RuntimeError("function definitions are not supposed to be run as tests")