eradiate.util
#
eradiate.util.deprecation
#
- eradiate.util.deprecation.deprecated(deprecated_in=None, removed_in=None, details='', current_version=None)[source]#
Decorate a component to signify its deprecation
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 thewarnings
module, which is a subclass of the built-inDeprecationWarning
. Note that built-inDeprecationWarning
s are ignored by default, so for users to be informed of said warnings they will need to enable them—see thewarnings
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 isNone
, 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 ordatetime.date
when the decorated method will be removed. The default isNone
, 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 toNone
.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 notNone
.
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):
>>> @deprecated(deprecated_in="0.21.1", removed_in="0.22.1") ... def foo(): ... >>> foo()
This will emit a
UnsupportedWarning
, which you can then handle. We can also deprecate classes:>>> @deprecated(deprecated_in="0.21.1", removed_in="0.22.1") ... class SomeClass: ...
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, anUnsupportedWarning
is emitted.When used with static or class methods, their respective decorators must be applied after this one:
>>> class SomeClass: ... @staticmethod ... @deprecated(deprecated_in="0.21.1", removed_in="0.22.1") ... def staticmethod(): ... ... ... @classmethod ... @deprecated(deprecated_in="0.21.1", removed_in="0.22.1") ... def classmethod(cls): ...
- eradiate.util.deprecation.substitute(subs)[source]#
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 theDeprecatedWarning
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 ... ) ... } ... )
- exception eradiate.util.deprecation.DeprecatedWarning(component, deprecated_in, removed_in, details='')[source]#
A warning class for deprecated methods
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 thewarnings
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
orcallable()
) – The component being deprecated.deprecated_in (
str
, optional, default:None
) – The version that component is deprecated in.removed_in (
str
ordatetime
, optional, default:None
) – The version ordatetime.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.
- exception eradiate.util.deprecation.UnsupportedWarning(component, deprecated_in, removed_in, details='')[source]#
A warning class for methods to be removed
This is a subclass of
DeprecatedWarning
and is used to output a proper message about a component being unsupported.
eradiate.util.misc
#
A collection of tools which don’t really fit anywhere else.
- class eradiate.util.misc.LoggingContext(logger, level=None, handler=None, close=True)[source]#
This context manager allows for a temporary override of logger settings.
- class eradiate.util.misc.MultiGenerator(generators)[source]#
This generator aggregates several generators and makes sure that items that have already been served are not repeated.
- class eradiate.util.misc.Singleton[source]# 1Creating a singleton in Python on Stack Overflow.
A simple singleton implementation. See 1Creating a singleton in Python on Stack Overflow. for details.
References
Examples
>>> class MySingleton(metaclass=Singleton): ... >>> my_singleton1 = MySingleton() >>> my_singleton2 = MySingleton() >>> my_singleton1 is my_singleton2 True
- class eradiate.util.misc.cache_by_id(func)[source]#
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.
Works with functions and methods.
Examples
>>> @cache_by_id ... def f(x, y): ... print("Calling f") ... return x, y >>> f(1, 2) Calling f (1, 2) >>> f(1, 2) (1, 2) >>> f(1, 1) Calling f (1, 1) >>> f(1, 1) (1, 1)
- eradiate.util.misc.deduplicate(value, preserve_order=True)[source]#
Remove duplicates from a sequence.
- Parameters:
- Returns:
list
– List of values with duplicates removed.
- eradiate.util.misc.find_runs(x)[source]#
Find runs of consecutive items in an array.
- Parameters:
x (array-like) – Input array.
- Returns:
tuple(array-like
, array-like,array-like)
– Run values, run starts, run lengths.
Notes
Credit: Alistair Miles Source: https://gist.github.com/alimanfoo/c5977e87111abe8127453b21204c1065
- eradiate.util.misc.flatten(d, sep='.', name='')[source]#
Flatten a nested dictionary.
- Parameters:
- Returns:
dict
– A flattened copy of d.
See also
- eradiate.util.misc.fullname(obj)[source]#
Get the fully qualified name of obj. Aliases will be dereferenced.
- eradiate.util.misc.get_class_that_defined_method(meth)[source]#
Get the class which defined a method, if relevant. Otherwise, return
None
.
- eradiate.util.misc.is_vector3(value)[source]#
Check if value can be interpreted as a 3-vector.
- Parameters:
value – Value to be checked.
- Returns:
bool
–True
if a value can be interpreted as a 3-vector.
- eradiate.util.misc.natsort_alphanum_key(x)[source]# 2Natural sorting on Stack Overflow.
Simple sort key natural order for string sorting. See 2Natural sorting on Stack Overflow. for details.
See also
References
- eradiate.util.misc.natsorted(l)[source]#
Sort a list of strings with natural ordering.
- Parameters:
l (iterable) – List to sort.
- Returns:
list
– List sorted usingnatsort_alphanum_key()
.
- eradiate.util.misc.nest(d, sep='.')[source]#
Turn a flat dictionary into a nested dictionary.
- Parameters:
- Returns:
dict
– A nested copy of d.
See also
- eradiate.util.misc.onedict_value(d)[source]#
Get the value of a single-entry dictionary.
- Parameters:
d (mapping) – A single-entry mapping.
- Returns:
object
– Unwrapped value.- Raises:
ValueError – If
d
has more than a single element.
Notes
This function is basically
next(iter(d.values()))
with a safeguard.Examples
>>> onedict_value({"foo": "bar"}) 'bar'
- eradiate.util.misc.set_nested(d, path, value, sep='.')[source]#
Set values in a nested dictionary using a flat path.
eradiate.util.numpydoc
#
Numpydoc docstring tools.
- eradiate.util.numpydoc.format_doc(sections)[source]#
Assemble docstring sections and format them according to the Numpydoc style.
- eradiate.util.numpydoc.NUMPYDOC_SECTION_TITLES = ['Parameters', 'Fields', 'Attributes', 'Returns', 'Yields', 'Receives', 'Other Parameters', 'Raises', 'Warns', 'Warnings', 'See Also', 'Notes', 'References', 'Examples']#
List of support docstring sections. The “Fields” section is unique to Eradiate.