Merge branch 'main' into feat/mcp

Author: cvanelteren

.github/workflows/build-ultraplot.yml

@@ -53,9 +53,15 @@ jobs:
         with:
           fetch-depth: 0
 
+      - name: Prepare compatible test environment
+        run: >-
+          python3 tools/ci/version_support.py
+          --matplotlib-version '${{ inputs.matplotlib-version }}'
+          --environment-output '${{ runner.temp }}/ultraplot-environment.yml'
+
       - uses: mamba-org/setup-micromamba@v3.2.1
         with:
-          environment-file: ./environment.yml
+          environment-file: ${{ runner.temp }}/ultraplot-environment.yml
           init-shell: bash
           condarc-file: ./.github/micromamba-condarc.yml
           post-cleanup: none
@@ -69,6 +75,14 @@ jobs:
       - name: Build Ultraplot
         run: |
           pip install --no-build-isolation --no-deps .
+          python - <<'PY'
+          import sys
+          import matplotlib, mpltern, pycirclize
+          assert sys.version_info[:2] == tuple(map(int, '${{ inputs.python-version }}'.split('.')))
+          assert matplotlib.__version__.startswith('${{ inputs.matplotlib-version }}.')
+          print('Python executable:', sys.executable)
+          print('Matplotlib:', matplotlib.__version__)
+          PY
 
   compare-baseline:
     name: Compare baseline Python ${{ inputs.python-version }} with MPL ${{ inputs.matplotlib-version }}
@@ -100,9 +114,15 @@ jobs:
 
       - uses: actions/checkout@v7
 
+      - name: Prepare compatible test environment
+        run: >-
+          python3 tools/ci/version_support.py
+          --matplotlib-version '${{ inputs.matplotlib-version }}'
+          --environment-output '${{ runner.temp }}/ultraplot-environment.yml'
+
       - uses: mamba-org/setup-micromamba@v3.2.1
         with:
-          environment-file: ./environment.yml
+          environment-file: ${{ runner.temp }}/ultraplot-environment.yml
           init-shell: bash
           condarc-file: ./.github/micromamba-condarc.yml
           post-cleanup: none
@@ -128,11 +148,26 @@ jobs:
           echo "base_sha=${BASE_SHA}" >> "${GITHUB_OUTPUT}"
           echo "Resolved baseline ref=${BASE_REF} sha=${BASE_SHA}"
 
+      - name: Check baseline version support
+        id: baseline-support
+        run: |
+          git show '${{ steps.baseline-ref.outputs.base_sha }}:pyproject.toml' > '${{ runner.temp }}/baseline-pyproject.toml'
+          python tools/ci/version_support.py \
+            --baseline-pyproject '${{ runner.temp }}/baseline-pyproject.toml' \
+            --python-version '${{ inputs.python-version }}' \
+            --matplotlib-version '${{ inputs.matplotlib-version }}' >> "$GITHUB_OUTPUT"
+
+      - name: Explain unavailable baseline
+        if: steps.baseline-support.outputs.baseline-supported != 'true'
+        run: |
+          echo '::notice::Image comparison skipped: the base commit does not support this Python/Matplotlib pair. PR tests still run in the coverage job.'
+          echo 'Image comparison skipped for Python ${{ inputs.python-version }} / Matplotlib ${{ inputs.matplotlib-version }}: base commit ${{ steps.baseline-ref.outputs.base_sha }} does not support this pair. The coverage job still tests the PR on this pair.' >> "$GITHUB_STEP_SUMMARY"
+
       # Cache Baseline Figures (Restore step)
       - name: Cache Baseline Figures
         id: cache-baseline
         uses: actions/cache@v6
-        if: ${{ env.IS_PR }}
+        if: env.IS_PR == 'true' && steps.baseline-support.outputs.baseline-supported == 'true'
         with:
           path: ./ultraplot/tests/baseline # The directory to cache
           # Key is based on OS, Python/Matplotlib versions, and the base commit SHA
@@ -143,7 +178,7 @@ jobs:
       # Conditional Baseline Generation (Only runs on cache miss)
       - name: Generate baseline from main
         # Skip this step if the cache was found (cache-hit is true)
-        if: steps.cache-baseline.outputs.cache-hit != 'true' || !env.IS_PR
+        if: steps.baseline-support.outputs.baseline-supported == 'true' && (steps.cache-baseline.outputs.cache-hit != 'true' || env.IS_PR != 'true')
         run: |
           mkdir -p ultraplot/tests/baseline
           echo "TEST_MODE=${TEST_MODE}"
@@ -219,6 +254,7 @@ jobs:
 
       # Image Comparison (Uses cached or newly generated baseline)
       - name: Image Comparison Ultraplot
+        if: steps.baseline-support.outputs.baseline-supported == 'true'
         run: |
           set -uo pipefail
           # This workflow runs in a login shell (bash -el), which executes

.github/workflows/main.yml

@@ -188,11 +188,16 @@ jobs:
             --progress-bar no
 
   coverage:
