Metadata-Version: 2.1
Name: unithandler
Version: 1.5.0
Summary: numeric mimic classes with units
Home-page: https://gitlab.com/larsyunker/unithandler
Author: Lars Yunker
License: MIT License
Project-URL: Documentation, https://unithandler.readthedocs.io/en/latest/index.html
Keywords: units,unit,float,int
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Operating System :: OS Independent
Classifier: Natural Language :: English
Requires-Python: >=3
Description-Content-Type: text/x-rst


unithandler
===========

This is a package for managing and interacting with units. The focus of
the package is to provide numeric type objects (e.g. ``float`` and ``int``\ )
which also have a ``unit`` attribute. The three core classes of this
package are ``Unit``\ , ``UnitFloat``\ , and ``UnitInt``.

While there are a variety of packages which support units, this
package focused on enabling straightforward implementation of units
without affecting Pythonic functionality of the numbers.

Additionally, the ``UnitFloat`` class was designed to represent the
magnitude of the stored value as best as possible with an appropriate
SI prefix. The value stored is scaled in its representation, but remains
locked to a specified prefix when operated upon. For example, ``0.005``
with the unit ``'L'`` would be represented as ``5 mL`` if printed, but will
behave as ``0.005`` for any numeric operations. This was implemented to
automatically keep track of the scale of a unit while allowing the user
to easily visualize the magnitude of the stored value.

Installation
------------

``unithandler`` is registered on PyPI.

.. code-block::

   pip install unithandler

Source files may be found in the `GitLab repository <https://gitlab.com/larsyunker/unithandler>`_.

The ``Unit`` class
----------------------

This class handles all unit-associated attributes and methods. The ``unit``
attribute returns an appropriately formatted unit (complete with
superscripts) as a string. Units are managed in dictionary format,
associating a power to each unit denoted. The class (and its subclasses)
are structured) so that the units may be easily modified using python
built-in multiplication and division operators (exactly as one would
track units with pen and paper).

The ``UnitFloat`` class
---------------------------

The ``UnitFloat`` class is a ``float``\ -like numeric class that has an
associated unit. The class has all defined Python magic methods, which
enable all appropriate modifications and operations on or by ``UnitFloat``
objects. Typically, the return of each magic method is another ``UnitFloat``
instance, but see the ``UnitFloat`` documentation for further details.

Known limitations
-----------------

Since this package is written entirely in Python, it does not provide
direct access to values as the true ``float`` and ``int`` would. As such,
some errors or unintended functionality may be encountered.

Currently ``numpy`` support is limited to basic ``ufunc`` implementation.
Unexpected behaviour may be encountered when performing ``numpy``
operations on ``UnitFloat`` or ``UnitInt``. We are working to implement full
support for vectorized operations on the numeric classes in this package.
To the best of our knowledge, the ``math`` package is fully supported, so
any numeric operations should be performed with that package while we
work to enable numpy support.


