Add pre-commit Git hooks to manage code style & QA during development (…

…#49) * Add pre-commit to dev env for code style & QA mgmt * Code & docs gardening by pre-commit This commit includes a series of changes made to improve readability and maintain coding hygiene. This includes minor reformatting of code blocks for easier comprehension and the removal of extraneous whitespace. In several places, overly long lines have been properly distributed over multiple lines, significantly improving readability. Furthermore, useless empty lines have been removed to keep the code compact and clean. * Integrate pre-commit for code style standardization The documentation has been updated to reflect the introduction of pre-commit, which will be used to maintain consistent code style and other aspects of quality assurance within the package. Git pre-commit hooks are now managed by pre-commit to ensure code conformity across various aspects including the code itself, documentation and overall repository quality. This includes the use of 'black' for code formatting.
UBC-MOAD · Dec 19, 2023 · ba2f6bb · ba2f6bb
1 parent cccae9f
commit ba2f6bb
Show file tree

Hide file tree

Showing 10 changed files with 64 additions and 44 deletions.
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -0,0 +1,21 @@
+# Git pre-commit hooks config file
+# Only takes effect if you have pre-commit installed in the env,
+# and after you run `pre-commit install`
+#
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+repos:
+  # Out-of-the-box hooks from the pre-commit org
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+  # Code formatting with black
+  - repo: https://github.com/psf/black
+    rev: 23.10.0
+    hooks:
+      - id: black
diff --git a/docs/Makefile b/docs/Makefile
@@ -17,4 +17,4 @@ help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/pkg_development.rst b/docs/pkg_development.rst
@@ -145,33 +145,35 @@ To deactivate the environment use:
 Coding Style
 ============
 
+.. image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white
+   :target: https://pre-commit.com
+   :alt: pre-commit
 .. image:: https://img.shields.io/badge/code%20style-black-000000.svg
     :target: https://black.readthedocs.io/en/stable/
     :alt: The uncompromising Python code formatter
 
-The :py:obj:`moad_tools` package uses the `black`_ code formatting tool to maintain
-a coding style that is very close to `PEP 8`_.
+The :py:obj:`moad_tools` package uses Git pre-commit hooks managed by `pre-commit`_
+to maintain consistent code style and and other aspects of code,
+docs,
+and repo QA.
 
-.. _black: https://black.readthedocs.io/en/stable/
-.. _PEP 8: https://peps.python.org/pep-0008/
+.. _pre-commit: https://pre-commit.com/
 
-:command:`black` is installed as part of the :ref:`moad_toolsDevelopmentEnvironment` setup.
-
-To run :command:`black` on the entire code-base use:
+To install the `pre-commit` hooks in a newly cloned repo,
+activate the conda development environment,
+and run :command:`pre-commit install`:
 
 .. code-block:: bash
 
     $ cd moad_tools
     $ conda activate moad-tools
-    (moad-tools)$ black ./
+    (moad-tools)$ pre-commit install
 
-in the repository root directory.
-The output looks something like::
+.. note::
+    You only need to install the hooks once immediately after you make a new clone of the
+    `moad_tools repository`_ and build your :ref:`moad_toolsDevelopmentEnvironment`.
 
-  reformatted /media/doug/warehouse/MOAD/moad_tools/docs/conf.py
-  reformatted /media/doug/warehouse/MOAD/moad_tools/moad_tools/observations.py
-  All done! ✨ 🍰 ✨
-  2 files reformatted, 5 files left unchanged.
+.. _moad_tools repository: https://github.com/UBC-MOAD/moad_tools
 
 
 .. _moad_toolsDocumentation:

diff --git a/envs/environment-dev.yaml b/envs/environment-dev.yaml
@@ -34,9 +34,10 @@ dependencies:
   - scipy
   - xarray
 
-  # For coding style, and pkg management
+  # For coding style, repo QA, and pkg management
   - black
   - hatch
+  - pre-commit
 
   # For unit tests
   - pytest

diff --git a/envs/requirements.txt b/envs/requirements.txt
@@ -18,6 +18,7 @@ branca==0.7.0
 Brotli==1.1.0
 certifi==2023.11.17
 cffi==1.16.0
+cfgv==3.3.1
 cftime==1.6.3
 charset-normalizer==3.3.2
 click==8.1.7
@@ -47,6 +48,7 @@ httpcore==1.0.2
 httpx==0.25.2
 hyperframe==6.0.1
 hyperlink==21.0.0
+identify==2.5.33
 idna==3.6
 imagesize==1.4.1
 importlib-metadata==7.0.0
@@ -67,6 +69,7 @@ munkres==1.1.4
 mypy-extensions==1.0.0
 netCDF4==1.6.5
 networkx==3.2.1
+nodeenv==1.8.0
 numexpr==2.8.7
 numpy==1.26.2
 packaging==23.2
@@ -78,6 +81,7 @@ pip==23.3.2
 platformdirs==4.1.0
 pluggy==1.3.0
 ply==3.11
+pre-commit==3.6.0
 ptyprocess==0.7.0
 py-cpuinfo==9.0.0
 pycparser==2.21
@@ -130,6 +134,7 @@ trove-classifiers==2023.11.29
 types-python-dateutil==2.8.19.14
 typing_extensions==4.9.0
 tzdata==2023.3
+ukkonen==1.0.1
 urllib3==2.1.0
 userpath==1.7.0
 virtualenv==20.25.0

diff --git a/moad_tools/midoss/geotiff_watermask.py b/moad_tools/midoss/geotiff_watermask.py
@@ -120,16 +120,16 @@ def write_numpy_file(watermask, numpy_file):
 
 @click.command(
     help="""
-    Calculate and store a Numpy array file containing a SalishSeaCast domain water mask for the 
-    AIS ship track density GeoTIFF files used to generate oil spill parameters for 
+    Calculate and store a Numpy array file containing a SalishSeaCast domain water mask for the
+    AIS ship track density GeoTIFF files used to generate oil spill parameters for
     Monte Carlo runs of MOHID.
 
     \b
-    Please see 
-    
+    Please see
+
     \b
     https://ubc-moad-tools.readthedocs.io/en/latest/moad_tools.html#moad_tools.midoss.geotiff_watermask.cli
-    
+
     for more information about arguments and options.
     """
 )
@@ -151,7 +151,7 @@ def write_numpy_file(watermask, numpy_file):
     type=click.Choice(("debug", "info", "warning", "error", "critical")),
     help="""
         Choose how much information you want to see about the progress of the calculation;
-        warning, error, and critical should be silent unless something bad goes wrong. 
+        warning, error, and critical should be silent unless something bad goes wrong.
     """,
 )
 def cli(geotiff_file, meshmask_file, numpy_file, verbosity):

