terrine 0.1.0a1__tar.gz

terrine-0.1.0a1/.github/CLA.md

@@ -0,0 +1,154 @@
+# terrine Individual Contributor License Agreement
+
+Version 1.0 · effective 2026-10-20
+
+The signature record stores the commit at which you signed, so the exact text
+you agreed to is always recoverable from this file's git history. If this
+Agreement is revised, the version above changes and existing signatures remain
+bound to the version in force when they were made.
+
+Thank you for your interest in contributing to terrine (the "Project"),
+owned by Kyle Caron ("Owner", "we", "us").
+
+This agreement clarifies the intellectual property license granted with
+Contributions from any person or entity. It protects both you and the Owner;
+it does **not** change your rights to use your own Contributions for any other
+purpose.
+
+**You keep the copyright in everything you contribute.** This is a license, not
+an assignment. You are free to use, sell, relicense, and redistribute your own
+Contributions however you wish, with no obligation to us.
+
+You accept and agree to the following terms for your present and future
+Contributions to the Project.
+
+## 1. Definitions
+
+"You" (or "Your") means the copyright owner, or the legal entity authorized by
+the copyright owner, entering into this Agreement.
+
+"Contribution" means any original work of authorship, including any
+modifications to or additions to an existing work, that is or previously has
+been intentionally submitted by You to the Owner for inclusion in, or
+documentation of, the Project. "Submitted" means any form of electronic,
+verbal, or written communication sent to the Owner or its representatives,
+including but not limited to communication on electronic mailing lists, source
+code control systems, and issue tracking systems that are managed by, or on
+behalf of, the Owner for the purpose of discussing and improving the Project,
+but excluding communication that is conspicuously marked or otherwise
+designated in writing by You as "Not a Contribution."
+
+## 2. Grant of Copyright License
+
+Subject to the terms and conditions of this Agreement, You hereby grant to the
+Owner and to recipients of software distributed by the Owner a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable, **transferable
+and assignable** copyright license to reproduce, prepare derivative works of,
+publicly display, publicly perform, **sublicense**, and distribute Your
+Contributions and such derivative works.
+
+The Owner may assign this Agreement, and the licenses granted under it, to a
+successor in interest to the Project, including by merger, reorganization, or
+sale of the assets to which the Project relates. This Agreement binds and
+benefits the Owner's successors and assigns.
+
+## 3. Right to License Under Any Terms
+
+You acknowledge and agree that the Owner may license, sublicense, and
+distribute Your Contributions — alone or as part of the Project — **under any
+license terms the Owner chooses**, including open source licenses, source
+available licenses, and proprietary or commercial licenses, and that the Owner
+may offer the Project under multiple licenses simultaneously (dual licensing).
+
+The Owner is under no obligation to distribute Your Contributions under the
+license currently applied to the Project.
+
+This clause exists so that the Owner can sustain the Project commercially. It
+does not restrict You: the rights You grant here are non-exclusive, and Your
+own rights in Your Contributions are unaffected.
+
+## 4. Grant of Patent License
+
+Subject to the terms and conditions of this Agreement, You hereby grant to the
+Owner and to recipients of software distributed by the Owner a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as
+stated in this section) patent license to make, have made, use, offer to sell,
+sell, import, and otherwise transfer the Project, where such license applies
+only to those patent claims licensable by You that are necessarily infringed by
+Your Contribution(s) alone or by combination of Your Contribution(s) with the
+Project to which such Contribution(s) was submitted.
+
+If any entity institutes patent litigation against You or any other entity
+(including a cross-claim or counterclaim in a lawsuit) alleging that Your
+Contribution, or the Project to which You have contributed, constitutes direct
+or contributory patent infringement, then any patent licenses granted to that
+entity under this Agreement for that Contribution or Project shall terminate as
+of the date such litigation is filed.
+
+## 5. You Represent That You Are Entitled To Grant This License
+
+You represent that You are legally entitled to grant the above license. If Your
+employer(s) has rights to intellectual property that You create that includes
+Your Contributions, You represent that You have received permission to make
+Contributions on behalf of that employer, that You will have received
+permission from Your current and future employers for all future
+Contributions, that Your employer has waived such rights for all of Your
+current and future Contributions to the Owner, or that Your employer has
+executed a Corporate Contributor License Agreement with the Owner.
+
+## 6. You Represent That Each Contribution Is Your Original Creation
+
+You represent that each of Your Contributions is Your original creation. You
+represent that Your Contribution submissions include complete details of any
+third-party license or other restriction (including, but not limited to,
+related patents and trademarks) of which You are personally aware and which are
+associated with any part of Your Contributions.
+
+## 7. Third-Party Work
+
+Should You wish to submit work that is not Your original creation, You may
+submit it to the Owner separately from any Contribution, identifying the
+complete details of its source and of any license or other restriction
+(including, but not limited to, related patents, trademarks, and license
+agreements) of which You are personally aware, and conspicuously marking the
+work as "Submitted on behalf of a third-party: [named here]".
+
+## 8. No Obligation of Support or Warranty
+
+You are not expected to provide support for Your Contributions, except to the
+extent You desire to provide support. You may provide support for free, for a
+fee, or not at all. Unless required by applicable law or agreed to in writing,
+You provide Your Contributions on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied, including, without
+limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT,
+MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE.
+
+## 9. Notification of Changed Circumstances
+
+You agree to notify the Owner of any facts or circumstances of which You become
+aware that would make these representations inaccurate in any respect.
+
+## Signing
+
+Contributions are accepted only from signers of this Agreement, except for
+automated accounts and coding agents named in the workflow allowlist, which
+cannot themselves sign; the human opening the pull request remains responsible
+for the representations above.
+
+Sign electronically by commenting the following on your pull request, exactly:
+
+```
+I have read the CLA Document and I hereby sign the CLA
+```
+
+You sign once; the signature covers all of Your Contributions to the Project,
+past and future.
+
+**Record kept.** Signing stores your GitHub username, the text of your comment,
+and a timestamp in the `cla-signatures` branch of this repository. That record
+is retained for as long as the Project exists, because it is the evidence of
+the licenses granted above. It is public if this repository is public.
+
+If you are contributing on behalf of a company and your employer requires its
+own agreement rather than the representations in section 5, contact
+kyle.j.caron@gmail.com before opening a pull request.

