---
description: Known limitations and non-goals of pyDeprecate — async, proxies, scoped switches, static checkers, and the audit tooling — each with the workaround.
---

# Limitations and non-goals

pyDeprecate favours a small API over covering every corner of Python. This page lists the corners it deliberately does not cover, so you can recognise them before they surprise you. Each entry states the behaviour in one or two sentences and links to the section with the details and the workaround.

## Async and generators

- **Callable objects with `async def __call__` are not detected as coroutine functions.** `inspect.iscoroutinefunction` does not look at `__call__`, and `@deprecated` rejects a plain callable instance with `TypeError`, so such an object cannot serve as an `async def` source. Define a thin `async def` that awaits the object and decorate that. See [functools.partial and callable wrappers](troubleshooting.md#why-cant-i-decorate-a-functoolspartial-or-callable-wrapper).
- **Async and sync targets are not interchangeable in both directions.** An `async def` source may forward to a sync target, which is called directly without being awaited. A sync source whose target is a coroutine function raises `TypeError` on the first call, because a sync wrapper cannot await it. Declare the source `async def`.
- **A `@types.coroutine` generator keeps the plain wrapper.** A generator-based coroutine is a generator function that `await` accepts only because its own code object carries the `CO_ITERABLE_COROUTINE` flag, which a generator wrapper lacks, so `@deprecated` gives it the plain function wrapper: the warning fires at the call rather than on the first step, and `inspect.isgeneratorfunction` reports `False` for the wrapper.
- **A deprecated generator raises its argument errors on the first step, not at the call.** A native generator function called with the wrong number of arguments raises `TypeError` at once, but its deprecated wrapper accepts any arguments and only creates the generator, so that arity `TypeError` (in pyDeprecate's own wording), and a `Failed mapping` error from a forwarding target, raise on the first `next()` or `async for` step. See [Deprecating generator functions](guide/advanced.md#deprecating-generator-functions).
- **Cycle detection is lazy.** A `target=` chain that loops back on itself is not caught at decoration time; the `RuntimeError` fires when a wrapper in the cycle is first called. For generator wrappers it fires on the first `next()` or `async for` step, because calling a generator wrapper runs nothing. The same error fires when a replacement recurses through the deprecated name while the wrapper is still on the call path (for a generator, before its first `yield`), so recurse through the replacement's own name instead. See [the cycle error](troubleshooting.md#runtimeerror-circular-deprecation-cycle-detected).

## Proxies (`deprecated_instance`, `deprecated_class`)

- **Item writes never warn.** `proxy["key"] = value` and `del proxy["key"]` pass through silently, like attribute writes, and they honour `skip_if`. With `read_only=True` they raise `AttributeError` unless `skip_if` is active. See [deprecated_instance](guide/classes.md).
- **`read_only` covers only the standard mutators.** Besides writes through the proxy, it blocks the collection methods `append`, `clear`, `discard`, `extend`, `insert`, `pop`, `remove`, `setdefault`, `update` and `add`. A custom method such as `register()` or `reload()` still mutates the wrapped object. See [read_only troubleshooting](troubleshooting.md#my-object-mutated-despite-read_onlytrue).
- **A proxy over a `str` or `bytes` value claims `os.PathLike`.** A proxy carries only the protocols the wrapped object supports, so `callable()`, `Iterator`, `Awaitable` and the other structural ABCs answer as for the object itself. The one exception is text: `int()`, `float()`, `complex()` and `os.fspath()` parse `str` and `bytes` without a dunder on the type, and the proxy keeps those conversions so a deprecated `"8080"` or path string still converts. That makes such a proxy report `os.PathLike` and `typing.SupportsInt` too. Check the type of the unwrapped object when you use one of those two checks as a guard.
- **A proxy's protocols are fixed when it is created.** The proxy picks the protocols it serves (calling, iteration, `len()`, `in`, subscript, hashing, operators) from the type of the wrapped object, and of its replacement, at the moment it is constructed. A method the type gains afterwards, such as a `__call__` patched in later or a magic method set on a `Mock` after wrapping, does not reach that proxy: `callable(obj)` can be `True` while `callable(proxy)` is `False`. Up to v0.14 every proxy forwarded every protocol. Finish setting up the object before you wrap it, or wrap it again after changing its type.
- **A class proxy cannot be pickled by reference when it replaces the class's own name.** When `deprecated_class` rebinds the module-level name of the decorated class, `pickle` finds the proxy where it expects the class, so pickling the class alias itself raises `PicklingError`. This covers the class object only: instances of a class deprecated in place pickle and load as instances of the original class, and neither step warns. A payload pickled before the in-place deprecation loads only while its recorded `module.qualname` still names the real class; once that name is rebound to the proxy, loading fails. Re-pickling before deprecating does not help, because a payload written while the name is still bound to the real class names that class directly; load such payloads through a `pickle.Unpickler.find_class` override that unwraps the proxy. This includes exception and `OrderedDict` subclasses, whose inherited `__reduce__` calls the class. A class that defines its own `__reduce_ex__` keeps its own pickling, so members of an Enum deprecated in place still raise `PicklingError`. `deprecated_instance` proxies pickle fine. See [copy, deepcopy and pickle](troubleshooting.md#does-the-deprecation-survive-copy-deepcopy-and-pickle).
- **Pickled instances of a class deprecated in place load only while the deprecation is in place.** Their payload names one of pyDeprecate's rebuild helpers instead of the class, so the loading process needs pyDeprecate installed, and once the deprecation is removed the helpers refuse the plain class with `AttributeError`. The helper names stay stable across releases, so upgrading pyDeprecate is safe. To migrate stored instances, load them while the deprecation is in place, then in the migration process set the module attribute back to the real class and re-pickle; re-pickling while the proxy still holds the name writes helper-dependent payloads again. See [loading pickled instances](troubleshooting.md#what-do-pickled-instances-of-a-class-deprecated-in-place-need-to-load).
- **The class of a proxy cannot be pickled.** `type(proxy)` is a generated subclass of `_DeprecatedProxy` that carries the proxy's protocols and borrows the base class's module and name, so `pickle.dumps(type(proxy))` raises `PicklingError`: the borrowed name resolves to a different class. pyDeprecate v0.14 pickled the proxy class by reference. Pickling the proxy itself is unaffected. To detect a proxy, check `isinstance(obj, DeprecationProxy)` rather than storing or pickling its class.
- **`cached_property` warns at most once per instance.** The cache is filled by the first read, so later reads of that instance never reach pyDeprecate and `num_warns` cannot raise the count. With `num_warns=-1` every instance warns on its first read; the default `num_warns=1` budget is shared by all instances, so only the first one warns. See [Properties](guide/properties.md).

## Configuration

- **`skip_if` must return a strict `bool`.** A truthy `int` or a string raises `TypeError`; wrap the result in `bool(...)`. See [the `skip_if` error](troubleshooting.md#typeerror-skip_if-function-must-return-bool).
- **A bound target does not work for a classmethod source.** A bound target such as `target=YourClass.method` works only for a source that is not a classmethod; for a genuine classmethod source it fails, because the bound target has no receiver parameter and the source's receiver argument is rejected. Inside the class body pass the raw descriptor (`target=method`) instead. See [Class methods and static methods](guide/advanced.md#class-methods-and-static-methods).
- **A classmethod target cannot tell a plain or static source from a classmethod.** A static source written `@deprecated(...)` above `@staticmethod` is rejected at decoration, but a plain function, or a static source written `@staticmethod` above `@deprecated(...)`, looks like a classmethod source. Its first argument, or that parameter's default when the call leaves it out, is forwarded as the replacement's class: a value that is not a class raises `TypeError` before any warning, but a class passed there or given as the default is forwarded as the receiver. Make the source a `@classmethod`, or give a static source a bound target such as `target=YourClass.method`. See [Class methods and static methods](guide/advanced.md#class-methods-and-static-methods).
- **An `as_exceptions()` scope reaches a new thread only if the interpreter copies the context.** The scope is local to the current thread and `asyncio` task, and tasks created inside it inherit it. Whether a thread started inside the block inherits it depends on the interpreter, so run the thread's target through `contextvars.copy_context().run(...)` when it must. Inside a scope `deprecate.AS_EXCEPTIONS` still reports the global value, so do not read it to detect a scope.
- **An `as_exceptions()` scope held across a generator `yield` applies to the consumer.** A generator or async generator runs in its consumer's context, so while it is suspended inside `with as_exceptions():` the consumer's own code is fatal too, and if the generator is closed from another task (`aclose()` elsewhere, garbage collection) the scope stays open in the consumer's context. Open and close the scope within one step of the generator. See [The global switch](guide/functions.md#the-global-switch).

## Static checkers

- **Only a literal `warnings.deprecated` is visible to type checkers.** PEP 702 tools recognise the decorator by name, so deprecations that pyDeprecate applies at runtime are invisible to mypy, pyright and IDEs. Stack a literal `warnings.deprecated` (or `typing_extensions.deprecated`) on top as shown in [Static type checkers (PEP 702)](guide/functions.md#static-type-checkers-pep-702); for classes see [PEP 702 static checkers](guide/classes.md#pep-702-static-checkers).

## Audit tooling

- **There is no import-free scan mode.** The audit imports the package it scans, so its module-level code runs and its runtime dependencies must be installed in the scanning environment. The remote pre-commit hook runs in an isolated environment and therefore only suits packages without such dependencies; use a `repo: local` hook otherwise. See [Audit Tools](guide/audit.md) and [the CLI reference](guide/cli.md).
- **Scans are per package, never per file.** A single `.py` path is rejected with `File paths are not supported`, and a directory holding two or more top-level packages is rejected as well, so "scan only the files changed in this commit" is not available. Pass the package directory or an importable name. See [Path formats](guide/cli.md#path-formats).
- **The GitHub Action's `install: true` re-pins pyDeprecate.** The default installs pyDeprecate from the action's own ref into the job's Python, replacing the version your job already had. Set `install: false` when your project pins its own version. See [GitHub Action](guide/audit.md#github-action).
