Skip to content

Commit

Permalink
doc: document consider_namespace_packages option
Browse files Browse the repository at this point in the history
  • Loading branch information
nicoddemus committed Mar 2, 2024
1 parent aac720a commit d6134bc
Show file tree
Hide file tree
Showing 4 changed files with 25 additions and 4 deletions.
4 changes: 2 additions & 2 deletions changelog/11475.feature.rst
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
pytest now correctly identifies modules that are part of `namespace packages <https://packaging.python.org/en/latest/guides/packaging-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 <https://packaging.python.org/en/latest/guides/packaging-namespace-packages>`__ when importing modules.
2 changes: 2 additions & 0 deletions changelog/11475.improvement.rst
Original file line number Diff line number Diff line change
@@ -1 +1,3 @@
:ref:`--import-mode=importlib <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``).
10 changes: 8 additions & 2 deletions doc/en/explanation/pythonpath.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down Expand Up @@ -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`.


Expand Down
13 changes: 13 additions & 0 deletions doc/en/reference/reference.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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 <https://packaging.python.org/en/latest/guides/packaging-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 <https://packaging.python.org/en/latest/guides/packaging-namespace-packages/#native-namespace-packages>`__
are supported, with no plans to support `legacy namespace packages <https://packaging.python.org/en/latest/guides/packaging-namespace-packages/#legacy-namespace-packages>`__.

.. versionadded:: 8.1

.. confval:: console_output_style

Sets the console output style while running tests:
Expand Down

0 comments on commit d6134bc

Please sign in to comment.