Python Deprecation Utilities

2.1.0 · maintenance · verified Sat Mar 28

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]

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

pip install deprecation Install stable version

Imports

deprecated
```
from deprecation import deprecated
```

fail_if_not_removed

from deprecation import fail_if_not_removed

Quickstart

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

view raw JSON →