This component wraps a component (function or class) that will soon be
removed and does two things:
The docstring of the method will be modified to include a notice
about deprecation, e.g. “Deprecated since 0.9.11. Use foo instead.”
Raises a DeprecatedWarning via the warnings module,
which is a subclass of the built-in DeprecationWarning. Note that
built-in DeprecationWarnings are ignored by default, so for users
to be informed of said warnings they will need to enable them—see
the warnings module documentation for more details.
Parameters:
deprecated_in (str, optional, default: None) – The version at which the decorated method is considered deprecated.
This will usually be the next version to be released when the decorator
is added. The default is None, which effectively means immediate
deprecation. If this is not specified, then the removed_in and
current_version arguments are ignored.
removed_in (str, optional, default: None) – The version or datetime.date when the decorated method will be
removed. The default is None, specifying that the component is not
currently planned to be removed.
Note: This parameter cannot be set to a value if deprecated_in is set
to None.
details (str, optional) – Extra details to be added to the method docstring and warning. For
example, the details may point users to a replacement method, such as
“Use the foo_bar method instead”. By default, there are no details.
current_version (str, optional) – Current version. If unset, Eradiate’s package version number is looked
up automatically.
Raises:
ValueError – If removed_in is not None and deprecated_in is not None.
Examples
This decorator allows for specifying the version from which the wrapped
component is deprecated, and when it will be retired (this latter argument
is optional):
If those components are used before v0.21.1, nothing happens. If they are
used between v0.21.1 (included) and v0.22.1 (excluded), a
DeprecatedWarning is emitted. If they are used from v0.22.1 on,
an UnsupportedWarning is emitted.
When used with static or class methods, their respective decorators must be
applied after this one:
Generate a simple module __getattr__() which redirects outdated
attribute lookups to current values with a deprecation warning.
Parameters:
subs (dict) – A dictionary with outdated names as keys. Values are 2-tuples consisting
of the current substitute and a dictionary of keyword arguments passed
to the DeprecatedWarning constructor.
Returns:
callable() – The generated module __getattr__() function.
Example
>>> __getattr__=substitute(... {... "OneDimExperiment":(# Old name... AtmosphereExperiment,# New type... {"deprecated_in":"0.22.5","removed_in":"0.22.7"},# Keyword args... )... }... )
This is a specialization of the built-in DeprecationWarning,
adding parameters that allow us to get information into the __str__
that ends up being sent through the warnings system.
The attributes aren’t able to be retrieved after the warning gets
raised and passed through the system as only the class–not the
instance–and message are what gets preserved.
Parameters:
component (type or callable()) – The component being deprecated.
deprecated_in (str, optional, default: None) – The version that component is deprecated in.
removed_in (str or datetime, optional, default: None) – The version or datetime.date specifying when component gets
removed.
details (str, optional) – Optional details about the deprecation. Most often this will include
directions on what to use instead of the now deprecated code.
Cache the result of a function based on the ID of its arguments.
This decorator caches the value returned by the function it wraps in order
to avoid unnecessary execution upon repeated calls with the same arguments.
Warning
The main difference with
functools.lru_cache(maxsize=1) is that the
cache is referenced by positional argument IDs instead of hashes.
Therefore, this decorator can be used with NumPy arrays; but it’s also
unsafe, because mutating an argument won’t trigger a recompute, while it
actually shoud! Use with great care!
Notes
Meant to be used as a decorator.
The wrapped function may only have positional arguments.
value (sequence) – Sequence to remove duplicates from.
preserve_order (bool, optional, default: True) – If True, preserve item ordering. The first occurrence of duplicated
items is kept. Setting to False may slightly improve performance.
sections (dict) – A dictionary mapping section names to their content. Special
_short_summary and _extended_summary keys are used for
summary contents.