numtraits 0.2
Numerical traits for Python objects
License: BSD

Numerical properties for Python objects
=======================================

|Travis Build Status| |Coverage Status|

**Please note:** this package is experimental and may still see some
changes to the API. If you have any suggestions for improving the API,
please open an issue!

About
-----

This simple module defines a descriptor class that can be used to define
numerical properties (scalar and n-dimensional arrays) on classes and
provide a way to validate these. Thus, instead of writing something
like:

.. code:: python

    class Sphere(object):

        @property
        def radius(self):
            return self._radius

        @radius.setter
        def radius(self, value):
            if value <= 0:
                raise ValueError("Value should be strictly positive")
            if not np.isscalar(value):
                raise TypeError("Value should be a scalar")
            if not np.isreal(value):
                raise TypeError("Value should be numerical")
            self._radius = value

for each property you want to define, you can simply do:

.. code:: python

    from numtraits import NumericalTrait
    from traitlets import HasTraits

    class Sphere(HasTraits):

        radius = NumericalTrait(domain='strictly-positive', ndim=0)

The ``NumericalTrait`` class is implemented on top of the
`traitlets <https://github.com/ipython/traitlets>`__ module. Any class
using ``NumericalTrait`` for the definition of a property **must**
derive from the ``traitlets.HasTraits`` class.

Support is also included for checking the dimensionality and shape of
arrays (which includes converting tuples and lists to arrays
on-the-fly), as well as checking the units of quantities for the
`astropy.units <docs.astropy.org/en/stable/units/>`__,
`pint <http://pint.readthedocs.org/>`__, and
`quantities <https://pythonhosted.org/quantities/>`__ unit frameworks.

Installing
----------

This package is compatible with Python 2.7, 3.3 and later, and requires
`numpy <http://www.numpy.org>`__ and
`traitlets <https://github.com/ipython/traitlets>`__. If you are
interested in doing unit validation, you will also need
`astropy <docs.astropy.org/en/stable/units/>`__,
`pint <http://pint.readthedocs.org/>`__, or
`quantities <https://pythonhosted.org/quantities/>`__, depending on
which unit framework you normally use.

To install, you can do:

::

    pip install numtraits

You can also bundle ``numtraits.py`` into your package if you want to
avoid using an external dependency, but please be sure to keep the
copyright and the license in the file.

Using
-----

To create self-validating numerical properties on a class, use the
``NumericalTrait`` class:

.. code:: python

    from traitlets import HasTraits
    from numtraits import NumericalTrait

    class Sphere(HasTraits):

        radius = NumericalTrait(domain='strictly-positive', ndim=0)
        position = NumericalTrait(shape=(3,))

When a property is set, it will be validated:

.. code:: python

    >>> s = Sphere()
    >>> s.radius = 1.
    >>> s.radius = -3
    ...
    TraitError: radius should be strictly positive
    >>> s.radius = [1,2]
    ...
    TraitError: radius should be a scalar value
    >>> s.position = (1,2,3)
    >>> s.position = 3
    ...
    TraitError: position should be a 1-d sequence
    >>> s.position = (1,2,3,4)
    ...
    TraitError: position has incorrect length (expected 3 but found 4)

The following arguments to ``NumericalTrait`` are available:

-  ``ndim``: restrict the values to arrays with this number of dimension
-  ``shape``: restrict the values to arrays with this shape. If
   specified, ``ndim`` does not need to be given.
-  ``domain``: restrict the values to a particular domain - can be one
   of ``positive``, ``strictly-positive``, ``negative``,
   ``strictly-negative``, or a tuple representing a range of values.
-  ``default``: the default value to return, if not specified (defaults
   to ``None``)
-  ``convertible_to``: restrict the values to ones with units that would
   be convertible to a specific set of units (see section below)

Note that tuples and lists will automatically get converted to Numpy
arrays, if they are considered valid.

Physical units
--------------

While ``NumericalTrait`` can be used for plain scalars and Numpy arrays,
it can also be used for scalars and arrays which have associated units,
with support for three popular unit handling units:
`astropy.units <docs.astropy.org/en/stable/units/>`__,
`pint <http://pint.readthedocs.org/>`__, and
`quantities <https://pythonhosted.org/quantities/>`__.

To restrict a ``NumericalTrait`` to quantities with a certain type of
unit, use the ``convertible_to`` option. This option takes units from
any of these three unit packages, and will ensure that any value passed
has units equivalent (but not necessarily equal) to those specified with
the ``convertible_to`` option.

If the units passed to ``convertible_to`` are
`astropy.units <docs.astropy.org/en/stable/units/>`__ units, then any
value passed to the property should then be an
`astropy.units <docs.astropy.org/en/stable/units/>`__ quantity. If the
units passed to ``convertible_to`` are
`pint <http://pint.readthedocs.org/>`__ units, then any quantity passed
to the property should be a `pint <http://pint.readthedocs.org/>`__
property. And finally if the units passed to ``convertible_to`` are
`quantities <https://pythonhosted.org/quantities/>`__ units, then any
quantity passed to the property should be a
`quantities <https://pythonhosted.org/quantities/>`__ quantity.

astropy.units Quantity example
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The following example shows how to restrict the ``radius`` property to
be an `astropy.units <docs.astropy.org/en/stable/units/>`__ quantity in
units of length:

.. code:: python

    from astropy import units as u

    class Sphere(HasTraits):
        radius = NumericalTrait(convertible_to=u.m)

will then behave as follows:

.. code:: python

    >>> s = Sphere()
    >>> s.radius = 3. * u.m
    >>> s.radius = 4. * u.cm
    >>> s.radius = 4. * u.s
    ...
    TraitError: radius should be in units convertible to m

pint Quantity example
~~~~~~~~~~~~~~~~~~~~~

The following example shows how to restrict the ``radius`` property to
be a `pint <http://pint.readthedocs.org/>`__ quantity in units of
length:

.. code:: python

    from pint import UnitRegistry
    ureg = UnitRegistry()

    class Sphere(HasTraits):
        radius = NumericalTrait(convertible_to=ureg.m)

will then behave as follows:

.. code:: python

    >>> s = Sphere()
    >>> s.radius = 3. * ureg.m
    >>> s.radius = 4. * ureg.cm
    >>> s.radius = 4. * ureg.s
    ...
    TraitError: radius should be in units convertible to meter

quantities Quantity example
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Finally, the following example shows how to restrict the ``radius``
property to be a `quantities <https://pythonhosted.org/quantities/>`__
quantity in units of length:

.. code:: python

    import quantities as pq

    class Sphere(HasTraits):
        radius = NumericalTrait(convertible_to=pq.m)

will then behave as follows:

.. code:: python

    >>> s = Sphere()
    >>> s.radius = 3. * pq.m
    >>> s.radius = 4. * pq.cm
    >>> s.radius = 4. * pq.s
    ...
    TraitError: radius should be in units convertible to m

Planned support
---------------

-  Linking of properties (e.g. a property should have the same
   dimensions as another)

.. |Travis Build Status| image:: https://travis-ci.org/astrofrog/numtraits.svg?branch=master
   :target: https://travis-ci.org/astrofrog/numtraits
.. |Coverage Status| image:: https://coveralls.io/repos/astrofrog/numtraits/badge.svg
   :target: https://coveralls.io/r/astrofrog/numtraits