dnakit 0.1.0.dev0__py3-none-any.whl

dnakit/core/record.py

@@ -0,0 +1,161 @@
+"""Immutable DNA record value object."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+from itertools import islice
+from typing import cast
+
+from dnakit.core._json import FrozenDict, freeze_mapping
+from dnakit.core.coordinates import CompoundLocation, UnresolvedLocation
+from dnakit.core.feature import DNAFeature
+from dnakit.core.gap import Gap
+from dnakit.core.sequence import DNASequence
+from dnakit.exceptions import SequenceError
+
+
+@dataclass(frozen=True, init=False)
+class DNARecord:
+    """A DNA sequence plus stable identity, annotations, and metadata."""
+
+    sequence: DNASequence
+    id: str
+    description: str
+    features: tuple[DNAFeature, ...]
+    metadata: FrozenDict
+    letter_annotations: Mapping[str, tuple[int | float, ...]]
+
+    __hash__ = None  # type: ignore[assignment]
+
+    def __init__(
+        self,
+        sequence: DNASequence,
+        id: str,
+        *,
+        description: str = "",
+        features: Iterable[DNAFeature] = (),
+        metadata: Mapping[str, object] | None = None,
+        letter_annotations: Mapping[str, Iterable[int | float]] | None = None,
+    ) -> None:
+        if not isinstance(sequence, DNASequence):
+            raise SequenceError(
+                "DNARecord sequence must be a DNASequence object.",
+                code="INVALID_RECORD_SEQUENCE",
+                context={"sequence_type": type(sequence).__name__},
+            )
+        if not isinstance(id, str) or not id.strip():
+            raise SequenceError(
+                "DNARecord id must be a non-empty string.",
+                code="INVALID_RECORD_ID",
+            )
+        if not isinstance(description, str):
+            raise SequenceError(
+                "DNARecord description must be a string.",
+                code="INVALID_RECORD_DESCRIPTION",
+            )
+        feature_tuple = tuple(features)
+        if any(not isinstance(feature, DNAFeature) for feature in feature_tuple):
+            raise SequenceError(
+                "DNARecord features must all be DNAFeature objects.",
+                code="INVALID_RECORD_FEATURE",
+            )
+        resolvable_span = 0
+        for part in sequence.parts:
+            if isinstance(part, str):
+                resolvable_span += len(part)
+            elif isinstance(part, Gap) and part.length is not None:
+                resolvable_span += part.length
+            else:
+                break
+        for index, feature in enumerate(feature_tuple):
+            location = feature.location
+            if isinstance(location, UnresolvedLocation):
+                intervals = location.anchors
+            else:
+                intervals = (
+                    location.parts if isinstance(location, CompoundLocation) else (location,)
+                )
+            if any(interval.end > resolvable_span for interval in intervals):
+                unknown_span = sequence.coordinate_span is None
+                raise SequenceError(
+                    (
+                        "A resolved feature extends beyond the resolvable sequence prefix."
+                        if unknown_span
+                        else "A feature location extends beyond the sequence coordinate span."
+                    ),
+                    code=(
+                        "FEATURE_LOCATION_UNRESOLVED" if unknown_span else "FEATURE_OUT_OF_BOUNDS"
+                    ),
+                    context={
+                        "feature_index": index,
+                        "feature_type": feature.type,
+                        "location_kind": type(location).__name__,
+                        "resolvable_span": resolvable_span,
+                        "sequence_span": sequence.coordinate_span,
+                    },
+                    hint=(
+                        "Use UnresolvedLocation for coordinates at or after an unknown-length Gap."
+                        if unknown_span
+                        else None
+                    ),
+                )
+
+        annotations_input: dict[str, object] = {}
+        for name, values in (letter_annotations or {}).items():
+            if not isinstance(name, str) or not name.strip():
+                raise SequenceError(
+                    "Letter annotation names must be non-empty strings.",
+                    code="INVALID_LETTER_ANNOTATION_NAME",
+                )
+            if isinstance(values, (str, bytes)):
+                raise SequenceError(
+                    "Letter annotation values must be numeric iterables.",
+                    code="INVALID_LETTER_ANNOTATION",
+                    context={"name": name},
+                )
+            try:
+                value_tuple = tuple(islice(iter(values), sequence.symbol_length + 1))
+            except TypeError as exc:
+                raise SequenceError(
+                    "Letter annotation values must be numeric iterables.",
+                    code="INVALID_LETTER_ANNOTATION",
+                    context={"name": name},
+                ) from exc
+            if len(value_tuple) != sequence.symbol_length:
+                raise SequenceError(
+                    "Letter annotation length must equal sequence symbol_length.",
+                    code="LETTER_ANNOTATION_LENGTH_MISMATCH",
+                    context={
+                        "name": name,
+                        "annotation_length": len(value_tuple),
+                        "symbol_length": sequence.symbol_length,
+                    },
+                )
+            if any(
+                isinstance(value, bool)
+                or not isinstance(value, (int, float))
+                or not math.isfinite(value)
+                for value in value_tuple
+            ):
+                raise SequenceError(
+                    "Letter annotations must contain only finite numeric values.",
+                    code="INVALID_LETTER_ANNOTATION",
+                    context={"name": name},
+                )
+            annotations_input[name] = value_tuple
+
+        object.__setattr__(self, "sequence", sequence)
+        object.__setattr__(self, "id", id)
+        object.__setattr__(self, "description", description)
+        object.__setattr__(self, "features", feature_tuple)
+        object.__setattr__(self, "metadata", freeze_mapping(metadata))
+        frozen_annotations = cast(
+            Mapping[str, tuple[int | float, ...]],
+            freeze_mapping(annotations_input),
+        )
+        object.__setattr__(self, "letter_annotations", frozen_annotations)
+
+
+__all__ = ["DNARecord"]

dnakit/core/results.py

@@ -0,0 +1,134 @@
+"""Generic immutable result values shared by DNAKit domains."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+from typing import Any, Generic, TypeVar, cast
+
+from dnakit.core._json import FrozenDict, JSONValue, freeze_json, freeze_mapping, to_json_compatible
+from dnakit.core.issues import Issue
+from dnakit.core.provenance import Provenance
+from dnakit.exceptions import ConfigurationError
+
+T = TypeVar("T")
+
+
+@dataclass(frozen=True, init=False)
+class Uncertainty:
+    """Optional uncertainty summary attached to a numerical result."""
+
+    confidence_interval: tuple[float, float] | None
+    standard_error: float | None
+    method: str | None
+
+    def __init__(
+        self,
+        confidence_interval: tuple[float, float] | None = None,
+        standard_error: float | None = None,
+        method: str | None = None,
+    ) -> None:
+        resolved_interval: tuple[float, float] | None = None
+        if confidence_interval is not None:
+            copied_interval = tuple(confidence_interval)
+            if len(copied_interval) != 2:
+                raise ConfigurationError("confidence_interval must contain exactly two bounds.")
+            lower, upper = copied_interval
+            if (
+                isinstance(lower, bool)
+                or not isinstance(lower, (int, float))
+                or isinstance(upper, bool)
+                or not isinstance(upper, (int, float))
+                or not math.isfinite(lower)
+                or not math.isfinite(upper)
+                or lower > upper
+            ):
+                raise ConfigurationError(
+                    "confidence_interval bounds must be finite and ordered.",
+                    context={"lower": lower, "upper": upper},
+                )
+            resolved_interval = (float(lower), float(upper))
+        if standard_error is not None and (
+            isinstance(standard_error, bool)
+            or not isinstance(standard_error, (int, float))
+            or not math.isfinite(standard_error)
+            or standard_error < 0
+        ):
+            raise ConfigurationError("standard_error must be a finite non-negative number.")
+        if method is not None and (not isinstance(method, str) or not method.strip()):
+            raise ConfigurationError("Uncertainty method must be None or a non-empty string.")
+
+        object.__setattr__(self, "confidence_interval", resolved_interval)
+        object.__setattr__(
+            self,
+            "standard_error",
+            None if standard_error is None else float(standard_error),
+        )
+        object.__setattr__(self, "method", method)
+
+
+@dataclass(frozen=True, init=False)
+class MetricResult(Generic[T]):
+    """A metric value plus method, conditions, provenance, and diagnostics."""
+
+    name: str
+    value: T
+    unit: str | None
+    method: str
+    algorithm_version: str
+    parameters: FrozenDict
+    conditions: FrozenDict
+    uncertainty: Uncertainty | None
+    provenance: Provenance
+    issues: tuple[Issue, ...]
+
+    def __init__(
+        self,
+        name: str,
+        value: T,
+        *,
+        method: str,
+        algorithm_version: str,
+        provenance: Provenance | None = None,
+        unit: str | None = None,
+        parameters: Mapping[str, object] | None = None,
+        conditions: Mapping[str, object] | None = None,
+        uncertainty: Uncertainty | None = None,
+        issues: Iterable[Issue] = (),
+    ) -> None:
+        for field_name, field_value in (
+            ("name", name),
+            ("method", method),
+            ("algorithm_version", algorithm_version),
+        ):
+            if not isinstance(field_value, str) or not field_value.strip():
+                raise ConfigurationError(f"MetricResult {field_name} must be non-empty.")
+        if unit is not None and (not isinstance(unit, str) or not unit.strip()):
+            raise ConfigurationError("MetricResult unit must be None or a non-empty string.")
+        if uncertainty is not None and not isinstance(uncertainty, Uncertainty):
+            raise ConfigurationError("MetricResult uncertainty must be Uncertainty or None.")
+        resolved_provenance = provenance or Provenance()
+        if not isinstance(resolved_provenance, Provenance):
+            raise ConfigurationError("MetricResult provenance must be Provenance.")
+        issue_tuple = tuple(issues)
+        if any(not isinstance(issue, Issue) for issue in issue_tuple):
+            raise ConfigurationError("MetricResult issues must all be Issue objects.")
+        frozen_value: JSONValue = freeze_json(value)
+
+        object.__setattr__(self, "name", name)
+        object.__setattr__(self, "value", cast(T, frozen_value))
+        object.__setattr__(self, "unit", unit)
+        object.__setattr__(self, "method", method)
+        object.__setattr__(self, "algorithm_version", algorithm_version)
+        object.__setattr__(self, "parameters", freeze_mapping(parameters))
+        object.__setattr__(self, "conditions", freeze_mapping(conditions))
+        object.__setattr__(self, "uncertainty", uncertainty)
+        object.__setattr__(self, "provenance", resolved_provenance)
+        object.__setattr__(self, "issues", issue_tuple)
+
+    def to_dict(self) -> dict[str, Any]:
+        return cast(dict[str, Any], to_json_compatible(self))
+
+
+__all__ = ["MetricResult", "Uncertainty"]

