Deprecated

Deprecated provides the @deprecated decorator, a small utility for marking Python functions, methods, and classes as obsolete so callers see a standard DeprecationWarning (or a category of your choice) pointing them toward a replacement. It’s built on top of wrapt, so decorated objects keep their original signature, docstring, and introspection behavior rather than being replaced by an opaque wrapper.

Beyond the basic decorator, the library ships a deprecated_params decorator for flagging individual keyword arguments as deprecated without breaking the whole function, and a deprecated.sphinx module that injects .. deprecated::, .. versionadded::, and .. versionchanged:: directives directly into docstrings for Sphinx-documented projects. It has supported Python since 2.7 and remains a common dependency for libraries that need to communicate API deprecations without hand-rolling warnings.warn calls.

What You Get

• The @deprecated decorator for functions, methods, classmethods, staticmethods, and classes, with optional reason and version metadata baked into the warning message
• A deprecated_params decorator that warns only when a caller actually passes a specific deprecated keyword argument, letting other parameters stay untouched
• A deprecated.sphinx module adding deprecated, versionadded, and versionchanged decorators that also rewrite the wrapped object’s docstring with the matching RST directive
• Configurable warning category (e.g. FutureWarning, PendingDeprecationWarning) and action (error, ignore, always, default, module, once) per decorated object
• An extensible ClassicAdapter base class so projects can override the warning message format entirely by subclassing

Common Use Cases

• A library maintainer wraps an old function with @deprecated(reason="use new_function instead", version="2.0") so downstream users get a warning pointing at the replacement
• A Sphinx-documented project uses deprecated.sphinx.deprecated alongside versionadded/versionchanged to keep docstring changelogs in sync with the actual code history
• A function renaming or retiring a keyword argument uses deprecated_params to warn only the callers still passing the old name, without breaking anyone immediately
• A CI pipeline passes action="error" in tests to fail the build the moment a deprecated code path is exercised, catching regressions before release

Under The Hood

Architecture The library centers on a single ClassicAdapter class (deprecated/classic.py) built on wrapt.AdapterFactory, which inspects whether the wrapped object is a class, function, method, or classmethod and formats an appropriate warning message before delegating to the original callable via wrapt.decorator; class deprecation is handled by monkey-patching __new__ rather than wrapping the class itself, so instantiation triggers the warning while the original class identity is preserved. The public deprecated() function in the same module is a thin factory supporting both bare (@deprecated) and parameterized (@deprecated(reason=..., version=...)) usage by inspecting whether the first positional argument is callable, falling back to functools.partial when configuration args are supplied instead. A parallel deprecated_params decorator (params.py) reuses the same warnings.warn plumbing but operates on bound argument names via inspect.signature, and subclassing ClassicAdapter — exactly what sphinx.SphinxAdapter does — is the extension point the whole design is built around, overriding message generation and injecting RST directives into docstrings rather than duplicating the wrapping logic.

Tech Stack The only runtime dependency is wrapt (bounded >=1.10,<3), used for its AdapterFactory/proxy machinery to produce transparent, introspectable wrappers; a conditional inspect2 dependency backports inspect.signature for legacy Python 2.7 support. The project is packaged with plain setuptools, tested across Python 2.7 through 3.14 and multiple wrapt versions via an extensive tox matrix, documented with Sphinx and published to Read the Docs, and additionally shipped as a Fedora/RPM package via a .packit.yml spec — a distribution path unusual for most PyPI libraries.

Code Quality Test coverage is extensive and scenario-driven — separate suites cover classic function/class deprecation, metaclass edge cases, Sphinx docstring injection, and parameter deprecation (tests/test_deprecated*.py, tests/test_sphinx*.py), run under pytest with coverage reported to Coveralls and exercised across the full tox version matrix in CI. Error handling favors explicit TypeError on misuse (such as decorating a non-callable) over silent failure, and CodeQL static analysis runs on every push. The codebase predates modern type-hint conventions, though — there are no inline annotations or .pyi stubs, with docstrings and Sphinx :type:/:param: fields carrying that documentation burden instead, and commit activity has slowed substantially in recent years even as the project remains maintained for compatibility.

API Design The core API is intentionally minimal — a single @deprecated decorator that works unconfigured on any function, method, or class — with all the customization power (custom message templates via ClassicAdapter subclassing, warning category, filter action, extra stack levels) available but never required for the common case. This zero-config-default, override-via-subclassing pattern extends cleanly to the Sphinx and parameter-deprecation variants, so a user who has learned the base deprecated decorator can pick up deprecated.sphinx.deprecated or deprecated_params with almost no new concepts to learn.