From 0ca23270699584b2b4cb0d83acc041a2cde22126 Mon Sep 17 00:00:00 2001 From: Ran Benita Date: Fri, 4 Sep 2020 20:46:15 +0300 Subject: [PATCH] doc: prefer to reference by public name when possible When a name is exported from `pytest`, prefer to refer to it by that rather than its `_pytest` import path. It is shorter and more appropriate in user-facing documentation (although that's not really visible). Our plan is to expose more names for typing purposes, in which can this could be more comprehensive. --- doc/en/fixture.rst | 8 ++++---- doc/en/reference.rst | 22 +++++++++++----------- doc/en/usage.rst | 2 +- src/_pytest/hookspec.py | 16 ++++++++-------- 4 files changed, 24 insertions(+), 24 deletions(-) diff --git a/doc/en/fixture.rst b/doc/en/fixture.rst index dd1f416cb..e0648a6a2 100644 --- a/doc/en/fixture.rst +++ b/doc/en/fixture.rst @@ -121,7 +121,7 @@ Fixtures as Function arguments Test functions can receive fixture objects by naming them as an input argument. For each argument name, a fixture function with that name provides the fixture object. Fixture functions are registered by marking them with -:py:func:`@pytest.fixture <_pytest.python.fixture>`. Let's look at a simple +:py:func:`@pytest.fixture `. Let's look at a simple self-contained test module containing a fixture and a test function using it: @@ -144,7 +144,7 @@ using it: assert 0 # for demo purposes Here, the ``test_ehlo`` needs the ``smtp_connection`` fixture value. pytest -will discover and call the :py:func:`@pytest.fixture <_pytest.python.fixture>` +will discover and call the :py:func:`@pytest.fixture ` marked ``smtp_connection`` fixture function. Running the test looks like this: .. code-block:: pytest @@ -252,7 +252,7 @@ Scope: sharing fixtures across classes, modules, packages or session Fixtures requiring network access depend on connectivity and are usually time-expensive to create. Extending the previous example, we can add a ``scope="module"`` parameter to the -:py:func:`@pytest.fixture <_pytest.python.fixture>` invocation +:py:func:`@pytest.fixture ` invocation to cause the decorated ``smtp_connection`` fixture function to only be invoked once per test *module* (the default is to invoke once per test *function*). Multiple test functions in a test module will thus @@ -775,7 +775,7 @@ through the special :py:class:`request ` object: smtp_connection.close() The main change is the declaration of ``params`` with -:py:func:`@pytest.fixture <_pytest.python.fixture>`, a list of values +:py:func:`@pytest.fixture `, a list of values for each of which the fixture function will execute and can access a value via ``request.param``. No test function code needs to change. So let's just do another run: diff --git a/doc/en/reference.rst b/doc/en/reference.rst index 313c76c4c..700d10133 100644 --- a/doc/en/reference.rst +++ b/doc/en/reference.rst @@ -240,7 +240,7 @@ For example: ... Will create and attach a :class:`Mark <_pytest.mark.structures.Mark>` object to the collected -:class:`Item <_pytest.nodes.Item>`, which can then be accessed by fixtures or hooks with +:class:`Item `, which can then be accessed by fixtures or hooks with :meth:`Node.iter_markers <_pytest.nodes.Node.iter_markers>`. The ``mark`` object will have the following attributes: .. code-block:: python @@ -676,7 +676,7 @@ items, delete or otherwise amend the test items: Test running (runtest) hooks ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -All runtest related hooks receive a :py:class:`pytest.Item <_pytest.main.Item>` object. +All runtest related hooks receive a :py:class:`pytest.Item ` object. .. autofunction:: pytest_runtestloop .. autofunction:: pytest_runtest_protocol @@ -752,14 +752,14 @@ CallInfo Class ~~~~~ -.. autoclass:: _pytest.python.Class() +.. autoclass:: pytest.Class() :members: :show-inheritance: Collector ~~~~~~~~~ -.. autoclass:: _pytest.nodes.Collector() +.. autoclass:: pytest.Collector() :members: :show-inheritance: @@ -787,13 +787,13 @@ ExceptionInfo ExitCode ~~~~~~~~ -.. autoclass:: _pytest.config.ExitCode +.. autoclass:: pytest.ExitCode :members: File ~~~~ -.. autoclass:: _pytest.nodes.File() +.. autoclass:: pytest.File() :members: :show-inheritance: @@ -815,14 +815,14 @@ FSCollector Function ~~~~~~~~ -.. autoclass:: _pytest.python.Function() +.. autoclass:: pytest.Function() :members: :show-inheritance: Item ~~~~ -.. autoclass:: _pytest.nodes.Item() +.. autoclass:: pytest.Item() :members: :show-inheritance: @@ -856,7 +856,7 @@ Metafunc Module ~~~~~~ -.. autoclass:: _pytest.python.Module() +.. autoclass:: pytest.Module() :members: :show-inheritance: @@ -890,7 +890,7 @@ PytestPluginManager Session ~~~~~~~ -.. autoclass:: _pytest.main.Session() +.. autoclass:: pytest.Session() :members: :show-inheritance: @@ -1032,7 +1032,7 @@ When set (regardless of value), pytest will use color in terminal output. Exceptions ---------- -.. autoclass:: _pytest.config.UsageError() +.. autoclass:: pytest.UsageError() :show-inheritance: .. _`warnings ref`: diff --git a/doc/en/usage.rst b/doc/en/usage.rst index aafdeb55f..6b2d529f8 100644 --- a/doc/en/usage.rst +++ b/doc/en/usage.rst @@ -33,7 +33,7 @@ Running ``pytest`` can result in six different exit codes: :Exit code 4: pytest command line usage error :Exit code 5: No tests were collected -They are represented by the :class:`_pytest.config.ExitCode` enum. The exit codes being a part of the public API can be imported and accessed directly using: +They are represented by the :class:`pytest.ExitCode` enum. The exit codes being a part of the public API can be imported and accessed directly using: .. code-block:: python diff --git a/src/_pytest/hookspec.py b/src/_pytest/hookspec.py index d4aaba1ec..2f0a04a06 100644 --- a/src/_pytest/hookspec.py +++ b/src/_pytest/hookspec.py @@ -237,7 +237,7 @@ def pytest_collection(session: "Session") -> Optional[object]: for example the terminal plugin uses it to start displaying the collection counter (and returns `None`). - :param _pytest.main.Session session: The pytest session object. + :param pytest.Session session: The pytest session object. """ @@ -247,16 +247,16 @@ def pytest_collection_modifyitems( """Called after collection has been performed. May filter or re-order the items in-place. - :param _pytest.main.Session session: The pytest session object. + :param pytest.Session session: The pytest session object. :param _pytest.config.Config config: The pytest config object. - :param List[_pytest.nodes.Item] items: List of item objects. + :param List[pytest.Item] items: List of item objects. """ def pytest_collection_finish(session: "Session") -> None: """Called after collection has been performed and modified. - :param _pytest.main.Session session: The pytest session object. + :param pytest.Session session: The pytest session object. """ @@ -393,7 +393,7 @@ def pytest_runtestloop(session: "Session") -> Optional[object]: If at any point ``session.shouldfail`` or ``session.shouldstop`` are set, the loop is terminated after the runtest protocol for the current item is finished. - :param _pytest.main.Session session: The pytest session object. + :param pytest.Session session: The pytest session object. Stops at first non-None result, see :ref:`firstresult`. The return value is not used, but only stops further processing. @@ -572,7 +572,7 @@ def pytest_sessionstart(session: "Session") -> None: """Called after the ``Session`` object has been created and before performing collection and entering the run test loop. - :param _pytest.main.Session session: The pytest session object. + :param pytest.Session session: The pytest session object. """ @@ -581,7 +581,7 @@ def pytest_sessionfinish( ) -> None: """Called after whole test run finished, right before returning the exit status to the system. - :param _pytest.main.Session session: The pytest session object. + :param pytest.Session session: The pytest session object. :param int exitstatus: The status which pytest will return to the system. """ @@ -633,7 +633,7 @@ def pytest_assertion_pass(item: "Item", lineno: int, orig: str, expl: str) -> No You need to **clean the .pyc** files in your project directory and interpreter libraries when enabling this option, as assertions will require to be re-written. - :param _pytest.nodes.Item item: pytest item object of current test. + :param pytest.Item item: pytest item object of current test. :param int lineno: Line number of the assert statement. :param str orig: String with the original assertion. :param str expl: String with the assert explanation.