deprecation

deprecation is a small, focused Python library that turns marking code as deprecated into an automated, testable process. Its @deprecated decorator records when a function or method was deprecated, when it will be removed, and why, and appends that information to the object’s docstring so generated API docs stay accurate without manual notices.

Its companion @fail_if_not_removed test decorator closes the loop: once a deprecated object passes its declared removal version, tests that exercise it raise an AssertionError, so your test suite reminds you to actually delete the code instead of letting deprecated APIs live on indefinitely.

What You Get

• A @deprecated decorator that emits warnings and records deprecated/removed versions and details
• Automatic appending of deprecation information to a callable’s docstring for accurate API docs
• A @fail_if_not_removed test decorator that fails tests once code is past its removal version
• Integration with both unittest and pytest test suites
• A tiny dependency footprint (only the packaging library) and single-module implementation

Common Use Cases

• Marking library functions as deprecated with clear removal timelines for users
• Keeping API documentation deprecation notices accurate without writing them by hand
• Using tests to enforce that deprecated code is actually removed on schedule

Under The Hood

Architecture - The entire library lives in a single module, deprecation.py (~290 lines). It centers on a DeprecatedWarning (a DeprecationWarning subclass) plus an UnsupportedWarning, a deprecated decorator that stores deprecated_in/removed_in/current_version metadata on the wrapped callable and mutates its doc, and a fail_if_not_removed decorator that inspects raised UnsupportedWarnings during tests to force a failure. Version comparisons are delegated to the packaging library so removal timing is evaluated with proper version semantics.

Tech Stack - Pure Python packaged with setuptools (setup.py/setup.cfg), depending only on packaging at runtime. Testing uses unittest/pytest with tox for multi-version test matrices, and documentation is built with Sphinx on Read the Docs.

Code Quality - Despite its small size the project is well tested: tests/test_deprecation.py exercises the decorators, warnings, docstring mutation, and removal enforcement, with coverage reporting configured. The single-module design and narrow dependency surface make the behavior easy to audit; the project is stable and unchanged since 2.1.0 rather than under active development.

API Design - The public API is two decorators, which makes it trivial to adopt: decorate the deprecated callable, optionally decorate the test, and the library handles warnings, documentation, and enforcement. Keyword arguments (deprecated_in, removed_in, current_version, details) read clearly at the call site, giving it a very gentle learning curve.