provium 0.1.0__tar.gz

provium-0.1.0/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: provium
+Version: 0.1.0
+Summary: Typed binary artifacts with automatic provenance
+Project-URL: Homepage, https://github.com/SirDavidLudwig/provium
+Project-URL: Issues, https://github.com/SirDavidLudwig/provium/issues
+Project-URL: Repository, https://github.com/SirDavidLudwig/provium
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Provides-Extra: test
+Requires-Dist: pydantic>=2.10; extra == "test"
+Requires-Dist: pytest>=8.3; extra == "test"
+Requires-Dist: pytest-cov>=6.0; extra == "test"
+
+# Provium
+
+Provium is a small standalone Python package for typed binary artifacts with
+automatic provenance.
+
+Provium artifact files use the `.pa` extension.
+
+Artifact I/O occurs only inside a scoped procedure execution. Every artifact
+opened in that scope is tracked automatically as an input, and every artifact
+created in that scope is tracked automatically as an output. Users do not
+construct or supply lineage manually.
+
+## Status
+
+Provium is in pre-alpha development. Implementation follows the test-driven
+sequence in [`provium_tdd_plan.md`](provium_tdd_plan.md), with each step reviewed
+before the next begins.
+
+## Development setup
+
+Provium requires Python 3.12 or newer and has no required runtime dependencies.
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e '.[test]'
+```
+
+Run the test suite with:
+
+```bash
+pytest
+```
+
+The project configuration requires 100% statement and branch coverage for the
+`provium` package.
+
+## Planned API
+
+```python
+from provium import Procedure
+
+ADD = Procedure(name="add", version="1")
+
+with ADD.execute():
+    left = Integer.open("left.pa")
+    right = Integer.open("right.pa")
+    result = Integer.create("sum.pa")
+    result.write(left.read() + right.read())
+```
+
+The API shown above is the target design and is not implemented yet.

provium-0.1.0/README.md

@@ -0,0 +1,53 @@
+# Provium
+
+Provium is a small standalone Python package for typed binary artifacts with
+automatic provenance.
+
+Provium artifact files use the `.pa` extension.
+
+Artifact I/O occurs only inside a scoped procedure execution. Every artifact
+opened in that scope is tracked automatically as an input, and every artifact
+created in that scope is tracked automatically as an output. Users do not
+construct or supply lineage manually.
+
+## Status
+
+Provium is in pre-alpha development. Implementation follows the test-driven
+sequence in [`provium_tdd_plan.md`](provium_tdd_plan.md), with each step reviewed
+before the next begins.
+
+## Development setup
+
+Provium requires Python 3.12 or newer and has no required runtime dependencies.
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e '.[test]'
+```
+
+Run the test suite with:
+
+```bash
+pytest
+```
+
+The project configuration requires 100% statement and branch coverage for the
+`provium` package.
+
+## Planned API
+
+```python
+from provium import Procedure
+
+ADD = Procedure(name="add", version="1")
+
+with ADD.execute():
+    left = Integer.open("left.pa")
+    right = Integer.open("right.pa")
+    result = Integer.create("sum.pa")
+    result.write(left.read() + right.read())
+```
+
+The API shown above is the target design and is not implemented yet.

provium-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["setuptools>=75"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "provium"
+version = "0.1.0"
+description = "Typed binary artifacts with automatic provenance"
+readme = "README.md"
+requires-python = ">=3.12"
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/SirDavidLudwig/provium"
+Issues = "https://github.com/SirDavidLudwig/provium/issues"
+Repository = "https://github.com/SirDavidLudwig/provium"
+
+[project.optional-dependencies]
+test = [
+    "pydantic>=2.10",
+    "pytest>=8.3",
+    "pytest-cov>=6.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+addopts = [
+    "--strict-config",
+    "--strict-markers",
+    "--cov=provium",
+    "--cov-branch",
+    "--cov-report=term-missing",
+    "--cov-fail-under=100",
+]
+testpaths = ["test"]
+
+[tool.coverage.run]
+branch = true
+source = ["provium"]
+
+[tool.coverage.report]
+fail_under = 100
+show_missing = true
+skip_covered = false
+
+[tool.ruff]
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "TRY", "UP"]
+ignore = ["TRY003"]

provium-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

provium-0.1.0/src/provium/__init__.py

