Skip to content

deprecation

deprecation ¤

Deprecation helpers: rename parameters, methods and classes without breaking callers.

Every helper keeps the old spelling working and emits a :class:DeprecationWarning that names the replacement, so a user's code keeps running and their test suite tells them what to change. The old names are removed in the next major release (see docs/naming.md).

  • :func:renamed_kwargs -- a keyword argument got a new name.
  • :func:deprecated_method -- a method got a new name.
  • :func:deprecated_class -- a class got a new name.
  • :func:keyword_only -- optional arguments become keyword-only; passing them positionally still works but warns.

The wrapped callables report the new signature to :func:inspect.signature (and so to the API reference and IDEs).

The deprecated objects are also marked the PEP 702 way (__deprecated__, via :func:warnings.deprecated on Python 3.13+), without a second runtime warning. Static type checkers only see a @deprecated decorator written in the source, so the defining modules also declare each alias with typing_extensions.deprecated inside an if TYPE_CHECKING: block; mypy (--enable-error-code deprecated), pyright and IDEs then flag its use.

deprecated_attribute ¤

deprecated_attribute(new_name: str)

A class attribute that forwards to new_name with a warning.

Example

class Loader: ... start_timestamp = deprecated_attribute("start")

Reading or setting loader.start_timestamp warns and uses loader.start.

caller_stacklevel ¤

caller_stacklevel() -> int

stacklevel that points a warning at the first frame outside ts_shape.

Call it directly in the warnings.warn(...) call. Detector methods are wrapped (signal checks, keyword-only and renamed-keyword shims), so a fixed number would attribute the warning to a wrapper inside the package, and Python's default filters would then hide a DeprecationWarning.

renamed_kwargs ¤

renamed_kwargs(**renames: str) -> Callable[[F], F]

Accept old keyword names, mapped to their new names, with a warning.

Example

@renamed_kwargs(freq="window") ... def per_window(df, window="1h"): ...

per_window(df, freq="1D") then works and warns; passing both the old and the new name raises :class:TypeError.

deprecated_method ¤

deprecated_method(new_name: str) -> Any

A class attribute that forwards to new_name with a warning.

Example

class OEEEvents: ... def oee(self): ... ... calculate_oee = deprecated_method("oee")

deprecated_class ¤

deprecated_class(new_cls: C, old_name: str) -> C

A subclass of new_cls named old_name that warns when created.

Instances are instances of new_cls, so isinstance checks and the event-log taxonomy (which resolves aliases) keep working.

keyword_only ¤

keyword_only(n_positional: int) -> Callable[[F], F]

Make every parameter after the first n_positional keyword-only.

n_positional counts self. Callers that still pass the later parameters positionally keep working, with a warning. The reported signature shows the keyword-only marker.