philiprehberger-deprecate
v0.3.0679 downloadsMIT
Decorator and utilities for deprecating functions, parameters, and classes with zero boilerplate
$
pip install philiprehberger-deprecateREADME
philiprehberger-deprecate
Decorator and utilities for deprecating functions, parameters, and classes with zero boilerplate.
Installation
pip install philiprehberger-deprecate
Usage
from philiprehberger_deprecate import (
deprecated,
deprecated_attribute,
deprecated_class,
deprecated_module,
deprecated_param,
silenced,
)
Deprecate a function
@deprecated(remove_in="2.0.0", alternative="new_fetch")
def old_fetch(url: str) -> str:
...
Calling old_fetch() emits:
DeprecationWarning: Function 'old_fetch' is deprecated. Will be removed in 2.0.0. Use 'new_fetch' instead.
Deprecate a parameter
@deprecated_param("color", renamed_to="colour", remove_in="2.0.0")
def draw(shape: str, *, colour: str = "red") -> None:
...
draw(shape="circle", color="blue") # warns and forwards color -> colour
Deprecate a class
@deprecated_class(remove_in="3.0.0", alternative="NewClient")
class OldClient:
def __init__(self, host: str) -> None:
self.host = host
Instantiating OldClient() emits a DeprecationWarning.
Deprecate a module
# in mypkg/legacy/__init__.py
from philiprehberger_deprecate import deprecated_module
deprecated_module(__name__, remove_in="2.0.0", alternative="mypkg.modern")
Importing mypkg.legacy emits:
DeprecationWarning: Module 'mypkg.legacy' is deprecated. Will be removed in 2.0.0. Use 'mypkg.modern' instead.
Deprecating attributes
class Config:
old_value = deprecated_attribute(
"old_value",
since="1.0",
removed_in="2.0",
replacement="new_value",
)
def __init__(self) -> None:
self.new_value = 42
cfg = Config()
cfg.old_value # emits DeprecationWarning and returns 42 (from new_value)
Silencing during tests
from philiprehberger_deprecate import silenced
with silenced():
old_function() # no DeprecationWarning emitted inside the block
API
| Function | Description |
|---|---|
deprecated(remove_in, *, alternative, message) | Function decorator that emits DeprecationWarning on each call |
deprecated_param(param, *, renamed_to, remove_in) | Function decorator that warns when a deprecated parameter is passed and optionally maps it to its replacement |
deprecated_class(remove_in, *, alternative, message) | Class decorator that emits DeprecationWarning on instantiation |
deprecated_module(name, *, remove_in, alternative, message) | Emits DeprecationWarning once when a deprecated module is imported |
deprecated_attribute(name, since=None, removed_in=None, replacement=None) | Descriptor that emits DeprecationWarning on attribute access; transparently returns the replacement attribute's value when set |
silenced() | Context manager that suppresses DeprecationWarning from this package (useful in tests) |
Development
pip install -e .
python -m pytest tests/ -v
Support
If you find this project useful: