Merge pull request #306 from roocs/modernize

Modernize packaging

.flake8

@@ -0,0 +1,21 @@
+[flake8]
+exclude =
+	.eggs,
+	.git,
+	build,
+	docs,
+	tests/mini-esgf-data
+max-line-length = 88
+max-complexity = 12
+ignore =
+	C901
+	E203
+	E231
+	E266
+	E402
+	E501
+	F401
+	F403
+   	F405
+	W503
+	W504

.github/disabled/tag-testpypi-staging.yml

@@ -0,0 +1,32 @@
+name: Publish Python 🐍 distributions 📦 to TestPyPI
+
+on:
+  push:
+    tags:
+      - 'v*.*' # Push events to matching v*, i.e. v1.0, v20.15.10
+
+jobs:
+  deploy-testpypi:
+    name: Build and publish Python 🐍 distributions 📦 to TestPyPI
+    runs-on: ubuntu-latest
+    environment: staging
+    permissions:
+      # IMPORTANT: this permission is mandatory for trusted publishing
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python3
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.9"
+      - name: Install packaging libraries
+        run: |
+          python -m pip install flit
+      - name: Build a binary wheel and a source tarball
+        run: |
+          python -m flit build
+      - name: Publish distribution 📦 to Test PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          skip-existing: true

.github/workflows/prepare-release.yml

@@ -0,0 +1,25 @@
+name: Prepare Release
+
+on:
+  push:
+    tags:
+      - 'v*.*' # Push events to matching v*, i.e. v1.0, v20.15.10
+
+jobs:
+  release:
+    name: Create Release from tag
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v') && endsWith(github.ref, '.0')
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      - name: Create Release
+        uses: softprops/action-gh-release@v1
+        env:
+          # This token is provided by Actions, you do not need to create your own token
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          tag_name: ${{ github.ref }}
+          name: Release ${{ github.ref }}
+          draft: true
+          prerelease: false

.github/workflows/publish-pypi-production.yml

@@ -0,0 +1,29 @@
+name: Publish Python 🐍 distributions 📦 to PyPI
+
+on:
+  release:
+    types:
+      - published
+
+jobs:
+  build-n-publish-pypi:
+    name: Build and publish Python 🐍 distributions 📦 to PyPI
+    runs-on: ubuntu-latest
+    environment: production
+    permissions:
+      # IMPORTANT: this permission is mandatory for trusted publishing
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python3
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.9"
+      - name: Install packaging libraries
+        run: |
+          python -m pip install flit
+      - name: Build a binary wheel and a source tarball
+        run: |
+          python -m flit build
+      - name: Publish distribution 📦 to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

.pre-commit-config.yaml

@@ -11,13 +11,15 @@ repos:
     rev: v4.5.0
     hooks:
       - id: trailing-whitespace
-        exclude: setup.cfg
       - id: end-of-file-fixer
-        exclude: setup.cfg
       - id: check-toml
       - id: check-yaml
       - id: debug-statements
       - id: mixed-line-ending
+  - repo: https://github.com/pappasam/toml-sort
+    rev: v0.23.1
+    hooks:
+      - id: toml-sort-fix
   - repo: https://github.com/psf/black-pre-commit-mirror
     rev: 23.11.0
     hooks:
@@ -26,7 +28,7 @@ repos:
     rev: 6.1.0
     hooks:
       - id: flake8
-        args: [ '--config=setup.cfg' ]
+        args: [ '--config=.flake8' ]
   - repo: https://github.com/PyCQA/isort
     rev: 5.12.0
     hooks:
@@ -41,6 +43,11 @@ repos:
     hooks:
       - id: nbstripout
         files: ".ipynb"
+  - repo: https://github.com/keewis/blackdoc
+    rev: v0.3.9
+    hooks:
+      - id: blackdoc
+        additional_dependencies: [ 'black==23.11.0' ]
   - repo: https://github.com/python-jsonschema/check-jsonschema
     rev: 0.27.1
     hooks:

CONTRIBUTING.rst

@@ -145,6 +145,7 @@ Logging
 .. code-block:: python
 
     from loguru import logger
+
     logger.warning("This a warning message!")
 
 The mechanism for enabling log reporting in scripts/notebooks using ``loguru`` is as follows:
@@ -226,36 +227,39 @@ To run a subset of tests:
 Versioning
 ----------
 
+A reminder for the maintainers on how to bump the version.
+
 In order to update and release the library to PyPI, it's good to use a semantic versioning scheme.
+
 The method we use is as follows::
 
-    major.minor.patch-release
+    major.minor.patch
 
 **Major** releases denote major changes resulting in a stable API;
 
 **Minor** is to be used when adding a module, process or set of components;
 
 **Patch** should be used for bug fixes and optimizations;
 
-**Release** is a keyword used to specify the degree of production readiness (`beta` [, and optionally, `gamma`])
+Packaging/Deploying
+-------------------
 
