api cleanup: remove ndsl/units.py (NOAA-GFDL#248)

The functions are all unused (I've checked pyFV3, pySHiELD, and pace)
and should be removed to keep API surface as small as possible. In the
future we envision NDSL to come with much more potent type checking for
units. Until then, if really needed, these functions can be implemented
trivially by dsl users.

Co-authored-by: Roman Cattaneo <1116746+romanc@users.noreply.github.com>

Author: romanc

ndsl/units.py

@@ -1,11 +1,33 @@
+import warnings
+
+
 def ensure_equal_units(units1: str, units2: str) -> None:
+    warnings.warn(
+        "`ensure_equal_units` is unused and usage is discouraged. The function "
+        "will be removed in the next version of NDSL.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
     if not units_are_equal(units1, units2):
         raise UnitsError(f"incompatible units {units1} and {units2}")
 
 
 def units_are_equal(units1: str, units2: str) -> bool:
+    warnings.warn(
+        "`units_are_equal` is unused and usage is discouraged. The function will "
+        "be removed in the next version of NDSL.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
     return units1.strip() == units2.strip()
 
 
 class UnitsError(Exception):
-    pass
+    def __init__(self, *args) -> None:
+        warnings.warn(
+            "`UnitsError` is unused and usage is discouraged. The class will be "
+            "removed in the next version of NDSL.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        super().__init__(*args)

tests/test_utils.py

@@ -0,0 +1,18 @@
+import pytest
+
+from ndsl.units import UnitsError, ensure_equal_units, units_are_equal
+
+
+def test_UnitsError_is_deprecated() -> None:
+    with pytest.deprecated_call():
+        UnitsError()
+
+
+def test_units_are_equal_is_deprecated() -> None:
+    with pytest.deprecated_call():
+        units_are_equal("asdf", "asdf")
+
+
+def test_ensure_equal_units_is_deprecated() -> None:
+    with pytest.deprecated_call():
+        ensure_equal_units("asdf", "asdf")