exceptiontools

This module implements some exception classes and related features.

Module exceptiontools implements the following members:

• T Type variable.

• T1 Type variable.

• T2 Type variable.

• HydPyDeprecationWarning Warning for deprecated HydPy features.

• AttributeNotReady The attribute is principally defined but so far unprepared.

• AttributeNotReadyWarning The attribute is principally defined but so far unprepared.

• attrready() Return False when trying the access the attribute of the given object results in an AttributeNotReady error and otherwise return True.

• hasattr_() Return True or False whether the object has an attribute with the given name.

• getattr_() Return the attribute with the given name or, if it does not exist, the default value, if available.

• OptionalModuleNotAvailable A HydPy function requiring an optional module is called, but this module is not available.

• OptionalImport Imports the first found module “lazily”.

---

exception hydpy.core.exceptiontools.HydPyDeprecationWarning

Bases: DeprecationWarning

Warning for deprecated HydPy features.

exception hydpy.core.exceptiontools.AttributeNotReady

Bases: RuntimeError

The attribute is principally defined but so far unprepared.

exception hydpy.core.exceptiontools.AttributeNotReadyWarning

Bases: Warning

The attribute is principally defined but so far unprepared.

hydpy.core.exceptiontools.attrready(obj: Any, name: str) → bool

Return False when trying the access the attribute of the given object results in an AttributeNotReady error and otherwise return True.

In HydPy, some properties raise an AttributeNotReady error when one tries to access them before they are correctly set. You can use method attrready() to find out the current state of such properties without doing the related exception handling on your own:

>>> from hydpy import attrready
>>> from hydpy.core.parametertools import Parameter
>>> class Par(Parameter):
...     NDIM, TYPE = 1, float
>>> par = Par(None)
>>> attrready(par, "NDIM")
True
>>> attrready(par, "ndim")
Traceback (most recent call last):
...
AttributeError: 'Par' object has no attribute 'ndim'
>>> attrready(par, "shape")
False
>>> par.shape = 2
>>> attrready(par, "shape")
True

hydpy.core.exceptiontools.hasattr_(obj: Any, name: str) → bool

Return True or False whether the object has an attribute with the given name.

In HydPy, some properties raise an AttributeNotReady error when one tries to access them before they are correctly set, which also happens when one applies function hasattr() to find out if the related object handles the property at all. Function hasattr_() extends function hasattr() by also catching AttributeNotReady errors:

>>> from hydpy import hasattr_
>>> from hydpy.core.parametertools import Parameter
>>> class Par(Parameter):
...     NDIM, TYPE = 1, float
>>> par = Par(None)
>>> hasattr_(par, "NDIM")
True
>>> hasattr_(par, "ndim")
False
>>> hasattr_(par, "shape")
True
>>> par.shape = 2
>>> attrready(par, "shape")
True

hydpy.core.exceptiontools.getattr_(obj: Any, name: str, default: T | _Enum = _Enum.GETATTR_NO_DEFAULT, type_: Type[T] | None = None) → Any

Return the attribute with the given name or, if it does not exist, the default value, if available.

In HydPy, some properties raise an AttributeNotReady error when one tries to access them before they are correctly set, which also happens when one applies function getattr() with default values. Function getattr_() extends function getattr() by also returning the default value when an AttributeNotReady error occurs:

>>> from hydpy import getattr_
>>> from hydpy.core.parametertools import Parameter
>>> class Par(Parameter):
...     NDIM, TYPE = 1, float
>>> par = Par(None)
>>> getattr_(par, "NDIM")
1
>>> getattr_(par, "NDIM", 2)
1
>>> getattr_(par, "ndim")
Traceback (most recent call last):
...
AttributeError: 'Par' object has no attribute 'ndim'
>>> getattr_(par, "ndim", 2)
2

>>> getattr_(par, "shape")
Traceback (most recent call last):
...
hydpy.core.exceptiontools.AttributeNotReady: Shape information for variable `par` can only be retrieved after it has been defined.
>>> getattr_(par, "shape", (4,))
(4,)
>>> par.shape = 2
>>> getattr_(par, "shape")
(2,)
>>> getattr_(par, "shape", (4,))
(2,)

Function getattr_() allows to specify the expected return type and raises an AssertionError if necessary:

>>> getattr_(par, "NDIM", type_=int)
1
>>> getattr_(par, "NDIM", type_=str)
Traceback (most recent call last):
...
AssertionError: returned type: int, allowed type: str

Additionally, it infers the expected return type from the default argument automatically:

>>> getattr_(par, "NDIM", "wrong")
Traceback (most recent call last):
...
AssertionError: returned type: int, allowed type(s): str

If the attribute type differs from the default value type, you need to define the attribute type explicitly:

>>> getattr_(par, "NDIM", "wrong", int)
1

exception hydpy.core.exceptiontools.OptionalModuleNotAvailable

Bases: ImportError

A HydPy function requiring an optional module is called, but this module is not available.

class hydpy.core.exceptiontools.OptionalImport(name: str, modules: List[str], namespace: Dict[str, Any])

Bases: module

Imports the first found module “lazily”.

>>> from hydpy.core.exceptiontools import OptionalImport
>>> numpy = OptionalImport(
...     "numpy", ["numpie", "numpy", "os"], locals())
>>> numpy.nan
nan

If no module could be imported at all, OptionalImport returns a dummy object which raises a OptionalModuleNotAvailable each time a one tries to access a member of the original module.

>>> numpie = OptionalImport("numpie", ["numpie"], locals())
>>> numpie.nan
Traceback (most recent call last):
...
hydpy.core.exceptiontools.OptionalModuleNotAvailable: HydPy could not load one of the following modules: `numpie`.  These modules are no general requirement but installing at least one of them is necessary for some specific functionalities.

Note the very special case that OptionalImport raises a plain AttributeError when asked for the attribute __wrapped__ (to avoid trouble when applying function wrapt of module inspect):

>>> numpie.__wrapped__
Traceback (most recent call last):
...
AttributeError