Python Deprecation Utilities

2.1.0 verified Tue May 12 auth: no python install: verified quickstart: verified maintenance

The `deprecation` library (version 2.1.0) provides decorators to manage automated deprecations in Python code, including updating docstrings and enabling test failures for removed code. It aims to automate the process of signaling deprecated features to users and ensuring timely removal of obsolete code. The library's last release was in April 2020, suggesting a maintenance or slower release cadence. [1, 7]

pip install deprecation

Common errors

error ModuleNotFoundError: No module named 'deprecation' ↓

cause The 'deprecation' library is not installed in the Python environment.

fix

Install the 'deprecation' library using pip: 'pip install deprecation'.

error ImportError: cannot import name 'deprecated' from 'deprecation' ↓

cause The 'deprecated' decorator is not correctly imported from the 'deprecation' library.

fix

Ensure the import statement is correct: 'from deprecation import deprecated'.

error TypeError: deprecated() missing 1 required positional argument: 'deprecated_in' ↓

cause The 'deprecated' decorator is used without specifying the 'deprecated_in' argument.

fix

Provide the 'deprecated_in' argument when using the decorator: '@deprecated(deprecated_in="1.0", removed_in="2.0", current_version=__version__, details="Use the bar function instead")'.

error AttributeError: module 'deprecation' has no attribute 'fail_if_not_removed' ↓

cause The 'fail_if_not_removed' decorator is not correctly imported from the 'deprecation' library.

fix

Ensure the import statement is correct: 'from deprecation import fail_if_not_removed'.

error DeprecationWarning: Call to deprecated function 'foo'. (Use the bar function instead) ↓

cause A function marked with the 'deprecated' decorator is being called.

fix

Update the code to use the recommended alternative function as specified in the deprecation warning.

Warnings

gotcha Python's default behavior is to ignore `DeprecationWarning` messages. Users of this library (or any library emitting `DeprecationWarning`) will not see the warnings unless they explicitly configure Python (e.g., by running with `python -Wd` or setting the environment variable `PYTHONWARNINGS=default`). This can lead to silently using deprecated code. [1, 7] ↓

fix Ensure `PYTHONWARNINGS` environment variable is set to `default` or `always` in development and testing environments, or run Python with the `-Wd` or `-Wa` flag. For production, consider capturing warnings in logs.

breaking The `fail_if_not_removed` decorator is designed to raise an `AssertionError` if the `current_version` meets or exceeds the `removed_in` version specified. This is an intentional feature to enforce removal of obsolete code but will cause build or test failures in continuous integration pipelines if not properly managed as versions progress. [1, 7] ↓

fix Actively remove code that has passed its `removed_in` version to avoid test failures. Use `current_version` parameter accurately to reflect your project's version.

gotcha There is another popular and more actively maintained library named `Deprecated` (PyPI slug `Deprecated`, often imported as `from deprecated import deprecated`). Users might confuse these two distinct libraries due to similar names and functionality. Ensure you are importing from `deprecation` (lowercase PyPI slug) if you intend to use this specific library by Brian Curtin. [3, 9, 11] ↓

fix Double-check import statements to ensure `from deprecation import deprecated` for this library, and `from deprecated import deprecated` for the other. Consult the respective library's documentation for API differences.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.02s 18.4M

3.10 slim (glibc) - - 0.01s 19M

3.11 alpine (musl) - - 0.05s 20.3M

3.11 slim (glibc) - - 0.04s 21M

3.12 alpine (musl) - - 0.03s 12.2M

3.12 slim (glibc) - - 0.03s 13M

3.13 alpine (musl) - - 0.06s 11.8M

3.13 slim (glibc) - - 0.06s 12M

3.9 alpine (musl) - - 0.02s 17.9M

3.9 slim (glibc) - - 0.02s 18M

Imports

deprecated
```
from deprecation import deprecated
```

fail_if_not_removed

from deprecation import fail_if_not_removed

Quickstart verified last tested: 2026-04-23

Demonstrates how to use the `@deprecated` decorator with versioning and how to call the decorated function. It also shows the typical use case for `fail_if_not_removed` in a testing context to ensure deprecated code is eventually removed. Note that `PYTHONWARNINGS` or a `-W` flag is often required to see `DeprecationWarning` messages at runtime. [1, 7]

import os
import warnings
from deprecation import deprecated, fail_if_not_removed

# Simulate library version for demonstration
__version__ = "1.5.0"

# Decorate a function as deprecated
@deprecated(deprecated_in="1.0", removed_in="2.0", current_version=__version__,
            details="This function is old, use new_api_function() instead.")
def old_api_function():
    """An old function that is going to be removed."""
    return "Result from old API"

# To see DeprecationWarnings, Python typically needs a special flag.
# For quick testing, you can uncomment the line below:
# os.environ['PYTHONWARNINGS'] = 'default'

print(f"Calling deprecated function: {old_api_function()}")

# Example of fail_if_not_removed (typically used in a test suite)
# This would cause an AssertionError if current_version >= removed_in
# import unittest
# class MyTests(unittest.TestCase):
#     @fail_if_not_removed(removed_in="2.0", current_version=__version__)
#     def test_old_function_is_gone(self):
#         # This test would fail if old_api_function still exists when version is 2.0 or higher
#         pass