uttrs API¶
uttrs bridge between attrs and Astropy units 1.
uttrs seeks to interoperate Classes defined using attrs and Astropy units in a simple manner with two main functionalities:
uttr.ib
which generates attributes sensitive to units.uttr.array_accessor
which allows access to attributes linked to units, and transform them into numpy arrays.
References
- 1
Price-Whelan, Adrian M., et al. “The Astropy project: Building an open-science project and status of the v2. 0 core package.” The Astronomical Journal 156.3 (2018): 123.
-
class
uttr.
ArrayAccessor
(instance)¶ Bases:
object
Automatic converter of the
uttrs
attributes innumpy.ndarray
.Instances of ArrayAccessor (
arr_
) access to the attributes (defined with uttrs) of the provided instance, and if they are ofatropy.units.Quantity
type it converts them intonumpy.ndarray
.If you try to access a attribute no defined by uttrs, an
AttributeErrror
is raised.Examples
>>> @attr.s() ... class Foo: ... quantity = uttr.ib(unit=u.km) ... array = attr.ib()
>>> foo = Foo( ... quantity=u.Quantity([1, 2]), ... array=np.array([1, 2]), ... )
>>> arr_ = ArrayAccessor(foo)
>>> arr_ ArrayAccessor( Foo(quantity=<Quantity [1., 2.]>, array=array([1, 2]))
>>> arr_.quantity array([1., 2., 3.])
>>> arr_.array AttributeError("No uttr.Attribute 'array'")
-
class
uttr.
UnitConverterAndValidator
(unit: astropy.units.core.UnitBase)¶ Bases:
object
Converter and validator of astropy.units for attrs.
- Parameters
unit (astropy.units.UnitBase) – The base units for attribute default unit assignation and validation of inputs.
-
convert_if_dimensionless
(value)¶ Assign a unit to a dimensionless object.
If the object already has a dimension it returns it without change
Examples
>>> uc = UnitConverter(u.km)
>>> uc.convert_if_dimensionless(1) # dimensionless then convert '<Quantity 1. km>'
>>> # the same object is returned >>> uc.convert_if_dimensionless(1 * u.kpc) '<Quantity 1. kpc>'
-
is_dimensionless
(v)¶ Return true if v is dimensionless.
-
to_array
(v)¶ Convert the quantity to an array of the given unit.
-
unit
: astropy.units.core.UnitBase¶
-
validate_is_equivalent_unit
(instance, attribute, value)¶ Validate that the unit equivalence with. the configured unit.
This method follows the suggested signature by attrs validators.
the instance that’s being validated (aka self),
the attribute that it’s validating, and finally
the value that is passed for it.
:raises ValueError:: If the value has a non-equivalent dimesion to unit.
-
uttr.
array_accessor
()¶ Provide an ArrayAccessor attribute to an attrs based class.
This new attribute allows access to any other uttrs defined attribute or of the class. It converts it to the default unit of the attribute and afterward to a numpy.ndarray.
If you try to access an attribute no defined by uttrs, an
AttributeErrror
is raised.Example
>>> @attr.s() ... class Foo: ... q = uttr.ib(unit=u.kg) ... a = attr.ib() ... arr_ = array_accessor()
>>> foo = Foo(q=[1, 2, 3] * u.kg, a=np.array([1, 2, 3])) >>> foo Foo(q=<Quantity [1., 2., 3.] kg>, a=array([1, 2, 3]))
>>> foo.q <Quantity [1., 2., 3.] kg>
>>> foo.arr_.q array([1., 2., 3.])
>>> foo.a array([1, 2, 3])
>>> foo.arr_.a array([1, 2, 3])
-
uttr.
attribute
(unit: astropy.units.core.UnitBase, **kwargs)¶ Create a new attribute with converters and validators for a given unit.
- Parameters
unit (u.UnitBase) – The unit to use in the converters and the attribute validator
kwargs – Extra parameter of attr.ib()
Example
>>> @attr.s() ... class Foo: ... p = unit_attribute(unit=(u.km / u.s)) >>>> Foo(p=[1, 2, 3]) Foo(p=<Quantity [1., 2., 3.] km / s>)
@attr.s() >>> class Foo: … p = unit_attribute(unit=(u.km / u.h))
>>> Foo(p=[1, 2, 3]) Foo(p=<Quantity [1., 2., 3.] km / h>)
>>> @attr.s() ... class Foo: ... p = unit_attribute(unit=(u.km / u.s))
>>> Foo(p=[1, 2, 3] * u.km / u.h) Foo(p=<Quantity [1., 2., 3.] km / h>)
>>> Foo(p=[1, 2, 3] * u.kpc) ValueError: Unit of attribute 'p' must be equivalent to 'km / s'. Found 'kpc'.
-
uttr.
ib
(unit: astropy.units.core.UnitBase, **kwargs)¶ Equivalent to
uttr.attribute
to use like attr.ib.