@@ -0,0 +1,45 @@
+from importlib.metadata import version
+
+from .artifact import Artifact, open_artifact
+from .catalog import ArtifactCatalog, ArtifactRegistration
+from .config import ConfigCodec, ConfigurationSnapshot, JsonValue
+from .discovery import discover_catalogs, reset_discovery
+from .header import ArtifactHeader, decode_header, encode_header
+from .procedure import ExecutionContext, Procedure, current_execution
+from .provenance import (
+    ArtifactLineage,
+    ArtifactRecord,
+    ArtifactReference,
+    ProcedureExecutionRecord,
+    ProcedureRecord,
+)
+from .reader import ArtifactReader
+from .writer import ArtifactWriter
+
+__version__ = version("provium")
+
+__all__ = [
+    "Artifact",
+    "ArtifactCatalog",
+    "ArtifactHeader",
+    "ArtifactLineage",
+    "ArtifactReader",
+    "ArtifactRecord",
+    "ArtifactReference",
+    "ArtifactRegistration",
+    "ArtifactWriter",
+    "ConfigCodec",
+    "ConfigurationSnapshot",
+    "ExecutionContext",
+    "JsonValue",
+    "Procedure",
+    "ProcedureExecutionRecord",
+    "ProcedureRecord",
+    "__version__",
+    "decode_header",
+    "discover_catalogs",
+    "encode_header",
+    "current_execution",
+    "open_artifact",
+    "reset_discovery",
+]

provium-0.1.0/src/provium/artifact.py

@@ -0,0 +1,125 @@
+"""Generic typed artifact definitions and lazy provider resolution."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from os import PathLike
+from typing import Any, ClassVar, cast, overload
+
+from .context import current_context
+from .reader import ArtifactReader
+from .writer import ArtifactWriter
+
+
+class Artifact[ReaderT: ArtifactReader, WriterT: ArtifactWriter]:
+    """Bind a logical artifact type to its concrete reader and writer types."""
+
+    reader: type[ReaderT] | Callable[[], type[ReaderT]]
+    writer: type[WriterT] | Callable[[], type[WriterT]]
+    _reader_type_cache: ClassVar[type[ArtifactReader] | None] = None
+    _writer_type_cache: ClassVar[type[ArtifactWriter] | None] = None
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        cls._reader_type_cache = None
+        cls._writer_type_cache = None
+
+    @classmethod
+    def _resolve_reader(cls) -> type[ReaderT]:
+        cached = cls._reader_type_cache
+        if cached is not None:
+            return cast(type[ReaderT], cached)
+        provider = getattr(cls, "reader", None)
+        candidate = (
+            provider
+            if isinstance(provider, type)
+            else provider()
+            if callable(provider)
+            else None
+        )
+        if not isinstance(candidate, type) or not issubclass(candidate, ArtifactReader):
+            raise TypeError("reader provider must resolve to an ArtifactReader type")
+        cls._reader_type_cache = candidate
+        return cast(type[ReaderT], candidate)
+
+    @classmethod
+    def _resolve_writer(cls) -> type[WriterT]:
+        cached = cls._writer_type_cache
+        if cached is not None:
+            return cast(type[WriterT], cached)
+        provider = getattr(cls, "writer", None)
+        candidate = (
+            provider
+            if isinstance(provider, type)
+            else provider()
+            if callable(provider)
+            else None
+        )
+        if not isinstance(candidate, type) or not issubclass(candidate, ArtifactWriter):
+            raise TypeError("writer provider must resolve to an ArtifactWriter type")
+        cls._writer_type_cache = candidate
+        return cast(type[WriterT], candidate)
+
+    @classmethod
+    def open(cls, path: str | PathLike[str]) -> ReaderT:
+        context = current_context()
+        if context is None:
+            raise RuntimeError("artifact I/O requires an active execution context")
+        opener = getattr(context, "open_artifact", None)
+        if not callable(opener):
+            raise TypeError("active context does not support artifact opening")
+        return cast(ReaderT, opener(cls, path, cls._resolve_reader()))
+
+    @classmethod
+    def create(cls, path: str | PathLike[str]) -> WriterT:
+        context = current_context()
+        if context is None:
+            raise RuntimeError("artifact I/O requires an active execution context")
+        creator = getattr(context, "create_artifact", None)
+        if not callable(creator):
+            raise TypeError("active context does not support artifact creating")
+        return cast(WriterT, creator(cls, path, cls._resolve_writer()))
+
+
+__all__ = ["Artifact"]
+
+
+@overload
+def open_artifact(path: str | PathLike[str]) -> ArtifactReader: ...
+
+
+@overload
+def open_artifact[ReaderT: ArtifactReader, WriterT: ArtifactWriter](
+    path: str | PathLike[str],
+    *,
+    expected: type[Artifact[ReaderT, WriterT]],
+) -> ReaderT: ...
+
+
+@overload
+def open_artifact(
+    path: str | PathLike[str],
+    *,
+    expected: tuple[type[Artifact], ...],
+) -> ArtifactReader: ...
+
+
+def open_artifact(
+    path: str | PathLike[str],
+    *,
+    expected: type[Artifact] | tuple[type[Artifact], ...] | None = None,
+) -> ArtifactReader:
+    """Open an artifact whose concrete type will be discovered from its header."""
+    context = current_context()
+    if context is None:
+        raise RuntimeError("artifact I/O requires an active execution context")
+    opener = getattr(context, "open_unknown_artifact", None)
+    if not callable(opener):
+        raise TypeError("active context does not support artifact opening")
+    expected_types = None
+    if expected is not None:
+        expected_types = expected if isinstance(expected, tuple) else (expected,)
+    return cast(ArtifactReader, opener(path, expected_types))
+
+
+__all__.append("open_artifact")

provium-0.1.0/src/provium/catalog.py

@@ -0,0 +1,80 @@
+"""Explicit registration of artifact classes and their persistent identifiers."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from types import MappingProxyType
+
+from .artifact import Artifact
+
+
+def _require_identifier(value: str, field_name: str) -> None:
+    if not isinstance(value, str) or not value:
+        raise ValueError(f"{field_name} must be a non-empty string")
+
+
+@dataclass(frozen=True, slots=True)
+class ArtifactRegistration:
+    canonical_identifier: str
+    artifact: type[Artifact]
+    aliases: tuple[str, ...] = ()
+
+
+class ArtifactCatalog:
+    """Map canonical identifiers and aliases to typed artifact definitions."""
+
+    def __init__(self) -> None:
+        self._identifiers: dict[str, ArtifactRegistration] = {}
+        self._artifacts: dict[type[Artifact], ArtifactRegistration] = {}
+
+    def register(
+        self,
+        canonical_identifier: str,
+        artifact: type[Artifact],
+        *,
+        aliases: tuple[str, ...] = (),
+    ) -> ArtifactRegistration:
+        _require_identifier(canonical_identifier, "canonical identifier")
+        if not isinstance(artifact, type) or not issubclass(artifact, Artifact):
+            raise TypeError("artifact must be an Artifact class")
+        for alias in aliases:
+            _require_identifier(alias, "alias")
+        if len(aliases) != len(set(aliases)):
+            raise ValueError("duplicate alias in registration")
+        if canonical_identifier in aliases:
+            raise ValueError("alias must differ from the canonical identifier")
+        if canonical_identifier in self._identifiers:
+            raise ValueError(
+                f"canonical identifier is already registered: {canonical_identifier}"
+            )
+        if artifact in self._artifacts:
+            raise ValueError("artifact class is already registered")
+        for alias in aliases:
+            if alias in self._identifiers:
+                raise ValueError(f"alias is already registered: {alias}")
+
+        registration = ArtifactRegistration(canonical_identifier, artifact, aliases)
+        self._identifiers[canonical_identifier] = registration
+        self._identifiers.update((alias, registration) for alias in aliases)
+        self._artifacts[artifact] = registration
+        return registration
+
+    def resolve(self, identifier: str) -> ArtifactRegistration:
+        return self._identifiers[identifier]
+
+    def registration_for(self, artifact: type[Artifact]) -> ArtifactRegistration:
+        return self._artifacts[artifact]
+
+    @property
+    def registrations(self) -> Mapping[str, ArtifactRegistration]:
+        """Canonical registrations keyed by canonical identifier."""
+        return MappingProxyType(
+            {
+                registration.canonical_identifier: registration
+                for registration in self._artifacts.values()
+            }
+        )
+
+
+__all__ = ["ArtifactCatalog", "ArtifactRegistration"]

provium-0.1.0/src/provium/config.py

@@ -0,0 +1,90 @@
+"""Typed, dependency-free procedure configuration serialization."""
+
+from __future__ import annotations
+
+import json
+import math
+from dataclasses import dataclass
+from typing import Protocol
+
+type JsonScalar = None | bool | int | float | str
+type JsonValue = JsonScalar | list[JsonValue] | dict[str, JsonValue]
+
+
+class ConfigCodec[ConfigT](Protocol):
+    """Encode and decode one procedure configuration type."""
+
+    identifier: str
+
+    def encode(self, config: ConfigT) -> JsonValue: ...
+
+    def decode(self, value: JsonValue) -> ConfigT: ...
+
+
+def _canonical_json_value(value: object) -> JsonValue:
+    """Validate a JSON value and return an independent normalized copy."""
+    _validate_json_value(value)
+    encoded = json.dumps(
+        value,
+        allow_nan=False,
+        ensure_ascii=False,
+        separators=(",", ":"),
+        sort_keys=True,
+    )
+    decoded: JsonValue = json.loads(encoded)
+    return decoded
+
+
+def _validate_json_value(value: object) -> None:
+    if value is None or isinstance(value, (bool, int, str)):
+        return
+    if isinstance(value, float):
+        if not math.isfinite(value):
+            raise ValueError("configuration must contain finite JSON numbers")
+        return
+    if isinstance(value, list):
+        for item in value:
+            _validate_json_value(item)
+        return
+    if isinstance(value, dict):
+        if any(not isinstance(key, str) for key in value):
+            raise TypeError("configuration JSON object keys must be strings")
+        for item in value.values():
+            _validate_json_value(item)
+        return
+    raise TypeError("configuration must be a JSON value")
+
+
+@dataclass(frozen=True, slots=True)
+class ConfigurationSnapshot:
+    """A JSON-compatible configuration value paired with its codec identity."""
+
+    codec_identifier: str
+    value: JsonValue
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.codec_identifier, str) or not self.codec_identifier:
+            raise ValueError("codec_identifier must be a non-empty string")
+        object.__setattr__(self, "value", _canonical_json_value(self.value))
+
+    def to_json(self) -> str:
+        return json.dumps(
+            {"codec_identifier": self.codec_identifier, "value": self.value},
+            allow_nan=False,
+            ensure_ascii=False,
+            separators=(",", ":"),
+            sort_keys=True,
+        )
+
+    @classmethod
+    def from_json(cls, value: str) -> ConfigurationSnapshot:
+        decoded = json.loads(value)
+        if not isinstance(decoded, dict) or set(decoded) != {
+            "codec_identifier",
+            "value",
+        }:
+            raise ValueError("invalid configuration snapshot")
+        return cls(decoded["codec_identifier"], decoded["value"])
+
+
+__all__ = ["ConfigCodec", "ConfigurationSnapshot", "JsonValue"]

provium-0.1.0/src/provium/context.py

@@ -0,0 +1,40 @@
+"""Logical execution-context state shared by context-bound resources."""
+
+from __future__ import annotations
+
+from collections.abc import Generator
+from contextlib import contextmanager
+from contextvars import ContextVar, Token
+
+_active_context: ContextVar[object | None] = ContextVar(
+    "provium_active_execution_context",
+    default=None,
+)
+
+
+def current_context() -> object | None:
+    """Return the active execution-context owner in this logical context."""
+    return _active_context.get()
+
+
+def set_context(owner: object) -> Token[object | None]:
+    """Set the active owner and return the token required to restore it."""
+    return _active_context.set(owner)
+
+
+def reset_context(token: Token[object | None]) -> None:
+    """Restore the logical context represented by a prior token."""
+    _active_context.reset(token)
+
+
+@contextmanager
+def activate_context(owner: object) -> Generator[None]:
+    """Activate an owner temporarily, restoring the previous owner on exit."""
+    token = set_context(owner)
+    try:
+        yield
+    finally:
+        reset_context(token)
+
+
+__all__ = ["activate_context", "current_context", "reset_context", "set_context"]

provium-0.1.0/src/provium/discovery.py

@@ -0,0 +1,44 @@
+"""Discover explicitly published artifact catalogs through package entry points."""
+
+from __future__ import annotations
+
+from importlib import metadata
+
+from .catalog import ArtifactCatalog
+
+ENTRY_POINT_GROUP = "provium.catalogs"
+_discovered_catalog: ArtifactCatalog | None = None
+
+
+def discover_catalogs() -> ArtifactCatalog:
+    """Load and combine installed catalogs, caching a successful discovery."""
+    global _discovered_catalog
+    if _discovered_catalog is not None:
+        return _discovered_catalog
+
+    discovered = ArtifactCatalog()
+    for entry_point in metadata.entry_points().select(group=ENTRY_POINT_GROUP):
+        catalog = entry_point.load()
+        if not isinstance(catalog, ArtifactCatalog):
+            message = (
+                f"catalog entry point {entry_point.name!r} must expose "
+                "an ArtifactCatalog"
+            )
+            raise TypeError(message)
+        for registration in catalog.registrations.values():
+            discovered.register(
+                registration.canonical_identifier,
+                registration.artifact,
+                aliases=registration.aliases,
+            )
+    _discovered_catalog = discovered
+    return discovered
+
+
+def reset_discovery() -> None:
+    """Clear cached discovery state, primarily for isolated tests."""
+    global _discovered_catalog
+    _discovered_catalog = None
+
+
+__all__ = ["discover_catalogs", "reset_discovery"]