-  An increment to the Major or Minor will reset the Release to `beta`. When a build is promoted above `beta` (ie: release-ready), it's a good idea to push this version towards PyPi.
+A reminder for the maintainers on how to deploy. This section is only relevant for maintainers when they are producing a new point release for the package.
 
-Deploying
----------
+#. Create a new branch from `master` (e.g. `prepare-release-v1.2.3`).
+#. Update the `HISTORY.rst` file to change the `unreleased` section to the current date.
+#. Create a pull request from your branch to `master`.
+#. Once the pull request is merged, create a new release on GitHub. On the main branch, run:
 
-A reminder for the maintainers on how to deploy.
-Make sure all your changes are committed (**including an entry in HISTORY.rst**).
-Then run:
+    .. code-block:: shell
 
-.. code-block:: shell
+        $ bump-my-version bump minor # In most cases, we will be releasing a minor version
+        $ git push
+        $ git push --tags
 
-    $ bumpversion <option> # possible options: major / minor / patch / release
-    $ git push
-    $ git push --tags
+    This will trigger the CI to build the package and upload it to TestPyPI. In order to upload to PyPI, this can be done by publishing a new version on GitHub. This will then trigger the workflow to build and upload the package to PyPI.
 
-Packaging
----------
+#. Once the release is published, it will go into a `staging` mode on Github Actions. Admins can then approve the release (an e-mail will be sent) and it will be published on PyPI.
 
 The Manual Approach
 ~~~~~~~~~~~~~~~~~~~
@@ -265,10 +269,10 @@ From the command line in your distribution, simply run the following from the cl
 .. code-block:: shell
 
     # To build the packages (sources and wheel)
-    $ flit build
+    $ python -m flit build
 
     # To upload to PyPI
-    $ flit publish
+    $ python -m flit publish dist/*
 
 The new version based off of the version checked out will now be available via pip ($ pip install clisops).
 

HISTORY.rst

@@ -19,6 +19,10 @@ Other Changes
 * GitHub Workflows for upstream dependencies are now examined a schedule or via `workflow_dispatch` (#243).
 * `black` steps are now called `lint` for clarity/inclusiveness of other linting hooks. (#243).
 * pre-commit hooks now include checks for TOML files, and for ReadTheDocs and GitHub Actions configuration files. (#243).
+* pre-commit hooks now include sorting of TOML file sections and running `black` on docstring Python examples. (#306).
+* `clisops` now uses GitHub Actions with environments for handling deployment via Trusted Publishing. (#306).
+* Documentation has been updated to reflect the new GitHub Actions CI/CD workflow. (#306).
+* `bump2version` has been replaced with `bump-my-version` for handling versioning. (#306).
 
 v0.11.0 (2023-08-22)
 --------------------

Makefile

@@ -51,11 +51,12 @@ clean-test: ## remove test and coverage artifacts
 	rm -fr .pytest_cache
 
 lint: ## check style with flake8
-	flake8 clisops tests
 	black --check clisops tests
+	isort --check-only clisops tests
+	flake8 --config=.flake8 clisops tests
 
 test: ## run tests quickly with the default Python
-	pytest
+	python -m pytest
 
 test-all: ## run tests on every Python version with tox
 	tox
@@ -74,18 +75,18 @@ docs: ## generate Sphinx HTML documentation, including API docs
 servedocs: docs ## compile the docs watching for changes
 	watchmedo shell-command -p '*.md' -c '$(MAKE) -C docs html' -R -D .
 
-release: dist ## package and upload a release
-	flit publish dist/*
-
 dist: clean ## builds source and wheel package
-	flit build
+	python -m flit build
 	ls -l dist
 
+release: dist ## package and upload a release
+	python -m flit publish dist/*
+
 install: clean ## install the package to the active Python's site-packages
-	python -m pip install .
+	python -m flit install
 
 develop: clean ## install the package and development dependencies in editable mode to the active Python's site-packages
-	python -m pip install --no-user --editable ".[dev]"
+	python -m flit install --no-user --symlink
 
-upstream: clean develop ## install the GitHub-based development branches of dependencies in editable mode to the active Python's site-packages
+upstream: develop ## install the GitHub-based development branches of dependencies in editable mode to the active Python's site-packages
 	python -m pip install --no-user --requirement requirements_upstream.txt

clisops/core/average.py

@@ -173,7 +173,9 @@ def average_over_dims(
         pr = xr.open_dataset(path_to_pr_file).pr
 
         # Average data array over latitude and longitude
-        prAvg = average_over_dims(pr, dims=['latitude', 'longitude'], ignore_undetected_dims=True)
+        prAvg = average_over_dims(
+            pr, dims=["latitude", "longitude"], ignore_undetected_dims=True
+        )
     """
 
     if not dims:
@@ -261,7 +263,7 @@ def average_time(
         pr = xr.open_dataset(path_to_pr_file).pr
 
         # Average data array over each month
-        prAvg = average_time(pr, freq='month')
+        prAvg = average_time(pr, freq="month")
     """
 
     if not freq: