rashdf 0.2.1__tar.gz → 0.3.0__tar.gz

{rashdf-0.2.1 → rashdf-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: rashdf
-Version: 0.2.1
+Version: 0.3.0
 Summary: Read data from HEC-RAS HDF files.
 Project-URL: repository, https://github.com/fema-ffrd/rashdf
 Classifier: Development Status :: 4 - Beta
@@ -16,20 +16,31 @@ License-File: LICENSE
 Requires-Dist: h5py
 Requires-Dist: geopandas
 Requires-Dist: pyarrow
+Requires-Dist: xarray
 Provides-Extra: dev
 Requires-Dist: pre-commit; extra == "dev"
 Requires-Dist: ruff; extra == "dev"
 Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: numpydoc; extra == "docs"
+Requires-Dist: sphinx_rtd_theme; extra == "docs"
 
 # rashdf
 [![CI](https://github.com/fema-ffrd/rashdf/actions/workflows/continuous-integration.yml/badge.svg?branch=main)](https://github.com/fema-ffrd/rashdf/actions/workflows/continuous-integration.yml)
 [![Release](https://github.com/fema-ffrd/rashdf/actions/workflows/release.yml/badge.svg)](https://github.com/fema-ffrd/rashdf/actions/workflows/release.yml)
 [![PyPI version](https://badge.fury.io/py/rashdf.svg)](https://badge.fury.io/py/rashdf)
+[![codecov](https://codecov.io/gh/fema-ffrd/rashdf/graph/badge.svg?token=CTIIONEHV1)](https://codecov.io/gh/fema-ffrd/rashdf)
+[![Documentation Status](https://readthedocs.org/projects/rashdf/badge/?version=latest)](https://rashdf.readthedocs.io/en/latest/?badge=latest)
 
 Read data from [HEC-RAS](https://www.hec.usace.army.mil/software/hec-ras/) [HDF](https://github.com/HDFGroup/hdf5) files.
 
 *Pronunciation: `raz·aitch·dee·eff`*
 
+## Documentation
+[rashdf on ReadTheDocs](http://rashdf.readthedocs.io/)
+
 ## Install
 ```bash
 $ pip install rashdf
@@ -120,9 +131,6 @@ Example: write structures GeoJSON to `stdout`:
 $ rashdf structures Potomac.p01.hdf
 ```
 
-## Documentation
-Coming soon.
-
 ## Developer Setup
 Create a virtual environment in the project directory:
 ```

{rashdf-0.2.1 → rashdf-0.3.0}/README.md

@@ -2,11 +2,16 @@
 [![CI](https://github.com/fema-ffrd/rashdf/actions/workflows/continuous-integration.yml/badge.svg?branch=main)](https://github.com/fema-ffrd/rashdf/actions/workflows/continuous-integration.yml)
 [![Release](https://github.com/fema-ffrd/rashdf/actions/workflows/release.yml/badge.svg)](https://github.com/fema-ffrd/rashdf/actions/workflows/release.yml)
 [![PyPI version](https://badge.fury.io/py/rashdf.svg)](https://badge.fury.io/py/rashdf)
+[![codecov](https://codecov.io/gh/fema-ffrd/rashdf/graph/badge.svg?token=CTIIONEHV1)](https://codecov.io/gh/fema-ffrd/rashdf)
+[![Documentation Status](https://readthedocs.org/projects/rashdf/badge/?version=latest)](https://rashdf.readthedocs.io/en/latest/?badge=latest)
 
 Read data from [HEC-RAS](https://www.hec.usace.army.mil/software/hec-ras/) [HDF](https://github.com/HDFGroup/hdf5) files.
 
 *Pronunciation: `raz·aitch·dee·eff`*
 
+## Documentation
+[rashdf on ReadTheDocs](http://rashdf.readthedocs.io/)
+
 ## Install
 ```bash
 $ pip install rashdf
@@ -97,9 +102,6 @@ Example: write structures GeoJSON to `stdout`:
 $ rashdf structures Potomac.p01.hdf
 ```
 
-## Documentation
-Coming soon.
-
 ## Developer Setup
 Create a virtual environment in the project directory:
 ```

{rashdf-0.2.1 → rashdf-0.3.0}/pyproject.toml

@@ -12,11 +12,12 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
 ]
-version = "0.2.1"
-dependencies = ["h5py", "geopandas", "pyarrow"]
+version = "0.3.0"
+dependencies = ["h5py", "geopandas", "pyarrow", "xarray"]
 
 [project.optional-dependencies]
-dev = ["pre-commit", "ruff", "pytest"]
+dev = ["pre-commit", "ruff", "pytest", "pytest-cov"]
+docs = ["sphinx", "numpydoc", "sphinx_rtd_theme"]
 
 [project.urls]
 repository = "https://github.com/fema-ffrd/rashdf"
@@ -28,10 +29,12 @@ rashdf = "cli:main"
 pythonpath = "src"
 testpaths = "tests"
 
-# TODO: linting for docstrings.
-# https://github.com/fema-ffrd/rashdf/issues/15
-# [tool.ruff.lint]
-# select = ["D"]
+[tool.ruff.lint]
+select = ["D"]
 
-# [tool.ruff.lint.pydocstyle]
-# convention = "numpy"
+[tool.ruff.lint.pydocstyle]
+convention = "numpy"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["D"]
+"docs/**" = ["D"]

{rashdf-0.2.1 → rashdf-0.3.0}/src/cli.py

@@ -1,4 +1,6 @@
-from rashdf import RasGeomHdf
+"""rashdf CLI."""
+
+from rashdf import RasGeomHdf, RasPlanHdf
 from rashdf.utils import df_datetimes_to_str
 
 import fiona
@@ -8,6 +10,7 @@ import argparse
 from ast import literal_eval
 from pathlib import Path
 import sys
+import re
 from typing import List, Optional
 import warnings
 
@@ -60,6 +63,7 @@ def fiona_supported_drivers() -> List[str]:
 
 
 def parse_args(args: str) -> argparse.Namespace:
+    """Parse command-line arguments."""
     parser = argparse.ArgumentParser(description="Extract data from HEC-RAS HDF files.")
     parser.add_argument(
         "--fiona-drivers",
@@ -100,21 +104,27 @@ def parse_args(args: str) -> argparse.Namespace:
 
 
 def export(args: argparse.Namespace) -> Optional[str]:
+    """Act on parsed arguments to extract data from HEC-RAS HDF files."""
     if args.fiona_drivers:
         for driver in fiona_supported_drivers():
             print(driver)
         return
-    if "://" in args.hdf_file:
-        geom_hdf = RasGeomHdf.open_uri(args.hdf_file)
+    if re.match(r"^.*\.p\d\d\.hdf$", args.hdf_file):
+        ras_hdf_class = RasPlanHdf
+    else:
+        ras_hdf_class = RasGeomHdf
+    if re.match(r"^\w+://", args.hdf_file):
+        geom_hdf = ras_hdf_class.open_uri(args.hdf_file)
     else:
-        geom_hdf = RasGeomHdf(args.hdf_file)
+        geom_hdf = ras_hdf_class(args.hdf_file)
     func = getattr(geom_hdf, args.func)
     gdf: GeoDataFrame = func()
     kwargs = literal_eval(args.kwargs) if args.kwargs else {}
     if args.to_crs:
         gdf = gdf.to_crs(args.to_crs)
     if not args.output_file:
-        # convert any datetime columns to strings
+        # If an output file path isn't provided, write the GeoDataFrame to stdout
+        # as GeoJSON. Convert any datetime columns to strings.
         gdf = df_datetimes_to_str(gdf)
         with warnings.catch_warnings():
             # Squash warnings about converting the CRS to OGC URN format.
@@ -139,14 +149,15 @@ def export(args: argparse.Namespace) -> Optional[str]:
     output_file_path = Path(args.output_file)
     output_file_ext = output_file_path.suffix
     if output_file_ext not in [".gpkg"]:
-        # unless the user specifies a format that supports datetime,
-        # convert any datetime columns to string
-        # TODO: besides Geopackage, which of the standard Fiona formats allow datetime?
+        # Unless the user specifies a format that supports datetime,
+        # convert any datetime columns to string.
+        # TODO: besides Geopackage, which of the standard Fiona drivers allow datetime?
         gdf = df_datetimes_to_str(gdf)
     gdf.to_file(args.output_file, **kwargs)
 
 
 def main():
+    """Entry point for the rashdf CLI."""
     args = parse_args(sys.argv[1:])
     export(args)
 

{rashdf-0.2.1 → rashdf-0.3.0}/src/rashdf/__init__.py

@@ -1,3 +1,5 @@
+"""rashdf package."""
+
 from .base import RasHdf
 from .geom import RasGeomHdf
 from .plan import RasPlanHdf

{rashdf-0.2.1 → rashdf-0.3.0}/src/rashdf/base.py

@@ -1,3 +1,5 @@
+"""Base class for reading HEC-RAS HDF files."""
+
 import h5py
 from .utils import hdf5_attrs_to_dict
 from typing import Dict
@@ -68,7 +70,7 @@ class RasHdf(h5py.File):
         return {}
 
     def get_root_attrs(self):
-        """Returns attributes at root level of HEC-RAS HDF file.
+        """Return attributes at root level of HEC-RAS HDF file.
 
         Returns
         -------

{rashdf-0.2.1 → rashdf-0.3.0}/src/rashdf/geom.py

@@ -1,3 +1,5 @@
+"""HEC-RAS Geometry HDF class."""
+
 from .base import RasHdf
 from .utils import (
     convert_ras_hdf_string,
@@ -16,27 +18,37 @@ from shapely import (
     LineString,
     MultiLineString,
     MultiPolygon,
-    polygonize,
+    polygonize_full,
 )
 
-from typing import List, Optional
+from typing import Dict, List, Optional
 
 
 class RasGeomHdf(RasHdf):
+    """HEC-RAS Geometry HDF class."""
+
     GEOM_PATH = "Geometry"
     GEOM_STRUCTURES_PATH = f"{GEOM_PATH}/Structures"
     FLOW_AREA_2D_PATH = f"{GEOM_PATH}/2D Flow Areas"
 
     def __init__(self, name: str, **kwargs):
+        """Open a HEC-RAS Geometry HDF file.
+
+        Parameters
+        ----------
+        name : str
+            The path to the RAS Geometry HDF file.
+        kwargs : dict
+            Additional keyword arguments to pass to h5py.File
+        """
         super().__init__(name, **kwargs)
 
     def projection(self) -> Optional[CRS]:
-        """Return the projection of the RAS geometry as a
-        pyproj.CRS object.
+        """Return the projection of the RAS geometry as a pyproj.CRS object.
 
         Returns
         -------
-        CRS
+        pyproj.CRS or None
             The projection of the RAS geometry.
         """
         proj_wkt = self.attrs.get("Projection")
@@ -47,20 +59,19 @@ class RasGeomHdf(RasHdf):
         return CRS.from_wkt(proj_wkt)
 
     def mesh_area_names(self) -> List[str]:
-        """Return a list of the 2D mesh area names of
-        the RAS geometry.
+        """Return a list of the 2D mesh area names of the RAS geometry.
 
         Returns
         -------
-        list
+        List[str]
             A list of the 2D mesh area names (str) within the RAS geometry if 2D areas exist.
         """
-        if "/Geometry/2D Flow Areas" not in self:
+        if self.FLOW_AREA_2D_PATH not in self:
             return list()
         return list(
             [
                 convert_ras_hdf_string(n)
-                for n in self["/Geometry/2D Flow Areas/Attributes"][()]["Name"]
+                for n in self[f"{self.FLOW_AREA_2D_PATH}/Attributes"][()]["Name"]
             ]
         )
 
@@ -76,7 +87,7 @@ class RasGeomHdf(RasHdf):
         if not mesh_area_names:
             return GeoDataFrame()
         mesh_area_polygons = [
-            Polygon(self[f"/Geometry/2D Flow Areas/{n}/Perimeter"][()])
+            Polygon(self[f"{self.FLOW_AREA_2D_PATH}/{n}/Perimeter"][()])
             for n in mesh_area_names
         ]
         return GeoDataFrame(
@@ -101,13 +112,13 @@ class RasGeomHdf(RasHdf):
 
         cell_dict = {"mesh_name": [], "cell_id": [], "geometry": []}
         for i, mesh_name in enumerate(mesh_area_names):
-            cell_cnt = self["/Geometry/2D Flow Areas/Cell Info"][()][i][1]
+            cell_cnt = self[f"{self.FLOW_AREA_2D_PATH}/Cell Info"][()][i][1]
             cell_ids = list(range(cell_cnt))
             cell_face_info = self[
-                f"/Geometry/2D Flow Areas/{mesh_name}/Cells Face and Orientation Info"
+                f"{self.FLOW_AREA_2D_PATH}/{mesh_name}/Cells Face and Orientation Info"
             ][()]
             cell_face_values = self[
-                f"/Geometry/2D Flow Areas/{mesh_name}/Cells Face and Orientation Values"
+                f"{self.FLOW_AREA_2D_PATH}/{mesh_name}/Cells Face and Orientation Values"
             ][()][:, 0]
             face_id_lists = list(
                 np.vectorize(
@@ -128,13 +139,19 @@ class RasGeomHdf(RasHdf):
             cell_dict["cell_id"] += cell_ids
             cell_dict["geometry"] += list(
                 np.vectorize(
-                    lambda face_id_list: polygonize(
-                        np.ravel(
-                            mesh_faces[
-                                np.array(face_id_list.strip("[]").split()).astype(int)
-                            ]
+                    lambda face_id_list: (
+                        lambda geom_col: Polygon((geom_col[0] or geom_col[3]).geoms[0])
+                    )(
+                        polygonize_full(
+                            np.ravel(
+                                mesh_faces[
+                                    np.array(face_id_list.strip("[]").split()).astype(
+                                        int
+                                    )
+                                ]
+                            )
                         )
-                    ).geoms[0]
+                    )
                 )(face_id_lists)
             )
         return GeoDataFrame(cell_dict, geometry="geometry", crs=self.projection())
@@ -152,8 +169,8 @@ class RasGeomHdf(RasHdf):
             return GeoDataFrame()
         pnt_dict = {"mesh_name": [], "cell_id": [], "geometry": []}
         for i, mesh_name in enumerate(mesh_area_names):
-            starting_row, count = self["/Geometry/2D Flow Areas/Cell Info"][()][i]
-            cell_pnt_coords = self["/Geometry/2D Flow Areas/Cell Points"][()][
+            starting_row, count = self[f"{self.FLOW_AREA_2D_PATH}/Cell Info"][()][i]
+            cell_pnt_coords = self[f"{self.FLOW_AREA_2D_PATH}/Cell Points"][()][
                 starting_row : starting_row + count
             ]
             pnt_dict["mesh_name"] += [mesh_name] * cell_pnt_coords.shape[0]
@@ -179,16 +196,16 @@ class RasGeomHdf(RasHdf):
         face_dict = {"mesh_name": [], "face_id": [], "geometry": []}
         for mesh_name in mesh_area_names:
             facepoints_index = self[
-                f"/Geometry/2D Flow Areas/{mesh_name}/Faces FacePoint Indexes"
+                f"{self.FLOW_AREA_2D_PATH}/{mesh_name}/Faces FacePoint Indexes"
             ][()]
             facepoints_coordinates = self[
-                f"/Geometry/2D Flow Areas/{mesh_name}/FacePoints Coordinate"
+                f"{self.FLOW_AREA_2D_PATH}/{mesh_name}/FacePoints Coordinate"
             ][()]
             faces_perimeter_info = self[
-                f"/Geometry/2D Flow Areas/{mesh_name}/Faces Perimeter Info"
+                f"{self.FLOW_AREA_2D_PATH}/{mesh_name}/Faces Perimeter Info"
             ][()]
             faces_perimeter_values = self[
-                f"/Geometry/2D Flow Areas/{mesh_name}/Faces Perimeter Values"
+                f"{self.FLOW_AREA_2D_PATH}/{mesh_name}/Faces Perimeter Values"
             ][()]
             face_id = -1
             for pnt_a_index, pnt_b_index in facepoints_index:
@@ -206,8 +223,8 @@ class RasGeomHdf(RasHdf):
                 face_dict["geometry"].append(LineString(coordinates))
         return GeoDataFrame(face_dict, geometry="geometry", crs=self.projection())
 
-    def get_geom_attrs(self):
-        """Returns base geometry attributes from a HEC-RAS HDF file.
+    def get_geom_attrs(self) -> Dict:
+        """Return base geometry attributes from a HEC-RAS HDF file.
 
         Returns
         -------
@@ -216,8 +233,8 @@ class RasGeomHdf(RasHdf):
         """
         return self.get_attrs(self.GEOM_PATH)
 
-    def get_geom_structures_attrs(self):
-        """Returns geometry structures attributes from a HEC-RAS HDF file.
+    def get_geom_structures_attrs(self) -> Dict:
+        """Return geometry structures attributes from a HEC-RAS HDF file.
 
         Returns
         -------
@@ -226,8 +243,8 @@ class RasGeomHdf(RasHdf):
         """
         return self.get_attrs(self.GEOM_STRUCTURES_PATH)
 
-    def get_geom_2d_flow_area_attrs(self):
-        """Returns geometry 2d flow area attributes from a HEC-RAS HDF file.
+    def get_geom_2d_flow_area_attrs(self) -> Dict:
+        """Return geometry 2d flow area attributes from a HEC-RAS HDF file.
 
         Returns
         -------
@@ -373,6 +390,11 @@ class RasGeomHdf(RasHdf):
     def structures(self, datetime_to_str: bool = False) -> GeoDataFrame:
         """Return the model structures.
 
+        Parameters
+        ----------
+        datetime_to_str : bool, optional
+            If True, convert datetime values to string format (default: False).
+
         Returns
         -------
         GeoDataFrame
@@ -419,50 +441,50 @@ class RasGeomHdf(RasHdf):
             )
         return struct_gdf
 
-    def connections(self) -> GeoDataFrame:
+    def connections(self) -> GeoDataFrame:  # noqa D102
         raise NotImplementedError
 
-    def ic_points(self) -> GeoDataFrame:
+    def ic_points(self) -> GeoDataFrame:  # noqa D102
         raise NotImplementedError
 
-    def reference_lines(self) -> GeoDataFrame:
+    def reference_lines(self) -> GeoDataFrame:  # noqa D102
         raise NotImplementedError
 
-    def reference_points(self) -> GeoDataFrame:
+    def reference_points(self) -> GeoDataFrame:  # noqa D102
         raise NotImplementedError
 
-    def pump_stations(self) -> GeoDataFrame:
+    def pump_stations(self) -> GeoDataFrame:  # noqa D102
         raise NotImplementedError
 
-    def mannings_calibration_regions(self) -> GeoDataFrame:
+    def mannings_calibration_regions(self) -> GeoDataFrame:  # noqa D102
         raise NotImplementedError
 
-    def classification_polygons(self) -> GeoDataFrame:
+    def classification_polygons(self) -> GeoDataFrame:  # noqa D102
         raise NotImplementedError
 
-    def terrain_modifications(self) -> GeoDataFrame:
+    def terrain_modifications(self) -> GeoDataFrame:  # noqa D102
         raise NotImplementedError
 
-    def cross_sections(self) -> GeoDataFrame:
+    def cross_sections(self) -> GeoDataFrame:  # noqa D102
         raise NotImplementedError
 
-    def river_reaches(self) -> GeoDataFrame:
+    def river_reaches(self) -> GeoDataFrame:  # noqa D102
         raise NotImplementedError
 
-    def flowpaths(self) -> GeoDataFrame:
+    def flowpaths(self) -> GeoDataFrame:  # noqa D102
         raise NotImplementedError
 
-    def bank_points(self) -> GeoDataFrame:
+    def bank_points(self) -> GeoDataFrame:  # noqa D102
         raise NotImplementedError
 
-    def bank_lines(self) -> GeoDataFrame:
+    def bank_lines(self) -> GeoDataFrame:  # noqa D102
         raise NotImplementedError
 
-    def ineffective_areas(self) -> GeoDataFrame:
+    def ineffective_areas(self) -> GeoDataFrame:  # noqa D102
         raise NotImplementedError
 
-    def ineffective_points(self) -> GeoDataFrame:
+    def ineffective_points(self) -> GeoDataFrame:  # noqa D102
         raise NotImplementedError
 
-    def blocked_obstructions(self) -> GeoDataFrame:
+    def blocked_obstructions(self) -> GeoDataFrame:  # noqa D102
         raise NotImplementedError