polspec 0.1.5__tar.gz

polspec-0.1.5/.github/workflows/docs.yml

@@ -0,0 +1,63 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+      - "zensical.toml"
+      - "README.md"
+      - ".github/workflows/docs.yml"
+  pull_request:
+    paths:
+      - "docs/**"
+      - "zensical.toml"
+      - "README.md"
+      - ".github/workflows/docs.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    # Runs on pull requests too, so a broken link fails before merge rather
+    # than after. Only the push to main deploys.
+    name: Build (strict)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.13"
+
+      # zensical is pinned by uv.lock through the docs group.
+      - name: Install docs tooling
+        run: uv sync --only-group docs --no-install-project
+
+      - name: Build site
+        run: uv run --no-sync zensical build --clean --strict
+
+      - name: Upload site
+        if: github.event_name == 'push'
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: site
+
+  deploy:
+    name: Deploy to GitHub Pages
+    if: github.event_name == 'push'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/configure-pages@v6
+      - uses: actions/deploy-pages@v5
+        id: deployment

polspec-0.1.5/.github/workflows/release.yml

@@ -0,0 +1,126 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  check-version:
+    name: Tag matches pyproject.toml version
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Compare tag to pyproject.toml
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          declared="$(python3 -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')"
+          if [ "$tag" != "$declared" ]; then
+            echo "Tag v$tag does not match pyproject.toml version $declared" >&2
+            exit 1
+          fi
+
+  # A tag publishes nothing unless the full test workflow is green.
+  test:
+    name: Test
+    needs: check-version
+    uses: ./.github/workflows/test.yml
+
+  build:
+    name: Build wheel (${{ matrix.os }}, ${{ matrix.target }})
+    needs: [check-version, test]
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            target: x86_64
+          - os: ubuntu-24.04-arm
+            target: aarch64
+          - os: macos-latest
+            target: aarch64
+          - os: macos-latest
+            target: x86_64
+          - os: windows-latest
+            target: x86_64
+
+    steps:
+      - uses: actions/checkout@v7
+
+      # One abi3 wheel per platform covers every supported CPython version.
+      - name: Build wheel
+        uses: PyO3/maturin-action@v1
+        with:
+          command: build
+          target: ${{ matrix.target }}
+          manylinux: auto
+          args: --release --out dist
+          sccache: "true"
+
+      - name: Upload wheel artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: wheels-${{ matrix.os }}-${{ matrix.target }}
+          path: dist/*.whl
+
+  sdist:
+    name: Build sdist
+    needs: [check-version, test]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Build sdist
+        uses: PyO3/maturin-action@v1
+        with:
+          command: sdist
+          args: --out dist
+
+      - name: Upload sdist artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: wheels-sdist
+          path: dist/*.tar.gz
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: [build, sdist]
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download all artifacts
+        uses: actions/download-artifact@v8
+        with:
+          pattern: wheels-*
+          path: dist
+          merge-multiple: true
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist
+          skip-existing: true
+
+  release:
+    name: Attach artifacts to GitHub Release
+    needs: [build, sdist]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Download all artifacts
+        uses: actions/download-artifact@v8
+        with:
+          pattern: wheels-*
+          path: dist
+          merge-multiple: true
+
+      - name: Upload to GitHub Release
+        uses: softprops/action-gh-release@v3
+        with:
+          files: |
+            dist/*.whl
+            dist/*.tar.gz

polspec-0.1.5/.github/workflows/test.yml

@@ -0,0 +1,126 @@
+name: Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_call:
+
+jobs:
+  lint:
+    name: Lint (ruff)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.13"
+
+      # The project itself is not installed: linting needs no Rust build.
+      - name: Sync dev dependencies
+        run: uv sync --no-install-project
+
+      - name: ruff check
+        run: uv run --no-sync ruff check .
+
+      - name: ruff format
+        run: uv run --no-sync ruff format --check .
+
+  rust:
+    name: Rust (fmt, clippy, test)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+
+      - name: Cache Rust build
+        uses: Swatinem/rust-cache@v2
+
+      - name: Install Python (the pyo3 build script needs an interpreter)
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.13"
+
+      - name: cargo fmt
+        run: cargo fmt --check
+
+      - name: cargo clippy
+        run: cargo clippy --release -- -D warnings
+
+      - name: cargo test
+        run: cargo test --release
+
+  test:
+    name: Test (${{ matrix.os }}, py${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.12", "3.13", "3.14"]
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache Rust build
+        uses: Swatinem/rust-cache@v2
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Sync dependencies
+        run: uv sync --all-extras
+
+      - name: Build extension (maturin develop)
+        run: uv run maturin develop --release
+
+      - name: Run tests
+        run: uv run pytest
+
+      - name: Run the worked example as a smoke test
+        run: uv run python examples/related_specs.py
+
+  polars-latest:
+    # uv.lock pins one Polars release; this job catches a break in the newest
+    # release that still satisfies the bound declared in pyproject.toml.
+    name: Test (ubuntu, py3.13, newest polars)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache Rust build
+        uses: Swatinem/rust-cache@v2
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.13"
+
+      - name: Upgrade polars within the declared bound
+        run: uv lock --upgrade-package polars
+
+      - name: Sync dependencies
+        run: uv sync --all-extras
+
+      - name: Report polars version
+        run: uv run python -c "import polars; print(polars.__version__)"
+
+      - name: Build extension (maturin develop)
+        run: uv run maturin develop --release
+
+      - name: Run tests
+        run: uv run pytest

polspec-0.1.5/.gitignore

@@ -0,0 +1,167 @@
+### Python template
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+*.pdb
+*.pyd
+
+*sandbox*

polspec-0.1.5/.pre-commit-config.yaml

@@ -0,0 +1,27 @@
+# Optional local hooks. Enable with:
+#   uv run --with pre-commit pre-commit install
+# CI runs the same ruff and cargo checks whether or not these are installed.
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-yaml
+      - id: check-toml
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.5
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: cargo-fmt
+        name: cargo fmt
+        entry: cargo fmt --
+        language: system
+        types: [rust]
+        pass_filenames: false

polspec-0.1.5/.python-version

@@ -0,0 +1 @@
+3.12

polspec-0.1.5/CHANGELOG.md

@@ -0,0 +1,113 @@
+# Changelog
+
+All notable changes to polspec are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Until 1.0, minor
+versions may break the Python API, the YAML format, and the values a given
+seed produces; see
+[Roadmap and stability](https://maxwellb13.github.io/polspec/reference/roadmap/).
+
+## [Unreleased]
+
+## [0.1.5] - 2026-09-03
+
+### Added
+
+- `python/polspec/py.typed`, so type checkers use the package's annotations.
+- `CONTRIBUTING.md`, this changelog, and a `.python-version` file.
+- `examples/related_specs.py`: a worked example of four related specs
+  (foreign keys, shared categories, rules, checks, a YAML-declared spec). It
+  runs in CI as a smoke test.
+- A release-workflow job that refuses a `vX.Y.Z` tag whose version does not
+  match `pyproject.toml`.
+- CI now runs `ruff check` with a wider rule set, `ruff format --check`, `cargo fmt --check`,
+  `cargo clippy -D warnings` and `cargo test`, tests on macOS as well as
+  Linux and Windows, and tests against the newest Polars release inside the
+  declared bound. The docs build runs strictly on pull requests.
+- Release builds now produce wheels for Linux aarch64 and macOS (x86_64 and
+  arm64) alongside Linux and Windows x86_64, plus an sdist, and only publish
+  when the test workflow is green.
+- An optional `.pre-commit-config.yaml` with ruff and cargo fmt hooks.
+- `tests/test_colspec.py` (2,000 lines, unsectioned) is split into
+  `test_generation.py`, `test_rules.py`, `test_serialization.py`,
+  `test_profiler.py`, `test_framespec.py`, `test_report.py` and
+  `test_foreign_key.py`, each with a docstring saying what it covers.
+
+### Changed
+
+- The crate version in `Cargo.toml` is a placeholder; `pyproject.toml` is the
+  only place the version is set, so `uv version --bump` works.
+- The `parquet`, `ipc` and `all` extras (all identical) are replaced by a
+  single `arrow` extra. Install with `polspec[arrow]` for the Parquet and
+  Arrow IPC sinks.
+- `polars` is bounded to `<2`; the Rust extension is coupled to a Polars
+  release line.
+- The abi3 floor is now Python 3.12, matching `requires-python`.
+- `cargo test` links again (`extension-module` is no longer an unconditional
+  crate feature; maturin enables it).
+
+### Fixed
+
+- Repository URL in package metadata pointed at the repository's old name.
+- README claimed the license was unspecified; it is MIT.
+- Documentation: `ColSpec(col_name=...)` is now described in *Declaring
+  columns*, `FrameSpec.to_python()` in *YAML specs*, the getting-started
+  example imports `date`, and the architecture page lists the `cli` module
+  and its tests.
+
+## [0.1.4] - 2026-09-02
+
+### Added
+
+- `polspec schema infer --output spec.py` and `FrameSpec.to_python()`, which
+  write a spec as an editable Python module rather than YAML.
+
+## [0.1.3] - 2026-09-01
+
+### Added
+
+- `ColSpec(col_name=...)`, so a column's name in data may differ from the
+  attribute name used to declare it.
+
+### Changed
+
+- Roadmap expanded with detailed plans for a spec registry, structured
+  validation results, and generation guardrails.
+
+## [0.1.2] - 2026-08-31
+
+Version bump only; no user-facing change.
+
+## [0.1.1] - 2026-08-31
+
+### Added
+
+- Test workflow on GitHub Actions (Linux and Windows, Python 3.12 to 3.14).
+
+### Fixed
+
+- `ColSpec.dtype` accepts a dtype class as well as an instance.
+
+## [0.1.0] - 2026-08-31
+
+First tagged release.
+
+- `ColSpec` and `FrameSpec`: declare a Polars schema with nullability,
+  bounds, string lengths, choices and weights, distributions, tags, and
+  conditional `ColRule`s.
+- `generate()` backed by a parallel Rust extension, `method="cartesian"` for
+  coverage sets, batched generation and Parquet/CSV/IPC/NDJSON sinks.
+- `validate()` collecting every violation in one Polars aggregation, with
+  column validators, multi-column `Check`s, composite uniqueness and
+  `ForeignKey`s.
+- `CatSpec` registries for shared `Enum`/`Categorical` domains.
+- YAML round-trip, `from_dataframe()` profiling, Markdown and Mermaid output.
+- CLI: `polspec schema infer`, `polspec schema new`, `polspec test`.
+- Documentation site, comparison guide, and release automation.
+
+[Unreleased]: https://github.com/MaxwellB13/polspec/compare/v0.1.5...HEAD
+[0.1.5]: https://github.com/MaxwellB13/polspec/compare/v0.1.4...v0.1.5
+[0.1.4]: https://github.com/MaxwellB13/polspec/compare/v0.1.3...v0.1.4
+[0.1.3]: https://github.com/MaxwellB13/polspec/compare/v0.1.2...v0.1.3
+[0.1.2]: https://github.com/MaxwellB13/polspec/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/MaxwellB13/polspec/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/MaxwellB13/polspec/releases/tag/v0.1.0

polspec-0.1.5/CONTRIBUTING.md

@@ -0,0 +1,85 @@
+# Contributing
+
+polspec is a Python package over a Rust extension. The Python side owns the
+vocabulary (what a column can declare and what it means); the Rust side owns
+the inner loop that fills arrays with values. See
+[Architecture](https://maxwellb13.github.io/polspec/reference/architecture/)
+for the module map.
+
+## Set up
+
+You need Python 3.12+, [uv](https://docs.astral.sh/uv/), and a Rust toolchain
+(`rustup`).
+
+```bash
+git clone https://github.com/MaxwellB13/polspec.git
+cd polspec
+uv sync --group dev          # Python deps, including maturin and pyarrow
+uv run maturin develop --release
+```
+
+`maturin develop` compiles the extension and installs the package into the
+project's virtual environment as editable. Re-run it whenever `src/` changes;
+Python-only edits are picked up immediately.
+
+## Check your change
+
+Run everything CI runs before opening a pull request:
+
+```bash
+uv run pytest                                # Python test suite
+uv run ruff check . && uv run ruff format --check .
+cargo test --release                         # Rust unit tests
+cargo clippy --release
+uv run python examples/related_specs.py      # worked example, doubles as a smoke test
+```
+
+Optionally, install the pre-commit hooks so ruff and `cargo fmt` run on
+every commit:
+
+```bash
+uv run --with pre-commit pre-commit install
+```
+
+The docs build with [zensical](https://pypi.org/project/zensical/):
+
+```bash
+uv run --group docs zensical serve           # live preview
+uv run --group docs zensical build --strict  # what the docs workflow runs
+```
+
+## Conventions
+
+- **Generate and validate must agree.** Anything `generate()` produces,
+  `validate()` must accept. `tests/test_roundtrip.py` pins that property. A
+  known gap is recorded once in
+  [`docs/reference/limitations.md`](docs/reference/limitations.md) and once as
+  an `xfail(strict=True)` test, so fixing it forces the docs to be updated.
+- **Error messages name the fix.** Say what was declared, what was expected,
+  and what to change. Look at the existing `ValueError`s in
+  `python/polspec/spec.py` for the register.
+- **Two tables must match.** The distribution parameter aliases live in both
+  `python/polspec/distributions.py` and `DistKind::from_spec` in
+  `src/lib.rs`. Change them together.
+- **Docs are part of the change.** A new field, option or CLI flag lands with
+  its guide page and a `CHANGELOG.md` entry under *Unreleased*.
+- Commit messages follow the existing `type: summary` style
+  (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `ci:`, `chore:`).
+
+## Releasing
+
+The version lives in exactly one place: `project.version` in
+`pyproject.toml`. maturin prefers it over the crate version in `Cargo.toml`,
+which is a placeholder.
+
+1. Bump it and refresh the lock file:
+
+   ```bash
+   uv version --bump patch   # or minor / major
+   uv lock
+   ```
+
+   Then move the *Unreleased* section of `CHANGELOG.md` under the new version.
+2. Commit, then tag `vX.Y.Z` and push the tag.
+3. The release workflow checks the tag matches `pyproject.toml`, builds wheels,
+   publishes to PyPI, and attaches the wheels to a GitHub release.