Require pyspssio as Python SPSS engine

Author: TonisOrmisson

README.md

@@ -39,8 +39,10 @@ openstatspec export --database-url postgresql+psycopg://... --dataset-id respons
 
 ## 0.1.0 support status
 
-The adapter supports unencrypted SAV and ZSAV import and SAV/ZSAV export for
-the semantics exposed by its SPSS engine. SQLite is the local reference path.
+The adapter requires pyspssio 0.5.1 as its sole SPSS engine. 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:
 
@@ -56,3 +58,6 @@ intentional lossy export auditable.
 
 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.

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 |
+| --- | --- | --- |
+| pyspssio | 0.5.1 | MIT for the Python wrapper, except for its IBM I/O Module files |
+| IBM I/O Modules for IBM SPSS Statistics Data Files | 28.0.1.0, bundled by 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 pyspssio==0.5.1; it has no alternate SPSS engine. This
+repository does not vendor, alter, or publish 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.

docs/pyspssio-spike.md

@@ -1,21 +1,14 @@
-# `pyspssio` engine spike
+# pyspssio engine assessment
 
-**Status:** investigated only; not a runtime dependency and not selected by the
-public adapter.
+**Status:** selected as the required, sole Python SPSS engine.
 
-This is a bounded technical spike for evaluating
-[`pyspssio`](https://pypi.org/project/pyspssio/) 0.5.1 as a future SPSS
-engine. The existing `pyreadstat` engine remains unchanged.
+OpenStatSpec Python uses [pyspssio](https://pypi.org/project/pyspssio/) 0.5.1
+for both SAV and ZSAV import and export. There is no alternate SPSS engine.
 
-## Environment and runtime result
+## Probe result
 
-The probe used Python 3.12 and `pyspssio==0.5.1` in a local development
-virtual environment. The wheel includes IBM SPSS I/O Modules 28.0.1.0 native
-libraries for Linux, macOS and Windows. No installed IBM SPSS Statistics
-application was needed for the probe.
-
-A local round trip created both a `.sav` and a `.zsav`, then read each
-back. The following metadata survived in both files:
+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;
@@ -25,51 +18,27 @@ back. The following metadata survived in both files:
 - case-weight variable;
 - a dichotomous multiple-response set.
 
-The public API used was `read_metadata()`, `read_sav()` and
-`write_sav()`; it supports both `.sav` and `.zsav` according to the
-suffix.
-
-## Material limitations found
-
-This is not yet a complete-fidelity engine.
-
-1. **Variable sets did not round trip.** A `var_sets` definition supplied to
-   `write_sav()` was absent from the metadata read back. The upstream source
-   itself notes a dictionary-commit / 8-byte-compatible-name limitation for
-   variable sets.
-2. **Print and write formats are not independently represented by the public
-   API.** `Header.var_formats` reads the print format; its setter calls both
-   `spssSetVarPrintFormat` and `spssSetVarWriteFormat` with the same value.
-   An OpenStatSpec exporter must retain and restore the two formats separately.
-3. **No public document-text or file-label property was found** in
-   `Header`. These must be added upstream or accessed through a supported
-   lower-level binding before this engine can satisfy the full profile.
-4. The functional probe covers one modern Unicode file. It does not establish
-   compatibility for legacy code-page SAV files, long-string edge cases, or
-   arbitrary pre-existing SPSS files.
-
-## License and CI boundary
+The public API used was read_metadata(), read_sav(), and write_sav().
 
-The Python wrapper is MIT, but its wheel contains IBM I/O Modules under a
-separate IBM licence. In particular, the accompanying redistribution terms
-apply to the bundled native libraries and are not covered by this repository's
-Apache-2.0 licence.
+## Required conformance work
 
-Therefore this spike intentionally:
+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:
 
-- does **not** add `pyspssio` to project dependencies;
-- does **not** run it in GitHub Actions; and
-- does **not** change adapter capability claims.
+1. variable-set round trips;
+2. independent print and write formats;
+3. file label and document text;
+4. legacy code-page files and long-string edge cases.
 
-Adopting it requires a maintainer licence/distribution review and an explicit
-optional-engine packaging decision. CI can then test it only on platforms and
-under terms approved for installing the bundled IBM modules.
+Until a feature is proved, the adapter must report it as unsupported rather
+than silently losing it.
 
-## Next implementation slice
+## Licence boundary
 
-If approved after that review, add a private `PyspssioEngine` behind the
-existing engine boundary, initially with a hermetic SAV/ZSAV metadata fixture.
-Do not make it default until the implementation proves or deliberately reports
-each of these separately: file label/documents, variable sets, independent
-print/write formats, custom attributes, multiple-response sets, roles,
-alignment, display width and legacy encodings.
+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.

docs/sav-profile.md

@@ -2,34 +2,35 @@
 
 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,
+column and __case_ordinal preserves case order. The adapter never pivots,
 chunks, or creates a cell/EAV representation.
 
-## Verified SQLite path
+## SPSS engine
 
-The SQLite reference path has a round-trip fixture covering numeric and string
-values, system-missing numerics, blank strings, labels, value labels, formats,
-measurement level, user-missing rules, file notes, and source encoding
-metadata. User-missing values remain stored values; their interpretation is
-kept as metadata and is restored to SAV on export.
+OpenStatSpec Python requires pyspssio 0.5.1 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 same 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.
-
-## Explicit current boundaries
-
-- Imports accept unencrypted `.sav` and `.zsav` sources through pyreadstat.
-- Exports write SAV and ZSAV; ZSAV output uses the engine's compressed
-  SAV writer path.
-- The writer restores metadata supported by pyreadstat. SPSS dictionary
-  constructs that pyreadstat does not expose as stable writer inputs—such as
-  multiple-response sets and variable sets—are not silently claimed as
-  round-tripped and require a later profile implementation.
-- Encryption and byte-identical reproduction are out of scope. The contract is
-  semantic equivalence of supported values, order, and dictionary metadata.
+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 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.
+
+## 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.

pyproject.toml

@@ -10,7 +10,7 @@ readme = "README.md"
 requires-python = ">=3.11"
 license = {text = "Apache-2.0"}
 authors = [{name = "OpenStatSpec"}]
-dependencies = ["SQLAlchemy>=2.0", "pandas>=2.2", "pyreadstat>=1.3"]
+dependencies = ["SQLAlchemy>=2.0", "pandas>=2.2", "pyspssio==0.5.1"]
 
 [project.optional-dependencies]
 dev = ["pytest>=8"]