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 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):

>>> @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, an UnsupportedWarning 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 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
...         )
...     }
... )
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 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.

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.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:
  • 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.

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:
  • d (dict) – Dictionary to be flattened.

  • name (str, optional, default: "") – Path to the parent dictionary. By default, no parent name is defined.

  • sep (str, optional, default: ".") – Flattened dict key separator.

Returns:

dict – A flattened copy of d.

See also

nest(), set_nested()

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:

boolTrue 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

Sorting HOWTO

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 using natsort_alphanum_key().

eradiate.util.misc.nest(d, sep='.')[source]#

Turn a flat dictionary into a nested dictionary.

Parameters:
  • d (dict) – Dictionary to be unflattened.

  • sep (str, optional, default: ".") – Flattened dict key separator.

Returns:

dict – A nested copy of d.

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.

Parameters:
  • d (dict) – Dictionary to operate on.

  • path (str) – Path to the value to be set.

  • value – Value to which path is to be set.

  • sep (str, optional, default: ".") – Separator used to decompose path.

See also

flatten(), nest()

eradiate.util.misc.summary_repr(value)[source]#
eradiate.util.misc.summary_repr(ds)
eradiate.util.misc.summary_repr(da)

Return a summarized repr for value.

eradiate.util.misc.summary_repr_vector(a, edgeitems=4)[source]#

Return a brief summary representation of a Numpy vector.

eradiate.util.numpydoc#

Numpydoc docstring tools.

eradiate.util.numpydoc.format_doc(sections)[source]#

Assemble docstring sections and format them according to the Numpydoc style.

Parameters:

sections (dict) – A dictionary mapping section names to contents. Section ordering follows the Nompydoc style guide.

Returns:

docstring (str) – Formatted docstring.

eradiate.util.numpydoc.parse_doc(doc)[source]#

Parse a docstring formatted with the Numpydoc style.

Parameters:

doc (str) – Docstring to parse.

Returns:

sections (dict) – A dictionary mapping section names to their content. Special _short_summary and _extended_summary keys are used for summary contents.

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.