From 6017666fe180205221f9969222a0e1208d4f5fe7 Mon Sep 17 00:00:00 2001 From: Bruno Oliveira Date: Tue, 31 May 2022 09:51:09 -0300 Subject: [PATCH] Do not advertise that importlib will be default import mode It is clear at this point that changing the default would break a lot of suites, and is not a clear win in all cases anyway. Close #10003 --- doc/en/explanation/goodpractices.rst | 5 ++--- doc/en/explanation/pythonpath.rst | 15 ++++++++++++--- 2 files changed, 14 insertions(+), 6 deletions(-) diff --git a/doc/en/explanation/goodpractices.rst b/doc/en/explanation/goodpractices.rst index 92110f4f9..0b812ba58 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 -------------------------------------------------