regret

Submodules

regret.emitted

Objects emitted whilst a deprecated object is being used.

class regret.emitted.Deprecation(kind: Deprecatable, name_of: name_of = <function _qualname>, replacement: Any = None, removal_date: date | None = None, addendum: str | None = None)

Bases: object

A single emitted deprecation.

message() → str

Express this deprecation as a comprehensible message.

class regret.emitted.Callable(object: Any)

Bases: object

A parameter for a particular callable.

message(name_of: name_of) → str

Express this deprecation as a comprehensible message.

class regret.emitted.Inheritance(type: type[Any])

Bases: object

The subclassing of a given parent type.

message(name_of: name_of) → str

Express this deprecation as a comprehensible message.

class regret.emitted.Parameter(callable: _Callable[..., Any], parameter: inspect.Parameter)

Bases: object

A parameter for a particular callable which should no longer be used.

message(name_of: name_of) → str

Express this deprecation as a comprehensible message.

class regret.emitted.OptionalParameter(callable: _Callable[..., Any], parameter: inspect.Parameter, default: Any)

Bases: object

A parameter for a particular callable which will become mandatory.

message(name_of: name_of) → str

Express this deprecation as a comprehensible message.

regret.testing

Helpers for testing your regret.

exception regret.testing.ExpectedDifferentDeprecations

Bases: AssertionError

Different deprecation(s) were seen than the ones which were expected.

class regret.testing.Recorder(saw: list[Deprecatable] = NOTHING)

Bases: object

Recorders keep track of deprecations as they are emitted.

They provide helper methods for asserting about the deprecations afterwards.

emit(deprecation: Deprecatable, extra_stacklevel: int) → None

“Emit” a deprecation by simply storing it.

An emitter suitable for passing to regret.Deprecator instances.

expect(**kwargs: Any) → contextlib.AbstractContextManager[None]

Expect a given set of deprecations to be emitted.

expect_deprecations(*deprecations: Deprecation) → Iterator[None]

Expect a given set of deprecations to be emitted.

expect_clean() → AbstractContextManager[None]

Expect no deprecations to be emitted.

regret.typing

Typing related helpers for regret.

class regret.typing.Deprecatable(*args, **kwargs)

Bases: Protocol

A single kind of deprecatable behavior.

message(name_of: Callable[[Any], str]) → str

Return a message summarizing this deprecation.

class regret.typing.Emitter(*args, **kwargs)

Bases: Protocol

A callable which reports when deprecated things are used.

regret.typing.name_of

Return a string name for any object.

alias of Callable[[Any], str]

class regret.typing.new_docstring(*args, **kwargs)

Bases: Protocol

A callable which transforms docstrings to include deprecation info.

Contents

You made a thing, but now you wish it’d go away… Deprecations, a love story.

class regret.Deprecator(emit: Emitter = <function emit>, name_of: name_of = <function _qualname>, new_docstring: new_docstring = <function doc_with_deprecated_directive>)

Bases: object

Deprecators help manifest regret.

Parameters:

• emit – a callable which will be called with one argument, a regret.emitted.Deprecation instance, whenever a deprecated object has been used. If unprovided, by default, a warning will be shown using the standard library warnings module.

• name_of – a callable which given any Python object should return a suitable name for the object. If unprovided, the __qualname__ will be used, and therefore an object’s (non-fully-)qualified name will appear in messages.

• new_docstring –

  a callable which should produce a docstring for newly deprecated objects. It will be called with three keyword :param * object: :param the object that is being deprecated: :param * name_of: calculating object names :param the callable described above for use in: calculating object names :param * version: :param the version that deprecates the provided object:

  and it should return a single string which will become the new docstring for a deprecated object. If unprovided, deprecation docstrings will be constructed using syntax suitable for Sphinx, via the deprecated directive.

callable(version: str, replacement: Any = None, removal_date: datetime.date | None = None, addendum: str | None = None)

Deprecate a callable as of the given version.

Parameters:

• version – the first version in which the deprecated object was considered deprecated

• replacement – optionally, an object that is the (direct or indirect) replacement for the functionality previously performed by the deprecated callable

• removal_date (datetime.date) – optionally, a date when the object is expected to be removed entirely

• addendum (str) – an optional additional message to include at the end of warnings emitted for this deprecation

inheritance(version: str)

Deprecate allowing a class to be subclassed.

Parameters:

version – the first version in which the deprecated object was considered deprecated

optional_parameter(version: str, name: str, default: Any)

Deprecate a parameter that was optional and will become required.

Parameters:

• version – the first version in which the parameter was to warn when unprovided

• name –

  the name of the parameter as specified in the callable’s signature.

  Requiring an optional parameter that was previously accepted only via arbitrary keyword arguments (”kwargs”) is also supported and should be specified using the name of the parameter as retrieved from the keyword arguments.

• default –

  whilst the parameter remains optional, the value that should be used when it is unprovided by a caller.

  It will be passed through to the wrapped callable, which can therefore assume the argument will always be present.

parameter(version: str, name: str)

Deprecate a parameter that was previously required and will be removed.

Parameters:

• version – the first version in which the deprecated parameter was considered deprecated

• name –

  the name of the parameter as specified in the callable’s signature.

  Deprecating a parameter that was previously accepted only via arbitrary keyword arguments (”kwargs”) is also supported and should be specified using the name of the parameter as retrieved from the keyword arguments.

regret.callable(version: str, replacement: Any = None, removal_date: datetime.date | None = None, addendum: str | None = None)

Deprecate a callable as of the given version.

Parameters:

• version – the first version in which the deprecated object was considered deprecated

• replacement – optionally, an object that is the (direct or indirect) replacement for the functionality previously performed by the deprecated callable

• removal_date (datetime.date) – optionally, a date when the object is expected to be removed entirely

• addendum (str) – an optional additional message to include at the end of warnings emitted for this deprecation

regret.inheritance(version: str)

Deprecate allowing a class to be subclassed.

Parameters:

version – the first version in which the deprecated object was considered deprecated

regret.optional_parameter(version: str, name: str, default: Any)

Deprecate a parameter that was optional and will become required.

Parameters:

• version – the first version in which the parameter was to warn when unprovided

• name –

  the name of the parameter as specified in the callable’s signature.

  Requiring an optional parameter that was previously accepted only via arbitrary keyword arguments (”kwargs”) is also supported and should be specified using the name of the parameter as retrieved from the keyword arguments.

• default –

  whilst the parameter remains optional, the value that should be used when it is unprovided by a caller.

  It will be passed through to the wrapped callable, which can therefore assume the argument will always be present.

regret.parameter(version: str, name: str)

Deprecate a parameter that was previously required and will be removed.

Parameters:

• version – the first version in which the deprecated parameter was considered deprecated

• name –

  the name of the parameter as specified in the callable’s signature.

  Deprecating a parameter that was previously accepted only via arbitrary keyword arguments (”kwargs”) is also supported and should be specified using the name of the parameter as retrieved from the keyword arguments.