deprecated.py

Overview

The `deprecated.py` module centralizes deprecation warnings and related code snippets used throughout the pytest codebase. Its primary purpose is to track features, APIs, or plugins that are planned to be removed in future pytest releases. By consolidating all deprecation messages and warning definitions into one file, it simplifies maintenance and ensures consistent communication about deprecated functionality across the project.

This module defines a collection of warning constants, mostly instances of [PytestWarning](/projects/286/67359) or `UnformattedWarning`, representing various deprecations. It also provides utility functions to facilitate the controlled issuance of deprecation warnings during runtime.

Contents

• Constants representing different deprecation warnings.

• A utility function check_ispytest to enforce private API usage.

• A set of deprecated external plugins to ignore during registration.

Detailed Explanations

Constants

Each constant in this module is a warning message related to deprecated functionality. They are designed to be raised via Python’s warning system and include references to official documentation for further guidance.

DEPRECATED_EXTERNAL_PLUGINS

DEPRECATED_EXTERNAL_PLUGINS: set[str]

• Description:
  A set of plugin names that have been integrated into the pytest core. These plugins should be ignored during plugin registration to avoid conflicts.

• Contents:

  • "pytest_catchlog"

  • "pytest_capturelog"

  • "pytest_faulthandler"

• Usage:
  This set is used internally in pytest's plugin management system to skip loading these plugins externally.

YIELD_FIXTURE

YIELD_FIXTURE = PytestDeprecationWarning(...)

• Description:
  Warning message indicating that @pytest.yield_fixture is deprecated and advising the use of @pytest.fixture instead.

• Message:

  "@pytest.yield_fixture is deprecated.\nUse @pytest.fixture instead; they are the same."

• Usage Example:
  If a user still uses @pytest.yield_fixture, pytest will emit this deprecation warning.

PRIVATE

PRIVATE = PytestDeprecationWarning(...)

• Description:
  Warning issued when a private pytest class or function is used externally. This warning helps enforce encapsulation and marks internal APIs that should not be accessed by test code or plugins.

• Message:

  "A private pytest class or function was used."

HOOK_LEGACY_PATH_ARG

HOOK_LEGACY_PATH_ARG = UnformattedWarning(...)

• Description:
  A warning for hook functions that use the deprecated py.path.local argument instead of the new pathlib.Path argument.

• Warning Class:
  PytestRemovedIn9Warning (indicates removal planned in pytest version 9).

• Message Template:

  "The ({pylib_path_arg}: py.path.local) argument is deprecated, please use ({pathlib_path_arg}: pathlib.Path)\nsee https://docs.pytest.org/en/latest/deprecations.html#py-path-local-arguments-for-hooks-replaced-with-pathlib-path"

• Parameters:

  • pylib_path_arg: Name of the deprecated argument.

  • pathlib_path_arg: Name of the new argument.

• Usage Example:
  When a hook implementation still declares the old argument type, pytest uses this warning to inform developers of the change.

NODE_CTOR_FSPATH_ARG

NODE_CTOR_FSPATH_ARG = UnformattedWarning(...)

• Description:
  Warning for node constructors that accept the deprecated fspath: py.path.local argument instead of the path: pathlib.Path argument.

• Warning Class:
  PytestRemovedIn9Warning

• Message Template:

  "The (fspath: py.path.local) argument to {node_type_name} is deprecated. Please use the (path: pathlib.Path) argument instead.\nSee https://docs.pytest.org/en/latest/deprecations.html#fspath-argument-for-node-constructors-replaced-with-pathlib-path"

• Parameters:

  • node_type_name: Name of the node type class or constructor.

HOOK_LEGACY_MARKING

HOOK_LEGACY_MARKING = UnformattedWarning(...)

• Description:
  Warning that indicates a hook uses old-style configuration options (marks or attributes) rather than the modern pytest.hook decorator.

• Warning Class:
  PytestDeprecationWarning

