re-org package and define public api (#18)

haileyajohnson · web-flow · commit 5132752875ff · 2025-09-15T10:46:35.000-07:00
* fix uninitialized variable in mop_data

* fix 'start' dates interpreted as local time rather than utc

* re-org package and define public api

config docs

* fix pyproject to include utils package
diff --git a/cdippy/__init__.py b/cdippy/__init__.py
@@ -0,0 +1,5 @@
+# import public top-level modules
+from . import cdipnc, nchashes, ncstats, ndbc, plots, spectra, stndata
+
+# public API (i.e. "from cdippy import *")
+__all__ = ["cdipnc", "nchashes", "ncstats", "ndbc", "plots", "spectra", "stndata"]
diff --git a/cdippy/cdipnc.py b/cdippy/cdipnc.py
@@ -9,8 +9,11 @@
 from bisect import bisect_left, bisect_right
 
 import cdippy.ndbc as ndbc
-import cdippy.utils as cu
-import cdippy.url_utils as uu
+import cdippy.utils.utils as cu
+import cdippy.utils.urls as uu
+
+
+logger = logging.getLogger(__name__)
 
 
 logger = logging.getLogger(__name__)
diff --git a/cdippy/mobile.py b/cdippy/mobile.py
diff --git a/cdippy/mopdata.py b/cdippy/mopdata.py
@@ -2,8 +2,7 @@
 from bisect import bisect_left
 
 from cdippy.cdipnc import CDIPnc
-import cdippy.timestamp_utils as tsu
-import cdippy.utils as cu
+import cdippy.utils.utils as cu
 
 
 class MopData(CDIPnc):
@@ -290,17 +289,13 @@ def get_target_timespan(
         if i_b == last_idx or stamps[i_b] == target_timestamp:
             closest_idx = i_b
         elif i_b > 0:
-            closest_idx = tsu.get_closest_index(i_b - 1, i_b, stamps, target_timestamp)
+            closest_idx = cu.get_closest_index(i_b - 1, i_b, stamps, target_timestamp)
 
         # Now we have the closest index, find the intervals
 
         if closest_idx is not None:
-            interval = tsu.get_interval(stamps, closest_idx, num_target_records)
+            interval = cu.get_interval(stamps, closest_idx, num_target_records)
             return interval
 
         # If we get to here there's a problem
         return (None, None, None)
-
-
-if __name__ == "__main__":
-    pass
diff --git a/cdippy/nchashes.py b/cdippy/nchashes.py
@@ -1,5 +1,5 @@
-import cdippy.url_utils as uu
-import cdippy.utils as cu
+import cdippy.utils.urls as uu
+import cdippy.utils.utils as cu
 
 
 class NcHashes:
@@ -48,7 +48,3 @@ def save_new_hashes(self):
 
     def get_old_hashes(self):
         return cu.pkl_load(self.hash_pkl)
-
-
-if __name__ == "__main__":
-    pass
diff --git a/cdippy/ncstats.py b/cdippy/ncstats.py
@@ -116,12 +116,3 @@ def make_categorical_flag_var(self, flag_name: str):
             self.data[flag_name], categories=self.meta.get_flag_values(flag_name)
         )
         return cat.rename_categories(self.meta.get_flag_meanings(flag_name))
-
-
-if __name__ == "__main__":
-    # - Tests
-    def t1():
-        av = NcStats("100p1")
-        print(av.make_stats())
-
-    # t1()
diff --git a/cdippy/ndbc.py b/cdippy/ndbc.py
@@ -3,8 +3,8 @@
 import os
 from datetime import datetime, timezone
 
-import cdippy.url_utils as uu
-import cdippy.utils as cu
+import cdippy.utils.urls as uu
+import cdippy.utils.utils as cu
 
 sos_base = "https://sdf.ndbc.noaa.gov/sos/server.php"
 request = "request=DescribeSensor"
@@ -47,7 +47,3 @@ def get_wmo_id(
         return ids[stn]
     else:
         return None
-
-
-if __name__ == "__main__":
-    pass
diff --git a/cdippy/plots/__init__.py b/cdippy/plots/__init__.py
@@ -0,0 +1,3 @@
+from . import annual_hs_boxplot, compendium, sst_climatology
+
+__all__ = ["annual_hs_boxplot", "compendium", "sst_climatology"]
diff --git a/cdippy/plots/compendium.py b/cdippy/plots/compendium.py
@@ -1,5 +1,5 @@
-import cdippy.utils as ut
-import cdippy.plots.plot_utils as pu
+import cdippy.utils.utils as ut
+import cdippy.plots.utils as pu
 from datetime import datetime
 import numpy as np
 import calendar
diff --git a/cdippy/plots/sst_climatology.py b/cdippy/plots/sst_climatology.py
@@ -5,7 +5,7 @@
 
 
 # CDIP imports
-from cdippy import utils as ut
+from cdippy.utils import utils as ut
 from cdippy.stndata import StnData
 
 import matplotlib as mpl
diff --git a/cdippy/plots/utils.py b/cdippy/plots/utils.py
diff --git a/cdippy/stndata.py b/cdippy/stndata.py
@@ -14,8 +14,7 @@
     Active,
     ActiveXY,
 )
-import cdippy.timestamp_utils as tsu
-import cdippy.utils as cu
+import cdippy.utils.utils as cu
 import cdippy.spectra as sp
 
 
@@ -568,7 +567,7 @@ def get_target_timespan(
             if i_b == r_last_idx or r_stamps[i_b] == target_timestamp:
                 r_closest_idx = i_b
             elif i_b > 0:
-                r_closest_idx = tsu.get_closest_index(
+                r_closest_idx = cu.get_closest_index(
                     i_b - 1, i_b, r_stamps, target_timestamp
                 )
 
@@ -595,39 +594,35 @@ def get_target_timespan(
                 else:  # No realtime file
                     h_closest_idx = i_b
             else:  # Within middle of historic stamps
-                h_closest_idx = tsu.get_closest_index(
+                h_closest_idx = cu.get_closest_index(
                     i_b - 1, i_b, h_stamps, target_timestamp
                 )
 
         # Now we have the closest index, find the intervals
 
         if r_closest_idx is not None:
-            r_interval = tsu.get_interval(r_stamps, r_closest_idx, num_target_records)
+            r_interval = cu.get_interval(r_stamps, r_closest_idx, num_target_records)
             # If bound exceeded toward H and H exists, cacluate h_interval
             if r_interval[2] < 0 and h_ok:
                 if not h_last_idx:
                     h_stamps = self.historic.get_var(time_var)[:]
                     h_last_idx = len(h_stamps) - 1
-                h_interval = tsu.get_interval(
+                h_interval = cu.get_interval(
                     h_stamps, h_last_idx, num_target_records + r_closest_idx + 1
                 )
-                return tsu.combine_intervals(h_interval, r_interval)
+                return cu.combine_intervals(h_interval, r_interval)
             else:
                 return r_interval
         elif h_closest_idx is not None:
-            h_interval = tsu.get_interval(h_stamps, h_closest_idx, num_target_records)
+            h_interval = cu.get_interval(h_stamps, h_closest_idx, num_target_records)
             # If bound exceeded toward R and R exists, cacluate r_interval
             if h_interval[2] > 0 and r_ok:
-                r_interval = tsu.get_interval(
+                r_interval = cu.get_interval(
                     r_stamps, 0, num_target_records + h_closest_idx - h_last_idx - 1
                 )
-                return tsu.combine_intervals(h_interval, r_interval)
+                return cu.combine_intervals(h_interval, r_interval)
             else:
                 return h_interval
 
         # If we get to here there's a problem
         return (None, None, None)
-
-
-if __name__ == "__main__":
-    pass
diff --git a/cdippy/timestamp_utils.py b/cdippy/timestamp_utils.py
diff --git a/cdippy/utils/__init__.py b/cdippy/utils/__init__.py
diff --git a/cdippy/utils/location.py b/cdippy/utils/location.py
@@ -95,7 +95,3 @@ def get_direction(self, loc):
         direction = degrees(direction)
         direction = (direction + 360) % 360
         return direction
-
-
-if __name__ == "__main__":
-    pass
diff --git a/cdippy/utils/urls.py b/cdippy/utils/urls.py
diff --git a/cdippy/utils/utils.py b/cdippy/utils/utils.py
@@ -92,6 +92,41 @@ def datetime_to_tz(dt: datetime, tzname: str = "US/Pacific") -> datetime:
     return utc_dt.astimezone(tz)
 
 
+# Utils for srrays of timestamps
+
+
+def get_closest_index(i1: int, i2: int, T: list, t0: int) -> int:
+    """Returns the index i such that abs(T[i]-t0) is minimum for i1,i2"""
+    if abs(T[i1] - t0) <= abs(T[i2] - t0):
+        return i1
+    else:
+        return i2
+
+
+def get_interval(T: list, i: int, n: int) -> tuple:
+    """
+    Returns a 3-tuple (T[i], T[i+n], bounds_exceeded) where -inf < n < inf
+    and bounds_exceeded is -1 or +1 if exceeded left or right respectively.
+    """
+    bounds_exceeded = 0
+    last_T_idx = len(T) - 1
+
+    if i + n > last_T_idx:
+        bounds_exceeded = 1
+    elif i + n < 0:
+        bounds_exceeded = -1
+
+    if n >= 0:
+        return (T[i], T[min(i + n, last_T_idx)], bounds_exceeded)
+    else:
+        return (T[max(0, i + n)], T[i], bounds_exceeded)
+
+
+def combine_intervals(I1: tuple, I2: tuple) -> tuple:
+    """Return a 2-tuple of timestamps (I1[0], I2[1])."""
+    return (I1[0], I2[1])
+
+
 # Timespan
 class Timespan:
     """Class to handle timespans."""
diff --git a/docs/api.md b/docs/api.md
@@ -0,0 +1,18 @@
+# CDIPpy API reference
+
+::: cdippy.cdipnc
+
+
+::: cdippy.nchashes
+
+
+::: cdippy.ncstats
+
+
+::: cdippy.ndbc
+
+
+::: cdippy.spectra
+
+
+::: cdippy.stndata
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -2,13 +2,24 @@ site_name: CDIPpy Docs
 
 plugins:
   - macros
+  - search
+  - mkdocstrings:
+      handlers:
+        python:
+          options: 
+            show_source: true
+            heading_level: 2
+            show_root_heading: true
+            show_signature_annotations: true
+            docstring_style: google
 
 theme:
   name: readthedocs
 
 nav:
   - Home: index.md
   - Quick start: quickstart.md
+  - API reference: api.md
   - Users guide:
     - Installation: user_guide/index.md
     - Data access: user_guide/data_access.md
diff --git a/pyproject.toml b/pyproject.toml
@@ -9,6 +9,7 @@ authors = [
 ]
 requires-python = ">=3.11"
 dependencies = [
+  "matplotlib",
   "numpy",
   "netCDF4",
   "pandas",
@@ -20,8 +21,8 @@ keywords = ["oceanography", "waves", "buoy", "data"]
 Homepage = "https://cdip.ucsd.edu"
 Source = "https://github.com/cdipsw/CDIPpy"
 
-[tool.setuptools]
-packages = ["cdippy"]
+[tool.setuptools.packages.find]
+where = ["."]
 
 [build-system]
 requires = ["setuptools>=61.0"]
@@ -34,5 +35,10 @@ dev = [
     "flake8",
     "mkdocs",
     "mkdocs-macros-plugin",
+    "mkdocstrings[python]",
+    "mkdocs-material",
+    "mkdocstrings[python]",
+    "nbval",
     "pre-commit",
+    "pytest",
 ]
diff --git a/tests/test_cdippy.py b/tests/test_cdippy.py

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+from . import annual_hs_boxplot, compendium, sst_climatology`
	`2`	`+`
	`3`	`+__all__ = ["annual_hs_boxplot", "compendium", "sst_climatology"]`