dnakit 0.1.0.dev0__py3-none-any.whl

dnakit/core/_json.py

@@ -0,0 +1,206 @@
+"""Immutable JSON-compatible containers for core value objects."""
+
+from __future__ import annotations
+
+import json
+import math
+from collections.abc import Iterator, Mapping
+from dataclasses import fields, is_dataclass
+from enum import Enum
+from types import MappingProxyType
+from typing import TypeAlias, Union
+
+from dnakit.exceptions import ConfigurationError
+
+JSONScalar: TypeAlias = bool | int | float | str | None
+JSONValue: TypeAlias = Union[JSONScalar, tuple["JSONValue", ...], "FrozenDict"]
+_MAX_JSON_DEPTH = 64
+_MAX_JSON_NODES = 1_000_000
+
+
+class _TraversalBudget:
+    __slots__ = ("active", "nodes")
+
+    def __init__(self) -> None:
+        self.nodes = 0
+        self.active: set[int] = set()
+
+    def count(self, depth: int) -> None:
+        self.nodes += 1
+        if depth > _MAX_JSON_DEPTH or self.nodes > _MAX_JSON_NODES:
+            raise ConfigurationError(
+                "JSON-compatible value exceeds structural limits.",
+                code="JSON_STRUCTURE_LIMIT",
+                context={"max_depth": _MAX_JSON_DEPTH, "max_nodes": _MAX_JSON_NODES},
+            )
+
+    def enter(self, value: object) -> None:
+        identity = id(value)
+        if identity in self.active:
+            raise ConfigurationError(
+                "JSON-compatible value contains a recursive reference.",
+                code="JSON_RECURSIVE_REFERENCE",
+            )
+        self.active.add(identity)
+
+    def leave(self, value: object) -> None:
+        self.active.remove(id(value))
+
+
+class FrozenDict(Mapping[str, JSONValue]):
+    """A recursively immutable and hashable mapping with string keys."""
+
+    __slots__ = ("_data", "_hash")
+
+    _data: Mapping[str, JSONValue]
+    _hash: int
+
+    def __init__(self, values: Mapping[str, object] | None = None) -> None:
+        source = {} if values is None else values
+        frozen = _freeze_json(source, _TraversalBudget(), 0)
+        if not isinstance(frozen, FrozenDict):  # pragma: no cover - source is a Mapping.
+            raise ConfigurationError("FrozenDict source must be a mapping.")
+        object.__setattr__(self, "_data", frozen._data)
+        object.__setattr__(self, "_hash", frozen._hash)
+
+    def __getitem__(self, key: str) -> JSONValue:
+        return self._data[key]
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._data)
+
+    def __len__(self) -> int:
+        return len(self._data)
+
+    def __hash__(self) -> int:
+        return self._hash
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Mapping):
+            return NotImplemented
+        return dict(self.items()) == dict(other.items())
+
+    def __repr__(self) -> str:
+        return f"FrozenDict({self._data!r})"
+
+    def __setattr__(self, name: str, value: object) -> None:
+        raise AttributeError("FrozenDict is immutable.")
+
+
+def _freeze_json(value: object, budget: _TraversalBudget, depth: int) -> JSONValue:
+    budget.count(depth)
+    if isinstance(value, Enum):
+        return _freeze_json(value.value, budget, depth + 1)
+    if value is None or isinstance(value, (bool, int, str)):
+        return value
+    if isinstance(value, float):
+        if not math.isfinite(value):
+            raise ConfigurationError(
+                "JSON-compatible floating-point values must be finite.",
+                context={"value": repr(value)},
+            )
+        return value
+    if isinstance(value, Mapping):
+        budget.enter(value)
+        try:
+            data: dict[str, JSONValue] = {}
+            for key in value:
+                budget.count(depth + 1)
+                if not isinstance(key, str):
+                    raise ConfigurationError(
+                        "JSON-compatible mapping keys must be strings.",
+                        context={"key_type": type(key).__name__},
+                    )
+                data[key] = _freeze_json(value[key], budget, depth + 1)
+            frozen = object.__new__(FrozenDict)
+            object.__setattr__(frozen, "_data", MappingProxyType(data))
+            object.__setattr__(frozen, "_hash", hash(tuple(sorted(data.items()))))
+            return frozen
+        finally:
+            budget.leave(value)
+    if isinstance(value, (tuple, list)):
+        budget.enter(value)
+        try:
+            return tuple(_freeze_json(item, budget, depth + 1) for item in value)
+        finally:
+            budget.leave(value)
+    raise ConfigurationError(
+        "Value is not JSON-compatible.",
+        context={"value_type": type(value).__name__},
+        hint="Use None, booleans, finite numbers, strings, lists, or string-keyed mappings.",
+    )
+
+
+def freeze_json(value: object) -> JSONValue:
+    """Validate and recursively freeze a bounded JSON-compatible value."""
+
+    return _freeze_json(value, _TraversalBudget(), 0)
+
+
+def freeze_mapping(values: Mapping[str, object] | None) -> FrozenDict:
+    """Return an immutable defensive copy of a JSON-compatible mapping."""
+
+    return FrozenDict(values)
+
+
+def to_json_compatible(value: object) -> object:
+    """Convert core values into plain objects accepted by ``json.dumps``."""
+
+    return _to_json_compatible(value, _TraversalBudget(), 0)
+
+
+def _to_json_compatible(value: object, budget: _TraversalBudget, depth: int) -> object:
+    budget.count(depth)
+    if isinstance(value, Enum):
+        return _to_json_compatible(value.value, budget, depth + 1)
+    if isinstance(value, Mapping):
+        budget.enter(value)
+        try:
+            result: dict[str, object] = {}
+            for key in value:
+                budget.count(depth + 1)
+                result[str(key)] = _to_json_compatible(value[key], budget, depth + 1)
+            return result
+        finally:
+            budget.leave(value)
+    if isinstance(value, frozenset):
+        budget.enter(value)
+        try:
+            converted = [_to_json_compatible(item, budget, depth + 1) for item in value]
+            return sorted(
+                converted,
+                key=lambda item: json.dumps(
+                    item,
+                    ensure_ascii=False,
+                    sort_keys=True,
+                    separators=(",", ":"),
+                ),
+            )
+        finally:
+            budget.leave(value)
+    if isinstance(value, (tuple, list)):
+        budget.enter(value)
+        try:
+            return [_to_json_compatible(item, budget, depth + 1) for item in value]
+        finally:
+            budget.leave(value)
+    if is_dataclass(value) and not isinstance(value, type):
+        budget.enter(value)
+        try:
+            return {
+                field.name: _to_json_compatible(getattr(value, field.name), budget, depth + 1)
+                for field in fields(value)
+            }
+        finally:
+            budget.leave(value)
+    return value
+
+
+__all__ = [
+    "FrozenDict",
+    "JSONScalar",
+    "JSONValue",
+    "freeze_json",
+    "freeze_mapping",
+    "to_json_compatible",
+]

