Skip to content

Commit 7aeb72b

Browse files
Improve docs on basetemp and retention (#12912) (#12928)
Improve coverage of current handling of `--basetemp` option and its lack of retention functionality. Also document `PYTEST_DEBUG_TEMPROOT`. Related to #10829 --------- Co-authored-by: Bruno Oliveira <[email protected]> (cherry picked from commit a1a4918) Co-authored-by: Stefaan Lippens <[email protected]>
1 parent c875841 commit 7aeb72b

File tree

5 files changed

+53
-40
lines changed

5 files changed

+53
-40
lines changed

changelog/10829.doc.rst

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Improve documentation on the current handling of the ``--basetemp`` option and its lack of retention functionality (:ref:`temporary directory location and retention`).

doc/en/how-to/tmp_path.rst

+35-15
Original file line numberDiff line numberDiff line change
@@ -133,27 +133,47 @@ API for details.
133133
Temporary directory location and retention
134134
------------------------------------------
135135

136-
Temporary directories are by default created as sub-directories of
137-
the system temporary directory. The base name will be ``pytest-NUM`` where
138-
``NUM`` will be incremented with each test run.
139-
By default, entries older than 3 temporary directories will be removed.
140-
This behavior can be configured with :confval:`tmp_path_retention_count` and
141-
:confval:`tmp_path_retention_policy`.
136+
The temporary directories,
137+
as returned by the :fixture:`tmp_path` and (now deprecated) :fixture:`tmpdir` fixtures,
138+
are automatically created under a base temporary directory,
139+
in a structure that depends on the ``--basetemp`` option:
142140

143-
Using the ``--basetemp``
144-
option will remove the directory before every run, effectively meaning the temporary directories
145-
of only the most recent run will be kept.
141+
- By default (when the ``--basetemp`` option is not set),
142+
the temporary directories will follow this template:
146143

147-
You can override the default temporary directory setting like this:
144+
.. code-block:: text
148145
149-
.. code-block:: bash
146+
{temproot}/pytest-of-{user}/pytest-{num}/{testname}/
150147
151-
pytest --basetemp=mydir
148+
where:
152149

153-
.. warning::
150+
- ``{temproot}`` is the system temporary directory
151+
as determined by :py:func:`tempfile.gettempdir`.
152+
It can be overridden by the :envvar:`PYTEST_DEBUG_TEMPROOT` environment variable.
153+
- ``{user}`` is the user name running the tests,
154+
- ``{num}`` is a number that is incremented with each test suite run
155+
- ``{testname}`` is a sanitized version of :py:attr:`the name of the current test <_pytest.nodes.Node.name>`.
154156

155-
The contents of ``mydir`` will be completely removed, so make sure to use a directory
156-
for that purpose only.
157+
The auto-incrementing ``{num}`` placeholder provides a basic retention feature
158+
and avoids that existing results of previous test runs are blindly removed.
159+
By default, the last 3 temporary directories are kept,
160+
but this behavior can be configured with
161+
:confval:`tmp_path_retention_count` and :confval:`tmp_path_retention_policy`.
162+
163+
- When the ``--basetemp`` option is used (e.g. ``pytest --basetemp=mydir``),
164+
it will be used directly as base temporary directory:
165+
166+
.. code-block:: text
167+
168+
{basetemp}/{testname}/
169+
170+
Note that there is no retention feature in this case:
171+
only the results of the most recent run will be kept.
172+
173+
.. warning::
174+
175+
The directory given to ``--basetemp`` will be cleared blindly before each test run,
176+
so make sure to use a directory for that purpose only.
157177

158178
When distributing tests on the local machine using ``pytest-xdist``, care is taken to
159179
automatically configure a `basetemp` directory for the sub processes such that all temporary

doc/en/reference/reference.rst

+5
Original file line numberDiff line numberDiff line change
@@ -1146,6 +1146,11 @@ processes can inspect it, see :ref:`pytest current test env` for more informatio
11461146

11471147
When set, pytest will print tracing and debug information.
11481148

1149+
.. envvar:: PYTEST_DEBUG_TEMPROOT
1150+
1151+
Root for temporary directories produced by fixtures like :fixture:`tmp_path`
1152+
as discussed in :ref:`temporary directory location and retention`.
1153+
11491154
.. envvar:: PYTEST_DISABLE_PLUGIN_AUTOLOAD
11501155

11511156
When set, disables plugin auto-loading through :std:doc:`entry point packaging

src/_pytest/legacypath.py

+5-10
Original file line numberDiff line numberDiff line change
@@ -304,16 +304,11 @@ def tmpdir_factory(request: FixtureRequest) -> TempdirFactory:
304304
@staticmethod
305305
@fixture
306306
def tmpdir(tmp_path: Path) -> LEGACY_PATH:
307-
"""Return a temporary directory path object which is unique to each test
308-
function invocation, created as a sub directory of the base temporary
309-
directory.
310-
311-
By default, a new base temporary directory is created each test session,
312-
and old bases are removed after 3 sessions, to aid in debugging. If
313-
``--basetemp`` is used then it is cleared each session. See
314-
:ref:`temporary directory location and retention`.
315-
316-
The returned object is a `legacy_path`_ object.
307+
"""Return a temporary directory (as `legacy_path`_ object)
308+
which is unique to each test function invocation.
309+
The temporary directory is created as a subdirectory
310+
of the base temporary directory, with configurable retention,
311+
as discussed in :ref:`temporary directory location and retention`.
317312
318313
.. note::
319314
These days, it is preferred to use ``tmp_path``.

src/_pytest/tmpdir.py

+7-15
Original file line numberDiff line numberDiff line change
@@ -41,9 +41,8 @@
4141
@final
4242
@dataclasses.dataclass
4343
class TempPathFactory:
44-
"""Factory for temporary directories under the common base temp directory.
45-
46-
The base directory can be configured using the ``--basetemp`` option.
44+
"""Factory for temporary directories under the common base temp directory,
45+
as discussed at :ref:`temporary directory location and retention`.
4746
"""
4847

4948
_given_basetemp: Path | None
@@ -257,18 +256,11 @@ def _mk_tmp(request: FixtureRequest, factory: TempPathFactory) -> Path:
257256
def tmp_path(
258257
request: FixtureRequest, tmp_path_factory: TempPathFactory
259258
) -> Generator[Path]:
260-
"""Return a temporary directory path object which is unique to each test
261-
function invocation, created as a sub directory of the base temporary
262-
directory.
263-
264-
By default, a new base temporary directory is created each test session,
265-
and old bases are removed after 3 sessions, to aid in debugging.
266-
This behavior can be configured with :confval:`tmp_path_retention_count` and
267-
:confval:`tmp_path_retention_policy`.
268-
If ``--basetemp`` is used then it is cleared each session. See
269-
:ref:`temporary directory location and retention`.
270-
271-
The returned object is a :class:`pathlib.Path` object.
259+
"""Return a temporary directory (as :class:`pathlib.Path` object)
260+
which is unique to each test function invocation.
261+
The temporary directory is created as a subdirectory
262+
of the base temporary directory, with configurable retention,
263+
as discussed in :ref:`temporary directory location and retention`.
272264
"""
273265
path = _mk_tmp(request, tmp_path_factory)
274266
yield path

0 commit comments

Comments
 (0)