terrine 0.1.0.dev0__tar.gz

terrine-0.1.0.dev0/.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.0.dev0/.github/workflows/ci.yml

@@ -0,0 +1,188 @@
+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:
+  checks:
+    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.13"
+      - run: uv sync --locked --group dev --group docs --all-extras
+      - run: make lint
+      - run: make typecheck
+  unit:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        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: "3.13"
+      - run: uv sync --locked --group dev --all-extras
+      - run: >-
+          uv run pytest -q tests
+          --splits 4 --group ${{ matrix.group }}
+          --splitting-algorithm least_duration
+          --durations-path tests/.test_durations
+  integration:
+    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.
+        group: [1, 2, 3, 4, 5, 6]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: uv sync --locked --group dev --all-extras
+      - if: matrix.group == 1
+        run: uv run python -m tests.integration.study_api_smoke
+      - run: >-
+          uv run pytest -q integration
+          --splits 6 --group ${{ matrix.group }}
+          --splitting-algorithm least_duration
+          --durations-path integration/.test_durations
+  docs-and-examples:
+    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.13"
+      - run: uv sync --locked --group dev --group docs --all-extras
+      - run: |
+          for example in examples/*.py; do
+            uv run python "$example"
+          done
+      - run: uv run --group docs python -m tests.documentation --build
+      - run: uv build
+  distributions:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.13", "3.14"]
+        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: ${{ matrix.python }}
+      - run: uv build
+      - run: >-
+          uv run --no-project --python "${{ matrix.python }}" python
+          -m tests.integration.distribution_smoke
+          --wheel dist/*.whl --sdist dist/*.tar.gz
+          --python "${{ matrix.python }}" --resolution "${{ matrix.resolution }}"
+  sketches:
+    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.13"
+      - run: uv sync --group dev --extra duckdb --extra pandas --extra sketches
+      - run: uv run pytest tests/temporal/test_sketches.py tests/spec/test_sketch_refusal.py tests/compile/test_nonadditive.py -q
+
+  postgres:
+    uses: ./.github/workflows/warehouse-backends.yml
+    with:
+      backend_mode: postgres
+
+  increment-compatibility:
+    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.13"
+      - run: uv sync --locked --group dev --extra duckdb --extra increment
+      - run: uv run pytest tests/compat tests/parity
+      - run: uv run pytest integration/parity
+
+  library-handoffs:
+    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.13"
+      - run: uv sync --locked --group dev --extra duckdb --extra doubleml --extra dowhy --extra duckreg --extra lifelines --extra diff-diff
+      - run: uv run pytest -q integration/handoffs
+
+  # 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.
+  ci-ok:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    needs:
+      - checks
+      - unit
+      - integration
+      - docs-and-examples
+      - distributions
+      - sketches
+      - postgres
+      - increment-compatibility
+      - library-handoffs
+    if: always()
+    permissions: {}
+    steps:
+      - name: Require every job to succeed
+        env:
+          NEEDS: ${{ toJSON(needs) }}
+        run: |
+          set -euo pipefail
+          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.0.dev0/.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.0.dev0/.github/workflows/release.yml

@@ -0,0 +1,173 @@
+name: release
+
+# Tag-driven release: pushing a vX.Y.Z tag whose version equals
+# `project.version` in pyproject.toml builds, verifies and publishes to PyPI,
+# then creates a GitHub Release.
+#
+# Publishing uses PyPI Trusted Publishing (OIDC). No API token is stored.
+# PyPI publisher settings:
+#   owner: kylejcaron   repository: terrine
+#   workflow: release.yml   environment: pypi
+# Configure required reviewers on the `pypi` environment so a pushed tag alone
+# cannot publish.
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions: {}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    outputs:
+      version: ${{ steps.check.outputs.version }}
+      prerelease: ${{ steps.check.outputs.prerelease }}
+    steps:
+      - name: Require a version tag
+        env:
+          REF: ${{ github.ref }}
+        run: |
+          set -euo pipefail
+          case "$REF" in
+            refs/tags/v*) ;;
+            *) echo "::error::release requires a v* tag ref, not a branch"; exit 1 ;;
+          esac
+
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@ae62891fec2bb8e7d6c99fc78c9fec3a63790f8d # v10.0.0
+        with:
+          enable-cache: true
+
+      - run: uv build --sdist --wheel --out-dir dist
+
+      - name: Verify built version matches the tag
+        id: check
+        shell: bash
+        run: |
+          set -euo pipefail
+          tag="${GITHUB_REF_NAME#v}"
+          # Wheel filename is {name}-{version}-{python}-{abi}-{platform}.whl
+          whl=$(ls dist/*.whl)
+          built=$(basename "$whl" | cut -d- -f2)
+          echo "tag=$tag built=$built"
+
+          if [ "$tag" != "$built" ]; then
+            echo "::error::tag v$tag does not match built version $built (pyproject.toml project.version)."
+            exit 1
+          fi
+
+          # PyPI rejects PEP 440 local versions; fail before publishing.
+          case "$built" in
+            *+*) echo "::error::version $built has a local segment; PyPI will reject it"; exit 1 ;;
+          esac
+
+          # a/b/rc/dev -> mark the GitHub Release as a prerelease
+          if printf '%s' "$built" | grep -Eq '(a|b|rc|\.dev)[0-9]+'; then
+            echo "prerelease=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "prerelease=false" >> "$GITHUB_OUTPUT"
+          fi
+          echo "version=$built" >> "$GITHUB_OUTPUT"
+
+      - name: Check metadata renders on PyPI
+        run: uvx twine check --strict dist/*
+
+      - name: Verify artifacts actually contain the package
+        shell: bash
+        run: |
+          set -euo pipefail
+          # hatchling builds a metadata-only wheel when the package directory is
+          # missing; refuse to publish an empty package, since PyPI versions can
+          # never be reused.
+          python3 - <<'PY'
+          import glob, sys, tarfile, zipfile
+
+          def one(pattern):
+              hits = glob.glob(pattern)
+              if not hits:
+                  sys.exit(f"::error::no artifact matching {pattern} -- the build produced nothing")
+              if len(hits) > 1:
+                  sys.exit(f"::error::expected exactly one {pattern}, found {len(hits)}: {hits}")
+              return hits[0]
+
+          whl = one("dist/*.whl")
+          mods = [n for n in zipfile.ZipFile(whl).namelist()
+                  if n.startswith("terrine/") and n.endswith(".py")]
+          if not mods:
+              sys.exit(f"::error::{whl} contains no terrine/*.py modules")
+          print(f"wheel: {len(mods)} module(s)")
+
+          sdist = one("dist/*.tar.gz")
+          with tarfile.open(sdist) as tf:
+              src = [n for n in tf.getnames()
+                     if "/terrine/" in n and n.endswith(".py")]
+          if not src:
+              sys.exit(f"::error::{sdist} contains no terrine/ sources")
+          print(f"sdist: {len(src)} module(s)")
+          PY
+
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    environment:
+      name: pypi
+      url: https://pypi.org/project/terrine/${{ needs.build.outputs.version }}
+    permissions:
+      # OIDC token for Trusted Publishing. This is the only credential used.
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          attestations: true
+          print-hash: true
+
+  github-release:
+    needs: [build, publish]
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ github.ref_name }}
+          PRERELEASE: ${{ needs.build.outputs.prerelease }}
+        run: |
+          set -euo pipefail
+          args=(--verify-tag --generate-notes --title "$TAG")
+          [ "$PRERELEASE" = "true" ] && args+=(--prerelease)
+          gh release create "$TAG" "${args[@]}" dist/*

terrine-0.1.0.dev0/.github/workflows/scale.yml

@@ -0,0 +1,32 @@
+name: scale
+
+# Resource-bound scale, oracle and live-warehouse checks. Too slow for every
+# push; run weekly and on demand.
+on:
+  schedule:
+    - cron: "0 7 * * 1"
+  workflow_dispatch:
+
+concurrency:
+  group: scale
+  cancel-in-progress: false
+
+env:
+  # One test at a time: each scale test saturates the 2-CPU runner (DuckDB uses
+  # every core), so parallel workers only contend and trip the hang guards.
+  PYTEST_ADDOPTS: -n 0
+
+jobs:
+  scale:
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: uv sync --locked --group dev --all-extras
+      - run: make test-scale