SR-Forge

Deprecation Utilities

Tools for handling deprecated functions, classes and module paths.

SRForgeDeprecationWarning

Bases: DeprecationWarning

A deprecation in SR-Forge's own API.

Shown by default. Python hides a plain DeprecationWarning unless it is raised from __main__ — but a config's _target paths are resolved inside the library, so a deprecated path in a config would never be reported. The filter below makes SR-Forge's own deprecations visible wherever they are triggered. Still a DeprecationWarning, so pytest.warns(DeprecationWarning) and -W error::DeprecationWarning keep working.

warn_deprecated(message: str, *, stacklevel: int = 2) -> None

Issue an SR-Forge deprecation warning, formatted like every other.

stacklevel counts from the caller of this function, as for :func:warnings.warn.

deprecated_module(old_module: str, moved: dict[str, str], *, removal: str, notes: dict[str, str] | None = None)

Forward names from a module that moved, warning on each use.

Returns (__getattr__, __dir__) for the old module to assign. Every old name resolves lazily to the object at its new path — the same object, not a copy or a subclass, so isinstance checks, class registries and existing subclasses are unaffected — and warns once, naming the new path. That covers from old import Name, old.Name and a config's _target: old.Name alike.

Nothing warns on merely importing the old module, so tooling that walks every module (registry discovery, documentation builds) stays quiet; only code that actually uses an old name is told.

Parameters:

Name	Type	Description	Default
old_module	str	The old module's dotted name (pass __name__).	required
moved	dict[str, str]	{old_name: "new.module.path.NewName"}.	required
removal	str	The release in which the old path goes away.	required
notes	dict[str, str] | None	Optional {old_name: sentence} appended to that name's warning — e.g. to explain a rename.	None

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

Create a deprecated class alias that warns on instantiation.

This function creates a new class that inherits from new_cls but issues a DeprecationWarning when it's initialized. The alias will have the old_name and can be used with isinstance checks as if it were the new class.

Parameters:

Name	Type	Description	Default
old_name	str	The name for the new deprecated class alias.	required
new_cls	type	The new, non-deprecated class to wrap.	required

Returns:

Name	Type	Description
type	type	A new class type that serves as a deprecated alias for new_cls.