deprecations.rst

Overview

The `deprecations.rst` file serves as the comprehensive changelog and reference document detailing **deprecated and removed features** in the `pytest` testing framework. It informs users and plugin developers about features that have been marked deprecated in recent `pytest` versions, explains the rationale behind removals or changes, and provides guidance on how to adapt codebases for compatibility with current or future `pytest` releases.

This document is essential for maintaining forward compatibility of test suites, plugins, and extensions with `pytest` by:

• Listing deprecated features with explanations and alternatives.

• Documenting breaking changes and removals from past major releases.

• Providing migration paths and usage examples.

• Clarifying internal API changes impacting plugin authors.

The file is organized in thematic sections covering various features, APIs, hooks, and behaviors that are deprecated or removed, each annotated with version information (e.g., [.. deprecated:: 7.0](/projects/286/67361) or `.. versionremoved:: 8.0`).

Detailed Explanations

Since this is a reStructuredText documentation file rather than source code, it does not define classes or functions directly. Instead, it documents many pytest features, APIs, and behaviors. Below are detailed explanations of selected notable deprecations and removals, illustrating their context, parameters (where applicable), and usage recommendations.

1. Sync test depending on async fixture (deprecated:: 8.4)

**Issue:** Synchronous test functions depending on asynchronous fixtures can cause confusing warnings or errors, especially with async yield fixtures, due to unawaited coroutines and caching effects.

**Explanation:**

• Previously, async test functions were detected and required plugins to handle them.

• Async fixtures used by sync tests issued warnings inconsistently.

• Caching async fixture results could hide problems if async tests run first.

**Recommended migration:** Wrap async fixtures inside a synchronous fixture that returns the coroutine, allowing [asyncio.run()](/projects/286/67309) in the test to await it properly.

**Example:**

import asyncio
import pytest

@pytest.fixture
def unawaited_fixture():
    async def inner_fixture():
        return 1
    return inner_fixture()

def test_foo(unawaited_fixture):
    assert 1 == asyncio.run(unawaited_fixture)

**Alternative:** Use `pytest_fixture_setup` hook in plugins to handle async fixtures before pytest sees them.

2. pytest.importorskip default behavior change (deprecated:: 8.2)

**Issue:** `pytest.importorskip()` traditionally catches all `ImportError`s, skipping tests when dependencies are missing. However, some `ImportError`s arise from broken installations rather than missing modules, and silently skipping hides real issues.

**Change:**

• Added exc_type parameter to specify which exceptions to catch (default is still ImportError for backward compatibility).

• Emits warnings if ImportError is caught without explicit exc_type parameter.

• Future versions will restrict catches to ModuleNotFoundError only, turning warnings into errors.

**Usage change:**

# Old usage (may skip on unexpected ImportErrors)
pytest.importorskip("somemodule")

# New recommended usage to skip only if module is missing
pytest.importorskip("somemodule", exc_type=ModuleNotFoundError)

3. fspath argument replaced by pathlib.Path in Node constructors (deprecated:: 7.0)

**Issue:** `pytest` is migrating from `py.path.local` objects to standard library `pathlib.Path` for path handling.

**Change:**

• Node constructors like pytest.Function.from_parent() should receive path argument of type pathlib.Path instead of fspath (py.path.local).

• Plugins should update custom node constructors to accept path, and avoid hardcoded fspath.

• Both fspath and path attributes exist currently for backward compatibility; fspath will be removed in future.

**Notes:**

• The naming of arguments/attributes differs between node constructors (path) and hooks (path was old argument).

• This is part of a gradual removal of the py dependency.

4. Deprecated direct construction of internal classes (deprecated:: 7.0)

**Affected classes:**

• _pytest.mark.structures.Mark

• _pytest.mark.structures.MarkDecorator

• _pytest.mark.structures.MarkGenerator

• _pytest.python.Metafunc

• _pytest.runner.CallInfo

• _pytest._code.ExceptionInfo

• _pytest.config.argparsing.Parser

• _pytest.config.argparsing.OptionGroup

• _pytest.pytester.HookRecorder

**Explanation:** These constructors have always been private, but now emit deprecation warnings and may become errors in `pytest 8`. Plugin authors should avoid instantiating these directly.

5. Diamond inheritance between pytest.Collector and pytest.Item (deprecated:: 7.0)

**Issue:** Custom node types inheriting from both `Collector` and `Item` cause complex diamond inheritance problems and hard-to-debug errors.

**Recommendation:** Use a separate collector node to collect items instead of combining the two in one class.

6. Deprecated yield_fixture (deprecated:: 6.2)

**Explanation:** `pytest.yield_fixture` is an alias for `pytest.fixture` and has been deprecated for a long time. Users should replace `@pytest.yield_fixture` with `@pytest.fixture`.

7. Removed support for yield tests (versionremoved:: 8.4)

**Issue:** Old-style test functions that `yield` test cases are no longer supported.

**Migration:** Switch to `@pytest.mark.parametrize` to define parameterized tests.

**Example migration:**

# Deprecated yield test
def test_squared():
    yield check, 2, 4
    yield check, 3, 9

# Updated parametrize style
@pytest.mark.parametrize("x, y", [(2, 4), (3, 9)])
def test_squared(x, y):
    assert x**x == y

8. Removed support for nose-style tests and utilities (deprecated:: 7.2, versionremoved:: 8.0)

• setup and teardown methods replaced by setup_method and teardown_method.

• @with_setup decorator from nose.tools replaced by fixtures.

• compat_co_firstlineno attribute ignored.

9. Passing msg= to pytest.skip, pytest.fail, or pytest.exit (deprecated:: 7.0, versionremoved:: 8.0)

**Change:** Use `reason=` keyword argument instead of `msg=` for consistency.

10. Other notable removals and deprecations:

• Removal of the pytest.Instance collector (removed in 7.0).

• Deprecation of pytest.warns(None) usage.

• Removal of pytest.collect module from public API (moved to pytest module).

• Removal of pytest_warning_captured hook in favor of pytest_warning_recorded.

• Removal of many legacy command-line options (--strict, --no-print-logs, --result-log).

• Migration to cooperative constructors for custom node subclasses (**kwargs in __init__).

• Removal of pytest_namespace hook and deprecated internal warning functions.

Implementation Details and Algorithms

As a documentation file, `deprecations.rst` does not implement algorithms or classes. Its content is structured using reStructuredText directives and cross-references, integrating with pytest’s documentation system to provide:

• Anchors for internal references (e.g., .. _sync-test-async-fixture:).

• Deprecation and removal annotations with version tags (.. deprecated::, .. versionremoved::).

• Code blocks illustrating old and new usage patterns.

• Links to related documentation and external resources for migration help.

The document is continuously updated alongside pytest releases to reflect current deprecation policies and provide a single source of truth for users and developers.

Interactions with Other Parts of the System

• User-facing Documentation: This file is part of the official pytest documentation, guiding users on best practices and migration steps.

• Warning System: Deprecated features documented here usually emit runtime warnings (PytestWarning or subclasses) to alert users when deprecated functionality is used.

• Plugin Ecosystem: Plugin authors rely on this document to update their plugins to maintain compatibility with pytest’s evolving API and internals.

• Test Suites: Test codebases consult this documentation to prepare for pytest upgrades by replacing deprecated constructs.

• Versioning and Release Management: The document reflects pytest’s backward compatibility policy, marking features for deprecation before removal in major releases.

Visual Diagram

Since this is a documentation file without code definitions, the most useful diagram is a **flowchart** illustrating the **categorization of deprecations and removals** and their relationships.

flowchart TD
    A[deprecations.rst] --> B[Deprecated Features]
    A --> C[Removed Features and Breaking Changes]

    B --> B1[sync test depending on async fixture]
    B --> B2[importorskip ImportError behavior]
    B --> B3[fspath argument replaced by pathlib.Path]
    B --> B4[Direct construction of internal classes]
    B --> B5[Diamond inheritance deprecated]
    B --> B6[yield_fixture deprecated]
    B --> B7[Passing msg= to skip/fail/exit deprecated]
    B --> B8[Calling fixtures directly deprecated]

    C --> C1[yield tests removed]
    C --> C2[nose support removed]
    C --> C3[pytest.Instance collector removed]
    C --> C4[pytest.collect module removed]
    C --> C5[Command-line options removed (--strict, --result-log)]
    C --> C6[pytest_namespace hook removed]

    B1 -->|Migration| M1[Wrap async fixture in sync fixture]
    B2 -->|Migration| M2[Use exc_type=ModuleNotFoundError]
    B3 -->|Migration| M3[Use pathlib.Path in node constructors]
    C1 -->|Migration| M4[Use @pytest.mark.parametrize]
    C2 -->|Migration| M5[Use pytest fixtures instead of nose setup]

    style A fill:#f9f,stroke:#333,stroke-width:2px
    style B fill:#bbf,stroke:#333,stroke-width:1px
    style C fill:#fbb,stroke:#333,stroke-width:1px

Summary

The `deprecations.rst` file is a crucial resource for pytest users and developers, documenting all deprecated and removed features, explaining their history, providing examples and migration advice, and ensuring smooth transitions across pytest versions. It promotes best practices, reduces user confusion, and supports the maintainability of pytest and its ecosystem.

By regularly consulting this file, users can keep their test suites and plugins up to date, avoiding surprises during pytest upgrades and leveraging the latest improvements in testing infrastructure.