`missing-deprecation`¶

Part of: Enrichment Check


Check	enrichment
Category	required
Applies to	functions, methods
Since	v1.15.0

Function uses deprecation patterns but has no deprecation notice in docstring

What it detects¶

This rule flags functions and methods that use deprecation patterns in their code but have no deprecation notice in their docstring. It detects two families of patterns:

warnings.warn() with a deprecation category — DeprecationWarning, PendingDeprecationWarning, or FutureWarning as the second positional argument or category keyword argument.
@deprecated decorator (PEP 702) — from typing_extensions or warnings (Python 3.13+).

A deprecation notice is satisfied by the word "deprecated" appearing anywhere in the docstring (case-insensitive).

Why is this a problem?¶

Users reading the documentation have no way to know the function is deprecated. Without a visible notice in the docstring, callers will continue using the deprecated API, miss migration deadlines, and encounter unexpected breakage when the function is eventually removed.

How to Fix¶

Add a deprecation notice to the docstring. The word "deprecated" must appear somewhere in the docstring (case-insensitive). Common formats:

Google-style:

Deprecated:
    Use :func:`new_func` instead. Will be removed in v3.0.

Sphinx-style:

.. deprecated:: 2.0
    Use :func:`new_func` instead.

Inline:

"""Connect to the server (deprecated — use connect_async)."""

Example¶

ViolationFix

import warnings

def connect(host: str) -> Connection:
    """Connect to the server.

    Args:
        host: The server hostname.

    Returns:
        An established connection.
    """
    warnings.warn(
        "connect() is deprecated, use connect_async()",
        DeprecationWarning,
        stacklevel=2,
    )
    return Connection(host)

import warnings

def connect(host: str) -> Connection:
    """Connect to the server.

    Deprecated:
        Use :func:`connect_async` instead. Will be removed in v3.0.

    Args:
        host: The server hostname.

    Returns:
        An established connection.
    """
    warnings.warn(
        "connect() is deprecated, use connect_async()",
        DeprecationWarning,
        stacklevel=2,
    )
    return Connection(host)

Configuration¶

Disable this rule in pyproject.toml:

[tool.docvet.enrichment]
require-deprecation-notice = false

Detected patterns¶

Pattern	Example
`warnings.warn(..., DeprecationWarning)`	`warnings.warn("old", DeprecationWarning)`
`warnings.warn(..., PendingDeprecationWarning)`	`warnings.warn("old", PendingDeprecationWarning)`
`warnings.warn(..., FutureWarning)`	`warnings.warn("old", FutureWarning)`
`warnings.warn(..., category=...)`	`warnings.warn("old", category=DeprecationWarning)`
`@deprecated("reason")`	PEP 702 decorator from `typing_extensions` or `warnings`

Note: warnings.warn("msg") with no explicit category defaults to UserWarning and is not detected by this rule.

missing-deprecation¶