tmp_path.rst

Overview

This documentation describes the usage and behavior of the `tmp_path` and related fixtures provided by `pytest` for managing temporary directories and files during test execution. These fixtures simplify the creation and handling of isolated file-system resources that are unique per test function, facilitating safe and clean testing of code involving file operations.

The file explains the purpose, usage, and retention policies of the `tmp_path` fixture, its session-scoped counterpart `tmp_path_factory`, as well as the legacy `tmpdir` and `tmpdir_factory` fixtures. It also details the location and lifecycle management of temporary directories created by these fixtures.

Key functionalities covered:

• Providing temporary directories as pathlib.Path objects to tests.

• Creating persistent temporary directories at session scope.

• Migration guidance from legacy py.path.local-based fixtures.

• Configuration and retention of temporary directories.

• Interaction with concurrent test runs and pytest-xdist.

Detailed Descriptions

The tmp_path Fixture

**Purpose:** The `tmp_path` fixture provides a temporary directory unique to each test function. It is a convenient and modern way to handle temporary file-system resources using Python's standard `pathlib.Path` API.

**Type:** `pathlib.Path` object

**Usage Example:**

CONTENT = "content"

def test_create_file(tmp_path):
    d = tmp_path / "sub"
    d.mkdir()
    p = d / "hello.txt"
    p.write_text(CONTENT, encoding="utf-8")
    assert p.read_text(encoding="utf-8") == CONTENT
    assert len(list(tmp_path.iterdir())) == 1

Here, `tmp_path` is a directory provided by `pytest`. The test creates a subdirectory and a file within it, writes content, and verifies the expected results.

**Important Details:**

• Each test invocation receives a unique temporary directory.

• By default, pytest retains the last 3 temporary directories created across test runs.

• The directories are automatically cleaned according to retention policies or when the base temporary directory is cleared.

The tmp_path_factory Fixture

**Purpose:** `tmp_path_factory` is a session-scoped fixture that allows creation of arbitrary temporary directories from any fixture or test. This is useful when generating expensive or large data once per test session rather than per test function.

**Usage Example:**

# conftest.py
import pytest

@pytest.fixture(scope="session")
def image_file(tmp_path_factory):
    img = compute_expensive_image()
    fn = tmp_path_factory.mktemp("data") / "img.png"
    img.save(fn)
    return fn

# test_image.py
def test_histogram(image_file):
    img = load_image(image_file)
    # compute and test histogram

**Important Details:**

• Allows efficient reuse of temporary resources during the whole test session.

• Uses mktemp() method to create named temporary directories.

• Returns pathlib.Path objects.

• Complements tmp_path by providing session scope instead of function scope.

The tmpdir and tmpdir_factory Fixtures (Legacy)

**Purpose:** Legacy fixtures similar to `tmp_path` and `tmp_path_factory`, but return `py.path.local` objects instead of `pathlib.Path`.

**Notes:**

• Usage of tmp_path and tmp_path_factory is preferred for new code.

• Legacy path support can be disabled with the legacypath plugin to modernize tests.

• Disabling legacy paths triggers errors on tests using these old fixtures, encouraging migration.

Temporary Directory Location and Retention

**Default Location Template:**

{temproot}/pytest-of-{user}/pytest-{num}/{testname}/

• {temproot}: System temp directory (tempfile.gettempdir()), overridable by PYTEST_DEBUG_TEMPROOT.

• {user}: Username running the tests.

• {num}: Incremented number for each test suite run (retention feature).

• {testname}: Sanitized current test name.

**Retention:**

• By default, the last 3 temporary directories are retained.

• Controlled by pytest config options tmp_path_retention_count and tmp_path_retention_policy.

**Using `--basetemp` option:**

{basetemp}/{testname}/

• Overrides the base temporary directory.

• No retention feature; directory is cleared before each run.

• Use with caution to avoid data loss.

**Interaction with `pytest-xdist`:**

• Temporary directories are configured per subprocess to avoid conflicts.

• Ensures all temp data lands under a single per-test run temporary directory.

Implementation and Algorithms

• The fixtures rely on Python's pathlib.Path for path manipulations, providing a modern and idiomatic interface to the filesystem.

• Temporary directories are created under a base directory with a unique structure to avoid collisions.

• Retention is implemented by keeping a configurable number of previous run directories, identified via incremented run numbers.

• When the --basetemp option is used, retention is disabled, and the directory is cleared before each test run.

• Support for concurrent test runs and distributed testing (pytest-xdist) ensures isolation by adjusting base temporary directories accordingly.

Interactions with Other Parts of the System

• These fixtures integrate deeply with the pytest testing framework, automatically injected into test functions or fixtures as needed.

• The temporary directories provided are used by the tests to isolate filesystem operations and avoid side effects.

• The retention and cleanup policies interact with pytest's configuration system via command-line options and configuration variables.

• The legacy tmpdir fixtures interface with the older py.path library, whereas tmp_path fixtures use standard library pathlib.

• When used with plugins like pytest-xdist, the fixtures adapt to support parallel or distributed test executions.

Visual Diagram: Mermaid Class and Fixture Interaction Diagram

classDiagram
    class tmp_path {
        +pathlib.Path directory
        +create_subdir(name)
        +write_text(file, content)
        +read_text(file)
    }

    class tmp_path_factory {
        +mktemp(name): pathlib.Path
    }

    class tmpdir {
        +py.path.local directory
    }

    class tmpdir_factory {
        +mktemp(name): py.path.local
    }

    tmp_path_factory --|> tmp_path : creates
    tmpdir_factory --|> tmpdir : creates
    tmp_path ..|> pathlib.Path
    tmpdir ..|> py.path.local

This diagram shows the relationship between the primary fixtures, their types, and their factory counterparts. `tmp_path` and `tmp_path_factory` use the modern `pathlib.Path`, while `tmpdir` and `tmpdir_factory` use the legacy `py.path.local` objects.

Summary

The [tmp_path.rst](/projects/286/67363) file serves as an authoritative guide on how pytest manages temporary directories and files for testing. It advocates the use of `tmp_path` and `tmp_path_factory` fixtures for modern, pathlib-based temporary file handling, explains legacy alternatives, and clarifies the configuration, retention, and lifecycle of these temporary resources. By using these fixtures, test authors can write cleaner, safer tests involving filesystem operations with automatic cleanup and isolation.

**End of Documentation**