openstatspec 0.1.0__tar.gz

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

@@ -0,0 +1,140 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+env:
+  OPENSTATSPEC_SPECIFICATION_DIR: ${{ github.workspace }}/openstatspec-specification
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v7
+      - name: Checkout OpenStatSpec specification fixtures
+        uses: actions/checkout@v7
+        with: &specification-checkout
+          repository: OpenStatSpec/specification
+          ref: 6b9d1fc38f2f083c0ac5cf1c64874a6d07b95045
+          path: openstatspec-specification
+      - name: Checkout required SPSS engine
+        uses: actions/checkout@v7
+        with: &engine-checkout
+          repository: TonisOrmisson/pyspssio
+          ref: e069adf33c70bcd9e8e6ee495106479463a84fa2
+          path: openstatspec-pyspssio
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install ./openstatspec-pyspssio
+      - run: python -m pip install -e ".[dev]"
+      - run: python -m pytest -m "not services"
+
+  package-smoke:
+    name: Build and install package artifact
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Checkout OpenStatSpec specification fixtures
+        uses: actions/checkout@v7
+        with: *specification-checkout
+      - name: Checkout required SPSS engine
+        uses: actions/checkout@v7
+        with: *engine-checkout
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade pip build
+      - run: python -m build
+      - run: python -m venv /tmp/openstatspec-wheel-smoke
+      - run: /tmp/openstatspec-wheel-smoke/bin/python -m pip install ./openstatspec-pyspssio
+      - run: /tmp/openstatspec-wheel-smoke/bin/python -m pip install dist/*.whl
+      - run: /tmp/openstatspec-wheel-smoke/bin/openstatspec capabilities
+
+  postgres-integration:
+    name: PostgreSQL ${{ matrix.postgres }} integration
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        postgres: ["17", "18"]
+    services:
+      postgres:
+        image: postgres:${{ matrix.postgres }}
+        ports: ["5432:5432"]
+        env:
+          POSTGRES_DB: openstatspec
+          POSTGRES_USER: openstatspec
+          POSTGRES_PASSWORD: openstatspec
+        options: >-
+          --health-cmd "pg_isready -U openstatspec -d openstatspec"
+          --health-interval 10s --health-timeout 5s --health-retries 5
+    env:
+      OPENSTATSPEC_POSTGRES_URL: postgresql+psycopg://openstatspec:openstatspec@localhost:5432/openstatspec
+    steps: &sql-test-steps
+      - uses: actions/checkout@v7
+      - name: Checkout OpenStatSpec specification fixtures
+        uses: actions/checkout@v7
+        with: *specification-checkout
+      - name: Checkout required SPSS engine
+        uses: actions/checkout@v7
+        with: *engine-checkout
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install ./openstatspec-pyspssio
+      - run: python -m pip install -e ".[dev,sql]"
+      - run: python -m pytest -m services
+
+  mysql-integration:
+    name: MySQL ${{ matrix.mysql }} integration
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        mysql: ["8.4", "9.7"]
+    services:
+      mysql:
+        image: mysql:${{ matrix.mysql }}
+        ports: ["3306:3306"]
+        env:
+          MYSQL_DATABASE: openstatspec
+          MYSQL_USER: openstatspec
+          MYSQL_PASSWORD: openstatspec
+          MYSQL_ROOT_PASSWORD: root
+        options: >-
+          --health-cmd "mysqladmin ping -h 127.0.0.1 -uopenstatspec -popenstatspec"
+          --health-interval 10s --health-timeout 5s --health-retries 10
+    env:
+      OPENSTATSPEC_MYSQL_URL: mysql+pymysql://openstatspec:openstatspec@localhost:3306/openstatspec
+    steps: *sql-test-steps
+
+  mariadb-integration:
+    name: MariaDB ${{ matrix.mariadb }} integration
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        mariadb: ["11.4", "11.8", "12.3"]
+    services:
+      mariadb:
+        image: mariadb:${{ matrix.mariadb }}
+        ports: ["3306:3306"]
+        env:
+          MARIADB_DATABASE: openstatspec
+          MARIADB_USER: openstatspec
+          MARIADB_PASSWORD: openstatspec
+          MARIADB_ROOT_PASSWORD: root
+        options: >-
+          --health-cmd "healthcheck.sh --connect --innodb_initialized"
+          --health-interval 10s --health-timeout 5s --health-retries 10
+    env:
+      OPENSTATSPEC_MARIADB_URL: mysql+pymysql://openstatspec:openstatspec@localhost:3306/openstatspec
+    steps: *sql-test-steps

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

@@ -0,0 +1,66 @@
+name: Release
+
+env:
+  OPENSTATSPEC_SPECIFICATION_DIR: ${{ github.workspace }}/openstatspec-specification
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Checkout normative specification fixtures
+        uses: actions/checkout@v7
+        with:
+          repository: OpenStatSpec/specification
+          ref: 6b9d1fc38f2f083c0ac5cf1c64874a6d07b95045
+          path: openstatspec-specification
+      - name: Checkout required SPSS engine
+        uses: actions/checkout@v7
+        with:
+          repository: TonisOrmisson/pyspssio
+          ref: e069adf33c70bcd9e8e6ee495106479463a84fa2
+          path: openstatspec-pyspssio
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.13"
+      - run: python -m pip install --upgrade pip build
+      - name: Verify required SPSS engine is publicly installable
+        run: >-
+          python -m pip download --only-binary=:all: --no-deps
+          --dest /tmp/openstatspec-engine-release
+          openstatspec-pyspssio==0.5.1.post2
+      - run: python -m pip install ./openstatspec-pyspssio
+      - run: python -m pip install -e ".[dev]"
+      - run: python -m pytest -m "not services"
+      - run: python -m build
+      - run: python -m venv /tmp/openstatspec-release-smoke
+      - run: /tmp/openstatspec-release-smoke/bin/python -m pip install ./openstatspec-pyspssio
+      - run: /tmp/openstatspec-release-smoke/bin/python -m pip install dist/*.whl
+      - run: /tmp/openstatspec-release-smoke/bin/openstatspec capabilities
+      - uses: actions/upload-artifact@v7
+        with:
+          name: python-distributions
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/openstatspec
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: python-distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

openstatspec-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+.pytest_cache/
+*.py[cod]
+.venv/
+build/
+dist/
+*.egg-info/

openstatspec-0.1.0/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to this reference implementation are documented here.
+
+## 0.1.0 — unreleased
+
+First public reference implementation of the OpenStatSpec strict wide-table
+SPSS profile.
+
+### Included
+
+- Import of unencrypted SAV and ZSAV sources into one dedicated wide SQL table
+  and its metadata catalog.
+- Export of supported dataset semantics to SAV and ZSAV.
+- SQLite, PostgreSQL, MySQL, and MariaDB profiles, including service-backed
+  PostgreSQL 17/18, MySQL 8.4/9.7, and MariaDB 11.4/11.8/12.3 CI coverage.
+- Preflight checks for target profile limits, atomic imports, validation, a
+  command-line interface, and machine-readable capability and loss reports.
+
+### Important boundaries
+
+- This release promises semantic round-trip equivalence only for supported
+  features; it never promises byte-identical SAV/ZSAV output.
+- The adapter requires explicit `allow_loss` consent before exporting known
+  unsupported or lossy dictionary semantics.
+- Multiple-response sets, variable alignment, variable sets, and custom
+  attributes have explicit capability diagnostics; see the SAV profile.
+- Encrypted SPSS files are not supported.

openstatspec-0.1.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: openstatspec
+Version: 0.1.0
+Summary: Reference adapter for the OpenStatSpec relational contract
+Author: OpenStatSpec
+License: Apache-2.0
+Requires-Python: >=3.11
+Requires-Dist: openstatspec-pyspssio==0.5.1.post2
+Requires-Dist: pandas>=2.2
+Requires-Dist: sqlalchemy>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Provides-Extra: sql
+Requires-Dist: psycopg[binary]>=3.2; extra == 'sql'
+Requires-Dist: pymysql>=1.1; extra == 'sql'
+Description-Content-Type: text/markdown
+
+# OpenStatSpec Python
+
+The reference Python implementation of the OpenStatSpec specification.
+
+This package implements the specification; it does not define or extend it.
+The normative model lives in the `OpenStatSpec/specification` repository.
+
+## Boundaries
+
+For each supported import, one source dataset becomes one dedicated wide SQL
+table. Cases are rows and source variables are physical SQL columns. The
+singular UUID-keyed tables from the specification (`dataset`, `variable`,
+`operation`, `fidelity_event`, and related metadata tables) are the public
+catalog contract. Historical `*_catalog` tables are an internal compatibility
+layer for the current exporter and are not the standard database interface.
+The adapter does not reshape data, create EAV
+or long-form tables, or harmonize studies or waves.
+
+Unsupported source features, SQL targets, or export paths fail explicitly.
+There is no silent truncation, type conversion, metadata loss, or partial
+import.
+
+## Package layout
+
+- `openstatspec.core`: pure standard concepts, validation, versions,
+  capabilities, and loss reports.
+- `openstatspec.sql`: database connection and wide-table/catalog operations.
+- `openstatspec.spss`: SAV/ZSAV adapter boundary.
+
+## Intended workflow
+
+```python
+from openstatspec import export_sav, import_sav
+
+import_sav("responses.sav", database_url="postgresql+psycopg://user:password@server/database", dataset_id="responses-2026")
+export_sav(database_url="postgresql+psycopg://user:password@server/database", dataset_id="responses-2026", destination="responses-roundtrip.sav")
+```
+
+```text
+openstatspec import responses.sav --database-url postgresql+psycopg://... --dataset-id responses-2026
+openstatspec export --database-url postgresql+psycopg://... --dataset-id responses-2026 --output responses-roundtrip.sav
+```
+
+## 0.1.0 support status
+
+The adapter requires `openstatspec-pyspssio==0.5.1.post2` as its sole SPSS
+engine. Its import module remains `pyspssio`; the exact source commit is recorded
+in operation metadata. There is no fallback reader or writer. It supports unencrypted SAV and ZSAV import and
+SAV/ZSAV export for the semantics exposed by that engine. SQLite is the local
+reference path.
+PostgreSQL, MySQL, and MariaDB are each covered by separate service-backed CI
+conformance checks. Use these explicit SQLAlchemy URLs:
+
+- SQLite: `sqlite:///dataset.sqlite`
+- PostgreSQL: `postgresql+psycopg://user:password@host/database`
+- MySQL/MariaDB: `mysql+pymysql://user:password@host/database`
+
+Run `openstatspec capabilities` before an integration to inspect the
+machine-readable feature matrix. Export is deliberately strict: if known
+dictionary semantics cannot be reproduced, it stops until you pass the exact
+diagnostic code with `--allow-loss`. This avoids silent loss while making an
+intentional lossy export auditable.
+
+The matrix is also available to Python callers as
+`openstatspec.capability_matrix()`. It distinguishes supported semantics from
+unobservable and fail-closed paths; see the SAV profile for the exact
+the openstatspec-pyspssio boundary.
+
+See [the SAV profile](docs/sav-profile.md) for feature boundaries and
+[release readiness](docs/release-readiness.md) for the pre-tag checklist.
+Read [third-party notices](THIRD_PARTY_NOTICES.md) before distributing a
+bundled application: the required engine includes IBM redistributables under
+separate terms.

openstatspec-0.1.0/README.md

@@ -0,0 +1,73 @@
+# OpenStatSpec Python
+
+The reference Python implementation of the OpenStatSpec specification.
+
+This package implements the specification; it does not define or extend it.
+The normative model lives in the `OpenStatSpec/specification` repository.
+
+## Boundaries
+
+For each supported import, one source dataset becomes one dedicated wide SQL
+table. Cases are rows and source variables are physical SQL columns. The
+singular UUID-keyed tables from the specification (`dataset`, `variable`,
+`operation`, `fidelity_event`, and related metadata tables) are the public
+catalog contract. Historical `*_catalog` tables are an internal compatibility
+layer for the current exporter and are not the standard database interface.
+The adapter does not reshape data, create EAV
+or long-form tables, or harmonize studies or waves.
+
+Unsupported source features, SQL targets, or export paths fail explicitly.
+There is no silent truncation, type conversion, metadata loss, or partial
+import.
+
+## Package layout
+
+- `openstatspec.core`: pure standard concepts, validation, versions,
+  capabilities, and loss reports.
+- `openstatspec.sql`: database connection and wide-table/catalog operations.
+- `openstatspec.spss`: SAV/ZSAV adapter boundary.
+
+## Intended workflow
+
+```python
+from openstatspec import export_sav, import_sav
+
+import_sav("responses.sav", database_url="postgresql+psycopg://user:password@server/database", dataset_id="responses-2026")
+export_sav(database_url="postgresql+psycopg://user:password@server/database", dataset_id="responses-2026", destination="responses-roundtrip.sav")
+```
+
+```text
+openstatspec import responses.sav --database-url postgresql+psycopg://... --dataset-id responses-2026
+openstatspec export --database-url postgresql+psycopg://... --dataset-id responses-2026 --output responses-roundtrip.sav
+```
+
+## 0.1.0 support status
+
+The adapter requires `openstatspec-pyspssio==0.5.1.post2` as its sole SPSS
+engine. Its import module remains `pyspssio`; the exact source commit is recorded
+in operation metadata. There is no fallback reader or writer. It supports unencrypted SAV and ZSAV import and
+SAV/ZSAV export for the semantics exposed by that engine. SQLite is the local
+reference path.
+PostgreSQL, MySQL, and MariaDB are each covered by separate service-backed CI
+conformance checks. Use these explicit SQLAlchemy URLs:
+
+- SQLite: `sqlite:///dataset.sqlite`
+- PostgreSQL: `postgresql+psycopg://user:password@host/database`
+- MySQL/MariaDB: `mysql+pymysql://user:password@host/database`
+
+Run `openstatspec capabilities` before an integration to inspect the
+machine-readable feature matrix. Export is deliberately strict: if known
+dictionary semantics cannot be reproduced, it stops until you pass the exact
+diagnostic code with `--allow-loss`. This avoids silent loss while making an
+intentional lossy export auditable.
+
+The matrix is also available to Python callers as
+`openstatspec.capability_matrix()`. It distinguishes supported semantics from
+unobservable and fail-closed paths; see the SAV profile for the exact
+the openstatspec-pyspssio boundary.
+
+See [the SAV profile](docs/sav-profile.md) for feature boundaries and
+[release readiness](docs/release-readiness.md) for the pre-tag checklist.
+Read [third-party notices](THIRD_PARTY_NOTICES.md) before distributing a
+bundled application: the required engine includes IBM redistributables under
+separate terms.

openstatspec-0.1.0/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,34 @@
+# Third-party notices
+
+OpenStatSpec Python source code is licensed under Apache-2.0. Its required
+SPSS engine is a separate third-party distribution:
+
+| Component | Version | Applicable terms |
+| --- | --- | --- |
+| openstatspec-pyspssio (import module `pyspssio`) | 0.5.1.post2, source commit e069adf33c70bcd9e8e6ee495106479463a84fa2 | MIT for the Python wrapper, except for its IBM I/O Module files |
+| IBM I/O Modules for IBM SPSS Statistics Data Files | bundled by openstatspec-pyspssio | IBM International License Agreement for Non-Warranted Programs and the accompanying License Information / REDIST files |
+
+pyspssio ships the IBM licence, redistribution list, and third-party notices
+inside its installed distribution, normally under pyspssio/spssio/license/.
+Those materials are authoritative. They are not relicensed by this repository's
+Apache-2.0 licence.
+
+## Distribution responsibility
+
+OpenStatSpec requires the exact openstatspec-pyspssio release declared in pyproject.toml; it has no alternate SPSS engine. This
+repository does not vendor or alter the IBM binaries. Anyone who
+distributes an application bundle containing the installed engine must review
+and comply with the IBM materials supplied with that engine. In particular, the
+IBM redistribution conditions require object-code-only distribution as part of
+the distributor's application, preservation of notices, restrictions on use
+and onward distribution, and end-user terms that protect IBM at least as much
+as the IBM agreement. They also include other conditions, including support,
+indemnity, and trademark restrictions.
+
+Do not remove the pyspssio licence directory or notices from a bundled
+installation. Do not describe IBM or its trademarks as endorsing OpenStatSpec.
+
+This is a factual third-party notice, not legal advice. A party preparing a
+binary or application distribution should have its own legal review of the
+exact LA_en, REDIST, and notices files installed with the selected pyspssio
+release.

openstatspec-0.1.0/docs/architecture.md

@@ -0,0 +1,14 @@
+# Architecture
+
+`openstatspec.core` contains only pure concepts defined by the standard:
+versioning, validation concepts, capability declarations, and loss reports.
+`openstatspec.sql` owns database-target and strict wide-table/catalog work.
+`openstatspec.spss` owns SAV/ZSAV source and export behavior.
+
+The public workflow remains database-connected. A supported import receives an
+SPSS source, a database URL or connection, and a dataset identity. It creates
+one dedicated wide data table plus separate catalog metadata. Export identifies
+the database dataset and writes a supported SPSS file.
+
+No layer may silently substitute EAV, long-form views, JSON, pivots, automatic
+harmonization, truncation, or partial import for the standard's strict mapping.

openstatspec-0.1.0/docs/pyspssio-spike.md

@@ -0,0 +1,45 @@
+# pyspssio engine assessment
+
+**Status:** selected as the required, sole Python SPSS engine.
+
+OpenStatSpec Python requires `openstatspec-pyspssio==0.5.1.post2`, built from
+TonisOrmisson/pyspssio commit `e069adf33c70bcd9e8e6ee495106479463a84fa2`, for both SAV and ZSAV import and
+export. There is no alternate SPSS engine.
+
+## Probe result
+
+A local round trip created both .sav and .zsav, then read each back. The
+following metadata survived in the probe:
+
+- UTF-8 encoding, variable names and storage widths;
+- variable and value labels;
+- numeric user-missing values;
+- measurement levels, roles, alignments and display widths;
+- file attributes and variable attributes;
+- case-weight variable;
+- a dichotomous multiple-response set.
+
+The public API used was read_metadata(), read_sav(), and write_sav().
+
+## Required conformance work
+
+This engine selection does not relax the OpenStatSpec profile. Every claimed
+feature must have a hermetic round-trip fixture. Current engine/API questions
+that require explicit tests or upstream work include:
+
+1. variable-set round trips;
+2. independent print and write formats;
+3. ordered document text;
+4. legacy code-page files and unusual very-long-string boundaries beyond the covered 340-byte UTF-8 fixture.
+
+Until a feature is proved, the adapter must report it as unsupported rather
+than silently losing it.
+
+## Licence boundary
+
+The pyspssio wrapper is MIT, except for IBM I/O Module files bundled in its
+wheel. Those redistributables have their own IBM terms. pyspssio is a required
+runtime dependency, not an optional plugin; OpenStatSpec does not copy or
+modify its IBM binaries. See [third-party notices](../THIRD_PARTY_NOTICES.md)
+for the distribution boundary and the location of the authoritative installed
+terms.

openstatspec-0.1.0/docs/release-readiness.md

@@ -0,0 +1,64 @@
+# 0.1.0 release readiness
+
+This page records the expected release contract, not a publication event.
+Creating a version tag remains a separate maintainer action.
+
+## Supported workflow
+
+For a supported unencrypted SAV or ZSAV source, the adapter imports one source
+dataset into exactly one dedicated wide data table plus the complete singular,
+UUID-keyed normative catalog from the SPSS profile. It can validate that
+representation and export it back to SAV or ZSAV. Historical `*_catalog`
+tables remain private compatibility storage and do not replace the normative
+database contract.
+
+## SQL profiles
+
+| Profile | Connection URL | Verification |
+| --- | --- | --- |
+| SQLite | `sqlite:///dataset.sqlite` | Python 3.11–3.14 local reference jobs |
+| PostgreSQL | `postgresql+psycopg://…` | PostgreSQL 17 and 18 service jobs |
+| MySQL | `mysql+pymysql://…` | MySQL 8.4 and 9.7 service jobs |
+| MariaDB | `mysql+pymysql://…` | MariaDB 11.4, 11.8, and 12.3 service jobs |
+
+Separate service matrices test the shared MySQL/MariaDB profile contract while
+retaining distinct active-server identities and version claims. This does not
+claim coverage for every server configuration. The machine-readable capability
+declaration reports both the theoretical profile boundaries and effective
+limits observed from the active connection.
+
+## Export-loss policy
+
+`capability_matrix()` and `openstatspec capabilities` expose the current
+feature state. Before export, the adapter combines source and writer
+diagnostics. An export with known loss fails unless the caller passes the
+relevant diagnostic codes through `allow_loss` or repeats `--allow-loss CODE`
+in the CLI.
+
+The concrete pyspssio boundaries are documented in the [SAV profile](sav-profile.md).
+The pinned OpenStatSpec fork preserves document text, file labels, legacy
+compatible names, separate print/write formats, variable sets,
+multiple-response sets, alignment, scalar attributes, and ordered
+custom-attribute arrays. Non-UTF-8 output requires an explicit matching locale;
+otherwise the strict export policy reports and blocks the loss. A caller
+that supplies consent for an available loss code receives the
+machine-readable loss report with the export result.
+
+## Maintainer checks before tagging
+
+1. Publish the pinned `openstatspec-pyspssio==0.5.1.post2` engine distribution
+   first and confirm that a clean environment can download it from PyPI. The
+   main package has no fallback SPSS engine.
+2. Run `python -m pytest`.
+3. Confirm the GitHub Actions matrix is green for PostgreSQL 17/18, MySQL
+   8.4/9.7, and MariaDB 11.4/11.8/12.3.
+4. Build with `python -m build` and install the generated wheel in a clean
+   environment.
+5. Confirm `openstatspec capabilities` reflects the intended support boundary.
+6. Review this document, the README, and CHANGELOG for accurate scope.
+
+The tag-triggered release workflow repeats the non-service test suite, builds
+the distributions, and installs the wheel with the exact required SPSS engine
+in a clean environment before it can reach the protected `pypi` environment.
+It fails closed if that exact engine version is not already downloadable from
+PyPI, preventing publication of an uninstallable OpenStatSpec release.

openstatspec-0.1.0/docs/sav-profile.md

@@ -0,0 +1,57 @@
+# SAV/ZSAV profile status
+
+The Python adapter implements a strict, source-faithful wide-table mapping.
+One SAV or ZSAV dataset becomes one table; every source variable is a physical
+column and __case_ordinal preserves case order. The adapter never pivots,
+chunks, or creates a cell/EAV representation.
+
+## SPSS engine
+
+OpenStatSpec Python requires `openstatspec-pyspssio==0.5.1.post2` as its sole
+SPSS engine. There is no fallback reader or writer. The engine reads
+unencrypted .sav and .zsav files, and writes both formats through the same implementation.
+
+## Verified SQL profiles
+
+SQLite has a local reference fixture. PostgreSQL, MySQL, and MariaDB have
+separate service-backed conformance checks in GitHub Actions that import,
+validate, and export the supported fixture. MySQL 8.4 and MariaDB 11.4 exercise
+the shared profile contract; this does not claim coverage for every server
+configuration. An import that exceeds a target's strict single-table column
+limit fails before it creates a dataset.
+
+## Fidelity contract
+
+The adapter must preserve and validate only the source semantics that the
+selected engine or the adapter's narrow, fail-closed type-6 document bridge exposes and that a conformance fixture proves. Unsupported
+semantics fail explicitly; they never silently disappear. Encryption and
+byte-identical reproduction are outside the contract. The contract is semantic
+equivalence of supported values, order, and dictionary metadata.
+
+## Engine capability boundary
+
+The `openstatspec capabilities` command and the
+`openstatspec.capability_matrix()` function are the machine-readable declaration
+of this boundary. It records the pinned source commit and installed engine version, and the adapter stores the same identity in every import and export operation record. The matrix deliberately distinguishes a supported feature from a feature that the underlying engine cannot observe or write faithfully.
+
+| SPSS semantic | Pinned pyspssio status | Behaviour |
+| --- | --- | --- |
+| File label | Supported through openstatspec-pyspssio | The adapter persists it in the dataset catalog and writes it through the IBM I/O identifier-string API. |
+| Very-long UTF-8 strings | Supported | The SAV and ZSAV fixture preserves a 340-byte, multi-byte UTF-8 string through the SQL catalog and back. |
+| Ordered document text | Supported through a strict type-6 dictionary bridge plus the pinned fork | Import stores normalized document rows; export creates a temporary UTF-8 SAV source and has IBM I/O copy the records into SAV or ZSAV without invalidating ZSAV dictionary offsets. |
+| Print and write formats independently | Supported as raw IBM I/O tuples | The adapter stores both tuples separately and writes them without collapsing either value. |
+| Variable sets | Supported through raw IBM I/O | The adapter stores source sets in the extension catalog and writes them through the raw dictionary setter. Invalid target definitions fail before data are written. |
+| Legacy compatible variable names | Supported through the strict dictionary bridge | The adapter stores the short-name mapping and rewrites both the fixed variable record and long-name extension before export. |
+| Source encoding | UTF-8 by default; legacy code page with an explicit OS locale | The caller supplies legacy_locale and the writer verifies that the emitted encoding matches the stored source encoding. Without it, export fails before output creation. |
+| Custom attributes with one value | Supported | File and variable scalar attributes round trip through the normalized attribute catalog. |
+| Custom-attribute value arrays | Supported through raw IBM I/O | The adapter represents an array as IBM SPSS `Name[1]`, `Name[2]`, … members and reconstructs the ordered array in the normalized catalog. |
+
+The remaining loss codes can be supplied through `allow_loss` only when a
+caller intentionally accepts the documented, machine-readable loss report.
+
+## Distribution
+
+The required engine includes IBM I/O Module redistributables under terms that
+are separate from OpenStatSpec's Apache-2.0 source licence. See
+[third-party notices](../THIRD_PARTY_NOTICES.md) before distributing a bundled
+application.

openstatspec-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "openstatspec"
+version = "0.1.0"
+description = "Reference adapter for the OpenStatSpec relational contract"
+readme = "README.md"
+requires-python = ">=3.11"
+license = {text = "Apache-2.0"}
+authors = [{name = "OpenStatSpec"}]
+dependencies = ["SQLAlchemy>=2.0", "pandas>=2.2", "openstatspec-pyspssio==0.5.1.post2"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+sql = ["psycopg[binary]>=3.2", "PyMySQL>=1.1"]
+
+[project.scripts]
+openstatspec = "openstatspec.cli:main"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+markers = ["services: requires a configured PostgreSQL or MySQL/MariaDB service"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/openstatspec"]

openstatspec-0.1.0/src/openstatspec/__init__.py

@@ -0,0 +1,6 @@
+"""Public API for the OpenStatSpec Python reference implementation."""
+
+from .api import capabilities, capability_matrix, export_sav, import_sav, inspect, validate
+from .core import CapabilityDeclaration, LossReport, UnsupportedOperationError
+
+__all__ = ["CapabilityDeclaration", "LossReport", "UnsupportedOperationError", "capabilities", "capability_matrix", "export_sav", "import_sav", "inspect", "validate"]