API Reference

class regret.Deprecator(emit=<function emit>, name_of=<function qualname>, new_docstring=<function doc_with_deprecated_directive>)[source]

Deprecators help manifest regret.

  • emit – a callable which will be called with one argument, an EmittedDeprecation 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, the object that is being deprecated: :param * name_of, the callable described above for use in: calculating object names :param * version, 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, replacement=None, removal_date=None, addendum=None)[source]

Deprecate a callable as of the given version.

  • 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

Deprecate allowing a class to be subclassed.

Parameters:version – the first version in which the deprecated object was considered deprecated
class regret.EmittedDeprecation(object, name_of=<function qualname>, replacement=None, removal_date=None, addendum=None)[source]

A single emitted deprecation.