WIP got rid of Units class

aospy/__init__.py

@@ -3,8 +3,6 @@
 from . import constants
 from .constants import Constant
 from . import utils
-from . import units
-from .units import Units
 from . import var
 from .var import Var
 from . import region
@@ -20,5 +18,5 @@
 from .automate import submit_mult_calcs
 from . import examples
 
-__all__ = ['Proj', 'Model', 'Run', 'Var', 'Units', 'Constant', 'Region',
-           'units', 'calc', 'constants', 'utils']
+__all__ = ['Proj', 'Model', 'Run', 'Var', 'Constant', 'Region',
+           'calc', 'constants', 'utils']

aospy/var.py

@@ -1,8 +1,6 @@
 """Funcionality for representing a physical variable in aospy."""
 import numpy as np
 
-from .units import Units
-
 
 class Var(object):
     """An object representing a physical quantity to be computed.
@@ -23,7 +21,7 @@ class Var(object):
         The variables passed to `func` to compute it
     func_input_dtype : {'DataArray', 'Dataset', 'numpy'}
         The datatype expected by `func` of its arguments
-    units : aospy.units.Units object
+    units : str
         The variable's physical units
     domain : str
         The physical domain of the variable, e.g. 'atmos', 'ocean', or 'land'
@@ -65,7 +63,7 @@ def __init__(self, name, alt_names=None, func=None, variables=None,
             will be passed to `self.function` in the same order.
         func_input_dtype : {None, 'DataArray', 'Dataset', 'numpy'}
             The datatype expected by `func` of its arguments
-        units : aospy.units.Units object
+        units : str
             The variable's physical units
         domain : str
             The physical domain of the variable, e.g. 'atmos', 'ocean', or
@@ -102,10 +100,7 @@ def __init__(self, name, alt_names=None, func=None, variables=None,
         assert func_input_dtype in (None, 'DataArray', 'Dataset', 'numpy')
         self.func_input_dtype = func_input_dtype
 
-        if not isinstance(units, Units):
-            self.units = Units(units=units)
-        else:
-            self.units = units
+        self.units = units
 
         if not description:
             if self.func.__doc__ is None:

docs/api.rst

@@ -122,6 +122,17 @@ Var
 
     .. automethod:: aospy.var.Var.__init__
 
+.. note::
+    While for the sake of tracking metadata we encourage users to add a ``units``
+    attribute to each of their :py:class:`Var` objects, these ``units`` attributes provide
+    nothing more than descriptive value.  One day we hope DataArrays
+    produced by loading or computing variables will be truly units-aware
+    (e.g. adding or subtracting two DataArrays with different units will lead to
+    an error, or multiplying two DataArrays will result in a DataArray with new units),
+    but we will leave that to upstream libraries to implement
+    (see `pydata/xarray#525 <https://github.com/pydata/xarray/issues/525>`_
+    for more discussion).
+
 Region
 ------
 
@@ -178,28 +189,16 @@ automate
     :members:
     :undoc-members:
 
-Units and Constants
-===================
+Constants
+=========
 
-aospy provides the classes :py:class:`Constant` and :py:class:`Units`
+aospy provides the classes :py:class:`Constant`
 for representing, respectively, physical constants (e.g. Earth's
-gravitational acceleration at the surface = 9.81 m/s^2) and physical
-units (e.g. meters per second squared in that example).
+gravitational acceleration at the surface = 9.81 m/s^2).
 
 aospy comes with several commonly used constants saved within the
 :py:class:`constants` module in which the :py:class:`Constant` class
-is also defined.  In contrast, there are no pre-defined
-:py:class:`Units` objects; the user must define any :py:class:`Units`
-objects they wish to use (e.g. to populate the :py:class:`units`
-attribute of their :py:class:`Var` objects).
-
-.. warning::
-
-   Whereas these baked-in :py:class:`Constant` objects are used by
-   aospy in various places, aospy currently does not actually use the
-   ``Var.units`` attribute during calculations or the
-   :py:class:`Units` class more generally; they are solely for the
-   user's own informational purposes.
+is also defined.
 
 constants
 ---------
@@ -208,21 +207,6 @@ constants
     :members:
     :undoc-members:
 
-units
------
-
-.. automodule:: aospy.units
-    :members:
-    :undoc-members:
-
-.. note::
-
-   There has been discussion of implementing units-handling upstream
-   within xarray (see `here
-   <https://github.com/pydata/xarray/issues/525>`_).  If that happens,
-   the :py:class:`Units` class will likely be deprecated and replaced
-   with the upstream version.
-
 Utilities
 =========
 

docs/whats-new.rst

@@ -3,10 +3,17 @@
 What's New
 ==========
 
-.. _whats-new.0.2.1:
+.. _whats-new.0.3:
 
-v0.2.1 (unreleased)
--------------------
+v0.3 (unreleased)
+-----------------
+
+Breaking Changes
+~~~~~~~~~~~~~~~~
+
+- Deprecate ``Units`` class, so now the ``units`` attribute of the
+  ``Var`` class is a string. (fixes :issue:`50` via :pull:`222`).
+  By `Micah Kim <https://github.com/micahkim23>`_.
 
 Documentation
 ~~~~~~~~~~~~~