-    name: Coverage
+    name: Coverage Python ${{ matrix.python-version }} / MPL ${{ matrix.matplotlib-version }}
     runs-on: ubuntu-latest
     needs:
       - run-if-changes
-    if: always() && needs.run-if-changes.outputs.run == 'true' && github.event_name == 'pull_request'
+      - get-versions
+    if: always() && needs.run-if-changes.outputs.run == 'true' && needs.get-versions.result == 'success' && github.event_name == 'pull_request'
+    strategy:
+      fail-fast: false
+      matrix:
+        include: ${{ fromJson(needs.get-versions.outputs.test-matrix) }}
     defaults:
       run:
         shell: bash -el {0}
@@ -206,16 +211,22 @@ jobs:
         with:
           fetch-depth: 0
 
+      - name: Prepare compatible coverage environment
+        run: >-
+          python3 tools/ci/version_support.py
+          --matplotlib-version '${{ matrix.matplotlib-version }}'
+          --environment-output '${{ runner.temp }}/ultraplot-environment.yml'
+
       - uses: mamba-org/setup-micromamba@v3.2.1
         with:
-          environment-file: ./environment.yml
+          environment-file: ${{ runner.temp }}/ultraplot-environment.yml
           init-shell: bash
           condarc-file: ./.github/micromamba-condarc.yml
           post-cleanup: none
           create-args: >-
             --verbose
-            python=3.10
-            matplotlib=3.9
+            python=${{ matrix.python-version }}
+            matplotlib=${{ matrix.matplotlib-version }}
           cache-environment: true
           cache-downloads: false
 
@@ -225,6 +236,16 @@ jobs:
 
       - name: Run full coverage suite
         run: |
+          python - <<'PY'
+          import sys
+          from importlib.metadata import version
+          import matplotlib, mpltern, pycirclize
+          assert sys.version_info[:2] == tuple(map(int, '${{ matrix.python-version }}'.split('.')))
+          assert matplotlib.__version__.startswith('${{ matrix.matplotlib-version }}.')
+          print('Python executable:', sys.executable)
+          for package in ('matplotlib', 'mpltern', 'pycirclize', 'cartopy'):
+              print(f'{package}: {version(package)}')
+          PY
           pytest -q --tb=short --disable-warnings -n auto -p pytest_cov \
             --cov=ultraplot --cov-branch --cov-context=test \
             --cov-report=xml:coverage.xml --cov-report= \
@@ -235,7 +256,7 @@ jobs:
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           files: ./coverage.xml
-          name: codecov-pr-python3.10-mpl3.9
+          name: codecov-pr-python${{ matrix.python-version }}-mpl${{ matrix.matplotlib-version }}
 
   build:
     needs:
@@ -261,6 +282,7 @@ jobs:
   build-success:
     needs:
       - build
+      - coverage
       - run-if-changes
       - stubs
     if: always()
@@ -270,7 +292,7 @@ jobs:
           if [[ '${{ needs.run-if-changes.outputs.run }}' == 'false' ]]; then
             echo "No changes detected, tests skipped."
           else
-            if [[ '${{ needs.build.result }}' == 'success' && '${{ needs.stubs.result }}' == 'success' ]]; then
+            if [[ '${{ needs.build.result }}' == 'success' && '${{ needs.stubs.result }}' == 'success' && ( '${{ needs.coverage.result }}' == 'success' || '${{ needs.coverage.result }}' == 'skipped' ) ]]; then
               echo "All tests passed successfully!"
             else
               echo "Tests failed!"

.gitignore

@@ -26,6 +26,8 @@ docs/_static/*
 !docs/_static/alias-explorer-v3.js
 !docs/_static/alias-map.svg
 !docs/_static/why_plots/
+!docs/_static/example_plots/
+!docs/_static/example_plots/data_aware_example.svg
 *.html
 docs/gallery/
 docs/sg_execution_times.rst

.pre-commit-config.yaml

@@ -14,3 +14,11 @@ repos:
     rev: 26.5.1
     hooks:
       - id: black
+
+  - repo: https://github.com/tombi-toml/tombi-pre-commit
+    rev: v1.5.2
+    hooks:
+      - id: tombi-format
+        args: ["--offline"]
+      - id: tombi-lint
+        args: ["--offline"]

INSTALL.rst

@@ -18,6 +18,12 @@ pyCirclize-based plots require the optional ``circos`` extra:
 
 The ``docs`` extra also includes pyCirclize for building the documentation.
 
+To install all optional dependency groups (``circos``, ``docs``, and ``stats``):
+
+.. code-block:: bash
+
+   pip install 'ultraplot[all]'
+
 Likewise, an existing installation of ultraplot can be upgraded to the latest version with:
 
 .. code-block:: bash

README.rst

@@ -112,6 +112,12 @@ pyCirclize-based plots require the optional ``circos`` extra:
 
 The ``docs`` extra also includes pyCirclize for building the documentation.
 
+To install all optional dependency groups (``circos``, ``docs``, and ``stats``):
+
+.. code-block:: bash
+
+   pip install 'ultraplot[all]'
+
 Likewise, an existing installation of UltraPlot can be upgraded
 to the latest version with: