Metadata-Version: 2.4
Name: philiprehberger-deprecate
Version: 0.1.1
Summary: Decorator and utilities for deprecating functions, parameters, and classes with zero boilerplate
Project-URL: Homepage, https://github.com/philiprehberger/py-deprecate
Project-URL: Repository, https://github.com/philiprehberger/py-deprecate
Project-URL: Issues, https://github.com/philiprehberger/py-deprecate/issues
Author: Philip Rehberger
License-Expression: MIT
License-File: LICENSE
Keywords: api,decorator,deprecate,deprecated,warning
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# philiprehberger-deprecate

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

## Install

```bash
pip install philiprehberger-deprecate
```

## Usage

```python
from philiprehberger_deprecate import deprecated, deprecated_class, deprecated_param
```

### Deprecate a function

```python
@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

```python
@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

```python
@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`.

## 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 |

## License

MIT