• Message Template:

  "The hook{type} {fullname} uses old-style configuration options (marks or attributes).\nPlease use the pytest.hook{type}({hook_opts}) decorator instead\n to configure the hooks.\n See https://docs.pytest.org/en/latest/deprecations.html#configuring-hook-specs-impls-using-markers"

• Parameters:

  • type: Hook type (e.g., "impl" or "spec").

  • fullname: Full name of the hook.

  • hook_opts: Options for the new decorator.

MARKED_FIXTURE

MARKED_FIXTURE = PytestRemovedIn9Warning(...)

• Description:
  Warning indicating that applying marks to fixtures has no effect and will be removed in pytest 9.

• Message:

  "Marks applied to fixtures have no effect\nSee docs: https://docs.pytest.org/en/stable/deprecations.html#applying-a-mark-to-a-fixture-function"

Functions

check_ispytest

def check_ispytest(ispytest: bool) -> None:

• Purpose:
  Utility function to help enforce that certain private pytest functions or constructors are only called internally by pytest itself. It helps prevent external code from using private APIs.

• Parameters:

  • ispytest (bool): Flag indicating if the caller is internal pytest code. Should be set to True internally; external calls will have it False by default.

• Behavior:
  If ispytest is False, the function issues the PRIVATE deprecation warning, indicating misuse of a private API.

• Usage Pattern:

  1. Define a private function with an extra keyword-only argument _ispytest: bool = False.

  2. Call check_ispytest(_ispytest) at the start of the function.

  3. Internal pytest code calls the function with _ispytest=True.

  4. External calls leave _ispytest as default False and trigger the warning.

• Example:

def _my_private_function(arg1, *, _ispytest: bool = False):
    check_ispytest(_ispytest)
    # Function implementation

# Internal call (allowed)
_my_private_function("value", _ispytest=True)

# External call (triggers warning)
_my_private_function("value")

Important Implementation Details

• The module relies heavily on specialized warning classes from _pytest.warning_types such as PytestDeprecationWarning, PytestRemovedIn9Warning, and UnformattedWarning. This abstraction allows warnings to be categorized by severity and planned removal timeline.

• UnformattedWarning is used for warnings requiring runtime formatting with parameters, enabling dynamic and contextual messages.

• The check_ispytest function provides a pattern to mark internal APIs and detect unauthorized external usage, supporting pytest’s internal encapsulation strategy.

• The constants include URLs linking to official pytest documentation about deprecations, facilitating user migration.

Interaction with Other Parts of the System

• This module is imported by other pytest modules that need to issue deprecation warnings. Instead of defining warnings locally, they import the relevant constant from deprecated.py.

• The warning classes (PytestDeprecationWarning, PytestRemovedIn9Warning, UnformattedWarning) are imported from _pytest.warning_types which provides the base warning infrastructure.

• The DEPRECATED_EXTERNAL_PLUGINS set is used by pytest’s plugin management system to skip loading integrated plugins externally.

• The check_ispytest function is intended to be called from private pytest APIs to enforce encapsulation and warn users who call internal APIs directly.

Visual Diagram

classDiagram
    class deprecated {
        <<module>>
        +DEPRECATED_EXTERNAL_PLUGINS: set[str]
        +YIELD_FIXTURE: PytestDeprecationWarning
        +PRIVATE: PytestDeprecationWarning
        +HOOK_LEGACY_PATH_ARG: UnformattedWarning
        +NODE_CTOR_FSPATH_ARG: UnformattedWarning
        +HOOK_LEGACY_MARKING: UnformattedWarning
        +MARKED_FIXTURE: PytestRemovedIn9Warning
        +check_ispytest(ispytest: bool) void
    }
    deprecated ..> PytestDeprecationWarning : uses
    deprecated ..> PytestRemovedIn9Warning : uses
    deprecated ..> UnformattedWarning : uses

Summary

The `deprecated.py` module is a centralized repository for deprecation warnings used throughout pytest. It simplifies maintenance by consolidating all deprecation messages and related utilities into a single place, standardizes how warnings are issued, and supports pytest’s internal API encapsulation. This approach improves the user experience by providing clear guidance on deprecated features and smooth migration to newer APIs.