From d6cf5e1e6b1f55975e464ad037bf41ba9f5fb706 Mon Sep 17 00:00:00 2001 From: Marcin Szewczyk Date: Sat, 24 Sep 2022 20:42:34 +0200 Subject: [PATCH] doc: mention pythonpath confval in Good Integration Practices Fixes #9833. PYTHONPATH/pythonpath is required in case of the recommended src layout. --- doc/en/explanation/goodpractices.rst | 34 +++++++++++++++++++++------- 1 file changed, 26 insertions(+), 8 deletions(-) diff --git a/doc/en/explanation/goodpractices.rst b/doc/en/explanation/goodpractices.rst index 0280f1434..ac6ed4298 100644 --- a/doc/en/explanation/goodpractices.rst +++ b/doc/en/explanation/goodpractices.rst @@ -88,14 +88,6 @@ This has the following benefits: * Your tests can run against an installed version after executing ``pip install .``. * Your tests can run against the local copy with an editable install after executing ``pip install --editable .``. -* If you don't use an editable install and are relying on the fact that Python by default puts the current - directory in ``sys.path`` to import your package, you can execute ``python -m pytest`` to execute the tests against the - local copy directly, without using ``pip``. - -.. note:: - - See :ref:`pytest vs python -m pytest` for more information about the difference between calling ``pytest`` and - ``python -m pytest``. For new projects, we recommend to use ``importlib`` :ref:`import mode ` (see which-import-mode_ for a detailed explanation). @@ -120,6 +112,32 @@ which are better explained in this excellent `blog post`_ by Ionel Cristian Măr .. _blog post: https://blog.ionelmc.ro/2014/05/25/python-packaging/#the-structure> +.. note:: + + If you do not use an editable install and use the ``src`` layout as above you need to extend the Python's + search path for module files to execute the tests against the local copy directly. You can do it in an + ad-hoc manner by setting the ``PYTHONPATH`` environment variable: + + .. code-block:: bash + + PYTHONPATH=src pytest + + or in a permanent manner by using the :confval:`pythonpath` configuration variable and adding the + following to your ``pyproject.toml``: + + .. code-block:: toml + + [tool.pytest.ini_options] + pythonpath = "src" + +.. note:: + + If you do not use an editable install and not use the ``src`` layout (``mypkg`` directly in the root + directory) you can rely on the fact that Python by default puts the current directory in ``sys.path`` to + import your package and run ``python -m pytest`` to execute the tests against the local copy directly. + + See :ref:`pytest vs python -m pytest` for more information about the difference between calling ``pytest`` and + ``python -m pytest``. Tests as part of application code ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^