mixle.utils.deprecation module

One mechanism for deprecating public names, implementing the policy in docs/support-policy.rst.

A deprecated stable name must keep working and tell the caller where to go, in a category tools can act on. This module is the single place that emits that signal, so every deprecation in the library speaks with one warning category (DeprecationWarning) and one message format:

<old> is deprecated since mixle <since>; use <new> instead. It will be removed in mixle <removed_in>.

Use deprecated_alias() to wrap a thin forwarding method or function; use warn_deprecated() directly for finer-grained cases (a deprecated argument value, a deprecated code path). The stacklevel is set so the warning points at the caller’s line, not at this module.

warn_deprecated(old, new, *, since, removed_in=None, stacklevel=1)[source]

Emit the standard DeprecationWarning for using old instead of new.

stacklevel counts caller frames above this function: the default (1) attributes the warning to the immediate caller. deprecated_alias() passes 2 to skip its own wrapper frame so the warning still lands on the user’s call site.

Parameters:
Return type:

None

deprecated_alias(new, *, since, removed_in=None, old=None)[source]

Mark a thin forwarding method/function as a deprecated alias for new.

The wrapped callable’s body is unchanged (it should just forward to the canonical name); calling it emits the standard warning first, attributed to the caller. old defaults to the wrapped callable’s qualified name (e.g. FooEstimator.accumulatorFactory).

Parameters:

  • new (str)

  • since (str)

  • removed_in (str | None)

  • old (str | None)

Return type:

Callable[[F], F]

deprecation_message(old, new, *, since, removed_in=None)[source]

Return the canonical deprecation message (the one format every mixle deprecation uses).

Parameters:
Return type:

str