From d6134bc21e27efee7a2e264bd089e6c223515904 Mon Sep 17 00:00:00 2001 From: Bruno Oliveira Date: Sat, 2 Mar 2024 12:16:12 -0300 Subject: [PATCH] doc: document consider_namespace_packages option --- changelog/11475.feature.rst | 4 ++-- changelog/11475.improvement.rst | 2 ++ doc/en/explanation/pythonpath.rst | 10 ++++++++-- doc/en/reference/reference.rst | 13 +++++++++++++ 4 files changed, 25 insertions(+), 4 deletions(-) diff --git a/changelog/11475.feature.rst b/changelog/11475.feature.rst index 6b73c8158..42550235d 100644 --- a/changelog/11475.feature.rst +++ b/changelog/11475.feature.rst @@ -1,3 +1,3 @@ -pytest now correctly identifies modules that are part of `namespace packages `__, for example when importing user-level modules for doctesting. +Added the new :confval:`consider_namespace_packages` configuration option, defaulting to ``False``. -Previously pytest was not aware of namespace packages, so running a doctest from a subpackage that is part of a namespace package would import just the subpackage (for example ``app.models``) instead of its full path (for example ``com.company.app.models``). +If set to ``True``, pytest will attempt to identify modules that are part of `namespace packages `__ when importing modules. diff --git a/changelog/11475.improvement.rst b/changelog/11475.improvement.rst index fc6e8be3a..4f6a4bffa 100644 --- a/changelog/11475.improvement.rst +++ b/changelog/11475.improvement.rst @@ -1 +1,3 @@ :ref:`--import-mode=importlib ` now tries to import modules using the standard import mechanism (but still without changing :py:data:`sys.path`), falling back to importing modules directly only if that fails. + +This means that installed packages will be imported under their canonical name if possible first, for example ``app.core.models``, instead of having the module name always be derived from their path (for example ``.env310.lib.site_packages.app.core.models``). diff --git a/doc/en/explanation/pythonpath.rst b/doc/en/explanation/pythonpath.rst index 6b1d3ae2c..33eba86b5 100644 --- a/doc/en/explanation/pythonpath.rst +++ b/doc/en/explanation/pythonpath.rst @@ -10,8 +10,7 @@ Import modes pytest as a testing framework needs to import test modules and ``conftest.py`` files for execution. -Importing files in Python (at least until recently) is a non-trivial processes, often requiring -changing :data:`sys.path`. Some aspects of the +Importing files in Python is a non-trivial processes, so aspects of the import process can be controlled through the ``--import-mode`` command-line flag, which can assume these values: @@ -100,10 +99,17 @@ these values: 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. +.. note:: + + By default, pytest will not attempt to resolve namespace packages automatically, but that can + be changed via the :confval:`consider_namespace_packages` configuration variable. + .. seealso:: The :confval:`pythonpath` configuration variable. + The :confval:`consider_namespace_packages` configuration variable. + :ref:`test layout`. diff --git a/doc/en/reference/reference.rst b/doc/en/reference/reference.rst index bba4a399c..f84b7ea48 100644 --- a/doc/en/reference/reference.rst +++ b/doc/en/reference/reference.rst @@ -1274,6 +1274,19 @@ passed multiple times. The expected format is ``name=value``. For example:: variables, that will be expanded. For more information about cache plugin please refer to :ref:`cache_provider`. +.. confval:: consider_namespace_packages + + Controls if pytest should attempt to identify `namespace packages `__ + when collecting Python modules. Default is ``False``. + + Set to ``True`` if you are testing namespace packages installed into a virtual environment and it is important for + your packages to be imported using their full namespace package name. + + Only `native namespace packages `__ + are supported, with no plans to support `legacy namespace packages `__. + + .. versionadded:: 8.1 + .. confval:: console_output_style Sets the console output style while running tests: