pyDeprecate 0.12.0 finishes the family. You could already deprecate a function, a class, or an instance — but not a whole module, and a plain PEP 562 __getattr__ hook can't warn on attributes that already exist in __dict__. deprecated_module() closes that gap with three modes and warns on every public attribute access, star-imports included. Alongside it, @deprecated becomes an explicit crossroad: it defaults to the new TargetMode.AUTO, which figures out the mode at decoration time instead of quietly rendering your args_mapping inert, and the long-threatened TypeError for @deprecated on a class is formally withdrawn — that dispatch is permanent. deprecated_callable() is there when you want the strict opposite, and deprecated proxies finally leave breadcrumbs (__wrapped__, __signature__) so inspect, Sphinx, griffe, and your IDE can see through them. One narrow breaking change, and it delivers on a TypeError that v0.11.0 already warned was coming.

✨ Spotlights

deprecated_module() — retire an entire module

One call at the bottom of the module you're retiring. It reassigns the module's __class__ to a wrapper that warns on every public attribute access — including attributes already in __dict__, which is exactly what a PEP 562 __getattr__ hook can't reach.

# old_calculator.py
from deprecate import deprecated_module


def add(a: float, b: float) -> float:
    return a + b


deprecated_module(__name__, deprecated_in="2.0", remove_in="3.0", message_template="Use `new_calculator` instead.")
# old_calculator.add(1, 2)  # warns: FutureWarning, returns 3

Three modes: warn in place, redirect unknown lookups to a replacement module (with optional attrs_mapping), or expose the old sub-module name on the parent package. from old_calculator import * warns too — CPython's IMPORT_STAR routes each name through the same interception. Calling it twice with the same configuration is a no-op; calling it again with a different configuration warns and keeps the first. A pre-existing __getattr__ gets chained rather than clobbered.

Audit tooling comes along for the ride: find_deprecation_wrappers() discovers deprecated modules, and validate_deprecation_wrapper() takes module objects directly.

TargetMode.AUTO is the new @deprecated default

@deprecated used to default to TargetMode.NOTIFY, which meant passing args_mapping without a target landed you in warn-only mode with an inert mapping and a misconfiguration flag. It now defaults to AUTO and resolves at decoration time from what you actually wrote:

from deprecate import deprecated


# A non-empty `args_mapping`, no explicit target → resolves to ARGS_REMAP
@deprecated(args_mapping={"coef": "coefficient"}, deprecated_in="1.0", remove_in="2.0")
def scale(value: float, coefficient: float = 1.0) -> float:
    return value * coefficient

AUTO never reaches DeprecationConfig — it resolves away before the config is frozen, so audit tooling always sees the concrete mode. It's the front-door default only; the strict forms reject it explicitly.

@deprecated on a class is permanent — and there's a strict form if you don't want that

Since v0.6 the warning said this would eventually become a TypeError. It won't. @deprecated on a class dispatches to deprecated_class with the full proxy and emits one informational UserWarning per module-qualified class name (silence it with stream=None). Only that notice goes away in v1.0.

If you want the opposite — a class handed to the decorator being an error — deprecated_callable() raises TypeError at decoration time, not call time. It shares every @deprecated parameter — with one default differing, since that is the whole point: deprecated_callable() defaults target to TargetMode.NOTIFY rather than TargetMode.AUTO, and rejects an explicit AUTO. It accepts functions, methods, lambdas, and the descriptor forms.

Proxies now leave AST breadcrumbs, and there's a public type to annotate them

Deprecated proxies used to be opaque to introspection: inspect.signature saw the proxy, Sphinx documented the proxy, IDEs offered nothing. Every proxy now carries __wrapped__ and __signature__ pointing at the source, and reading either emits no warning.

from deprecate import DeprecationProxy, deprecated_class


class HttpClient:
    def __init__(self, timeout: int = 30) -> None:
        self.timeout = timeout


@deprecated_class(target=HttpClient, deprecated_in="0.2", remove_in="0.4")
class Client: ...


# `Client` is now a proxy object, not a class — annotate it against the public
# protocol instead of the private `_DeprecatedProxy`
LegacyClient: DeprecationProxy = Client
print(isinstance(LegacyClient, DeprecationProxy))  # True — @runtime_checkable

The breadcrumbs survive copy and deepcopy, and pickle for the proxies that were already picklable — a deprecated_class proxy that replaces its class's module-level name still can't be pickled, since pickle resolves the name to the proxy rather than the original class. Sources with no introspectable signature (a plain dict, C-level types) get __signature__ = None rather than an error, so wrapping never fails.

template_mgs is now message_template, and skip_if works on proxies

The custom-notice parameter carried a typo (mgs for msg) since it was introduced. template_mgs still works as a deprecated alias that warns and forwards; it's removed in v1.0. And skip_if — previously callable-decorators-only — now works on deprecated_class() and deprecated_instance(), serving the wrapped source completely transparently while the condition holds.

🔄 Migration guide

One breaking change, and it only affects a configuration that never worked in the first place. Nothing was removed from the deprecated() signature — message_template was added to it.

@deprecated(target=TargetMode.ATTRS_REMAP) now raises TypeError for a class source. The mode needs attrs_mapping to redirect anything, and the front door has never exposed that keyword (it is deprecated_class-only). Previously a class source built a no-op proxy: the mode was recorded, nothing was ever remapped, and v0.11.0 emitted two UserWarnings about it — the class-dispatch notice, plus one naming attrs_mapping and stating outright that the proxy had "zero selective effect" and would become a TypeError in v1.0. This release delivers that. The callable path already raised.

from deprecate import TargetMode, deprecated, deprecated_class


# Before v0.12.0 — accepted, remapped nothing, and warned that it would become a TypeError
@deprecated(target=TargetMode.ATTRS_REMAP, deprecated_in="1.0", remove_in="2.0")
class Theme: ...


# v0.12.0 — TypeError at decoration time, pointing at the decorator that can do this.
# `attrs_mapping` values must name attributes that actually exist on the class.
@deprecated_class(attrs_mapping={"color": "colour"}, deprecated_in="1.0", remove_in="2.0")
class Theme:
    colour = "red"

If you had this in your codebase, check what mapping you intended before porting it — it was not being applied.

Deprecated: template_mgs → message_template on all four decorators. The old name warns and forwards through v0.12; passing both raises TypeError. Audit code reading DeprecationConfig.template_mgs keeps working through a read-only property alias.

Worth reviewing, not breaking: explicit target=TargetMode.NOTIFY together with args_mapping is still flagged at decoration time with a UserWarning, and the mapping stays inert — the same as in v0.11.0. It becomes a TypeError in v1.0, so it is worth fixing now: drop the explicit NOTIFY and let AUTO resolve the remap, name ARGS_REMAP outright, or drop the mapping if you really did mean warn-only.

Packaging: building from source now requires setuptools>=82 (up from >=70, across #225 and #227). Wheel installs are unaffected; the package still has zero runtime dependencies.

Full detail with before/after examples: releases/v0.12.0/MIGRATION.md.

📝 Notable changes

🚀 Added

• deprecated_module() — PEP-562-inspired module-level deprecation in three modes, with audit-tool support. (#203)
• deprecated_callable() — strict callable-only form of @deprecated that rejects a class at decoration time. (#221)
• TargetMode.AUTO — decoration-time mode inference, now the @deprecated default. (#222)
• skip_if on deprecated_class() and deprecated_instance(). (#222)
• Public DeprecationProxy protocol for annotating proxies, replacing the private _DeprecatedProxy. (#226, #228)
• AST breadcrumbs (__wrapped__, __signature__) on every deprecated_class / deprecated_instance proxy. (#226)

🌱 Changed

• @deprecated on a class is now first-class and permanent, dispatching to deprecated_class with an informational notice instead of a threatened TypeError. (#222)
• message_template and skip_if passed through @deprecated on a class now reach the proxy — message_template was previously dropped silently on that path. (#222)
• @deprecated(target=TargetMode.ATTRS_REMAP) now raises TypeError for a class source instead of building a no-op proxy. (#222)
• Legacy target=True/target=False sentinels now resolve to an unset target and follow the same auto-resolve as an omitted target. (#222)
• Non-callable sources raise a clear TypeError naming deprecated_instance instead of crashing later on __name__. (#222)
• Source builds now require setuptools>=82; wheel installs unaffected, runtime dependencies still zero. (#227)

🗑️ Deprecated

• template_mgs renamed to message_template on @deprecated, deprecated_callable, deprecated_class, and deprecated_instance. The old name warns and forwards; removed in v1.0. (#223)

🏆 Contributors

• Jirka Borovec (@Borda, LinkedIn) — deprecated_module() module-level deprecation, the deprecated() class/callable crossroad with TargetMode.AUTO inference, and the strict deprecated_callable() form with the engine split into focused modules
• Gabriel Fruet (@gabrielfruet, LinkedIn) — AST breadcrumbs (__wrapped__ / __signature__) on every deprecated proxy, making them legible to inspect, Sphinx autodoc, griffe, and IDEs

Full changelog: v0.11.0...v0.12.0

pyDeprecate 0.11.0 makes deprecated object proxies act like real drop-in replacements instead of leaky wrappers. Operators and protocol methods — arithmetic, iteration, context managers, async support — now forward to the wrapped object. Proxies survive copy/deepcopy/pickle (they used to blow up with RecursionError), and you can now subclass a deprecated_class alias directly instead of hitting a TypeError. Two identity fixes make isinstance behave the way you'd expect, and validate_deprecation_expiry() now catches expired class members by default. No breaking changes.

✨ Spotlights

Operators and protocol methods now forward to the wrapped object

Arithmetic, comparisons, context managers, iteration, numeric conversion, os.fspath, format, and async protocols all delegate to the wrapped object now instead of raising TypeError.

from deprecate import deprecated_instance

DEFAULTS = deprecated_instance({"lr": 0.001}, deprecated_in="1.2", remove_in="2.0", read_only=True)
print(DEFAULTS["lr"])  # 0.001 — warns once

Subclassing a deprecated class alias now works

class Child(OldName) on a deprecated_class alias used to raise a confusing metaclass error. It now resolves cleanly to the active replacement class.

validate_deprecation_expiry() now scans class members by default

The include_members default flipped from False to True, matching find_deprecation_wrappers(). If your CI expiry check was missing expired methods, constructors, or properties, it'll catch them now — pass include_members=False if you want the old, narrower scope back.

Proxy identity fixes: __class__, isinstance/issubclass

A deprecated proxy's __class__ now reports the wrapped object's real type, so isinstance checks against it work as expected; type(proxy) still tells you it's a proxy. Passing an instance proxy as the second argument to isinstance/issubclass now raises TypeError instead of silently returning False.

Proxies support copy, deepcopy, and pickle

These used to crash with RecursionError. deprecated_instance proxies over plain objects are now fully picklable; deprecated_class alias proxies may still raise PicklingError — use copy.deepcopy for those instead.

🔄 Migration guide

No breaking changes in this release. Nothing was removed or renamed.

Three behavior changes are worth a quick look. None require action for typical use — the last two only matter if your code depends on the specific old behavior:

• validate_deprecation_expiry() now scans class members by default — pass include_members=False to restore the old scope.
• A deprecated proxy's __class__ now reports the wrapped type. If you're detecting a proxy by checking obj.__class__ is _DeprecatedProxy, switch to type(obj) is _DeprecatedProxy instead.
• isinstance/issubclass with an instance proxy as the second argument now raises TypeError instead of silently returning False.

📝 Notable changes

🚀 Added

• Deprecated proxies forward operators and protocol methods to the wrapped object — arithmetic, comparison/ordering, context managers, iteration, numeric conversion, os.fspath, format, and async protocols now delegate instead of raising TypeError; binary operators still return NotImplemented where Python expects it, and in-place operators (+=) rebind to the plain result. (#214)
• Subclassing a deprecated class alias now works — the alias resolves to the active class and warns, staying silent when the proxy only remaps attributes or arguments. (#214)

🌱 Changed

• Call forwarding is about 2.4× faster — no behavior change, just less overhead on every call. (#214)
• validate_deprecation_expiry() default include_members flipped from False to True — your CI expiry gate now scans class members by default; pass include_members=False to restore the old scope. (#210)
• A deprecated proxy's __class__ now reports the wrapped object's type — this gives you real isinstance transparency for JSON encoders, validators, functools.singledispatch, and similar; type(proxy) still tells you it's a proxy. (#210)
• Proxy identity operations (repr, str, ==, hash) now route through the active object — previously they used the deprecated source while attribute/item/call access used the active target, which was inconsistent. (#216)
• isinstance/issubclass with an instance proxy as the second argument now raise TypeError — previously this returned False silently, which could hide bugs. Class-alias proxies are unaffected. (#216)
• Batch expiry checks now warn on an unparsable remove_in instead of skipping it silently. (#216)

🔧 Fixed

• Inspecting a deprecated proxy — hasattr, copy/deepcopy, reading dunder attributes — no longer counts against your warning limit. (#210)
• Functions with positional-only parameters no longer raise TypeError on every call in notify-only and self-remapping modes (both sync and async). (#210)
• Extra *args are now forwarded to callable targets instead of silently dropped. (#210)
• Positional-only forwarding no longer misbinds arguments when an earlier parameter is missing; the same fix applies to deprecated_class(args_mapping=...). (#210)
• CLI: unknown or misspelled flags now exit non-zero instead of being silently ignored. (#210)
• CLI: version auto-detection no longer walks up into an unrelated project's pyproject.toml. (#210)
• Recursive audits (find_deprecation_wrappers(recursive=True)) now survive submodules that raise errors other than ImportError on import. (#210)
• Deprecated proxies now support copy.copy, copy.deepcopy, and pickle. (#212)
• The warning count (num_warns) is now tracked safely when multiple threads call a deprecated function for the first time at once. (#214)
• Forwarding between static methods on different classes no longer raises a spurious TypeError. (#214)
• Instantiating a deprecated class that only remaps attributes is now silent — only the deprecated-attribute access itself warns. (#214)
• Audit scans no longer double-count re-exported wrappers. (#215)
• Audit report formatting no longer triggers chained proxies (which caused spurious warnings, drained the warning budget, and fabricated a module path). (#215)
• CLI all/status no longer fail on plain directories that lack an __init__.py. (#215)
• CLI version auto-detection now resolves distributions whose name differs from the import name. (#215)
• A bare @deprecated (missing parens) now raises a clear TypeError when the first argument isn't callable. (#216)
• A custom template_mgs with a bare %-conversion is now rejected with ValueError at decoration time instead of failing later. (#216)
• args_mapping, args_extra, and attrs_mapping are now copied defensively when you apply the decorator, so later mutation of the originals can't leak through. (#216)
• The cross-class forwarding guard now also catches @property/@classmethod/@staticmethod-decorated methods. (#216)
• A warning stream that raises TypeError internally is no longer invoked twice. (#216)
• Argument validation against a **kwargs/*args target gives you the curated error message again. (#216)
• Audits now surface deprecated private (_-prefixed) and dunder members instead of skipping them. (#216)
• Audits now detect a proxy pointing at itself and report it as a no-op instead of as an effective deprecation. (#216)
• Recursive audits now tolerate foreign objects whose attribute access raises something other than AttributeError. (#216)
• Version strings with PEP 440 local segments (e.g. 1.2.3+cuda) now parse correctly instead of losing that segment. (#216)
• CLI: no longer crashes when the terminal doesn't report a text encoding. (#216)
• CLI: exceptions without a message now still exit with a non-blank line on stderr. (#216)

Full changelog: v0.10.1...v0.11.0

pyDeprecate 0.10.1 closes two correctness gaps and ships one new audit diagnostic. Callable deprecation cycles now raise a clear RuntimeError instead of crashing with a RecursionError. The inner_order_property flag in audit results lets CI pipelines detect the silent setter/deleter gap from inner-order @property @deprecated stacking, and the new opt-in from deprecate import property catches that same mistake at class-body evaluation time — before any instance is created.

No migration required. All changes are additive.

✨ Spotlights

Circular deprecation chains raise RuntimeError

A target= chain that loops back (A → B → A) previously caused unbounded recursion. The decorator now detects re-entry via a ContextVar guard and raises a named error immediately. Async tasks each get an independent detection set — no false positives from concurrent coroutines.

@deprecated(deprecated_in="1.0", remove_in="2.0", target=lambda: cycle_b())
def cycle_a(): ...


@deprecated(deprecated_in="1.0", remove_in="2.0", target=cycle_a)
def cycle_b(): ...


cycle_a()
# RuntimeError: Circular deprecation cycle detected: `cycle_a` re-entered via its own target chain.

inner_order_property audit flag

find_deprecation_wrappers() now sets inner_order_property=True when a plain property has a @deprecated-wrapped fget — the inner-order shape where only the getter warns; setters and deleters added via @value.setter remain silently unprotected.

results = find_deprecation_wrappers(my_module)
flagged = [r for r in results if r.inner_order_property]
# Add to CI: assert not flagged, "Inner-order @property @deprecated found"

Opt-in strict property replacement

from deprecate import property shadows the builtin with _StrictProperty, which raises TypeError at class-body time when handed an already-@deprecated getter — turning the silent footgun into a loud, immediate failure.

from deprecate import deprecated
from deprecate import property  # opt-in strict mode for this module


class MyModel:
    @property  # TypeError raised here —
    @deprecated(deprecated_in="1.0", remove_in="2.0")  # before any instance is created
    def old_value(self): ...

Star imports (from deprecate import *) are unaffected — strictness is per-module opt-in only.

📝 Notable changes

🚀 Added

• DeprecationWrapperInfo.inner_order_property flag — find_deprecation_wrappers() sets True for inner-order @property @deprecated where only fget warns; CI pipelines can filter on this field. (#201)
• Opt-in strict property via from deprecate import property — raises TypeError at class-definition time when a getter already carries @deprecated metadata; star imports unaffected. (#201)

🔧 Fixed

• Circular deprecation chains now raise RuntimeError at call time — ContextVar re-entrancy guard replaces unbounded recursion; async cycle detection avoids false positives from concurrent tasks. (#200)
• _StrictProperty TypeError message references correct module path — error now points to deprecate.deprecation._StrictProperty. (#201)

🏆 Contributors

• Jirka Borovec (@Borda) — cycle detection implementation, inner-order audit flag, strict property enforcement

Full changelog: v0.10.0...v0.10.1

v0.10.0 brings fine-grained attribute-level deprecation to deprecated_class via a new attrs_mapping parameter — deprecate individual attribute names (reads, writes, deletes) with per-attribute warning budgets and, for dataclasses, automatic constructor-kwarg expansion. The release also closes two coverage gaps: @deprecated @property now wraps the setter and deleter in addition to the getter, and raw staticmethod/classmethod descriptors are accepted as target without the .__func__ workaround. A correctness fix ensures calls to targets with positional-only parameters no longer raise TypeError.

✨ Spotlights / highlights

1. deprecated_class(attrs_mapping={...}) — selective attribute deprecation

Deprecate individual attribute names with per-attribute budgets. Reads, writes, and deletes each fire FutureWarning independently. None as the redirect value means warn-only (no rename). TargetMode.ATTRS_REMAP is the corresponding mode. (#191)

from deprecate import deprecated_class


@deprecated_class(attrs_mapping={"color": "colour"}, deprecated_in="2.0", remove_in="3.0")
class Palette:
    colour: str = "red"  # canonical name
    size: int = 10  # unlisted — always silent


print(Palette.color)  # warns: FutureWarning → redirected to colour
print(Palette.colour)  # silent

2. Dataclass attrs_mapping auto-expand

When the wrapped class is a @dataclass, one attrs_mapping entry automatically covers both attribute access and constructor kwargs — no separate args_mapping needed.

from dataclasses import dataclass
from deprecate import deprecated_class


@deprecated_class(attrs_mapping={"px": "x", "py": "y"}, deprecated_in="2.0", remove_in="3.0")
@dataclass
class OldPoint:
    x: float = 0.0
    y: float = 0.0


pt = OldPoint(px=1.0, py=2.0)  # warns on px and py → x=1.0, y=2.0

Explicit args_mapping entries always win over auto-expanded ones. (#193)

3. @deprecated @property wraps fset and fdel

Outer-order @deprecated @property now wraps all three accessors. Previously only fget fired a warning. Chain-style @value.setter / @value.deleter re-wraps automatically via the new _DeprecatedProperty subclass.

from deprecate import deprecated


class Config:
    def __init__(self) -> None:
        self._timeout: int = 30

    @deprecated(deprecated_in="1.0", remove_in="2.0")
    @property
    def timeout(self) -> int:
        return self._timeout

    @timeout.setter
    def timeout(self, value: int) -> None:
        self._timeout = value

    @timeout.deleter
    def timeout(self) -> None:
        del self._timeout


cfg = Config()
_ = cfg.timeout  # warns: FutureWarning (read)
cfg.timeout = 60  # warns: FutureWarning (write)
del cfg.timeout  # warns: FutureWarning (delete)

Inner order (@property @deprecated) still wraps fget only. (#190)

4. Raw staticmethod/classmethod descriptors as target

Inside a class body, pass the new method directly as target=new_method — no .__func__ needed. (#192)

from deprecate import deprecated, void


class Compute:
    @staticmethod
    def area(radius: float) -> float:
        return 3.14159 * radius**2

    @staticmethod
    @deprecated(target=area, deprecated_in="1.0", remove_in="2.0")
    def surface(radius: float) -> float:
        """Deprecated — use area() instead."""
        return void(radius)


print(Compute.surface(3.0))  # warns: FutureWarning, returns area(3.0)

5. Fix: @deprecated forwards calls to POSITIONAL_ONLY targets

Previously raised TypeError at call time when target declared positional-only parameters (def fn(x, /)). Now detects at decoration time, emits UserWarning, and splits call dispatch positionally. (#194)

from deprecate import deprecated


def new_fn(value: float, /) -> float:
    return value * 2


@deprecated(target=new_fn, deprecated_in="1.0", remove_in="2.0")
def old_fn(value: float) -> float: ...


result = old_fn(value=5.0)  # warns: FutureWarning; calls new_fn(5.0) correctly
print(result)  # 10.0

⬆️ Upgrade notes

No breaking changes. All existing code continues to work.

If you use @deprecated @property with a setter or deleter and run filterwarnings=error::FutureWarning: setter and deleter writes now correctly fire FutureWarning — they were silently skipped before (bug). Tests that write to or delete a deprecated property will now raise as expected. To intentionally keep only the getter warned, switch to inner order (@property @deprecated).

📋 Notable changes

🚀 Added

• deprecated_class(attrs_mapping={...}) for selective attribute deprecation. Deprecated attribute names emit FutureWarning on read, write, and delete with per-attribute warning budgets. None as the redirect value means warn-only. TargetMode.ATTRS_REMAP is the corresponding mode. Multi-hop chains allowed; cycles raise ValueError at decoration time. (#191)
• deprecated_class stacking now supported. Two @deprecated_class decorators on the same class work correctly — isinstance() delegates through the chain, instantiation emits at most one warning. (#193)
• Dataclass attrs_mapping auto-expand. Single attrs_mapping entry covers both attribute access and constructor kwargs on a @dataclass. Explicit args_mapping always wins. (#193)
• validate_mapping_compatibility() audit function. Returns all deprecated_class proxies whose args_mapping remaps to POSITIONAL_ONLY constructor parameters. Use in CI alongside validate_deprecation_expiry. (#193)
• @deprecated @property wraps fset and fdel. Outer-order decoration now covers all three accessors via the new _DeprecatedProperty subclass. (#190)
• Raw staticmethod/classmethod descriptors accepted as target. _normalize_target unwraps automatically inside class bodies. (#192)

🔧 Fixed

• @deprecated correctly forwards calls to targets with POSITIONAL_ONLY parameters. Detects at decoration time, emits UserWarning, splits call dispatch positionally. args_mapping applied before split. (#194)
• args_mapping precedence: explicit new-name always wins. When caller passes both deprecated old name and new name simultaneously, new-name value wins regardless of call-site order. (#198)

🏆 Contributors

• Jirka Borovec (@Borda) — all features and fixes in this release (#190–#198)

Full changelog: v0.9.0...v0.10.0

🎉 pyDeprecate 0.9.0

pyDeprecate 0.9.0 adds async support, fixes descriptor ordering, and introduces Markdown audit tables — @deprecated now wraps async def coroutines, async generators, and sync generators correctly, decorator order on @classmethod and friends no longer matters, and pydeprecate status renders Markdown audit reports you can commit to your docs.

📋 Summary

v0.9.0 closes three long-standing gaps in @deprecated. Sync generators, async coroutines, and async generators are all wrapped correctly — sync generators fire the warning eagerly at call time instead of after the first next(), inspect.iscoroutinefunction(wrapper) returns True for async coroutines, and async generators no longer raise a UserWarning at decoration time.

Descriptor decorator order is no longer a footgun. Both @classmethod @deprecated and @deprecated @classmethod (and the equivalent for @staticmethod) produce a working classmethod(deprecated_wrapper) — the descriptor is unwrapped, the inner function is deprecated, and the result is re-wrapped. find_deprecation_wrappers() looks inside descriptor members too, so audit scans no longer miss wrapped classmethods or staticmethods.

A new generate_deprecation_table() function and pydeprecate status CLI subcommand render Markdown reports grouped by module and API type (function, method, classmethod, staticmethod, property, class, instance) — with compact and matrix styles, lifecycle classification via the new DeprecationStatus enum, and --output FILE for committable artifacts.

One breaking CLI change: --skip_errors was renamed to --exit-zero across all four subcommands. The flag was introduced in v0.8.0 and renamed because the old name reads as if it swallows exceptions; the new name matches ruff, pylint, and shellcheck convention and describes the behavior plainly. Update CI scripts before upgrading. v0.8.0's target=None / target=True / DeprecationWrapperInfo field deprecations are still active and are scheduled for removal in v1.0.

🚀 Spotlights

Generator function support for @deprecated

Decorating a generator function (def fn(): yield ...) now emits the deprecation warning eagerly at call time — before the first next() — consistent with regular function behavior. The generator body executes lazily as normal when iterated. All three TargetMode variants work transparently; no isgeneratorfunction check is needed at the call site.

from deprecate import deprecated


@deprecated(deprecated_in="0.9", remove_in="1.0")
def stream_legacy_rows():
    for row in _legacy_source():
        yield row


it = stream_legacy_rows()  # FutureWarning fires eagerly here
for row in it:  # iteration runs lazily, unchanged
    process(row)

async def coroutine and async-generator support

@deprecated now wraps async def coroutines and async def + yield async generators with no changes needed at the call site for direct use. The async-coroutine wrapper is itself async def, so inspect.iscoroutinefunction(wrapper) returns True and the warning fires when the coroutine is awaited. For async generators, the wrapper is a sync callable that fires the warning eagerly at call time and returns the async-generator object — iterate with async for. Note: inspect.isasyncgenfunction(wrapper) returns False for the async-generator case (the wrapper is sync), so frameworks that branch on that flag to decide how to call the function may need a thin async def passthrough.

import inspect

from deprecate import deprecated


@deprecated(deprecated_in="0.9", remove_in="1.0")
async def fetch_legacy(url: str) -> bytes:
    return await _http_get(url)


assert inspect.iscoroutinefunction(fetch_legacy)  # True
# FutureWarning fires here, at await time:
data = await fetch_legacy("https://example.com")

Order-agnostic @classmethod / @staticmethod

Both @classmethod @deprecated and @deprecated @classmethod (and the equivalent for @staticmethod) produce a working classmethod(deprecated_wrapper). The descriptor is unwrapped at decoration time, the inner function is deprecated, and the result is re-wrapped. FutureWarning fires at call time in either order; no decoration-time UserWarning is emitted. find_deprecation_wrappers() now inspects descriptor members so wrapped classmethods and staticmethods show up in audit scans.

from deprecate import deprecated


class Repo:
    # preferred order
    @classmethod
    @deprecated(target=new_load, deprecated_in="0.9", remove_in="1.0")
    def load(cls, path): ...

    # also works in v0.9.0
    @deprecated(target=new_load, deprecated_in="0.9", remove_in="1.0")
    @classmethod
    def load_alt(cls, path): ...

Markdown deprecation tables — generate_deprecation_table() + pydeprecate status

Two new public enums power the reports: DeprecationStatus (lifecycle classification — ACTIVE, EXPIRED, plus dev/alpha/beta/rc removal windows) and TableStyle (COMPACT / MATRIX). Tables are grouped by module and API type, auto-detect the package version from pyproject.toml or installed metadata, and write to stdout or a file via --output. pydeprecate all now includes the table automatically.

pydeprecate status src/mypackage --style compact --output DEPRECATIONS.md

Sample output (COMPACT style):

⚠️ Migration guide

One breaking change: the CLI flag --skip_errors was renamed to --exit-zero across all four subcommands (check, expiry, chains, all). Update any CI scripts before upgrading.

# before — fails on v0.9.0
pydeprecate check src/mypackage --skip_errors

# after
pydeprecate check src/mypackage --exit-zero

v0.8.0 deprecations (target=None, target=True, DeprecationWrapperInfo field renames) are still active and will be removed in v1.0. See MIGRATION.md for full before/after examples.

📝 Notable changes

🚀 Added

• Generator function support for @deprecated. Warning emitted eagerly at call time, before the first next(). All three TargetMode variants work transparently. (#176)
• async def coroutine wrapper support for @deprecated. Wrapper is async def, inspect.iscoroutinefunction(wrapper) returns True, warning fires when the coroutine is awaited. All three TargetMode variants work with async sources and async targets. (#180)
• Async generator function support for @deprecated. No more decoration-time UserWarning; wrapper is a sync callable that fires the warning eagerly and returns an async-generator object. All three TargetMode variants work. (#181)
• Order-agnostic @classmethod / @staticmethod. Both orders produce classmethod(deprecated_wrapper); decorator order no longer matters. (#178)
• Stacked @deprecated — ARGS_REMAP + NOTIFY combination. Rename arguments first, deprecate the whole function later. Six other stacking shapes emit UserWarning at decoration time and will become TypeError in v1.0. (#172)
• Markdown deprecation tables — generate_deprecation_table() + pydeprecate status CLI subcommand. New DeprecationStatus and TableStyle public enums. New --style and --output CLI flags. Integrated into pydeprecate all. Auto-detects package version from pyproject.toml or installed metadata. (#133)
• ChainType enum now exported as public API. Previously returned by validate_deprecation_chains(); now listed in deprecate.__all__. (#133)
• Audit discovery extended to class descriptors. find_deprecation_wrappers() now inspects classmethod and staticmethod descriptors on class members. (#178)

⚠️ Breaking Changes

• CLI flag renamed: --skip_errors → --exit-zero across all four subcommands (check, expiry, chains, all). No transitional release — flag was new in v0.8.0. Canonical spelling is --exit-zero; --exit_zero also accepted by the CLI framework. (#187)
• Programmatic cmd_check / cmd_expiry / cmd_chains / cmd_all keyword renamed from skip_errors to exit_zero. (#187)

🌱 Changed

• Misconfigured stacking combinations warn at decoration time. Six previously-undefined @deprecated stacking shapes now emit UserWarning at decoration time naming the specific shape. Scheduled to become TypeError in v1.0. (#172)
• Audit chain classification — ARGS_REMAP + NOTIFY is now classified as STACKED rather than TARGET. Fixes audit reports for the supported stacking shape. (#172)
• CLI warning suppression narrowed to deprecate.* warnings only. Third-party warnings emitted during a scan are no longer silenced. (#133)
• generate_deprecation_table() gains include_members parameter for scanning descriptor members; validate_deprecation_expiry() default unchanged at include_members=False to preserve existing scan scope. (#133)

🔧 Fixed

• stacklevel attribution on Python 3.12+. inspect.signature(warnings.warn) raises ValueError on 3.12+ (the C builtin lacks an introspectable signature), which caused every @deprecated warning to point to deprecation.py instead of the caller. Replaced the inspect.signature probe with a try/except at call site. (#176)
• find_deprecation_wrappers() no longer aborts on PEP 702 typing_extensions.deprecated objects. Scanner was matching PEP 702 wrappers (whose __deprecated__ is a string) and raising ValueError. (#178)
• Short-circuit forwarding for *args sources now preserves extra positional arguments. Previously, extra positional arguments past the named parameters were silently dropped. (#180)

Full changelog: v0.8.0...v0.9.0

releasing 0.9.0.rc1

releasing 0.9.0.rc0

🎉 pyDeprecate 0.8.0

pyDeprecate 0.8.0 is the TargetMode enum & CLI tooling release — deprecation intent is now typed and explicit, warn-only deprecation is the default, and a new pydeprecate CLI lets you scan any package for misconfigured wrappers without writing a single audit script.

Summary

v0.8.0 centers on TargetMode: a proper enum (TargetMode.NOTIFY, TargetMode.ARGS_REMAP) replacing the target=None / target=True boolean sentinels. The old sentinels still work — they emit FutureWarning at decoration time — so you've got a full release cycle to migrate before they're removed in v1.0.

target now defaults to TargetMode.NOTIFY, so the most common pattern — warn callers and run the original body unchanged — needs nothing more than deprecated_in and remove_in:

@deprecated(deprecated_in="1.0", remove_in="2.0")
def old_fn(): ...

A new pydeprecate CLI (four subcommands) rounds out the release. Run pydeprecate check path/to/mypackage to surface misconfigured wrappers across a whole codebase in seconds.

🚀 Spotlights

TargetMode enum

from deprecate import deprecated, TargetMode


# Warn-only: source body executes unchanged
@deprecated(target=TargetMode.NOTIFY, deprecated_in="0.8", remove_in="1.0")
def old_api(): ...


# Argument-rename: warns only when old arg name is passed
@deprecated(
    target=TargetMode.ARGS_REMAP,
    deprecated_in="0.8",
    remove_in="1.0",
    args_mapping={"old_param": "new_param"},
)
def new_api(new_param): ...

TargetMode is exported from deprecate and works everywhere target= is accepted: @deprecated, deprecated_class(), and deprecated_instance().

Zero-boilerplate warn-only deprecation

target is now optional — TargetMode.NOTIFY is the default. Drop the target= entirely:

@deprecated(deprecated_in="0.8", remove_in="1.0")
def old_fn(): ...

Omitting deprecated_in now surfaces a UserWarning at decoration time, not silently at call time, so misconfiguration is visible immediately.

pydeprecate CLI

pydeprecate check path/to/mypackage    # validate wrapper configuration
pydeprecate expiry path/to/mypackage   # find wrappers past remove_in date
pydeprecate chains path/to/mypackage   # detect deprecated→deprecated chains
pydeprecate all path/to/mypackage      # run all three in one pass

Also available as python -m deprecate. Requires pip install 'pyDeprecate[cli]' for all subcommands (fire dependency). expiry additionally needs pip install 'pyDeprecate[audit]'. Or install both: pip install 'pyDeprecate[cli,audit]'.

Migration guide

No breaking changes. All v0.7.x code continues to run. The items below emit deprecation warnings now and will be removed in v1.0.

target=None → TargetMode.NOTIFY

# before — emits FutureWarning at decoration time
@deprecated(target=None, deprecated_in="0.8", remove_in="1.0")
def old_fn(): ...


# after — explicit or implicit (default)
@deprecated(target=TargetMode.NOTIFY, deprecated_in="0.8", remove_in="1.0")
def old_fn(): ...


# simplest form — NOTIFY is the default
@deprecated(deprecated_in="0.8", remove_in="1.0")
def old_fn(): ...

target=True → TargetMode.ARGS_REMAP

# before — emits FutureWarning at decoration time
@deprecated(target=True, deprecated_in="0.8", remove_in="1.0", args_mapping={"old_arg": "new_arg"})
def new_fn(new_arg): ...


# after
@deprecated(target=TargetMode.ARGS_REMAP, deprecated_in="0.8", remove_in="1.0", args_mapping={"old_arg": "new_arg"})
def new_fn(new_arg): ...

DeprecationWrapperInfo field renames

# before
if info.empty_mapping or info.identity_mapping:
    ...

# after
if info.empty_args_mapping or info.identity_args_mapping:
    ...

DeprecationConfig.target no longer stores raw sentinels

Code that inspects wrapper.__deprecated__.target and compares against None or True must update:

# before
assert fn.__deprecated__.target is None

# after
from deprecate import TargetMode

assert fn.__deprecated__.target is TargetMode.NOTIFY

Notable changes

Added

• TargetMode enum (NOTIFY, ARGS_REMAP) exported from deprecate — typed replacement for target=None / target=True sentinels. (#150)
• target defaults to TargetMode.NOTIFY on @deprecated — warn-only deprecation now requires only deprecated_in and remove_in. (#162)
• pydeprecate CLI — check, expiry, chains, all subcommands.
  • initial CLI scaffolding (#76)
  • check, expiry, chains, all subcommands (#149)
• template_mgs and args_extra on deprecated_class() and deprecated_instance() — proxy factories now at full parity with @deprecated. (#150)
• DeprecationWrapperInfo.empty_deprecated_in — True when deprecated_in is absent; for CI pipeline use. (#166)
• DeprecationConfig.misconfigured — True when an invalid raw target sentinel (False) was passed at decoration time; surfaced via DeprecationWrapperInfo.misconfigured_target. (#150)
• num_warns=0 documented — equivalent to stream=None; suppresses all warnings. (#150)
• Stacked-callable-target guard — @deprecated(target=callable_a) stacked over another callable-target wrapper now emits UserWarning at decoration time instead of crashing with TypeError at call time. (#169)
• template_mgs validated at decoration time — malformed %-style placeholders raise ValueError immediately. (#169)

Changed

• DeprecationConfig.target normalized at decoration time — stores TargetMode or Callable, never raw None/True/False. (#150)
• Misconfigured TargetMode combos warn at construction time — ARGS_REMAP without args_mapping, NOTIFY with args_mapping or args_extra all emit UserWarning immediately. (#150)
• Docs site URL layout versioned — content now at https://borda.github.io/pyDeprecate/stable/ (and /<tag>/); the bare root redirects to stable/. Existing bookmarks to flat paths will break on first deploy. (#148)
• CLI chains reporting — check subcommand reports chains as warnings; chains/all subcommands report chains as errors. (#149)

Deprecated

• target=None — use TargetMode.NOTIFY. Emits FutureWarning. Removed in v1.0. (#150)
• target=True — use TargetMode.ARGS_REMAP. Emits FutureWarning. Removed in v1.0. (#150)
• target=False — never valid; now emits UserWarning, treated as TargetMode.NOTIFY. Raises TypeError in v1.0. (#150)
• DeprecationWrapperInfo.empty_mapping → empty_args_mapping. Emits DeprecationWarning. Removed in v1.0. (#166)
• DeprecationWrapperInfo.identity_mapping → identity_args_mapping. Emits DeprecationWarning. Removed in v1.0. (#166)

Fixed

• PEP 702 stacking crash — @deprecated stacked under @typing.deprecated no longer raises AttributeError on __deprecated__ lookup. (#169)
• Double FutureWarning on deprecated_class() in NOTIFY mode. (#162)
• Cross-class guard false positives — metaclass/dynamic-class qualnames and pre-applied decorators that rewrite __qualname__ no longer trigger spurious TypeError at decoration time; the guard still raises for genuine cross-class forwarding. (#169)
• args_mapping rename no longer clobbers source default when both old and new parameter names are supplied simultaneously. (#150)

🏆 Contributors

• Onuralp SEZER (@onuralpszr) — initial CLI scaffolding (#76)
• Jiri Borovec (@Borda) — TargetMode enum, CLI subcommands, proxy parity, cross-class guard hardening, docs site restructure

Full changelog: v0.7.0...v0.8.0

releasing 0.8.0.rc0

Added

Docstring injection

• MkDocs admonition output. @deprecated now accepts docstring_style="mkdocs" (alias: "markdown"). When update_docstring=True, the deprecation notice is injected as a !!! warning "Deprecated in X" admonition instead of a Sphinx .. deprecated:: directive. Use docstring_style="auto" to detect style automatically from existing docstring content. (#134)
• Google / NumPy section-aware docstring injection. update_docstring=True now inserts the deprecation notice before the first section (Args:, Returns:, Parameters, …) rather than appending it at the end. (#134)
• Inline arg deprecation in docstrings. When args_mapping is set and update_docstring=True, each renamed or removed argument is annotated directly in the Args: / :param section of the docstring. (#136)

Extensions & demos

• Griffe extension for mkdocstrings (deprecate.docstring.griffe_ext, beta) and Sphinx autodoc extension for deprecated classes (deprecate.docstring.sphinx_ext, beta). (#134)
• Live demo documentation published to GitHub Pages — MkDocs demo, Sphinx demo, and portal landing page. (#134, #137)

Fixed

• Fixed getattr/setattr string-literal calls (B009/B010) replaced with direct attribute access. (#139)
• Fixed proxy swap skipped correctly when super().import_object() returns False in the Griffe extension; empty _proxy_doc now delegates to super().get_doc() in the Sphinx extension. (#139)

Added

• deprecated_class() and deprecated_instance() — full proxy support. Enum, dataclass, and built-in types can now be wrapped in a transparent proxy. Attribute access, item access, method calls, and class behaviour all forward to the underlying type with a FutureWarning emitted on first access. (#114)
• Correct isinstance() / issubclass() semantics on proxy classes. isinstance(x, proxy) and issubclass(Sub, proxy) now work as expected — previously raised TypeError. Type checks do not consume the warning budget. (#126)

Changed

• @deprecated on a class raises TypeError. Applying @deprecated directly to a class now raises TypeError at decoration time instead of silently misbehaving. Superseded in v0.6.0.post0 by a UserWarning + delegation to deprecated_class(). Use @deprecated_class() for class-level deprecation. (#120)

Deprecated

• Audit API renamed for consistency. Old names remain as @deprecated shims until v1.0. (#125)

  Old name	New name
  find_deprecated_callables	find_deprecation_wrappers
  validate_deprecated_callable	validate_deprecation_wrapper
  DeprecatedCallableInfo	DeprecationWrapperInfo

• no_warning_call renamed to assert_no_warnings. The new name mirrors assertWarns / assertRaises from the standard library, making test intent immediately obvious. Old name kept as a deprecated alias until v1.0. (#131)

Fixed

• Cross-class method forwarding now fails at decoration time. Passing a class as target on a non-__init__ method previously silently forwarded self of the wrong type — always a runtime bug, never a valid pattern. The guard now raises TypeError at decoration time so the misconfiguration is caught immediately. (#121)
• find_deprecation_wrappers() no longer reports false invalid_args for proxy objects. The proxy __call__ catch-all signature previously caused all args_mapping keys to be flagged as invalid; signature validation is now skipped for proxy objects. (#124)

Added

• deprecate.audit module — deprecation lifecycle management. A dedicated module grouping all inspection and enforcement utilities, designed to be called from pytest or CI scripts. Requires the optional [audit] extra: pip install pyDeprecate[audit]. (#111)
• find_deprecated_callables() / validate_deprecated_callable() — zero-impact wrapper detection. Scans a module or package for @deprecated wrappers that have no real effect: invalid args_mapping keys, identity mappings, self-referencing targets, or missing version fields. Returns DeprecatedCallableInfo dataclasses. (#72)
• validate_deprecation_expiry() — enforce removal deadlines in CI. Scans a module or package and returns all wrappers whose remove_in version has been reached or passed. Auto-detects the installed package version. Integrate as a pytest fixture or CI step to prevent zombie code from shipping past its scheduled removal. (#89)
• validate_deprecation_chains() — detect deprecated-to-deprecated forwarding. Identifies wrappers whose target is itself a deprecated callable, forming chains that users traverse unnecessarily. Reports two chain kinds via the ChainType enum: TARGET (forwarding chain) and STACKED (composed argument mappings). (#90)

Fixed

• @deprecated wrappers now correctly handle var-positional Enum signatures. A subtle edge case where callables with var-positional parameters in their Enum signature caused incorrect argument forwarding is now resolved. (#104)

Added

• update_docstring parameter — automatic Sphinx deprecation notices. Set update_docstring=True on @deprecated to automatically append a .. deprecated:: reStructuredText block to the function's docstring. IDE tooltips and Sphinx-generated API docs show the notice without any manual edits. (#31)

Changed

• Deprecation warnings now use FutureWarning instead of DeprecationWarning. DeprecationWarning is silenced by Python's default warning filters outside of test contexts, making it invisible to most end-users. FutureWarning is shown by default, ensuring callers actually see the migration message. (#16)
• Minimum Python version raised to 3.9. Python 3.8 reached end-of-life in October 2024. (#73)
• License changed from MIT to Apache-2.0.
• Error messages now include the originating class or function name for easier debugging when a mapping fails. (#11)

Added

• target functions using **kwargs are now supported. Previously, forwarding to a target that accepted **kwargs and accessed them via kwargs.get(...) raised TypeError for unrecognised argument names. Extra arguments from the deprecated call are now forwarded correctly. (#6)

Fixed

• void() type annotation corrected to satisfy mypy. The return type of void() is now properly annotated — IDE and type checker warnings about unused parameters in deprecated function bodies are suppressed correctly.

Added

• skip_if parameter — conditional deprecation. Pass a bool or a zero-argument callable returning bool to skip the warning and forwarding when a runtime condition is true. Useful for gating deprecation behaviour on package version checks or feature flags. (#4)

Added

• target=True — self-deprecation mode. Deprecate and remap arguments within the same function without forwarding to a separate callable. Use with args_mapping to rename a parameter while keeping the function body intact. (#3)
• void() helper. Accepts any arguments and returns None. Silences IDE "unused parameter" warnings in deprecated function bodies where the body is never reached.
• no_warning_call() context manager. Assert that a block of code raises no deprecation warning — useful for verifying that new API paths are clean in tests. Renamed to assert_no_warnings() in v0.6.0. (#2)
• Stacked @deprecated decorators. Multiple @deprecated(True, ...) decorators can be stacked on the same function for multi-hop argument migrations across versions, each with independent warning counts and version metadata.

Added

• num_warns=-1 — always-on warnings. Setting num_warns to -1 causes the deprecation warning to fire on every call rather than stopping after N times.
• target=None — warn-only mode. The original function body still executes; @deprecated adds only a warning with no call forwarding. Useful when you want to signal deprecation without changing any call behaviour.

Added

Core decorator & forwarding

• @deprecated(target=callable) decorator. Marks a function as deprecated and automatically forwards all calls — including argument mapping — to a replacement function. The deprecated function body is never executed when target is a callable.
• Automatic argument mapping. Positional arguments are resolved to keyword arguments and forwarded to the target's signature. args_mapping renames ({"old": "new"}) or drops ({"old": None}) individual arguments during forwarding.
• args_extra — inject additional kwargs into the target call. Pass a dict of extra keyword arguments to merge into every forwarded call. Useful for providing default values or adapter arguments that the deprecated API never accepted.

Warning controls

• Configurable warning count (num_warns). Warnings fire once per function by default; set to any positive integer to limit the total count per function lifetime.
• Custom warning message template (template_mgs). Format string with %(source_name)s, %(target_path)s, %(deprecated_in)s, %(remove_in)s, and %(argument_map)s placeholders.
• Custom warning stream (stream). Route warnings to logging.warning, warnings.warn, or any callable.