Add type stubs to the Python module

.github/workflows/main.yml

@@ -436,6 +436,93 @@ jobs:
         files: ./coverage.xml,./build/pycov.xml,./interfaces/dotnet/coverage.cobertura.xml,./test/matlab_experimental/matlabCoverage.xml
         fail_ci_if_error: true
 
+  type-checking:
+    name: Verify typing correctness and coverage of the public Python API
+    runs-on: ubuntu-24.04
+    timeout-minutes: 20
+    needs: ["ubuntu-multiple-pythons"]
+    strategy:
+      fail-fast: false
+    steps:
+      # Only need pyproject.toml for type checker settings
+      - name: Checkout the repository
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Setup Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.10"
+          architecture: x64
+      - name: Install Apt dependencies
+        run: |
+          sudo apt update
+          sudo apt install graphviz libhdf5-dev libfmt-dev libopenblas-openmp-dev
+      - name: Download the wheel artifact
+        uses: actions/download-artifact@v5
+        with:
+          name: cantera-wheel-3.10-ubuntu-24.04
+          path: dist
+      - name: Download the Cantera shared library (.so)
+        uses: actions/download-artifact@v5
+        with:
+          name: libcantera_shared-ubuntu-24.04.so
+          path: build/lib
+      - name: Set up environment
+        run: |
+          ln -s libcantera_shared.so build/lib/libcantera_shared.so.3
+          echo "LD_LIBRARY_PATH=build/lib" >> $GITHUB_ENV
+          mkdir -p type_check
+      - name: Upgrade pip
+        run: python3 -m pip install -U pip setuptools wheel
+      - name: Install Python dependencies
+        run: |
+          python3 -m pip install numpy ruamel.yaml pandas pandas-stubs \
+            scipy pint graphviz typing_extensions pyright mypy[reports]
+          python3 -m pip install --pre --no-index --find-links dist cantera
+      - name: Check static type correctness with mypy
+        run: |
+          mypy --config-file interfaces/cython/pyproject.toml \
+            -p cantera | tee type_check/mypy_check.txt
+      - name: Generate coverage report with mypy
+        if: failure() || success()
+        run: |
+          mypy --config-file interfaces/cython/pyproject.toml \
+            --cobertura-xml-report type_check/ interfaces/cython/cantera
+      - name: Summarize the report
+        uses: danielpalme/ReportGenerator-GitHub-Action@9870ed167742d546b99962ff815fcc1098355ed8 # v5.4.17
+        with:
+          reports: './type_check/cobertura.xml'
+          targetdir: './type_check'
+          reporttypes: 'MarkdownSummaryGithub'
+      - run: cat ./type_check/SummaryGithub.md >> $GITHUB_STEP_SUMMARY
+        shell: bash
+      - name: Generate coverage report with pyright
+        if: failure() || success()
+        run: |
+          pyright --ignoreexternal --verifytypes cantera \
+            | tee type_check/pyright_verifytypes.txt
+      - name: Check type correctness against runtime with stubtest
+        if: failure() || success()
+        run: |
+          stubtest --mypy-config-file interfaces/cython/pyproject.toml \
+            --ignore-disjoint-bases --allowlist interfaces/cython/.mypyignore \
+            --concise cantera | tee type_check/stubtest_concise.txt
+          stubtest --mypy-config-file interfaces/cython/pyproject.toml \
+            --ignore-disjoint-bases --allowlist interfaces/cython/.mypyignore \
+            cantera >> type_check/stubtest_detailed.txt
+          stubtest --mypy-config-file interfaces/cython/pyproject.toml \
+            --ignore-disjoint-bases --allowlist interfaces/cython/.mypyignore \
+            --generate-allowlist cantera >> type_check/stubtest_allowlist.txt
+      - name: Archive Python API type checking results
+        if: failure() || success()
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-type-check-reports
+          path: type_check/*
+          retention-days: 5
+
   docs:
     name: Build docs
     runs-on: ubuntu-latest
@@ -885,7 +972,7 @@ jobs:
       - name: Install Python dependencies
         run: |
           python -m pip install -U pip setuptools wheel
-          python -m pip install 'scons<4.4.0' pypiwin32 numpy ruamel.yaml cython!=3.1.2 pandas graphviz pytest pytest-xdist pytest-github-actions-annotate-failures
+          python -m pip install 'scons<4.4.0' pypiwin32 numpy ruamel.yaml cython!=3.1.2 pandas graphviz pytest pytest-xdist pytest-github-actions-annotate-failures typing_extensions
       - name: Restore Boost cache
         uses: actions/cache@v4
         id: cache-boost

AUTHORS.md

@@ -23,6 +23,7 @@ update, please report on Cantera's
 - **Parker Clayton** [@parkerclayton](https://github.com/parkerclayton)
 - **Ryan Crisanti** [@rcrisanti](https://github.com/rcrisanti)
 - **Nicholas Curtis** [@arghdos](https://github.com/arghdos)
+- **Tim Dawson** [@TimothyEDawson](https://github.com/TimothyEDawson) - CFD Research Corporation
 - **Steven DeCaluwe** [@decaluwe](https://github.com/decaluwe) - Colorado School of Mines
 - **Vishesh Devgan** [@vdevgan](https://github.com/vdevgan)
 - **Matthias Diener** [@matthiasdiener](https://github.com/matthiasdiener) - University of Illinois at Urbana-Champaign

interfaces/cython/.mypyignore

@@ -0,0 +1,71 @@
+cantera._types.*
+
+# Exclude ArgumentParser, Path, and various types
+((_|\w)+\.)+_?(ArgumentParser|Path|Any|Iterable|Sequence|TypedDict|TypeVar).*
+
+# Exclude all dunder methods
+# cantera\.((_|\w)+\.)+__[a-zA-Z0-9_]*__
+
+# Exclude all dunder methods except for __init__
+# cantera\.((_|\w)+\.)+__(?!init__$)[a-zA-Z0-9_]*__
+
+# Exclude specific dunder methods
+cantera\.((_|\w)+\.)+__(.*cython|test|pyx_capi|mutable_keys|readonly_keys)__
+
+# Current output of stubtest --generate-allowlist
+cantera.Arrhenius.__init__
+cantera.ArrheniusRate.__init__
+cantera.BlowersMaselRate.__init__
+cantera.ConnectorNode.__init__
+cantera.ElectronCollisionPlasmaRate.__init__
+cantera.ExtensibleRate.__init__
+cantera.FalloffRate.__init__
+cantera.GasTransportData.__init__
+cantera.InterfaceArrheniusRate.__init__
+cantera.InterfaceBlowersMaselRate.__init__
+cantera.Mixture.__call__
+cantera.Mixture.__init__
+cantera.PlogRate.__init__
+cantera.Quantity.clear_user_data
+cantera.Quantity.clear_user_header
+cantera.Quantity.reactions
+cantera.Quantity.update_electron_energy_distribution
+cantera.Reaction.__init__
+cantera.ReactionPathDiagram.__init__
+cantera.SolutionArray.__init__
+cantera.SolutionArray.reactions
+cantera.SolutionArrayBase.__init__
+cantera.SpeciesThermo.__init__
+cantera.StickingBlowersMaselRate.__init__
+cantera.SystemJacobian.__init__
+cantera.ThirdBody.__init__
+cantera.TwoTempPlasmaRate.__init__
+cantera.ck2yaml.ChemicallyActivated.__init__
+cantera.ck2yaml.Falloff.__init__
+cantera.composite.Quantity.clear_user_data
+cantera.composite.Quantity.clear_user_header
+cantera.composite.Quantity.reactions
+cantera.composite.Quantity.update_electron_energy_distribution
+cantera.composite.SolutionArray.__init__
+cantera.composite.SolutionArray.reactions
+cantera.jacobians.SystemJacobian.__init__
+cantera.mixture.Mixture.__call__
+cantera.mixture.Mixture.__init__
+cantera.reaction.Arrhenius.__init__
+cantera.reaction.ArrheniusRate.__init__
+cantera.reaction.BlowersMaselRate.__init__
+cantera.reaction.ElectronCollisionPlasmaRate.__init__
+cantera.reaction.ExtensibleRate.__init__
+cantera.reaction.FalloffRate.__init__
+cantera.reaction.InterfaceArrheniusRate.__init__
+cantera.reaction.InterfaceBlowersMaselRate.__init__
+cantera.reaction.PlogRate.__init__
+cantera.reaction.Reaction.__init__
+cantera.reaction.StickingBlowersMaselRate.__init__
+cantera.reaction.ThirdBody.__init__
+cantera.reaction.TwoTempPlasmaRate.__init__
+cantera.reactionpath.ReactionPathDiagram.__init__
+cantera.reactor.ConnectorNode.__init__
+cantera.solutionbase.SolutionArrayBase.__init__
+cantera.speciesthermo.SpeciesThermo.__init__
+cantera.transport.GasTransportData.__init__

interfaces/cython/SConscript

@@ -22,7 +22,6 @@ if localenv["example_data"]:
             localenv.Command(f"cantera/data/example_data/{yaml.name}", yaml.abspath,
                              Copy("$TARGET", "$SOURCE"))))
 
-
 # Install Python samples
 install(localenv.RecursiveInstall, "$inst_sampledir/python", "#samples/python")
 
@@ -120,9 +119,10 @@ if env['OS'] == 'Windows':
 else:
     localenv.Depends(ext, localenv['cantera_shlib'])
 
-for f in (multi_glob(localenv, 'cantera', 'py') +
-          multi_glob(localenv, 'cantera/*', 'py')):
+for f in (multi_glob(localenv, 'cantera', 'py', 'pyi') +
+          multi_glob(localenv, 'cantera/*', 'py', 'pyi')):
     localenv.Depends(mod, f)
+localenv.Depends(mod, 'cantera/py.typed')
 
 units = localenv.UnitsInterfaceBuilder(
     "cantera/with_units/solution.py",

interfaces/cython/cantera/__init__.pyi

@@ -0,0 +1,28 @@
+# This file is part of Cantera. See License.txt in the top-level directory or
+# at https://cantera.org/license.txt for license and copyright information.
+
+from ._onedim import *
+from ._utils import *
+from ._utils import __git_commit__ as __git_commit__
+from ._utils import __sundials_version__ as __sundials_version__
+from ._utils import __version__ as __version__
+from .composite import *
+from .constants import *
+from .data import *
+from .delegator import *
+from .func1 import *
+from .jacobians import *
+from .kinetics import *
+from .liquidvapor import *
+from .mixture import *
+from .onedim import *
+from .reaction import *
+from .reactionpath import *
+from .reactor import *
+from .solutionbase import *
+from .speciesthermo import *
+from .thermo import *
+from .transport import *
+from .units import *
+from .utils import *
+from .yamlwriter import *