Initialize Python reference adapter scaffold

Author: TonisOrmisson

.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+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@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install -e ".[dev]"
+      - run: python -m pytest

.gitignore

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

README.md

@@ -0,0 +1,42 @@
+# 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. Catalog
+metadata is stored separately. 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
+```
+
+The initial scaffold deliberately declares no conforming SPSS or SQL profile.
+The entry points are stable, but fail explicitly until an implementation has
+been proven by OpenStatSpec conformance fixtures.

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.

pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "openstatspec"
+version = "0.0.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"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[project.scripts]
+openstatspec = "openstatspec.cli:main"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/openstatspec"]

src/openstatspec/__init__.py

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

src/openstatspec/api.py

@@ -0,0 +1,31 @@
+"""Stable, database-connected public API."""
+
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from .core import CapabilityDeclaration
+from .spss import export_dataset, import_dataset, inspect_source
+from .sql import validate_dataset
+
+
+def capabilities() -> Mapping[str, Any]:
+    return CapabilityDeclaration.empty().as_dict()
+
+
+def inspect(source: str | Path, /, **options: Any) -> Mapping[str, Any]:
+    return inspect_source(source, **options)
+
+
+def import_sav(source: str | Path, /, *, database_url: Any, dataset_id: str, **options: Any) -> Mapping[str, Any]:
+    """Import one source file into one dedicated wide SQL table."""
+    return import_dataset(source, database_url=database_url, dataset_id=dataset_id, **options)
+
+
+def export_sav(*, database_url: Any, dataset_id: str, destination: str | Path, **options: Any) -> Mapping[str, Any]:
+    """Export one database-resident conforming dataset to SAV/ZSAV."""
+    return export_dataset(database_url=database_url, dataset_id=dataset_id, destination=destination, **options)
+
+
+def validate(*, database_url: Any, dataset_id: str, **options: Any) -> Mapping[str, Any]:
+    return validate_dataset(database_url=database_url, dataset_id=dataset_id, **options)

src/openstatspec/cli.py

@@ -0,0 +1,25 @@
+"""Command-line entry points for the database-connected workflow."""
+
+import argparse
+from collections.abc import Sequence
+
+from .api import export_sav, import_sav
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="openstatspec")
+    commands = parser.add_subparsers(dest="command", required=True)
+    importer = commands.add_parser("import", help="import one SAV/ZSAV file")
+    importer.add_argument("source")
+    importer.add_argument("--database-url", required=True)
+    importer.add_argument("--dataset-id", required=True)
+    exporter = commands.add_parser("export", help="export one dataset to SAV/ZSAV")
+    exporter.add_argument("--database-url", required=True)
+    exporter.add_argument("--dataset-id", required=True)
+    exporter.add_argument("--output", required=True)
+    args = parser.parse_args(argv)
+    if args.command == "import":
+        import_sav(args.source, database_url=args.database_url, dataset_id=args.dataset_id)
+    else:
+        export_sav(database_url=args.database_url, dataset_id=args.dataset_id, destination=args.output)
+    return 0

src/openstatspec/core/__init__.py

@@ -0,0 +1,29 @@
+"""Pure OpenStatSpec concepts; no file or database adapter code."""
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+class UnsupportedOperationError(NotImplementedError):
+    """Raised when faithful support for a requested operation is unavailable."""
+
+
+@dataclass(frozen=True)
+class LossReport:
+    """Machine-readable fidelity outcome for a completed future operation."""
+
+    events: tuple[dict[str, Any], ...] = ()
+
+
+@dataclass(frozen=True)
+class CapabilityDeclaration:
+    specification: str | None = None
+    formats: dict[str, Any] = field(default_factory=dict)
+    database_profiles: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def empty(cls) -> "CapabilityDeclaration":
+        return cls()
+
+    def as_dict(self) -> dict[str, Any]:
+        return {"specification": self.specification, "formats": self.formats, "database_profiles": self.database_profiles, "operations": {"inspect": False, "import_sav": False, "export_sav": False, "validate": False}}

src/openstatspec/spss/__init__.py

@@ -0,0 +1,18 @@
+"""SAV/ZSAV adapter boundary; never a data-model transformation layer."""
+
+from pathlib import Path
+from typing import Any
+
+from ..core import UnsupportedOperationError
+
+
+def inspect_source(source: str | Path, **options: Any) -> dict[str, Any]:
+    raise UnsupportedOperationError("No SAV/ZSAV profile is implemented; source metadata cannot be guessed.")
+
+
+def import_dataset(source: str | Path, *, database_url: Any, dataset_id: str, **options: Any) -> dict[str, Any]:
+    raise UnsupportedOperationError("No SAV/ZSAV-to-SQL profile is implemented; no partial import was attempted.")
+
+
+def export_dataset(*, database_url: Any, dataset_id: str, destination: str | Path, **options: Any) -> dict[str, Any]:
+    raise UnsupportedOperationError("No SQL-to-SAV/ZSAV profile is implemented; no lossy export was attempted.")