dnakit/core/sequence.py

@@ -0,0 +1,327 @@
+"""Immutable DNA sequence value object."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator, Sequence
+from dataclasses import dataclass
+
+from dnakit.core.enums import DNAAlphabet, Strandedness, Topology
+from dnakit.core.gap import Gap
+from dnakit.exceptions import (
+    InvalidAlphabetError,
+    SequenceError,
+    UnknownLengthError,
+    UnsupportedGapOperationError,
+)
+
+STRICT_SYMBOLS = frozenset("ACGT")
+IUPAC_SYMBOLS = frozenset("ACGTRYSWKMBDHVN")
+_COMPLEMENT = str.maketrans(
+    {
+        "A": "T",
+        "C": "G",
+        "G": "C",
+        "T": "A",
+        "R": "Y",
+        "Y": "R",
+        "S": "S",
+        "W": "W",
+        "K": "M",
+        "M": "K",
+        "B": "V",
+        "D": "H",
+        "H": "D",
+        "V": "B",
+        "N": "N",
+    }
+)
+
+
+def _coerce_alphabet(value: DNAAlphabet | str) -> DNAAlphabet:
+    try:
+        return value if isinstance(value, DNAAlphabet) else DNAAlphabet(value)
+    except (TypeError, ValueError) as exc:
+        raise SequenceError(
+            "Unknown DNA alphabet.",
+            code="INVALID_ALPHABET_DECLARATION",
+            context={"alphabet": value},
+            hint=f"Choose one of: {', '.join(item.value for item in DNAAlphabet)}.",
+        ) from exc
+
+
+def _coerce_topology(value: Topology | str) -> Topology:
+    try:
+        return value if isinstance(value, Topology) else Topology(value)
+    except (TypeError, ValueError) as exc:
+        raise SequenceError(
+            "Unknown sequence topology.",
+            code="INVALID_TOPOLOGY",
+            context={"topology": value},
+            hint=f"Choose one of: {', '.join(item.value for item in Topology)}.",
+        ) from exc
+
+
+def _coerce_strandedness(value: Strandedness | str) -> Strandedness:
+    try:
+        return value if isinstance(value, Strandedness) else Strandedness(value)
+    except (TypeError, ValueError) as exc:
+        raise SequenceError(
+            "Unknown sequence strandedness.",
+            code="INVALID_STRANDEDNESS",
+            context={"strandedness": value},
+            hint=f"Choose one of: {', '.join(item.value for item in Strandedness)}.",
+        ) from exc
+
+
+def _decode_ascii(value: bytes) -> str:
+    try:
+        return value.decode("ascii")
+    except UnicodeDecodeError as exc:
+        raise InvalidAlphabetError(
+            "DNA bytes must use ASCII encoding.",
+            context={"byte_offset": exc.start},
+            hint="Decode or clean the raw input with normalize() before construction.",
+        ) from exc
+
+
+def _normalize_parts(parts: str | bytes | Iterable[str | Gap]) -> tuple[str | Gap, ...]:
+    if isinstance(parts, bytes):
+        raw_parts: Iterable[str | Gap] = (_decode_ascii(parts),)
+    elif isinstance(parts, str):
+        raw_parts = (parts,)
+    else:
+        try:
+            raw_parts = iter(parts)
+        except TypeError as exc:
+            raise SequenceError(
+                "Sequence parts must be text, bytes, or an iterable of text and Gap objects.",
+                code="INVALID_SEQUENCE_PARTS",
+                context={"parts_type": type(parts).__name__},
+            ) from exc
+
+    normalized: list[str | Gap] = []
+    text_buffer: list[str] = []
+
+    def flush_text() -> None:
+        if text_buffer:
+            normalized.append("".join(text_buffer))
+            text_buffer.clear()
+
+    for index, part in enumerate(raw_parts):
+        if isinstance(part, str):
+            if part:
+                text_buffer.append(part)
+        elif isinstance(part, Gap):
+            flush_text()
+            normalized.append(part)
+        else:
+            raise SequenceError(
+                "Each sequence part must be a string or Gap.",
+                code="INVALID_SEQUENCE_PART",
+                context={"part_index": index, "part_type": type(part).__name__},
+            )
+    flush_text()
+    return tuple(normalized)
+
+
+@dataclass(frozen=True, init=False)
+class DNASequence:
+    """Canonical immutable DNA symbols and explicit gap parts.
+
+    The constructor validates already-normalized content.  It deliberately does
+    not uppercase, strip whitespace, or replace uracil; callers should use the
+    normalization API for those auditable transformations.
+    """
+
+    parts: tuple[str | Gap, ...]
+    alphabet: DNAAlphabet
+    topology: Topology
+    strandedness: Strandedness
+
+    def __init__(
+        self,
+        parts: str | bytes | Iterable[str | Gap],
+        *,
+        alphabet: DNAAlphabet | str = DNAAlphabet.STRICT,
+        topology: Topology | str = Topology.LINEAR,
+        strandedness: Strandedness | str = Strandedness.SINGLE,
+    ) -> None:
+        resolved_parts = _normalize_parts(parts)
+        resolved_alphabet = _coerce_alphabet(alphabet)
+        resolved_topology = _coerce_topology(topology)
+        resolved_strandedness = _coerce_strandedness(strandedness)
+
+        allowed = STRICT_SYMBOLS if resolved_alphabet is DNAAlphabet.STRICT else IUPAC_SYMBOLS
+        for part_index, part in enumerate(resolved_parts):
+            if isinstance(part, Gap):
+                continue
+            invalid = next(
+                ((offset, symbol) for offset, symbol in enumerate(part) if symbol not in allowed),
+                None,
+            )
+            if invalid is not None:
+                offset, symbol = invalid
+                raise InvalidAlphabetError(
+                    f"Symbol {symbol!r} is not valid for the {resolved_alphabet.value} alphabet.",
+                    context={
+                        "alphabet": resolved_alphabet.value,
+                        "part_index": part_index,
+                        "part_offset": offset,
+                        "symbol": symbol,
+                    },
+                    hint="Pass raw or mixed-case input through normalize() first.",
+                )
+
+        symbol_length = sum(len(part) for part in resolved_parts if isinstance(part, str))
+        if resolved_topology is Topology.CIRCULAR and symbol_length == 0:
+            raise SequenceError(
+                "A circular DNA sequence must contain at least one nucleotide symbol.",
+                code="EMPTY_CIRCULAR_SEQUENCE",
+                hint="Use linear topology for an empty placeholder sequence.",
+            )
+
+        object.__setattr__(self, "parts", resolved_parts)
+        object.__setattr__(self, "alphabet", resolved_alphabet)
+        object.__setattr__(self, "topology", resolved_topology)
+        object.__setattr__(self, "strandedness", resolved_strandedness)
+
+    @classmethod
+    def from_fragments(
+        cls,
+        fragments: Iterable[str | bytes],
+        gaps: Iterable[Gap],
+        *,
+        alphabet: DNAAlphabet | str = DNAAlphabet.STRICT,
+        topology: Topology | str = Topology.LINEAR,
+        strandedness: Strandedness | str = Strandedness.SINGLE,
+    ) -> DNASequence:
+        """Interleave ``n`` gaps between exactly ``n + 1`` sequence fragments."""
+
+        fragment_tuple = tuple(
+            _decode_ascii(fragment) if isinstance(fragment, bytes) else fragment
+            for fragment in fragments
+        )
+        gap_tuple = tuple(gaps)
+        if len(fragment_tuple) != len(gap_tuple) + 1:
+            raise SequenceError(
+                "from_fragments() requires exactly one more fragment than gaps.",
+                code="FRAGMENT_GAP_COUNT_MISMATCH",
+                context={"fragment_count": len(fragment_tuple), "gap_count": len(gap_tuple)},
+            )
+        if any(not isinstance(fragment, str) for fragment in fragment_tuple):
+            raise SequenceError(
+                "Fragments must be strings or ASCII bytes.",
+                code="INVALID_SEQUENCE_FRAGMENT",
+            )
+        if any(not isinstance(gap, Gap) for gap in gap_tuple):
+            raise SequenceError("All gaps must be Gap objects.", code="INVALID_GAP")
+
+        parts: list[str | Gap] = []
+        for index, fragment in enumerate(fragment_tuple):
+            parts.append(fragment)
+            if index < len(gap_tuple):
+                parts.append(gap_tuple[index])
+        return cls(
+            parts,
+            alphabet=alphabet,
+            topology=topology,
+            strandedness=strandedness,
+        )
+
+    @property
+    def symbol_length(self) -> int:
+        """Number of nucleotide symbols, excluding explicit gap spans."""
+
+        return sum(len(part) for part in self.parts if isinstance(part, str))
+
+    @property
+    def canonical_base_count(self) -> int:
+        return sum(
+            sum(symbol in STRICT_SYMBOLS for symbol in part)
+            for part in self.parts
+            if isinstance(part, str)
+        )
+
+    @property
+    def ambiguity_count(self) -> int:
+        return self.symbol_length - self.canonical_base_count
+
+    @property
+    def coordinate_span(self) -> int | None:
+        span = self.symbol_length
+        for part in self.parts:
+            if isinstance(part, Gap):
+                if part.length is None:
+                    return None
+                span += part.length
+        return span
+
+    @property
+    def length(self) -> int | None:
+        """Explicit alias for :attr:`coordinate_span`."""
+
+        return self.coordinate_span
+
+    @property
+    def is_gapped(self) -> bool:
+        return any(isinstance(part, Gap) for part in self.parts)
+
+    @property
+    def has_unknown_length(self) -> bool:
+        return any(isinstance(part, Gap) and part.length is None for part in self.parts)
+
+    @property
+    def symbols(self) -> str:
+        """Concatenate nucleotide symbols while explicitly omitting gaps."""
+
+        return "".join(part for part in self.parts if isinstance(part, str))
+
+    def to_string(self) -> str:
+        """Return an ordinary string only when doing so cannot discard gaps."""
+
+        if self.is_gapped:
+            raise UnsupportedGapOperationError(
+                "A gapped DNASequence cannot be represented as a plain DNA string.",
+                hint="Inspect parts or use symbols explicitly if omitting gaps is intended.",
+            )
+        return self.symbols
+
+    def __len__(self) -> int:
+        span = self.coordinate_span
+        if span is None:
+            raise UnknownLengthError(
+                "Exact sequence length is unknown because at least one gap has unknown length.",
+                hint="Use symbol_length or resolve every Gap.length before requesting len().",
+            )
+        return span
+
+    def __iter__(self) -> Iterator[str | Gap]:
+        return iter(self.parts)
+
+    def reverse(self) -> DNASequence:
+        return self._transform(reverse=True, complement=False)
+
+    def complement(self) -> DNASequence:
+        return self._transform(reverse=False, complement=True)
+
+    def reverse_complement(self) -> DNASequence:
+        return self._transform(reverse=True, complement=True)
+
+    def _transform(self, *, reverse: bool, complement: bool) -> DNASequence:
+        source: Sequence[str | Gap] = self.parts[::-1] if reverse else self.parts
+        transformed: list[str | Gap] = []
+        for part in source:
+            if isinstance(part, Gap):
+                transformed.append(part)
+                continue
+            text = part[::-1] if reverse else part
+            transformed.append(text.translate(_COMPLEMENT) if complement else text)
+        return DNASequence(
+            transformed,
+            alphabet=self.alphabet,
+            topology=self.topology,
+            strandedness=self.strandedness,
+        )
+
+
+__all__ = ["IUPAC_SYMBOLS", "STRICT_SYMBOLS", "DNASequence"]