philiprehberger-deprecate 0.3.0

Decorator and utilities for deprecating functions, parameters, and classes with zero boilerplate

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:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT