Add support for Python 3.13 -- update environment files and GitHub Actions

.github/workflows/build-gcpy-environment.yml → .github/workflows/build-gcpy-environment-py312.yml

@@ -1,9 +1,10 @@
 ---
 #
-# GitHub action to build the GCPy production environment with micromamba
+# GitHub action to build the GCPy production environment
+# (for Python 3.12) with micromamba
 # See: https://github.com/marketplace/actions/setup-micromamba
 #
-name: build-gcpy-environment
+name: build-gcpy-environment-py312
 
 on:
   push:
@@ -17,15 +18,15 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
     steps:
       - name: Checkout the GCPy repository
         uses: actions/checkout@v4
       - name: Create "gcpy_env" environment
         uses: mamba-org/setup-micromamba@v1
         with:
           micromamba-version: 'latest'
-          environment-file: docs/environment_files/gcpy_environment.yml
+          environment-file: docs/environment_files/gcpy_environment_py312.yml
           init-shell: bash
           cache-environment: false
           generate-run-shell: true

.github/workflows/build-gcpy-environment-py313.yml

@@ -0,0 +1,39 @@
+---
+#
+# GitHub action to build the GCPy production environment
+# (for Python 3.12) with micromamba
+# See: https://github.com/marketplace/actions/setup-micromamba
+#
+name: build-gcpy-environment-py313
+
+on:
+  push:
+    branches: [ "main", "dev", "dependabot/*" ]
+  pull_request:
+    # The branches below must be a subset of the branches above
+    branches: [ "main", "dev" ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - name: Checkout the GCPy repository
+        uses: actions/checkout@v4
+      - name: Create "gcpy_env" environment
+        uses: mamba-org/setup-micromamba@v1
+        with:
+          micromamba-version: 'latest'
+          environment-file: docs/environment_files/gcpy_environment_py313.yml
+          init-shell: bash
+          cache-environment: false
+          generate-run-shell: true
+          post-cleanup: 'all'
+      - name: Test if "import gcpy" works
+        run: python -c "import gcpy"
+        shell: micromamba-shell {0}
+      - name: Test if we can create a plot
+        run: python -m gcpy.examples.plotting.create_test_plot
+        shell: micromamba-shell {0}

.github/workflows/build-rtd-environment.yml

@@ -17,7 +17,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
     steps:
       - name: Checkout the GCPy repository
         uses: actions/checkout@v4

CHANGELOG.md

@@ -5,8 +5,20 @@ All notable changes to GCPy will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased] - TBD
+### Added
+- Added GCPy environment file `docs/environment_files/gcpy_environment_py313.yml`, which is based on Python 3.13
+- Added GitHub Actions config file`.github/workflows/build-gcpy-environment-py313.yml`
+
 ### Changed
 - Updated paths to regridding weights in `benchmark/config/*.yml` and `examples/diagnostics/compare_diags.yml` files
+- Renamed `docs/environment_files/gcpy_environment.yml` to `gcpy_environment_py312.yml`
+- Updated symbolic link `environment.yml` to point to `docs/source/gcpy_environment_py312.yml`
+- Renamed GitHub Actions config file `.github/workflows/build-gcpy-environment.yml` to `build-gcpy-environment-py312.yml`
+- Updated package version information in ReadTheDocs documentation
+
+### Removed
+- Removed PyPi configuration file  `docs/environment_files/gcpy_requirements.txt` and symbolic link `./requirements.txt`
+- Removed Python 3.8 from the `python-version` list in `.github/workflows/*.yml` files
 
 ## [1.6.0] - 2025-01-29
 ### Added

docs/environment_files/README.md

@@ -1,13 +1,6 @@
 # Environment files
 
-This folder contains environment files that are used to install dependencies for GCPy and the ReadTheDocs documentation.
-
-NOTE: Most users will install GCPy with:
-
-```console
-$ pip install geoschem-gcpy
-```
-but GCPy developers may need to install the dependencies separately using the environment files in this folder.
+This folder contains environment files that are used to install dependencies for GCPy and the ReadTheDocs documentation. 
 
 ## Installing GCPy dependencies
 
@@ -16,17 +9,13 @@ but GCPy developers may need to install the dependencies separately using the en
 Use one of these commands to build a Mamba/Conda environment with all of the GCPy dependencies.
 
 ```console
-$ mamba env create -n gcpy_env --file=gcpy_environment.yml
+$ mamba env create -n gcpy_env --file=gcpy_environment_py312.yml   # If you wish to use Python 3.12
+$ mamba env create -n gcpy_env --file=gcpy_environment_py313.yml   # If you wish to use Python 3.13
 ```
 or
 ```console
-$ conda env create -n gcpy_env --file=gcpy_environment.yml
-```
-
-### With pip
-Or use this command to install the dependencies from PyPI:
-```console
-$ pip install -r gcpy_requirements.txt
+$ conda env create -n gcpy_env --file=gcpy_environment_py312.yml   # If you wish to use Python 3.12
+$ conda env create -n gcpy_env --file=gcpy_environment_py313.yml   # If you wish to use Python 3.13
 ```
 
 ## Installing ReadTheDocs dependencies

docs/environment_files/gcpy_environment_py312.yml

@@ -0,0 +1,40 @@
+---
+# ======================================================================
+# GCPy environment file (based on Python 3.12)
+#
+# If you wish to build a Mamba/Conda environment with the dependencies
+# for GCPy, use this command:
+#
+# $ mamba env create -n gcpy_env --file=/path/to/gcpy_environment_py312.yml
+# =====================================================================
+name: gcpy_env
+channels:
+  - conda-forge
+  - nodefaults
+dependencies:
+  - cartopy        ==0.23.0     # Geospatial data processing
+  - cf_xarray      ==0.9.1      # CF conventions for xarray
+  - dask           ==2024.5.2   # Parallel library; backend for xarray
+  - esmf           ==8.6.1      # Earth system modeling framework
+  - esmpy          ==8.6.1      # Python wrapper for ESMF
+  - gridspec       ==0.1.0      # Define Earth System Model grids
+  - ipython        ==8.25.0     # Interactive Python (used by Jupyter)
+  - joblib         ==1.4.2      # Parallelize python code
+  - jupyter        ==1.0.0      # Jupyter Notebook
+  - matplotlib     ==3.8.4      # Creates plots and visualizations
+  - netcdf4        ==1.6.5      # Python wrapper for netCDF
+  - netcdf-fortran ==4.6.1      # Python wrapper for netCDF-Fortran
+  - numpy          ==1.26.4     # Optimized mathematical functions
+  - pandas         ==2.2.2      # Tables/timeseries manipulation
+  - pip            ==24.0       # Install packages from PyPi
+  - pylint         ==3.2.2      # Python linter
+  - pyproj         ==3.6.1      # Python map projections library
+  - python         ==3.12.0     # Python language
+  - pypdf          ==4.2.0      # PDF utilities (bookmarks, etc.)
+  - requests       ==2.32.3     # HTTP library
+  - scipy          ==1.13.1     # Scientific python package
+  - sparselt       ==0.1.3      # Regridding earth system model data
+  - tabulate       ==0.9.0      # Pretty-printing for column data
+  - tk             ==8.6.13     # Tcl/tk library
+  - xarray         ==2024.5.0   # Read data from netCDF etc files
+  - xesmf          ==0.8.5      # Universal regridder

docs/environment_files/gcpy_environment_py313.yml

@@ -0,0 +1,48 @@
+---
+# ======================================================================
+# GCPy environment file (based on Python 3.13)
+#
+# If you wish to build a Mamba/Conda environment with the dependencies
+# for GCPy, use this command:
+#
+# $ mamba env create -n gcpy_env --file=/path/to/gcpy/environment.yml
+#
+# NOTE: This combination of packages may produce a warning
+#
+#   VersionWarning: ESMF installation version 8.8.0, ESMPy version 8.8.0b0
+#
+# that you can disable by adding this to your ~/.bashrc
+#
+#   export PYTHONWARNINGS="ignore"
+# =====================================================================
+name: gcpy_env
+channels:
+  - conda-forge
+  - nodefaults
+dependencies:
+  - cartopy        ==0.24.0     # Geospatial data processing
+  - cf_xarray      ==0.10.0     # CF conventions for xarray
+  - dask           ==2025.2.0   # Parallel library; backend for xarray
+  - esmf           ==8.8.0      # Earth System Model Framework
+  - esmpy          ==8.8.0      # Python wrapper for ESMF
+  - gridspec       ==0.1.0      # Define Earth System Model grids
+  - ipython        ==9.0.0      # Interactive Python (used by Jupyter)
+  - joblib         ==1.4.2      # Parallelize python code
+  - jupyter        ==1.1.1      # Jupyter Notebook
+  - matplotlib     ==3.10.1     # Creates plots and visualizations
+  - netcdf4        ==1.7.2      # Python wrapper for netCDF
+  - netcdf-fortran ==4.6.1      # Python wrapper for netCDF-Fortran
+  - numpy          ==2.1.3      # Optimized mathematical functions
+  - pandas         ==2.2.3      # Tables/timeseries manipulation
+  - pip            ==25.0.1     # Install packages from PyPi
+  - pylint         ==3.3.4      # Python linter
+  - pyproj         ==3.7.1      # Python map projections library
+  - python         ==3.13       # Python language
+  - pypdf          ==5.3.1      # PDF utilities (bookmarks, etc.)
+  - requests       ==2.32.3     # HTTP library
+  - scipy          ==1.15.2     # Scientific python package
+  - sparselt       ==0.1.3      # Regridding earth system model data
+  - tabulate       ==0.9.0      # Pretty-printing for column data
+  - tk             ==8.6.13     # Tcl/tk library
+  - xarray         ==2025.1.2   # Read data from netCDF etc files
+  - xesmf          ==0.8.8      # Universal regridder