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.
- class regret.emitted.Inheritance(type: type[Any])¶
Bases:
object
The subclassing of a given parent type.
- class regret.emitted.Parameter(callable: _Callable[..., Any], parameter: inspect.Parameter)¶
Bases:
object
A parameter for a particular callable which should no longer be used.
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.
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 librarywarnings
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 thedeprecated
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
- 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.
- 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.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.