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.

  • uttr.s a class decorator to automatically add the array_accessor.

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 in numpy.ndarray.

Instances of ArrayAccessor (arr_) access to the attributes (defined with uttrs) of the provided instance, and if they are of atropy.units.Quantity type it converts them into numpy.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: Optional[astropy.units.core.UnitBase] = None, **kwargs)

Create a new attribute with converters and validators for a given unit.

Parameters

  • unit (u.UnitBase or None) – The unit to use in the converters and the attribute validator. If it’s None, the call is equivalent to attr.ib(**kwargs)

  • 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: Optional[astropy.units.core.UnitBase] = None, **kwargs)

Equivalent to uttr.attribute to use like attr.ib.

uttr.s(maybe_cls=None, *, aaccessor='arr_', **kwargs)

Class decorator to automatically add an array accessor to the class.

The behaviour is the same as attr.s function but also automatically creates an uttrs.ArrayAccessor property with defined by aaccessor.

Parameters

  • aaccessor (str or None, default 'arr_`) – Name of the array accessor property. If is None, no property is added.

  • maybe_cls (class or None, default None.) – Same behavior of attr.s() maybe_cls parameter.

  • kwargs – Same parameter as attr.s().

Examples

The next two codes are equivalent

import astropy.units as u
import uttr

@attr.s
class Foo:
    attribute = uttr.ib(unit=u.K)
    arr_ = uttr.array_accessor()

import astropy.units as u
import uttr

@uttr.s
class Foo:
    attribute = uttr.ib(unit=u.K)