diff --git a/moad_tools/midoss/hdf5_to_netcdf4.py b/moad_tools/midoss/hdf5_to_netcdf4.py
@@ -422,7 +422,7 @@ def _write_netcdf(ds, netcdf4_file, time_coord=True, scaled_vars=True):
     type=click.Choice(("debug", "info", "warning", "error", "critical")),
     help="""
         Choose how much information you want to see about the progress of the transformation;
-        warning, error, and critical should be silent unless something bad goes wrong. 
+        warning, error, and critical should be silent unless something bad goes wrong.
     """,
 )
 def cli(hdf5_file, netcdf4_file, verbosity):

diff --git a/moad_tools/midoss/random_oil_spills.py b/moad_tools/midoss/random_oil_spills.py
@@ -610,10 +610,8 @@ def get_oil_capacity(oil_attrs, vessel_length, vessel_type, random_generator):
             else 0
         )
     else:
-
         # ~~~ tankers ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
         if vessel_type == "tanker":
-
             bins = oil_attrs["vessel_attributes"]["tanker"]["length_bins"]
 
             if vessel_length >= max(max(bins)):
@@ -635,7 +633,6 @@ def get_oil_capacity(oil_attrs, vessel_length, vessel_type, random_generator):
 
         # ~~~ atbs ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
         elif vessel_type == "atb":
-
             atb_min_cargo = oil_attrs["vessel_attributes"]["atb"]["min_cargo"]
             atb_max_cargo = oil_attrs["vessel_attributes"]["atb"]["max_cargo"]
 
@@ -671,7 +668,6 @@ def get_oil_capacity(oil_attrs, vessel_length, vessel_type, random_generator):
 
         # ~~~ barges ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
         elif vessel_type == "barge":
-
             cargo_weight = oil_attrs["vessel_attributes"]["barge"][
                 "cargo_capacity_probability"
             ]
@@ -695,7 +691,6 @@ def get_oil_capacity(oil_attrs, vessel_length, vessel_type, random_generator):
         ###  Fuel capacities below this line are still being evaluated ###
         # ~~~ cargo ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
         elif vessel_type == "cargo":
-
             C = oil_attrs["vessel_attributes"]["cargo"]["fuel_fit_coefs"]
 
             fit_capacity = numpy.exp(C[1]) * numpy.exp(C[0] * vessel_length)
