pyDeprecate: Deprecation Tooling

0.7.0 · active · verified Sun Apr 12

pyDeprecate is a lightweight Python library (version 0.7.0) for managing function and class deprecations with zero dependencies. It provides automatic call forwarding to replacement functions, argument mapping between old and new APIs, and configurable warning controls to prevent log spam. It is actively maintained and designed to help library maintainers evolve APIs while maintaining backward compatibility.

Warnings

gotcha When using `@deprecated` with a `target` function, the body of the deprecated function is never executed; all calls are automatically forwarded to the target. Do not put critical logic inside a deprecated function if a target is specified.
Fix: Ensure all necessary logic resides within the `target` function. If the deprecated function's body *must* be executed, set `target=None` to only issue a warning without forwarding.
gotcha Conversely, if `target=None` is explicitly set in `@deprecated`, the deprecated function's own body *will* be executed after the warning is issued. This behavior is distinct from when a callable target is provided.
Fix: Understand the behavior difference: `target=Callable` forwards calls and skips the deprecated body; `target=None` runs the deprecated body after warning. Choose based on whether the old implementation should still execute.
gotcha `deprecated_instance` cannot intercept primitive protocol methods (e.g., numeric arithmetic on `float`, concatenation on `str`). This means direct operations on wrapped primitive constants will not trigger deprecation warnings.
Fix: For primitive constants that need deprecation warnings, either wrap them in a custom object/dictionary or manually update all call sites to use the new API directly.
gotcha When using `update_docstring=True` with the `@deprecated` decorator, consider setting the `docstring_style` parameter (e.g., `'sphinx'`, `'mkdocs'`, or `'auto'`) to ensure the deprecation notice is injected and formatted correctly for your specific documentation generator.
Fix: Explicitly set `docstring_style` in the `@deprecated` decorator (e.g., `docstring_style='mkdocs'`) or use `docstring_style='auto'` to let `pydeprecate` attempt to detect the style from existing docstring content.

Install

pip install pydeprecate Install stable version

Imports

deprecated
```
from deprecate import deprecated
```
deprecated_class
```
from deprecate import deprecated_class
```

deprecated_instance

from deprecate import deprecated_instance

void
```
from deprecate import void
```
Helper function to silence IDE warnings about unused parameters in deprecated functions when a 'target' is specified.

Quickstart

This quickstart demonstrates how to use the `@deprecated` decorator with and without a `target` function. When a `target` is provided, calls are forwarded to the new function, and the `void` helper silences IDE warnings. When `target=None`, the deprecated function's own body is executed after a warning is issued. Warnings are initially suppressed for clean output but re-enabled to show the deprecation messages.

import warnings
from deprecate import deprecated, void

# Suppress DeprecationWarning for cleaner output in example, will re-enable later
warnings.simplefilter('ignore', DeprecationWarning)

# NEW/FUTURE API — renamed to be more explicit about what it computes
def compute_sum(a: int = 0, b: int = 3) -> int:
    """Computes the sum of two numbers."""
    return a + b

# OLD API — 'addition' was the original name before the rename
@deprecated(target=compute_sum, deprecated_in="1.0", remove_in="2.0", template_mgs="{name} is deprecated, use {target_path} instead.")
def addition(a: int, b: int = 5) -> int:
    """Adds two numbers (deprecated)."""
    # The body of 'addition' is never executed because 'target' is specified.
    # The 'void' helper is used here to silence IDE warnings about 'a' and 'b' being unused.
    return void(a, b)

# Deprecating a function with no direct target (its own body runs)
@deprecated(target=None, deprecated_in="0.5", remove_in="0.8", template_mgs="Method {name} is deprecated and will be removed.")
def old_method(value: str) -> str:
    """An old method that will be removed."""
    return f"Processing: {value}"

# Example usage:
print("--- Using deprecated function with target ---")
print(f"Result of addition(1, 2): {addition(1, 2)}")
print(f"Result of addition(10): {addition(10)}")

print("\n--- Using deprecated function with no target ---")
print(f"Result of old_method('test'): {old_method('test')}")

# To demonstrate the warning, re-enable DeprecationWarnings
print("\n--- Enabling warnings to show deprecation output ---")
warnings.simplefilter('default', DeprecationWarning)
print(f"Result of addition(3, 4): {addition(3, 4)}")
print(f"Result of old_method('another test'): {old_method('another test')}")

view raw JSON →