dnakit/core/backend_info.py

@@ -0,0 +1,70 @@
+"""Passive metadata describing an optional computational backend."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+from typing import Any, cast
+
+from dnakit.core._json import FrozenDict, freeze_mapping, to_json_compatible
+from dnakit.exceptions import ConfigurationError
+
+
+@dataclass(frozen=True, init=False)
+class BackendInfo:
+    """Backend probe result without importing a domain protocol or adapter."""
+
+    name: str
+    version: str | None
+    executable_path: str | None
+    package_location: str | None
+    license_expression: str | None
+    capabilities: frozenset[str]
+    available: bool
+    metadata: FrozenDict
+
+    def __init__(
+        self,
+        name: str,
+        *,
+        version: str | None = None,
+        executable_path: str | None = None,
+        package_location: str | None = None,
+        license_expression: str | None = None,
+        capabilities: Iterable[str] = (),
+        available: bool = True,
+        metadata: Mapping[str, object] | None = None,
+    ) -> None:
+        if not isinstance(name, str) or not name.strip():
+            raise ConfigurationError("Backend name must be a non-empty string.")
+        for field_name, value in (
+            ("version", version),
+            ("executable_path", executable_path),
+            ("package_location", package_location),
+            ("license_expression", license_expression),
+        ):
+            if value is not None and (not isinstance(value, str) or not value.strip()):
+                raise ConfigurationError(
+                    f"Backend {field_name} must be None or a non-empty string.",
+                    context={field_name: value},
+                )
+        capability_set = frozenset(capabilities)
+        if any(not isinstance(item, str) or not item.strip() for item in capability_set):
+            raise ConfigurationError("Backend capabilities must be non-empty strings.")
+        if not isinstance(available, bool):
+            raise ConfigurationError("Backend available must be a boolean.")
+
+        object.__setattr__(self, "name", name)
+        object.__setattr__(self, "version", version)
+        object.__setattr__(self, "executable_path", executable_path)
+        object.__setattr__(self, "package_location", package_location)
+        object.__setattr__(self, "license_expression", license_expression)
+        object.__setattr__(self, "capabilities", capability_set)
+        object.__setattr__(self, "available", available)
+        object.__setattr__(self, "metadata", freeze_mapping(metadata))
+
+    def to_dict(self) -> dict[str, Any]:
+        return cast(dict[str, Any], to_json_compatible(self))
+
+
+__all__ = ["BackendInfo"]

dnakit/core/collection.py

@@ -0,0 +1,163 @@
+"""In-memory immutable DNA record collection."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Iterator, Mapping
+from dataclasses import dataclass
+from typing import overload
+
+from dnakit.core._json import FrozenDict, freeze_mapping
+from dnakit.core.record import DNARecord
+from dnakit.core.sequence import DNASequence
+from dnakit.exceptions import DuplicateIDError, SequenceError
+
+IDFactory = Callable[[int, DNASequence], str]
+
+
+def _default_id_factory(index: int, sequence: DNASequence) -> str:
+    del sequence
+    return f"sequence_{index + 1}"
+
+
+@dataclass(frozen=True, init=False)
+class DNASet:
+    """A repeatable, materialized collection of :class:`DNARecord` objects."""
+
+    records: tuple[DNARecord, ...]
+    name: str | None
+    source: str | None
+    version: str | None
+    metadata: FrozenDict
+
+    __hash__ = None  # type: ignore[assignment]
+
+    def __init__(
+        self,
+        records: Iterable[DNARecord],
+        *,
+        name: str | None = None,
+        source: str | None = None,
+        version: str | None = None,
+        metadata: Mapping[str, object] | None = None,
+    ) -> None:
+        record_tuple = tuple(records)
+        if any(not isinstance(record, DNARecord) for record in record_tuple):
+            raise SequenceError(
+                "DNASet records must all be DNARecord objects.",
+                code="INVALID_DNASET_RECORD",
+            )
+        for field_name, value in (("name", name), ("source", source), ("version", version)):
+            if value is not None and (not isinstance(value, str) or not value.strip()):
+                raise SequenceError(
+                    f"DNASet {field_name} must be None or a non-empty string.",
+                    code="INVALID_DNASET_METADATA",
+                    context={field_name: value},
+                )
+        object.__setattr__(self, "records", record_tuple)
+        object.__setattr__(self, "name", name)
+        object.__setattr__(self, "source", source)
+        object.__setattr__(self, "version", version)
+        object.__setattr__(self, "metadata", freeze_mapping(metadata))
+
+    @classmethod
+    def from_records(
+        cls,
+        records: Iterable[DNARecord],
+        *,
+        name: str | None = None,
+        source: str | None = None,
+        version: str | None = None,
+        metadata: Mapping[str, object] | None = None,
+    ) -> DNASet:
+        return cls(
+            records,
+            name=name,
+            source=source,
+            version=version,
+            metadata=metadata,
+        )
+
+    @classmethod
+    def from_sequences(
+        cls,
+        sequences: Iterable[DNASequence],
+        *,
+        id_factory: IDFactory | None = None,
+        name: str | None = None,
+        source: str | None = None,
+        version: str | None = None,
+        metadata: Mapping[str, object] | None = None,
+    ) -> DNASet:
+        factory = _default_id_factory if id_factory is None else id_factory
+        records: list[DNARecord] = []
+        for index, sequence in enumerate(sequences):
+            if not isinstance(sequence, DNASequence):
+                raise SequenceError(
+                    "DNASet.from_sequences() accepts only DNASequence objects.",
+                    code="INVALID_DNASET_SEQUENCE",
+                    context={"index": index, "value_type": type(sequence).__name__},
+                )
+            record_id = factory(index, sequence)
+            records.append(DNARecord(sequence, record_id))
+        return cls(
+            records,
+            name=name,
+            source=source,
+            version=version,
+            metadata=metadata,
+        )
+
+    def __len__(self) -> int:
+        return len(self.records)
+
+    def __iter__(self) -> Iterator[DNARecord]:
+        return iter(self.records)
+
+    @overload
+    def __getitem__(self, index: int) -> DNARecord: ...
+
+    @overload
+    def __getitem__(self, index: slice) -> DNASet: ...
+
+    def __getitem__(self, index: int | slice) -> DNARecord | DNASet:
+        if isinstance(index, slice):
+            return DNASet(
+                self.records[index],
+                name=self.name,
+                source=self.source,
+                version=self.version,
+                metadata=self.metadata,
+            )
+        return self.records[index]
+
+    @property
+    def ids(self) -> tuple[str, ...]:
+        return tuple(record.id for record in self.records)
+
+    def get(self, record_id: str) -> DNARecord:
+        """Return one record by ID, rejecting missing and duplicate matches."""
+
+        matches = tuple(record for record in self.records if record.id == record_id)
+        if not matches:
+            raise KeyError(record_id)
+        if len(matches) > 1:
+            raise DuplicateIDError(
+                "Record ID is not unique in this DNASet.",
+                context={"record_id": record_id, "count": len(matches)},
+                hint="Run validate() and resolve duplicate IDs before keyed lookup.",
+            )
+        return matches[0]
+
+    def select(self, indices: Iterable[int]) -> DNASet:
+        """Return records at the requested input-order indices."""
+
+        return DNASet(
+            (self.records[index] for index in indices),
+            name=self.name,
+            source=self.source,
+            version=self.version,
+            metadata=self.metadata,
+        )
+
+
+__all__ = ["DNASet", "IDFactory"]