useful-views 0.1.0__tar.gz

useful_views-0.1.0/.gitattributes

@@ -0,0 +1,4 @@
+# The test data is compared byte for byte and pinned by SHA-256, so git must
+# never change its line endings (core.autocrlf on Windows would).
+tests/data/** -text
+*.parquet binary

useful_views-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,91 @@
+name: CI
+
+# Runs on every push to main or dev, on every pull request, and by hand
+# (Actions tab > CI > Run workflow).
+on:
+  push:
+    branches: [main, dev]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: test (${{ matrix.os }}, Python ${{ matrix.python }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v6
+      - name: Install
+        run: uv sync --locked --python ${{ matrix.python }}
+      - name: Test
+        run: uv run --locked pytest -n auto
+
+  lowest-dependencies:
+    name: test (oldest supported pyarrow)
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v6
+      - name: Install with pyarrow 16
+        run: |
+          uv venv --python 3.11
+          echo "pyarrow==16.0.0" > constraints.txt
+          # The dev group's bounds (pyproject.toml), with pyarrow held at the oldest supported.
+          uv pip install -c constraints.txt -e . "pytest>=8" "pytest-xdist>=3" "polars>=1.20" "frictionless[pandas]>=5.18,<6"
+      - name: Test
+        run: .venv/bin/python -m pytest -n auto
+
+  package:
+    name: build and check the package
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v6
+      - name: Build
+        run: uv build
+      - name: Check metadata
+        run: uvx twine check --strict dist/*
+      - name: Install the wheel and build the real example with it
+        # Downloads the pinned example from GitHub, so it also checks the
+        # pinned tag and checksums, and that the wheel holds its templates.
+        run: |
+          uv venv --python 3.11 /tmp/wheel-env
+          uv pip install --python /tmp/wheel-env/bin/python dist/*.whl polars
+          cd /tmp
+          /tmp/wheel-env/bin/useful-views --version
+          /tmp/wheel-env/bin/useful-views example pwt smoke
+          /tmp/wheel-env/bin/useful-views -C smoke sync
+          /tmp/wheel-env/bin/useful-views -C smoke check
+          /tmp/wheel-env/bin/useful-views -C smoke cookbook
+          /tmp/wheel-env/bin/useful-views -C smoke cookbook --check
+          test -f smoke/AGENTS.md
+
+  # One check that is green only when every job above is, for branch
+  # protection to require (instead of naming each job of the matrix).
+  all-green:
+    name: all checks passed
+    if: always()
+    needs: [test, lowest-dependencies, package]
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Fail unless every job passed
+        if: contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') || contains(needs.*.result, 'skipped')
+        run: exit 1
+      - name: Every job passed
+        run: echo "All jobs passed."

useful_views-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,110 @@
+name: CI Docs
+
+# Builds on every pull request (as a check, without publishing), and builds
+# and publishes to GitHub Pages on every push to main. Also runs by hand
+# (Actions tab > CI Docs > Run workflow).
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build-docs:
+    name: "Build Docs"
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0 # Full history for accurate page timestamps
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      - name: Install package and dependencies
+        run: |
+          python -m pip install uv
+          uv sync --locked --group docs
+
+      - name: Check the generated reference pages are up to date
+        run: |
+          uv run python scripts/generate_docs.py
+          git diff --exit-code user_guide/reference
+
+      - name: Set up Quarto
+        uses: quarto-dev/quarto-actions/setup@v2
+
+      - name: Build docs
+        run: uv run --group docs great-docs build
+
+      - name: Save docs artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: docs-html
+          path: great-docs/_site
+          include-hidden-files: true
+
+      - name: How to preview this build locally
+        if: github.event_name == 'pull_request'
+        run: uv run --group docs great-docs ci notice --run ${{ github.run_id }} --pr ${{ github.event.number }}
+
+      - name: Upload build timings
+        uses: actions/upload-artifact@v7
+        with:
+          name: build-timings
+          path: great-docs/_site/build-timings.json
+
+  publish-docs:
+    name: "Publish Docs"
+    runs-on: ubuntu-latest
+    needs: "build-docs"
+    if: github.ref == 'refs/heads/main'
+    # One deployment at a time; a newer one waits instead of cancelling.
+    concurrency:
+      group: pages
+      cancel-in-progress: false
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/download-artifact@v7
+        with:
+          name: docs-html
+          path: great-docs/_site
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: great-docs/_site
+          include-hidden-files: true
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5
+
+  preview-docs:
+    name: "Preview Docs"
+    runs-on: ubuntu-latest
+    needs: "build-docs"
+    if: github.event_name == 'pull_request'
+    permissions:
+      pull-requests: write
+    steps:
+      # Post (and keep updated) a sticky PR comment with the local-preview
+      # command, pinned to this run so it reproduces the build under review.
+      # Runs the released great-docs via pipx (no install step needed); kept as
+      # its own minimal job so the docs build never holds a pull-requests:write
+      # token. continue-on-error so fork PRs (read-only token) don't fail the run.
+      - name: Post preview instructions to the PR
+        continue-on-error: true
+        run: pipx run great-docs ci pr-comment --run ${{ github.run_id }} --pr ${{ github.event.number }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

useful_views-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,78 @@
+name: Release
+
+# Publishes a release to PyPI when a version tag is pushed:
+#
+#   git tag v0.1.0 && git push origin v0.1.0
+#
+# Before the first release, PyPI must trust this workflow: on pypi.org,
+# Your projects > Publishing > Add a new pending publisher, with owner
+# jameshorine, repository useful-views, workflow release.yml and
+# environment pypi. No password or API token is stored anywhere.
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build and check
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v6
+      - name: The tag must match the version in pyproject.toml
+        run: |
+          version=$(uv run --no-project python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
+          if [ "v$version" != "$GITHUB_REF_NAME" ]; then
+            echo "Tag $GITHUB_REF_NAME does not match version $version in pyproject.toml"
+            exit 1
+          fi
+      - name: Build
+        run: uv build
+      - name: Check metadata
+        run: uvx twine check --strict dist/*
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    environment:
+      name: pypi
+      url: https://pypi.org/project/useful-views/
+    permissions:
+      id-token: write  # Trusted Publishing: PyPI checks who is publishing
+    steps:
+      - uses: actions/download-artifact@v7
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: GitHub release
+    needs: publish
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/download-artifact@v7
+        with:
+          name: dist
+          path: dist/
+      - name: Create the release, with this version's CHANGELOG section as its notes
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          version="${GITHUB_REF_NAME#v}"
+          awk -v v="$version" '$0 ~ "^## "v" " {on=1; next} /^## / {on=0} on' CHANGELOG.md > notes.md
+          gh release create "$GITHUB_REF_NAME" dist/* --title "useful-views $version" --notes-file notes.md

useful_views-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.DS_Store
+.venv/
+__pycache__/
+.pytest_cache/
+*.egg-info/
+dist/
+build/
+great-docs/

useful_views-0.1.0/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+All notable changes to useful-views are recorded here. Versions follow
+[semantic versioning](https://semver.org/); while the version starts with
+0, a minor release may change behaviour.
+
+## 0.1.0 (2026-10-15)
+
+The first release: the minimum version.
+
+- A fixed project structure: `raw/`, `recipes/`, `work/`, `useful-views/`,
+  a generated `datapackage.json` and a generated catalog,
+  `useful-views/README.md`.
+- `init`, `new_recipe`, `run`, `check` and `sync`, as Python functions and
+  as the `useful-views` command, and `root` (Python only). `init` also writes
+  an `AGENTS.md` for AI coding assistants, and refuses the home folder or the
+  top of a drive without `--force`.
+- `example` downloads a ready-to-run example project from the
+  useful-views-data repository, pinned to a tag and checked by SHA-256.
+- `check` reports what `run` and `sync` would refuse (`refused`, with the
+  rule number) and recipes changed since they last ran (`out-of-date`).
+  `sync` checks every recipe before changing anything and lists every
+  problem at once.
+- `useful-views cookbook` writes `cookbook.json`, the ledger of the recipes a
+  project uses, in run order (format version 1; file hashes are planned);
+  `cookbook --check` verifies it in CI without needing the data, and `check`
+  reports `stale-cookbook` (and `stale-catalog` for a hand-edited catalog).
+- For scripts and AI tools: `--json` on every command (with `warnings` and one
+  error shape), `-C <path>`, `useful-views rules` (and `useful_views.RULES`),
+  exit codes in `--help`, and errors that carry the recipe, rule, file and
+  step (`to_dict()`). Progress lines go to standard error.
+- One command at a time: `run`, `sync` and `cookbook` hold a lock on the
+  project. On the command line, SIGTERM and SIGHUP stop the running step and
+  clean up as Ctrl-C does. `run` warns about recipes downstream of it, and a
+  `sync` that stops partway removes the views it left out of date.
+- Recipes are folders with a `recipe.toml` and numbered Python step files;
+  every view records the recipe, inputs and steps that made it.
+- `sync` makes the views match the recipe folders, like `uv sync`: it runs
+  what is missing or changed, upstream first, and removes what is no longer
+  declared.
+- Schemas are read with pyarrow; the generated `datapackage.json` passes
+  `frictionless validate`.
+- A documentation site built with great-docs: getting started, concepts
+  (projects, steps, recipes, running, records and the cookbook), a guide for
+  AI tools, a generated command-line and rules reference, an API reference
+  from the docstrings, and `llms.txt` and a hand-written `SKILL.md` for
+  coding agents.
+- Tested on Python 3.11 to 3.14.

useful_views-0.1.0/CITATION.cff

@@ -0,0 +1,22 @@
+cff-version: 1.2.0
+message: "If you use useful-views in your research, please cite it as below."
+type: software
+title: "useful-views: Documented derived tables for data projects"
+abstract: >-
+  A Python package that gives a data project a fixed structure, in
+  which every derived table (a "useful view") records the recipe, inputs and
+  steps that made it, in a standard Data Package.
+authors:
+  - family-names: Horine
+    given-names: James
+version: 0.1.0
+date-released: "2026-10-15"
+license: MIT
+repository-code: "https://github.com/jameshorine/useful-views"
+url: "https://jameshorine.github.io/useful-views/"
+keywords:
+  - research data
+  - reproducibility
+  - data provenance
+  - data package
+  - python

useful_views-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 James Horine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.