terrine-0.1.0a1/.github/workflows/ci.yml

@@ -0,0 +1,287 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+# A newer push supersedes an in-flight run of the same ref.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+
+jobs:
+  # Each pushed commit runs every job once. A branch push defers to the
+  # pull-request run of the same commit when one exists; GitHub runs none for a
+  # pull request with merge conflicts, so an open pull request alone does not
+  # defer. Other events and tag pushes always run every job.
+  scope:
+    runs-on: ubuntu-latest
+    timeout-minutes: 3
+    permissions:
+      contents: read
+      actions: read
+    outputs:
+      defer: ${{ steps.scope.outputs.defer }}
+    steps:
+      - if: github.event_name == 'push' && startsWith(github.ref, 'refs/heads/')
+        uses: actions/checkout@v4
+      - id: scope
+        env:
+          GH_TOKEN: ${{ github.token }}
+          LOOKUP: ${{ github.event_name == 'push' && startsWith(github.ref, 'refs/heads/') }}
+        run: |
+          set -euo pipefail
+          if [ "$LOOKUP" = true ]; then
+            python3 scripts/ci_scope.py --sha "$GITHUB_SHA" --repo "$GITHUB_REPOSITORY"
+          else
+            echo "defer=false" >> "$GITHUB_OUTPUT"
+          fi
+  checks:
+    needs: scope
+    if: needs.scope.outputs.defer != 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+      - run: uv sync --locked --group dev --group docs --all-extras
+      - run: make lint
+      - run: make typecheck
+  unit:
+    needs: scope
+    if: needs.scope.outputs.defer != 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.14"]
+        group: [1, 2]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "${{ matrix.python-version }}"
+      - run: uv sync --locked --group dev --all-extras
+      - run: >-
+          /usr/bin/time -f "terrine-pytest-cpu %U %S" uv run pytest -q tests
+          -n auto --splits 2 --group ${{ matrix.group }}
+          --splitting-algorithm least_duration
+          --durations-path tests/.test_durations
+          --ignore=tests/temporal/test_sketches.py
+          --ignore=tests/spec/test_sketch_refusal.py
+          --ignore=tests/compile/test_nonadditive.py
+          --ignore=tests/compat
+          --ignore=tests/parity
+  integration:
+    needs: scope
+    if: needs.scope.outputs.defer != 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        # Groups are balanced from integration/.test_durations; tests without a
+        # stored duration get the average and are still assigned to a group.
+        python-version: ["3.12", "3.14"]
+        group: [1, 2, 3, 4]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "${{ matrix.python-version }}"
+      - run: uv sync --locked --group dev --all-extras
+      - run: >-
+          /usr/bin/time -f "terrine-pytest-cpu %U %S" uv run pytest -q integration
+          -n auto --dist loadscope --splits 4 --group ${{ matrix.group }}
+          --splitting-algorithm duration_based_chunks
+          --durations-path integration/.test_durations
+          --ignore=integration/parity
+          --ignore=integration/handoffs
+      # The same known answers compiled through the portable base expression
+      # policy; about twenty seconds beside the native run.
+      - if: matrix.group == 1
+        run: /usr/bin/time -f "terrine-pytest-cpu %U %S" uv run pytest -q -n auto integration/conformance --generic-dialect
+  docs-and-examples:
+    needs: scope
+    if: needs.scope.outputs.defer != 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: uv sync --locked --group dev --group docs --all-extras
+      - run: uv run --group docs python -m tests.documentation --build
+      - run: uv build
+  # Builds once per resolution and installs those distributions on every
+  # supported Python in turn.
+  distributions:
+    needs: scope
+    if: needs.scope.outputs.defer != 'true'
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        resolution: [highest, lowest-direct]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - uses: actions/setup-python@v5
+        with:
+          python-version: |
+            3.12
+            3.13
+            3.14
+      - run: uv build
+      - env:
+          RESOLUTION: ${{ matrix.resolution }}
+        run: |
+          set -euo pipefail
+          for python in 3.12 3.13 3.14; do
+            uv run --no-project --python "$python" python \
+              -m tests.integration.distribution_smoke \
+              --wheel dist/*.whl --sdist dist/*.tar.gz \
+              --python "$python" --resolution "$RESOLUTION"
+          done
+
+  # Suites for optional extras, in turn. Each re-syncs with exactly its own
+  # extras, so every extra is proven without the others installed.
+  optional-suites:
+    needs: scope
+    if: needs.scope.outputs.defer != 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Sync sketches extras
+        run: uv sync --group dev --extra duckdb --extra pandas --extra sketches
+      - run: /usr/bin/time -f "terrine-pytest-cpu %U %S" uv run pytest -n auto tests/temporal/test_sketches.py tests/spec/test_sketch_refusal.py tests/compile/test_nonadditive.py -q
+      - name: Sync increment compatibility extras
+        run: uv sync --locked --group dev --extra duckdb --extra increment
+      - run: /usr/bin/time -f "terrine-pytest-cpu %U %S" uv run pytest -n auto tests/compat tests/parity
+      - run: /usr/bin/time -f "terrine-pytest-cpu %U %S" uv run pytest -n auto integration/parity
+      - name: Sync library hand-off extras
+        run: uv sync --locked --group dev --extra duckdb --extra doubleml --extra dowhy --extra duckreg --extra lifelines --extra diff-diff
+      - run: /usr/bin/time -f "terrine-pytest-cpu %U %S" uv run pytest -q -n auto integration/handoffs
+
+  postgres:
+    needs: scope
+    if: needs.scope.outputs.defer != 'true'
+    uses: ./.github/workflows/warehouse-backends.yml
+    with:
+      backend_mode: postgres
+
+  conformance-newest-python:
+    needs: scope
+    if: needs.scope.outputs.defer != 'true'
+    runs-on: ubuntu-latest
+    env:
+      UV_PYTHON: "3.14"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv sync --locked --group dev --extra duckdb
+      - run: /usr/bin/time -f "terrine-pytest-cpu %U %S" uv run pytest -q -n auto integration/conformance
+
+  # Validates stable exports and annotations, then compares signatures with the
+  # newest versioned snapshot; differences are informational during 0.x.
+  api-compat:
+    needs: scope
+    if: needs.scope.outputs.defer != 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: uv sync --locked --group dev
+      - name: Check stable API against release tags
+        run: uv run python scripts/api_check.py
+      - name: Compare stable API snapshot
+        run: |
+          set -euo pipefail
+          snapshot=$(uv run python -c '
+          from pathlib import Path
+          from packaging.version import Version
+          snapshots = list(Path("tests/artifacts/surface").glob("*.txt"))
+          print(max(snapshots, key=lambda path: Version(path.stem.removeprefix("v"))) if snapshots else "")
+          ')
+          if [ -z "$snapshot" ]; then
+            uv run python scripts/api_check.py --compare tests/artifacts/surface/.no-snapshot-yet.txt
+            exit $?
+          fi
+          uv run python scripts/api_check.py --compare "$snapshot"
+
+  # Single check to require in branch protection. Matrix jobs report one check
+  # per entry, so requiring them individually means editing the ruleset every
+  # time a matrix changes. GitHub reports a job skipped by a condition as
+  # successful, so a deferred run renames this job and never reports a check
+  # named exactly `ci-ok`; the pull-request run reports it instead.
+  ci-ok:
+    name: ${{ needs.scope.outputs.defer == 'true' && 'ci-ok (checked by the pull request run)' || 'ci-ok' }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    needs:
+      - scope
+      - checks
+      - unit
+      - integration
+      - docs-and-examples
+      - distributions
+      - optional-suites
+      - postgres
+      - conformance-newest-python
+      - api-compat
+    if: always()
+    permissions: {}
+    steps:
+      - name: Require every job to succeed
+        env:
+          DEFER: ${{ needs.scope.outputs.defer }}
+          NEEDS: ${{ toJSON(needs) }}
+        run: |
+          set -euo pipefail
+          if [ "$DEFER" = true ]; then
+            echo "The pull-request run of this commit runs and checks every job."
+            exit 0
+          fi
+          echo "$NEEDS" | jq -r 'to_entries[] | "\(.key): \(.value.result)"'
+          failed=$(echo "$NEEDS" | jq -r '[to_entries[] | select(.value.result != "success") | .key] | join(", ")')
+          if [ -n "$failed" ]; then
+            echo "::error::jobs did not succeed: $failed"
+            exit 1
+          fi

terrine-0.1.0a1/.github/workflows/cla.yml

@@ -0,0 +1,61 @@
+name: cla
+
+# Signatures are committed to the `cla-signatures` branch of this repo using
+# the job's GITHUB_TOKEN, which is why `contents: write` below is required.
+
+on:
+  issue_comment: {types: [created]}
+  pull_request_target: {types: [opened, closed, reopened, synchronize]}
+
+concurrency:
+  # Recording a signature is a read-modify-write on one JSON file guarded by a
+  # SHA precondition; concurrent signings would race and one would 409.
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.event.issue.number }}
+  cancel-in-progress: false
+
+permissions: {}
+
+jobs:
+  cla:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      actions: write
+      contents: write
+      pull-requests: write
+      statuses: write
+    # Write scopes on a pull_request_target job are safe only while nothing
+    # here checks out or executes PR-controlled content. Don't add a checkout
+    # or build step.
+    steps:
+      # Maintained fork of the archived contributor-assistant/github-action,
+      # pinned by SHA because this job holds write scopes under
+      # pull_request_target.
+      - uses: iainmcgin/cla-github-action@0d27e5a16278d4adb6b0c4b92f08ad27b0a21dc8 # v3.2.0
+        # Without this guard the action runs on every comment on every plain
+        # issue, where there is no pull request to resolve, and fails the check.
+        if: (github.event.comment.body == 'recheck' || github.event.comment.body == 'I have read the CLA Document and I hereby sign the CLA') || github.event_name == 'pull_request_target'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          path-to-document: ${{ github.server_url }}/${{ github.repository }}/blob/${{ github.event.repository.default_branch }}/.github/CLA.md
+          path-to-signatures: signatures/v1/cla.json
+          branch: cla-signatures
+          # AI coding agents add Co-authored-by trailers; they are counted as
+          # committers but cannot comment to sign, so they must be allowlisted
+          # or every agent-assisted PR blocks permanently.
+          # Name automated accounts explicitly; a wildcard such as bot* would also
+          # exempt human accounts whose names start with "bot".
+          allowlist: kylejcaron,dependabot[bot],renovate[bot],github-actions[bot],copilot,Copilot,Codex,Cursor,noreply@anthropic.com,cursoragent@cursor.com,codex@openai.com
+          # Fail the check when the PR opener authored none of the commits.
+          require-opener-as-author: true
+          lock-pullrequest-aftermerge: false
+          custom-pr-sign-comment: I have read the CLA Document and I hereby sign the CLA
+          custom-notsigned-prcomment: >
+            Thanks for the pull request. Before it can be merged, please read
+            the [Contributor License Agreement](${{ github.server_url }}/${{ github.repository }}/blob/${{ github.event.repository.default_branch }}/.github/CLA.md)
+            and sign it by posting the comment below. You keep the copyright in
+            your work; the CLA grants terrine's owner the right to license it,
+            including commercially. You sign once and it covers all your future
+            contributions.
+          custom-allsigned-prcomment: CLA signed by all contributors. Thank you.

terrine-0.1.0a1/.github/workflows/docs.yml

@@ -0,0 +1,42 @@
+name: Documentation
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: uv sync --group docs
+      - run: uv run --group docs python -m tests.documentation --build
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    if: github.ref == 'refs/heads/main'
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    permissions:
+      pages: write
+      id-token: write
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

terrine-0.1.0a1/.github/workflows/durations.yml

@@ -0,0 +1,40 @@
+name: durations
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  refresh:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: uv sync --locked --group dev --all-extras
+      - name: Store unit test durations
+        run: >-
+          /usr/bin/time -f "terrine-pytest-cpu %U %S" uv run pytest tests -n auto
+          --store-durations --durations-path tests/.test_durations
+          --ignore=tests/temporal/test_sketches.py
+          --ignore=tests/spec/test_sketch_refusal.py
+          --ignore=tests/compile/test_nonadditive.py
+          --ignore=tests/compat --ignore=tests/parity
+      - name: Store integration test durations
+        run: >-
+          /usr/bin/time -f "terrine-pytest-cpu %U %S" uv run pytest integration -n auto
+          --store-durations --durations-path integration/.test_durations
+          --ignore=integration/parity --ignore=integration/handoffs
+      - uses: actions/upload-artifact@v4
+        with:
+          name: stored-test-durations
+          path: |
+            tests/.test_durations
+            integration/.test_durations
+          include-hidden-files: true