dnakit 0.1.0.dev0__py3-none-any.whl

dnakit/core/feature.py

@@ -0,0 +1,90 @@
+"""Immutable DNA feature annotations."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+from dnakit.core._json import FrozenDict, freeze_mapping
+from dnakit.core.coordinates import CompoundLocation, Interval, Location, UnresolvedLocation
+from dnakit.core.enums import Strand
+from dnakit.exceptions import FeatureError
+
+
+@dataclass(frozen=True, init=False)
+class DNAFeature:
+    """A typed annotation referring to a location without copying sequence data."""
+
+    type: str
+    location: Location
+    id: str | None
+    strand: Strand
+    label: str | None
+    score: float | None
+    phase: int | None
+    qualifiers: FrozenDict
+    source: str | None
+
+    __hash__ = None  # type: ignore[assignment]
+
+    def __init__(
+        self,
+        type: str,
+        location: Location,
+        *,
+        id: str | None = None,
+        strand: Strand | str = Strand.UNKNOWN,
+        label: str | None = None,
+        score: float | None = None,
+        phase: int | None = None,
+        qualifiers: Mapping[str, object] | None = None,
+        source: str | None = None,
+    ) -> None:
+        if not isinstance(type, str) or not type.strip():
+            raise FeatureError("Feature type must be a non-empty string.")
+        if not isinstance(location, (Interval, CompoundLocation, UnresolvedLocation)):
+            raise FeatureError("Feature location must be an internal Location object.")
+        for field_name, value in (("id", id), ("label", label), ("source", source)):
+            if value is not None and (not isinstance(value, str) or not value.strip()):
+                raise FeatureError(
+                    f"Feature {field_name} must be None or a non-empty string.",
+                    context={field_name: value},
+                )
+        try:
+            resolved_strand = strand if isinstance(strand, Strand) else Strand(strand)
+        except (TypeError, ValueError) as exc:
+            raise FeatureError(
+                "Unknown feature strand.",
+                context={"strand": strand},
+                hint=f"Choose one of: {', '.join(item.value for item in Strand)}.",
+            ) from exc
+        if score is not None and (
+            isinstance(score, bool)
+            or not isinstance(score, (int, float))
+            or not math.isfinite(score)
+        ):
+            raise FeatureError(
+                "Feature score must be a finite number or None.",
+                context={"score": score},
+            )
+        if phase is not None and (
+            isinstance(phase, bool) or not isinstance(phase, int) or phase not in (0, 1, 2)
+        ):
+            raise FeatureError(
+                "Feature phase must be 0, 1, 2, or None.",
+                context={"phase": phase},
+            )
+
+        object.__setattr__(self, "type", type)
+        object.__setattr__(self, "location", location)
+        object.__setattr__(self, "id", id)
+        object.__setattr__(self, "strand", resolved_strand)
+        object.__setattr__(self, "label", label)
+        object.__setattr__(self, "score", None if score is None else float(score))
+        object.__setattr__(self, "phase", phase)
+        object.__setattr__(self, "qualifiers", freeze_mapping(qualifiers))
+        object.__setattr__(self, "source", source)
+
+
+__all__ = ["DNAFeature"]

dnakit/core/gap.py

@@ -0,0 +1,82 @@
+"""Explicit known- and unknown-length sequence gaps."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+
+from dnakit.core._json import FrozenDict, freeze_mapping
+from dnakit.core.enums import GapKind
+from dnakit.exceptions import SequenceError
+
+
+@dataclass(frozen=True, init=False)
+class Gap:
+    """A gap between sequence fragments.
+
+    ``length=None`` denotes an unknown coordinate span.  A gap never stores a
+    second copy of its flanking sequence; the flanks are determined by its
+    position in :class:`DNASequence.parts`.
+    """
+
+    length: int | None
+    kind: GapKind
+    crossable: bool | None
+    evidence: tuple[str, ...]
+    metadata: FrozenDict
+
+    def __init__(
+        self,
+        length: int | None,
+        kind: GapKind | str = GapKind.UNKNOWN,
+        crossable: bool | None = None,
+        evidence: Iterable[str] = (),
+        metadata: Mapping[str, object] | None = None,
+    ) -> None:
+        if length is not None and (isinstance(length, bool) or not isinstance(length, int)):
+            raise SequenceError(
+                "Gap length must be a positive integer or None.",
+                code="INVALID_GAP_LENGTH",
+                context={"length": length},
+            )
+        if length is not None and length <= 0:
+            raise SequenceError(
+                "Gap length must be greater than zero.",
+                code="INVALID_GAP_LENGTH",
+                context={"length": length},
+                hint="Use None when the gap length is unknown.",
+            )
+        try:
+            resolved_kind = kind if isinstance(kind, GapKind) else GapKind(kind)
+        except (TypeError, ValueError) as exc:
+            raise SequenceError(
+                "Unknown gap kind.",
+                code="INVALID_GAP_KIND",
+                context={"kind": kind},
+                hint=f"Choose one of: {', '.join(item.value for item in GapKind)}.",
+            ) from exc
+        if crossable is not None and not isinstance(crossable, bool):
+            raise SequenceError(
+                "Gap crossable policy must be True, False, or None.",
+                code="INVALID_GAP_POLICY",
+                context={"crossable": crossable},
+            )
+        evidence_tuple = tuple(evidence)
+        if any(not isinstance(item, str) or not item.strip() for item in evidence_tuple):
+            raise SequenceError(
+                "Gap evidence entries must be non-empty strings.",
+                code="INVALID_GAP_EVIDENCE",
+            )
+
+        object.__setattr__(self, "length", length)
+        object.__setattr__(self, "kind", resolved_kind)
+        object.__setattr__(self, "crossable", crossable)
+        object.__setattr__(self, "evidence", evidence_tuple)
+        object.__setattr__(self, "metadata", freeze_mapping(metadata))
+
+    @property
+    def is_known_length(self) -> bool:
+        return self.length is not None
+
+
+__all__ = ["Gap"]

dnakit/core/issues.py

@@ -0,0 +1,62 @@
+"""Structured, serializable non-fatal diagnostics."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, cast
+
+from dnakit.core._json import FrozenDict, freeze_mapping, to_json_compatible
+from dnakit.core.coordinates import CompoundLocation, Interval, Location, UnresolvedLocation
+from dnakit.core.enums import IssueSeverity
+from dnakit.exceptions import ConfigurationError
+
+
+@dataclass(frozen=True, init=False)
+class Issue:
+    """A stable machine-readable finding that does not require raising."""
+
+    code: str
+    severity: IssueSeverity
+    message: str
+    location: Location | None
+    details: FrozenDict
+
+    def __init__(
+        self,
+        code: str,
+        severity: IssueSeverity | str,
+        message: str,
+        location: Location | None = None,
+        details: Mapping[str, object] | None = None,
+    ) -> None:
+        if not isinstance(code, str) or not code.strip():
+            raise ConfigurationError("Issue code must be a non-empty string.")
+        if not isinstance(message, str) or not message.strip():
+            raise ConfigurationError("Issue message must be a non-empty string.")
+        try:
+            resolved_severity = (
+                severity if isinstance(severity, IssueSeverity) else IssueSeverity(severity)
+            )
+        except (TypeError, ValueError) as exc:
+            raise ConfigurationError(
+                "Unknown issue severity.",
+                context={"severity": severity},
+                hint=f"Choose one of: {', '.join(item.value for item in IssueSeverity)}.",
+            ) from exc
+        if location is not None and not isinstance(
+            location, (Interval, CompoundLocation, UnresolvedLocation)
+        ):
+            raise ConfigurationError("Issue location must be None or an internal Location.")
+
+        object.__setattr__(self, "code", code)
+        object.__setattr__(self, "severity", resolved_severity)
+        object.__setattr__(self, "message", message)
+        object.__setattr__(self, "location", location)
+        object.__setattr__(self, "details", freeze_mapping(details))
+
+    def to_dict(self) -> dict[str, Any]:
+        return cast(dict[str, Any], to_json_compatible(self))
+
+
+__all__ = ["Issue"]

dnakit/core/provenance.py

@@ -0,0 +1,305 @@
+"""Implementation, reference, artifact, and run provenance value objects."""
+
+from __future__ import annotations
+
+import platform as platform_module
+import re
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+from importlib.metadata import PackageNotFoundError, version
+from typing import Any, cast
+
+from dnakit.core._json import FrozenDict, freeze_mapping, to_json_compatible
+from dnakit.core.backend_info import BackendInfo
+from dnakit.core.enums import ExecutionMode, ImplementationLabel, OriginClass
+from dnakit.core.issues import Issue
+from dnakit.exceptions import ConfigurationError
+
+_SHA256_PATTERN = re.compile(r"^[0-9a-fA-F]{64}$")
+
+
+def _installed_dnakit_version() -> str:
+    try:
+        return version("dnakit")
+    except PackageNotFoundError:
+        return "unknown"
+
+
+def _non_empty_optional(value: str | None, name: str) -> None:
+    if value is not None and (not isinstance(value, str) or not value.strip()):
+        raise ConfigurationError(f"{name} must be None or a non-empty string.")
+
+
+@dataclass(frozen=True)
+class Citation:
+    """A compact citation identifier with optional resolvable metadata."""
+
+    key: str
+    title: str | None = None
+    doi: str | None = None
+    url: str | None = None
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.key, str) or not self.key.strip():
+            raise ConfigurationError("Citation key must be a non-empty string.")
+        for name in ("title", "doi", "url"):
+            _non_empty_optional(getattr(self, name), f"Citation {name}")
+
+
+@dataclass(frozen=True, init=False)
+class ImplementationInfo:
+    """The single authoritative classification of an implementation."""
+
+    label: ImplementationLabel
+    execution_mode: ExecutionMode
+    origin_class: OriginClass
+    license_expression: str | None
+    citations: tuple[Citation, ...]
+
+    def __init__(
+        self,
+        label: ImplementationLabel | str = ImplementationLabel.NATIVE,
+        execution_mode: ExecutionMode | str = ExecutionMode.INTERNAL,
+        origin_class: OriginClass | str = OriginClass.DNAKIT,
+        license_expression: str | None = None,
+        citations: Iterable[Citation] = (),
+    ) -> None:
+        try:
+            resolved_label = (
+                label if isinstance(label, ImplementationLabel) else ImplementationLabel(label)
+            )
+            resolved_execution = (
+                execution_mode
+                if isinstance(execution_mode, ExecutionMode)
+                else ExecutionMode(execution_mode)
+            )
+            resolved_origin = (
+                origin_class if isinstance(origin_class, OriginClass) else OriginClass(origin_class)
+            )
+        except (TypeError, ValueError) as exc:
+            raise ConfigurationError(
+                "Invalid implementation classification.",
+                context={
+                    "label": label,
+                    "execution_mode": execution_mode,
+                    "origin_class": origin_class,
+                },
+            ) from exc
+        _non_empty_optional(license_expression, "Implementation license_expression")
+        citation_tuple = tuple(citations)
+        if any(not isinstance(citation, Citation) for citation in citation_tuple):
+            raise ConfigurationError("Implementation citations must all be Citation objects.")
+
+        object.__setattr__(self, "label", resolved_label)
+        object.__setattr__(self, "execution_mode", resolved_execution)
+        object.__setattr__(self, "origin_class", resolved_origin)
+        object.__setattr__(self, "license_expression", license_expression)
+        object.__setattr__(self, "citations", citation_tuple)
+
+
+@dataclass(frozen=True, init=False)
+class ReferenceInfo:
+    """Versioned reference database metadata."""
+
+    name: str
+    version: str | None
+    date: str | None
+    checksum: str | None
+    filters: FrozenDict
+
+    def __init__(
+        self,
+        name: str,
+        *,
+        version: str | None = None,
+        date: str | None = None,
+        checksum: str | None = None,
+        filters: Mapping[str, object] | None = None,
+    ) -> None:
+        if not isinstance(name, str) or not name.strip():
+            raise ConfigurationError("Reference name must be a non-empty string.")
+        for field_name, value in (
+            ("version", version),
+            ("date", date),
+            ("checksum", checksum),
+        ):
+            _non_empty_optional(value, f"Reference {field_name}")
+        object.__setattr__(self, "name", name)
+        object.__setattr__(self, "version", version)
+        object.__setattr__(self, "date", date)
+        object.__setattr__(self, "checksum", checksum)
+        object.__setattr__(self, "filters", freeze_mapping(filters))
+
+
+@dataclass(frozen=True, init=False)
+class Provenance:
+    """Environment and implementation identity attached to a result."""
+
+    dnakit_version: str
+    python_version: str
+    platform: str
+    dependency_versions: FrozenDict
+    implementation: ImplementationInfo
+    backend: BackendInfo | None
+    reference: ReferenceInfo | None
+
+    def __init__(
+        self,
+        dnakit_version: str | None = None,
+        python_version: str | None = None,
+        platform: str | None = None,
+        dependency_versions: Mapping[str, str] | None = None,
+        implementation: ImplementationInfo | None = None,
+        backend: BackendInfo | None = None,
+        reference: ReferenceInfo | None = None,
+    ) -> None:
+        resolved_dnakit = _installed_dnakit_version() if dnakit_version is None else dnakit_version
+        resolved_python = (
+            platform_module.python_version() if python_version is None else python_version
+        )
+        resolved_platform = platform_module.platform() if platform is None else platform
+        for field_name, value in (
+            ("dnakit_version", resolved_dnakit),
+            ("python_version", resolved_python),
+            ("platform", resolved_platform),
+        ):
+            if not isinstance(value, str) or not value.strip():
+                raise ConfigurationError(f"Provenance {field_name} must be non-empty.")
+        if dependency_versions is not None and any(
+            not isinstance(name, str)
+            or not name.strip()
+            or not isinstance(value, str)
+            or not value.strip()
+            for name, value in dependency_versions.items()
+        ):
+            raise ConfigurationError("Dependency versions must map non-empty strings to strings.")
+        resolved_implementation = implementation or ImplementationInfo()
+        if not isinstance(resolved_implementation, ImplementationInfo):
+            raise ConfigurationError("Provenance implementation must be ImplementationInfo.")
+        if backend is not None and not isinstance(backend, BackendInfo):
+            raise ConfigurationError("Provenance backend must be BackendInfo or None.")
+        if reference is not None and not isinstance(reference, ReferenceInfo):
+            raise ConfigurationError("Provenance reference must be ReferenceInfo or None.")
+
+        object.__setattr__(self, "dnakit_version", resolved_dnakit)
+        object.__setattr__(self, "python_version", resolved_python)
+        object.__setattr__(self, "platform", resolved_platform)
+        object.__setattr__(self, "dependency_versions", freeze_mapping(dependency_versions))
+        object.__setattr__(self, "implementation", resolved_implementation)
+        object.__setattr__(self, "backend", backend)
+        object.__setattr__(self, "reference", reference)
+
+    def to_dict(self) -> dict[str, Any]:
+        return cast(dict[str, Any], to_json_compatible(self))
+
+
+@dataclass(frozen=True)
+class ArtifactRef:
+    """Integrity-checked reference to a persisted result artifact."""
+
+    relative_path: str
+    media_type: str
+    schema_version: str
+    sha256: str
+    byte_size: int
+    created_at: str
+
+    def __post_init__(self) -> None:
+        for name in ("relative_path", "media_type", "schema_version", "created_at"):
+            value = getattr(self, name)
+            if not isinstance(value, str) or not value.strip():
+                raise ConfigurationError(f"Artifact {name} must be a non-empty string.")
+        if not isinstance(self.sha256, str) or not _SHA256_PATTERN.fullmatch(self.sha256):
+            raise ConfigurationError("Artifact sha256 must contain exactly 64 hexadecimal digits.")
+        if (
+            isinstance(self.byte_size, bool)
+            or not isinstance(self.byte_size, int)
+            or self.byte_size < 0
+        ):
+            raise ConfigurationError("Artifact byte_size must be a non-negative integer.")
+
+
+@dataclass(frozen=True, init=False)
+class RunManifest:
+    """Resolved parameters and artifacts for a reproducible execution."""
+
+    run_id: str
+    command: tuple[str, ...]
+    resolved_config: FrozenDict
+    seed: int | None
+    seed_derivation: str | None
+    inputs: tuple[ArtifactRef, ...]
+    outputs: tuple[ArtifactRef, ...]
+    provenance: Provenance
+    started_at: str
+    finished_at: str | None
+    status: str
+    issues: tuple[Issue, ...]
+
+    def __init__(
+        self,
+        run_id: str,
+        command: Iterable[str],
+        resolved_config: Mapping[str, object],
+        provenance: Provenance,
+        started_at: str,
+        status: str,
+        *,
+        seed: int | None = None,
+        seed_derivation: str | None = None,
+        inputs: Iterable[ArtifactRef] = (),
+        outputs: Iterable[ArtifactRef] = (),
+        finished_at: str | None = None,
+        issues: Iterable[Issue] = (),
+    ) -> None:
+        for field_name, value in (
+            ("run_id", run_id),
+            ("started_at", started_at),
+            ("status", status),
+        ):
+            if not isinstance(value, str) or not value.strip():
+                raise ConfigurationError(f"RunManifest {field_name} must be non-empty.")
+        _non_empty_optional(seed_derivation, "RunManifest seed_derivation")
+        _non_empty_optional(finished_at, "RunManifest finished_at")
+        if seed is not None and (isinstance(seed, bool) or not isinstance(seed, int)):
+            raise ConfigurationError("RunManifest seed must be an integer or None.")
+        command_tuple = tuple(command)
+        if not command_tuple or any(
+            not isinstance(argument, str) or not argument for argument in command_tuple
+        ):
+            raise ConfigurationError("RunManifest command must contain non-empty strings.")
+        input_tuple = tuple(inputs)
+        output_tuple = tuple(outputs)
+        issue_tuple = tuple(issues)
+        if any(not isinstance(item, ArtifactRef) for item in (*input_tuple, *output_tuple)):
+            raise ConfigurationError("RunManifest artifacts must be ArtifactRef objects.")
+        if any(not isinstance(issue, Issue) for issue in issue_tuple):
+            raise ConfigurationError("RunManifest issues must be Issue objects.")
+        if not isinstance(provenance, Provenance):
+            raise ConfigurationError("RunManifest provenance must be Provenance.")
+
+        object.__setattr__(self, "run_id", run_id)
+        object.__setattr__(self, "command", command_tuple)
+        object.__setattr__(self, "resolved_config", freeze_mapping(resolved_config))
+        object.__setattr__(self, "seed", seed)
+        object.__setattr__(self, "seed_derivation", seed_derivation)
+        object.__setattr__(self, "inputs", input_tuple)
+        object.__setattr__(self, "outputs", output_tuple)
+        object.__setattr__(self, "provenance", provenance)
+        object.__setattr__(self, "started_at", started_at)
+        object.__setattr__(self, "finished_at", finished_at)
+        object.__setattr__(self, "status", status)
+        object.__setattr__(self, "issues", issue_tuple)
+
+    def to_dict(self) -> dict[str, Any]:
+        return cast(dict[str, Any], to_json_compatible(self))
+
+
+__all__ = [
+    "ArtifactRef",
+    "Citation",
+    "ImplementationInfo",
+    "Provenance",
+    "ReferenceInfo",
+    "RunManifest",
+]