openstatspec 0.1.0__py3-none-any.whl

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"]

openstatspec/api.py

@@ -0,0 +1,95 @@
+"""Stable, database-connected public API."""
+
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from .core.results import result
+from .spss import export_dataset, import_dataset, inspect_source
+from .spss.sav import engine_identity
+from .sql import declared_profiles, validate_dataset
+from .sql.capabilities import (
+    SPECIFICATION_COMMIT, SPECIFICATION_RELEASE, active_connection, catalog_binding,
+)
+
+
+
+def capability_matrix(database_url: str | None = None) -> Mapping[str, Any]:
+    """Return the pyspssio-backed SAV/ZSAV fidelity boundary.
+
+    supported means that the adapter has a tested faithful path.
+    unobservable means that pyspssio's public reader API cannot expose the
+    source semantic. fail-closed-on-export means an imported/catalogued value
+    blocks export unless the documented audited loss route exists; a plain
+    fail-closed feature has no faithful writer route at all.
+    """
+    declaration = {
+        "specification": "OpenStatSpec",
+        "specification_status": "release_candidate",
+        "specification_release": SPECIFICATION_RELEASE,
+        "specification_commit": SPECIFICATION_COMMIT,
+        "profile": "SPSS SAV/ZSAV 1.0",
+        "directions": ["import", "export", "semantic_round_trip"],
+        "required_capabilities": [
+            "sav_read", "sav_write", "zsav_read", "zsav_write",
+            "file_label", "documents", "source_encoding", "attributes",
+            "variable_dictionary", "value_labels", "missing_rules",
+            "lowest_highest_missing", "long_utf8_strings", "weight_variable",
+            "variable_sets", "multiple_response_sets",
+            "multiple_response_string_counted_value",
+        ],
+        "engine": engine_identity(),
+        "spss": {
+            "values": "supported", "variable_labels": "supported",
+            "value_labels": "supported",
+            "print_format": "supported",
+            "write_format": "supported",
+            "file_label": "supported",
+            "documents": "supported",
+            "source_encoding": {
+                "utf8": "supported",
+                "legacy_code_pages": "requires-explicit-legacy-locale",
+            },
+            "measurement_level": "supported", "user_missing_rules": "supported",
+            "multiple_response_sets": "supported",
+            "variable_alignment": "supported",
+            "variable_sets": "supported",
+            "compatible_variable_names": "supported",
+            "custom_attributes": {
+                "scalar_values": "supported",
+                "ordered_value_arrays": "supported",
+            },
+            "variable_role": "supported",
+        },
+        "resource_behavior": {
+            "streaming_import": False, "streaming_export": False,
+            "buffering": "fully_buffered", "maximum_cases": None,
+            "maximum_source_file_bytes": None,
+            "limit_basis": "runtime memory and active SQL connection limits",
+        },
+        "active_connection": active_connection(database_url) if database_url else None,
+        "catalog_binding": catalog_binding(database_url) if database_url else None,
+        "sql_profiles": declared_profiles(database_url),
+    }
+    return declaration
+
+def capabilities(database_url: str | None = None) -> Mapping[str, Any]:
+    return capability_matrix(database_url)
+
+
+def inspect(source: str | Path, /, **options: Any) -> Mapping[str, Any]:
+    return result(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 result(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 result(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 result(validate_dataset(database_url=database_url, dataset_id=dataset_id, **options))

openstatspec/cli.py

@@ -0,0 +1,42 @@
+"""Command-line entry points for the database-connected workflow."""
+import json
+
+import argparse
+from collections.abc import Sequence
+
+from .api import capability_matrix, export_sav, import_sav, inspect, validate
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="openstatspec")
+    commands = parser.add_subparsers(dest="command", required=True)
+    capability_parser = commands.add_parser("capabilities", help="show supported and lossy feature matrix")
+    capability_parser.add_argument("--database-url", help="include active connection limits")
+    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)
+    inspector = commands.add_parser("inspect", help="inspect one SAV/ZSAV dictionary")
+    inspector.add_argument("source")
+    validator = commands.add_parser("validate", help="validate one imported dataset")
+    validator.add_argument("--database-url", required=True)
+    validator.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)
+    exporter.add_argument("--allow-loss", action="append", default=[])
+    exporter.add_argument("--legacy-locale", help="OS locale for a non-UTF-8 source encoding")
+    args = parser.parse_args(argv)
+    if args.command == "capabilities":
+        result = capability_matrix(database_url=args.database_url)
+    elif args.command == "import":
+        result = import_sav(args.source, database_url=args.database_url, dataset_id=args.dataset_id)
+    elif args.command == "export":
+        result = export_sav(database_url=args.database_url, dataset_id=args.dataset_id, destination=args.output, allow_loss=args.allow_loss, legacy_locale=args.legacy_locale)
+    elif args.command == "inspect":
+        result = inspect(args.source)
+    else:
+        result = validate(database_url=args.database_url, dataset_id=args.dataset_id)
+    print(json.dumps(result.as_dict() if hasattr(result, "as_dict") else result, default=str, sort_keys=True))
+    return 0

openstatspec/core/__init__.py

@@ -0,0 +1,33 @@
+from .results import Diagnostic, OperationResult
+"""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": True, "import_sav": True, "export_sav": True, "validate": True},
+        }

openstatspec/core/results.py

@@ -0,0 +1,47 @@
+"""Typed public results while retaining mapping compatibility."""
+
+from collections.abc import Iterator, Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class Diagnostic:
+    code: str
+    detail: str
+    details: Mapping[str, Any] = field(default_factory=dict)
+
+    def as_dict(self) -> dict[str, Any]:
+        result: dict[str, Any] = {"code": self.code, "detail": self.detail}
+        if self.details:
+            result["details"] = dict(self.details)
+        return result
+
+
+@dataclass(frozen=True)
+class OperationResult(Mapping[str, Any]):
+    values: Mapping[str, Any] = field(default_factory=dict)
+    diagnostics: tuple[Diagnostic, ...] = ()
+
+    def as_dict(self) -> dict[str, Any]:
+        result = dict(self.values)
+        result["loss_report"] = [item.as_dict() for item in self.diagnostics]
+        return result
+
+    def __getitem__(self, key: str) -> Any:
+        return self.as_dict()[key]
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self.as_dict())
+
+    def __len__(self) -> int:
+        return len(self.as_dict())
+
+
+def result(values: Mapping[str, Any]) -> OperationResult:
+    payload = dict(values)
+    diagnostics = tuple(
+        Diagnostic(code=item["code"], detail=item["detail"], details=item.get("details", {}))
+        for item in payload.pop("loss_report", ())
+    )
+    return OperationResult(payload, diagnostics)

openstatspec/spss/__init__.py

@@ -0,0 +1,22 @@
+"""SAV/ZSAV adapter boundary; never a data-model transformation layer."""
+
+from pathlib import Path
+from typing import Any
+
+from .sav import export_sav_dataset, import_sav_dataset, inspect_sav
+
+
+def inspect_source(source: str | Path, **options: Any) -> dict[str, Any]:
+    return inspect_sav(source)
+
+
+def import_dataset(source: str | Path, *, database_url: Any, dataset_id: str, **options: Any) -> dict[str, Any]:
+    return import_sav_dataset(source=source, database_url=str(database_url), dataset_id=dataset_id)
+
+
+def export_dataset(*, database_url: Any, dataset_id: str, destination: str | Path, **options: Any) -> dict[str, Any]:
+    return export_sav_dataset(
+        database_url=str(database_url), dataset_id=dataset_id, destination=destination,
+        allow_loss=tuple(options.get("allow_loss", ())),
+        legacy_locale=options.get("legacy_locale"),
+    )

openstatspec/spss/dictionary.py

@@ -0,0 +1,180 @@
+"""Small, contained bridge to pyspssio's IBM I/O dictionary functions.
+
+The convenient read_metadata/write_sav helpers deliberately flatten some
+dictionary information. OpenStatSpec needs separate print/write formats and
+ordered repeated custom attributes. Keeping ctypes calls here makes that
+boundary explicit and testable.
+"""
+
+from __future__ import annotations
+
+from ctypes import POINTER, c_char_p, c_int
+from typing import Any, Iterable, Mapping
+
+from pyspssio.header import spss_formats_simple, varformat_to_tuple, warn_or_raise
+
+FormatTuple = tuple[int, int, int]
+AttributePair = tuple[str, str]
+
+
+def format_tuples(header: Any) -> tuple[dict[str, FormatTuple], dict[str, FormatTuple]]:
+    """Return raw SPSS print and write format tuples by variable."""
+    return (
+        {name: _get_format(header, name, "spssGetVarPrintFormat") for name in header.var_names},
+        {name: _get_format(header, name, "spssGetVarWriteFormat") for name in header.var_names},
+    )
+
+
+def _get_format(header: Any, name: str, function_name: str) -> FormatTuple:
+    function = getattr(header.spssio, function_name)
+    function.argtypes = [c_int, c_char_p, POINTER(c_int), POINTER(c_int), POINTER(c_int)]
+    kind, decimals, width = c_int(), c_int(), c_int()
+    retcode = function(header.fh, name.encode(header.encoding), kind, decimals, width)
+    warn_or_raise(retcode, function, name)
+    return kind.value, width.value, decimals.value
+
+
+def format_string(value: FormatTuple) -> str:
+    kind, width, decimals = value
+    return f"{spss_formats_simple[kind]}{width}" + (f".{decimals}" if decimals else "")
+
+
+def format_tuple(value: Any) -> FormatTuple:
+    if isinstance(value, (list, tuple)) and len(value) == 3:
+        return int(value[0]), int(value[1]), int(value[2])
+    return tuple(int(part) for part in varformat_to_tuple(value))  # type: ignore[return-value]
+
+
+def set_format_tuples(
+    header: Any, *, name: str, print_format: FormatTuple, write_format: FormatTuple,
+) -> None:
+    """Set print and write formats independently before dictionary commit."""
+    for function_name, value in (
+        ("spssSetVarPrintFormat", print_format),
+        ("spssSetVarWriteFormat", write_format),
+    ):
+        function = getattr(header.spssio, function_name)
+        function.argtypes = [c_int, c_char_p, c_int, c_int, c_int]
+        kind, width, decimals = value
+        retcode = function(
+            header.fh, name.encode(header.encoding), c_int(kind), c_int(decimals), c_int(width),
+        )
+        warn_or_raise(retcode, function, name, value)
+
+
+def file_attribute_pairs(header: Any) -> list[AttributePair]:
+    return _get_attributes(header, function_name="spssGetFileAttributes")
+
+
+def variable_attribute_pairs(header: Any, name: str) -> list[AttributePair]:
+    return _get_attributes(header, function_name="spssGetVarAttributes", name=name)
+
+
+def _get_attributes(header: Any, *, function_name: str, name: str | None = None) -> list[AttributePair]:
+    """Read ordered attribute pairs without the public dict(zip()) loss."""
+    function = getattr(header.spssio, function_name)
+
+    def call(size: int) -> tuple[Any, Any, Any, int]:
+        names = POINTER(c_char_p * size)()
+        texts = POINTER(c_char_p * size)()
+        count = c_int()
+        argtypes = [c_int]
+        arguments: list[Any] = [header.fh]
+        if name is not None:
+            argtypes.append(c_char_p)
+            arguments.append(name.encode(header.encoding))
+        argtypes.extend([
+            POINTER(POINTER(c_char_p * size)), POINTER(POINTER(c_char_p * size)), POINTER(c_int),
+        ])
+        arguments.extend([names, texts, count])
+        function.argtypes = argtypes
+        retcode = function(*arguments)
+        warn_or_raise(retcode, function, *([name] if name is not None else []))
+        return names, texts, count, count.value
+
+    names, texts, count, size = call(0)
+    _free_attributes(header, names, texts, count)
+    if not size:
+        return []
+    names, texts, count, size = call(size)
+    try:
+        return [
+            (names[0][index].decode(header.encoding), texts[0][index].decode(header.encoding))
+            for index in range(size)
+        ]
+    finally:
+        _free_attributes(header, names, texts, count)
+
+
+def _free_attributes(header: Any, names: Any, texts: Any, count: Any) -> None:
+    function = header.spssio.spssFreeAttributes
+    retcode = function(names, texts, count)
+    warn_or_raise(retcode, function)
+
+
+def attribute_values(pairs: Iterable[AttributePair]) -> dict[str, Any]:
+    """Decode SPSS ``Name[1]`` array members to ordered catalog arrays."""
+    import re
+
+    scalar: dict[str, Any] = {}
+    arrays: dict[str, list[tuple[int, str]]] = {}
+    for name, value in pairs:
+        match = re.fullmatch(r"(.+)\[(\d+)\]", name)
+        if match and int(match.group(2)) > 0:
+            arrays.setdefault(match.group(1), []).append((int(match.group(2)), value))
+        else:
+            scalar[name] = value
+    for name, members in arrays.items():
+        members.sort(key=lambda item: item[0])
+        # A real SPSS attribute array begins at one.  Preserve a malformed or
+        # non-contiguous spelling as literal attributes instead of guessing.
+        if [index for index, _ in members] == list(range(1, len(members) + 1)):
+            scalar.pop(name, None)
+            scalar[name] = [value for _, value in members]
+        else:
+            scalar.update({f"{name}[{index}]": value for index, value in members})
+    return scalar
+
+
+def attribute_pairs(values: Mapping[str, Any]) -> list[AttributePair]:
+    """Encode catalog arrays as IBM SPSS ``Name[1]`` attribute members."""
+    pairs: list[AttributePair] = []
+    for name, value in values.items():
+        if isinstance(value, (list, tuple)):
+            pairs.extend(
+                (f"{name}[{index}]", "" if item is None else str(item))
+                for index, item in enumerate(value, start=1)
+            )
+        else:
+            pairs.append((str(name), "" if value is None else str(value)))
+    return pairs
+
+
+def set_file_attribute_pairs(header: Any, pairs: Iterable[AttributePair]) -> None:
+    _set_attributes(header, function_name="spssSetFileAttributes", pairs=pairs)
+
+
+def set_variable_attribute_pairs(header: Any, name: str, pairs: Iterable[AttributePair]) -> None:
+    _set_attributes(header, function_name="spssSetVarAttributes", pairs=pairs, name=name)
+
+
+def _set_attributes(
+    header: Any, *, function_name: str, pairs: Iterable[AttributePair], name: str | None = None,
+) -> None:
+    values = list(pairs)
+    if not values:
+        return
+    size = len(values)
+    names = (c_char_p * size)(*(key.encode(header.encoding) for key, _ in values))
+    texts = (c_char_p * size)(*(value.encode(header.encoding) for _, value in values))
+    function = getattr(header.spssio, function_name)
+    argtypes = [c_int]
+    arguments: list[Any] = [header.fh]
+    if name is not None:
+        argtypes.append(c_char_p)
+        arguments.append(name.encode(header.encoding))
+    argtypes.extend([POINTER(c_char_p * size), POINTER(c_char_p * size), c_int])
+    arguments.extend([names, texts, c_int(size)])
+    function.argtypes = argtypes
+    retcode = function(*arguments)
+    warn_or_raise(retcode, function, *([name] if name is not None else []))