Add UltraLayout: Advanced constraint-based positioning for non-orthogonal subplot arrangements

.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,31 @@
+<!-- Thanks for helping us make ultraplot a better package! If this is a bug report, please use the template provided below. If this is a feature request, you can delete the template text (just try to be descriptive with your request). -->
+
+### Description
+
+[Description of the bug or feature.]
+
+### Steps to reproduce
+
+A "[Minimal, Complete and Verifiable Example](http://matthewrocklin.com/blog/work/2018/02/28/minimal-bug-reports)" will make it much easier for maintainers to help you.
+
+```python
+# your code here
+# we should be able to copy-paste this into python and exactly reproduce your bug
+```
+
+**Expected behavior**: [What you expected to happen]
+
+**Actual behavior**: [What actually happened]
+
+### Equivalent steps in matplotlib
+
+Please try to make sure this bug is related to a ultra-specific feature. If you're not sure, try to replicate it with the [native matplotlib API](https://matplotlib.org/3.1.1/api/index.html). Matplotlib bugs belong on the [matplotlib github page](https://github.com/matplotlib/matplotlib).
+
+```python
+# your code here, if applicable
+import matplotlib.pyplot as plt
+```
+
+### Ultra version
+
+Paste the results of `import matplotlib; print(matplotlib.__version__); import ultra; print(ultra.version)` here.

.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    groups:
+      github-actions:
+        patterns:
+          - '*'

.github/workflows/build-ultraplot.yml

@@ -0,0 +1,104 @@
+name: Build and Test
+on:
+  workflow_call:
+    inputs:
+      python-version:
+        required: true
+        type: string
+      matplotlib-version:
+        required: true
+        type: string
+
+env:
+  LC_ALL: en_US.UTF-8
+  LANG: en_US.UTF-8
+
+jobs:
+  build-ultraplot:
+    name: Test Python ${{ inputs.python-version }} with MPL ${{ inputs.matplotlib-version }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    defaults:
+      run:
+        shell: bash -el {0}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - uses: mamba-org/[email protected]
+        with:
+          environment-file: ./environment.yml
+          init-shell: bash
+          create-args: >-
+            --verbose
+            python=${{ inputs.python-version }}
+            matplotlib=${{ inputs.matplotlib-version }}
+          cache-environment: true
+          cache-downloads: false
+
+      - name: Build Ultraplot
+        run: |
+          pip install --no-build-isolation --no-deps .
+
+      - name: Test Ultraplot
+        run: |
+          pytest --cov=ultraplot --cov-branch --cov-report term-missing --cov-report=xml ultraplot
+
+      - name: Upload coverage reports to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          slug: Ultraplot/ultraplot
+
+  compare-baseline:
+    name: Compare baseline Python ${{ inputs.python-version }} with MPL ${{ inputs.matplotlib-version }}
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash -el {0}
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: mamba-org/[email protected]
+        with:
+          environment-file: ./environment.yml
+          init-shell: bash
+          create-args: >-
+            --verbose
+            python=${{ inputs.python-version }}
+            matplotlib=${{ inputs.matplotlib-version }}
+          cache-environment: true
+          cache-downloads: false
+
+      - name: Generate baseline from main
+        run: |
+          mkdir -p baseline
+          git fetch origin ${{ github.event.pull_request.base.sha }}
+          git checkout ${{ github.event.pull_request.base.sha }}
+          python -c "import ultraplot as plt; plt.config.Configurator()._save_yaml('ultraplot.yml')"
+          pytest -W ignore \
+            --mpl-generate-path=./baseline/ \
+            --mpl-default-style="./ultraplot.yml"\
+            ultraplot/tests
+          git checkout ${{ github.sha }}  # Return to PR branch
+
+      - name: Image Comparison Ultraplot
+        run: |
+          mkdir -p results
+          python -c "import ultraplot as plt; plt.config.Configurator()._save_yaml('ultraplot.yml')"
+          pytest -W ignore \
+              --mpl \
+              --mpl-baseline-path=./baseline/ \
+              --mpl-results-path=./results/ \
+              --mpl-generate-summary=html \
+              --mpl-default-style="./ultraplot.yml" \
+              ultraplot/tests
+
+      # Return the html output of the comparison even if failed
+      - name: Upload comparison failures
+        if: always()
+        uses: actions/upload-artifact@v6
+        with:
+          name: failed-comparisons-${{ inputs.python-version }}-${{ inputs.matplotlib-version }}-${{ github.sha }}
+          path: results/*

.github/workflows/main.yml

@@ -0,0 +1,155 @@
+name: Matrix Test
+on:
+  push:
+    branches: [main, devel]
+  pull_request:
+    branches: [main, devel]
+
+jobs:
+  run-if-changes:
+    runs-on: ubuntu-latest
+    outputs:
+      run: ${{ (github.event_name == 'push' && github.ref_name == 'main') && 'true' || steps.filter.outputs.python }}
+    steps:
+      - uses: actions/checkout@v6
+      - uses: dorny/paths-filter@v3
+        id: filter
+        with:
+          filters: |
+            python:
+              - 'ultraplot/**'
+
+  get-versions:
+    runs-on: ubuntu-latest
+    needs:
+      - run-if-changes
+    if: always() && needs.run-if-changes.outputs.run == 'true'
+    outputs:
+      python-versions: ${{ steps.set-versions.outputs.python-versions }}
+      matplotlib-versions: ${{ steps.set-versions.outputs.matplotlib-versions }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: pip install tomli
+
+      - id: set-versions
+        run: |
+          # Create a Python script to read and parse versions
+          cat > get_versions.py << 'EOF'
+          import tomli
+          import re
+          import json
+
+          # Read pyproject.toml
+          with open("pyproject.toml", "rb") as f:
+              data = tomli.load(f)
+
+          # Get Python version requirement
+          python_req = data["project"]["requires-python"]
+
+          # Parse min and max versions
+          min_version = re.search(r">=(\d+\.\d+)", python_req)
+          max_version = re.search(r"<(\d+\.\d+)", python_req)
+
+          python_versions = []
+          if min_version and max_version:
+              # Convert version strings to tuples
+              min_v = tuple(map(int, min_version.group(1).split(".")))
+              max_v = tuple(map(int, max_version.group(1).split(".")))
+
+              # Generate version list
+              current = min_v
+              while current < max_v:
+                  python_versions.append(".".join(map(str, current)))
+                  current = (current[0], current[1] + 1)
+
+
+          # parse MPL versions
+          mpl_req = None
+          for d in data["project"]["dependencies"]:
+            if d.startswith("matplotlib"):
+              mpl_req = d
+              break
+          assert mpl_req is not None, "matplotlib version not found in dependencies"
+          min_version = re.search(r">=(\d+\.\d+)", mpl_req)
+          max_version = re.search(r"<(\d+\.\d+)", mpl_req)
+
+          mpl_versions = []
+          if min_version and max_version:
+              # Convert version strings to tuples
+              min_v = tuple(map(int, min_version.group(1).split(".")))
+              max_v = tuple(map(int, max_version.group(1).split(".")))
+
+              # Generate version list
+              current = min_v
+              while current < max_v:
+                  mpl_versions.append(".".join(map(str, current)))
+                  current = (current[0], current[1] + 1)
+
+          # If no versions found, default to 3.9
+          if not mpl_versions:
+              mpl_versions = ["3.9"]
+
+          # Create output dictionary
+          output = {
+              "python_versions": python_versions,
+              "matplotlib_versions": mpl_versions
+          }
+
+          # Print as JSON
+          print(json.dumps(output))
+          EOF
+
+          # Run the script and capture output
+          OUTPUT=$(python3 get_versions.py)
+          PYTHON_VERSIONS=$(echo $OUTPUT | jq -r '.python_versions')
+          MPL_VERSIONS=$(echo $OUTPUT | jq -r '.matplotlib_versions')
+
+          echo "Detected Python versions: ${PYTHON_VERSIONS}"
+          echo "Detected Matplotlib versions: ${MPL_VERSIONS}"
+          echo "python-versions=$(echo $PYTHON_VERSIONS | jq -c)" >> $GITHUB_OUTPUT
+          echo "matplotlib-versions=$(echo $MPL_VERSIONS | jq -c)" >> $GITHUB_OUTPUT
+
+  build:
+    needs:
+      - get-versions
+      - run-if-changes
+    if: always() && needs.run-if-changes.outputs.run == 'true' && needs.get-versions.result == 'success'
+    strategy:
+      matrix:
+        python-version: ${{ fromJson(needs.get-versions.outputs.python-versions) }}
+        matplotlib-version: ${{ fromJson(needs.get-versions.outputs.matplotlib-versions) }}
+      fail-fast: false
+    uses: ./.github/workflows/build-ultraplot.yml
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}-${{ matrix.python-version }}-${{ matrix.matplotlib-version }}
+      cancel-in-progress: true
+    with:
+      python-version: ${{ matrix.python-version }}
+      matplotlib-version: ${{ matrix.matplotlib-version }}
+
+  build-success:
+    needs:
+      - build
+      - run-if-changes
+    if: always()
+    runs-on: ubuntu-latest
+    steps:
+      - run: |
+          if [[ '${{ needs.run-if-changes.outputs.run }}' == 'false' ]]; then
+            echo "No changes detected, tests skipped."
+          else
+            if [[ '${{ needs.build.result }}' == 'success' ]]; then
+              echo "All tests passed successfully!"
+            else
+              echo "Tests failed!"
+              exit 1
+            fi
+          fi