diff --git a/doc/en/explanation/goodpractices.rst b/doc/en/explanation/goodpractices.rst index 32a14991a..9ea7d226f 100644 --- a/doc/en/explanation/goodpractices.rst +++ b/doc/en/explanation/goodpractices.rst @@ -173,10 +173,9 @@ This layout prevents a lot of common pitfalls and has many benefits, which are b `blog post by Ionel Cristian Mărieș `_. .. note:: - The new ``--import-mode=importlib`` (see :ref:`import-modes`) doesn't have + The ``--import-mode=importlib`` option (see :ref:`import-modes`) does not have any of the drawbacks above because ``sys.path`` is not changed when importing - test modules, so users that run - into this issue are strongly encouraged to try it and report if the new option works well for them. + test modules, so users that run into this issue are strongly encouraged to try it. The ``src`` directory layout is still strongly recommended however. diff --git a/doc/en/explanation/pythonpath.rst b/doc/en/explanation/pythonpath.rst index 2330356b8..e1d240b49 100644 --- a/doc/en/explanation/pythonpath.rst +++ b/doc/en/explanation/pythonpath.rst @@ -45,10 +45,19 @@ these values: * ``importlib``: new in pytest-6.0, this mode uses :mod:`importlib` to import test modules. This gives full control over the import process, and doesn't require changing :py:data:`sys.path`. - For this reason this doesn't require test module names to be unique, but also makes test - modules non-importable by each other. + For this reason this doesn't require test module names to be unique. + + One drawback however is that test modules are non-importable by each other. Also, utility + modules in the tests directories are not automatically importable because the tests directory is no longer + added to :py:data:`sys.path`. + + Initially we intended to make ``importlib`` the default in future releases, however it is clear now that + it has its own set of drawbacks so the default will remain ``prepend`` for the foreseeable future. + +.. seealso:: + + The :confval:`pythonpath` configuration variable. - We intend to make ``importlib`` the default in future releases, depending on feedback. ``prepend`` and ``append`` import modes scenarios -------------------------------------------------