@@ -710,7 +705,6 @@ def get_oil_capacity(oil_attrs, vessel_length, vessel_type, random_generator):
 
         # ~~~ cruise ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
         elif vessel_type == "cruise":
-
             C = oil_attrs["vessel_attributes"]["cruise"]["fuel_fit_coefs"]
 
             fit_capacity = C[1] + C[0] * vessel_length
@@ -725,7 +719,6 @@ def get_oil_capacity(oil_attrs, vessel_length, vessel_type, random_generator):
 
         # ~~~ ferry ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
         elif vessel_type == "ferry":
-
             C = oil_attrs["vessel_attributes"]["ferry"]["fuel_fit_coefs"]
 
             fit_capacity = numpy.exp(C[1]) * numpy.exp(C[0] * vessel_length)
@@ -740,10 +733,9 @@ def get_oil_capacity(oil_attrs, vessel_length, vessel_type, random_generator):
 
         # ~~~ fishing ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
         elif vessel_type == "fishing":
-
             C = oil_attrs["vessel_attributes"]["fishing"]["fuel_fit_coefs"]
 
-            fit_capacity = C[2] + C[1] * vessel_length + C[0] * vessel_length ** 2
+            fit_capacity = C[2] + C[1] * vessel_length + C[0] * vessel_length**2
 
             cargo_capacity = 0
 
@@ -755,7 +747,6 @@ def get_oil_capacity(oil_attrs, vessel_length, vessel_type, random_generator):
 
         # ~~~ small pass ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
         elif vessel_type == "smallpass":
-
             C = oil_attrs["vessel_attributes"]["smallpass"]["fuel_fit_coefs"]
 
             fit_capacity = numpy.exp(C[1]) * numpy.exp(C[0] * vessel_length)
@@ -770,7 +761,6 @@ def get_oil_capacity(oil_attrs, vessel_length, vessel_type, random_generator):
 
         # ~~~ other ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
         elif vessel_type == "other":
-
             C = oil_attrs["vessel_attributes"]["other"]["fuel_fit_coefs"]
 
             fit_capacity = numpy.exp(C[1]) * numpy.exp(C[0] * vessel_length)
@@ -1592,18 +1582,18 @@ def write_csv_file(df, csv_file):
     help="""
     Calculate and store a CSV file containing parameters of a set of random oil spills
     to drive Monte Carlo runs of MOHID.
-    
+
     \b
-    Please see 
-    
+    Please see
+
     \b
     https://ubc-moad-tools.readthedocs.io/en/latest/moad_tools.html#moad_tools.midoss.random_oil_spills.cli
-    
+
     for more information about arguments and options, and
-    
+
     \b
     https://ubc-moad-tools.readthedocs.io/en/latest/moad_tools.html#processing-configuration-yaml-file
-    
+
     for details of the contents of the config file.
 """
 )
@@ -1622,7 +1612,7 @@ def write_csv_file(df, csv_file):
     type=click.Choice(("debug", "info", "warning", "error", "critical")),
     help="""
         Choose how much information you want to see about the progress of the calculation;
-        warning, error, and critical should be silent unless something bad goes wrong. 
+        warning, error, and critical should be silent unless something bad goes wrong.
     """,
 )
 def cli(n_spills, config_file, csv_file, verbosity):

diff --git a/tests/midoss/test_hdf5_to_netcdf4.py b/tests/midoss/test_hdf5_to_netcdf4.py
@@ -18,4 +18,3 @@
 
 """Unit tests for hdf5_to_netcdf4 module.
 """
-
diff --git a/tests/test_random_oil_spills.py b/tests/test_random_oil_spills.py
@@ -271,7 +271,9 @@ def test_get_lat_lon_indices(self, config_file):
         assert lon == pytest.approx(expected.lon)
         assert geotiff_x_index == expected.geotiff_x_index
         assert geotiff_y_index == expected.geotiff_y_index
-        shapely.testing.assert_geometries_equal(geotiff_bbox, expected.geotiff_bbox, tolerance=1e-6)
+        shapely.testing.assert_geometries_equal(
+            geotiff_bbox, expected.geotiff_bbox, tolerance=1e-6
+        )
 
 
 class TestGetVesselType:
@@ -725,7 +727,7 @@ def test_get_oil_type_atb_tanker_cargo_spill(
                       fraction_of_total: 0
                     other:
                       fraction_of_total: 0
-                    
+
                   tanker:
                     akns:
                       fraction_of_total: 0.5