dnakit 0.1.0.dev0__py3-none-any.whl

dnakit/ops/_common.py

@@ -0,0 +1,201 @@
+"""Internal helpers shared by deterministic sequence operations."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from dnakit.core import DNAAlphabet, DNASequence, Gap, Interval, Strandedness, Topology
+from dnakit.exceptions import (
+    ConfigurationError,
+    CoordinateError,
+    SequenceError,
+    UnknownLengthError,
+    UnsupportedGapOperationError,
+)
+
+
+def require_sequence(sequence: DNASequence) -> DNASequence:
+    """Return a validated sequence argument with a domain-specific error."""
+
+    if not isinstance(sequence, DNASequence):
+        raise SequenceError(
+            "A DNASequence object is required.",
+            code="INVALID_SEQUENCE_ARGUMENT",
+            context={"type": type(sequence).__name__},
+        )
+    return sequence
+
+
+def resolved_span(sequence: DNASequence, *, operation: str) -> int:
+    """Return a coordinate span, refusing to guess an unknown gap length."""
+
+    span = sequence.coordinate_span
+    if span is None:
+        raise UnknownLengthError(
+            f"{operation} requires every Gap to have a known length.",
+            code="UNRESOLVED_OPERATION_COORDINATES",
+            context={"operation": operation},
+            hint="Resolve unknown Gap.length values before using coordinate-based operations.",
+        )
+    return span
+
+
+def validate_position(position: int, *, span: int, allow_end: bool = True) -> None:
+    """Validate one zero-based position or insertion boundary."""
+
+    if isinstance(position, bool) or not isinstance(position, int):
+        raise CoordinateError(
+            "Position must be a non-negative integer.",
+            context={"position": position, "sequence_span": span},
+        )
+    upper_ok = position <= span if allow_end else position < span
+    if position < 0 or not upper_ok:
+        relation = "at most" if allow_end else "smaller than"
+        raise CoordinateError(
+            f"Position must be a non-negative integer {relation} the sequence span.",
+            context={"position": position, "sequence_span": span},
+        )
+
+
+def validate_interval(start: int, end: int, *, span: int) -> Interval:
+    """Build and bounds-check an internal zero-based, half-open interval."""
+
+    interval = Interval(start, end)
+    if interval.end > span:
+        raise CoordinateError(
+            "Interval exceeds the sequence coordinate span.",
+            context={"start": start, "end": end, "sequence_span": span},
+        )
+    return interval
+
+
+def copy_gap(gap: Gap, *, length: int) -> Gap:
+    """Copy a gap while replacing only its known coordinate length."""
+
+    return Gap(
+        length,
+        kind=gap.kind,
+        crossable=gap.crossable,
+        evidence=gap.evidence,
+        metadata=gap.metadata,
+    )
+
+
+def interval_overlaps_gap(sequence: DNASequence, interval: Interval) -> bool:
+    """Return whether a resolved interval contains any gap coordinate."""
+
+    cursor = 0
+    for part in sequence.parts:
+        part_length = len(part) if isinstance(part, str) else part.length
+        if part_length is None:
+            raise UnknownLengthError(
+                "Gap overlap cannot be resolved for an unknown-length Gap.",
+                code="UNRESOLVED_GAP_COORDINATES",
+            )
+        part_end = cursor + part_length
+        if isinstance(part, Gap) and interval.start < part_end and cursor < interval.end:
+            return True
+        cursor = part_end
+    return False
+
+
+def position_inside_gap(sequence: DNASequence, position: int) -> bool:
+    """Return whether an insertion boundary lies strictly inside a gap."""
+
+    cursor = 0
+    for part in sequence.parts:
+        part_length = len(part) if isinstance(part, str) else part.length
+        if part_length is None:
+            raise UnknownLengthError(
+                "Insertion coordinates cannot be resolved for an unknown-length Gap.",
+                code="UNRESOLVED_GAP_COORDINATES",
+            )
+        part_end = cursor + part_length
+        if isinstance(part, Gap) and cursor < position < part_end:
+            return True
+        cursor = part_end
+    return False
+
+
+def reject_gap_overlap(sequence: DNASequence, interval: Interval, *, operation: str) -> None:
+    """Reject edits that would silently consume assembly-gap coordinates."""
+
+    if interval_overlaps_gap(sequence, interval):
+        raise UnsupportedGapOperationError(
+            f"{operation} cannot overlap a Gap.",
+            code="EDIT_OVERLAPS_GAP",
+            context={"operation": operation, "start": interval.start, "end": interval.end},
+            hint="Edit nucleotide fragments separately or resolve the assembly gap first.",
+        )
+
+
+def infer_alphabet(symbols: str, *, fallback: DNAAlphabet) -> DNAAlphabet:
+    """Infer the narrowest DNA alphabet for already-normalized symbols."""
+
+    if not symbols:
+        return fallback
+    return DNAAlphabet.STRICT if set(symbols) <= set("ACGT") else DNAAlphabet.IUPAC
+
+
+def promote_alphabet(*alphabets: DNAAlphabet) -> DNAAlphabet:
+    """Return IUPAC if any contributing sequence requires it."""
+
+    return (
+        DNAAlphabet.IUPAC
+        if any(alphabet is DNAAlphabet.IUPAC for alphabet in alphabets)
+        else DNAAlphabet.STRICT
+    )
+
+
+def coerce_fragment(
+    fragment: DNASequence | str,
+    *,
+    fallback_alphabet: DNAAlphabet,
+    strandedness: Strandedness,
+) -> DNASequence:
+    """Convert a normalized string or linear sequence to an embeddable fragment."""
+
+    if isinstance(fragment, str):
+        alphabet = infer_alphabet(fragment, fallback=fallback_alphabet)
+        return DNASequence(fragment, alphabet=alphabet, strandedness=strandedness)
+    if not isinstance(fragment, DNASequence):
+        raise SequenceError(
+            "A sequence fragment must be DNASequence or normalized DNA text.",
+            code="INVALID_SEQUENCE_FRAGMENT",
+            context={"type": type(fragment).__name__},
+        )
+    if fragment.topology is Topology.CIRCULAR:
+        raise ConfigurationError(
+            "A circular DNASequence cannot be embedded as a linear fragment.",
+            code="CIRCULAR_FRAGMENT_NOT_SUPPORTED",
+        )
+    if fragment.strandedness is not strandedness:
+        raise ConfigurationError(
+            "All sequence fragments must have matching strandedness.",
+            code="STRANDEDNESS_MISMATCH",
+            context={
+                "expected": strandedness.value,
+                "observed": fragment.strandedness.value,
+            },
+        )
+    return fragment
+
+
+def combine_parts(
+    parts: Iterable[str | Gap],
+    *,
+    alphabet: DNAAlphabet,
+    topology: Topology,
+    strandedness: Strandedness,
+) -> DNASequence:
+    """Construct a fresh immutable sequence from operation output parts."""
+
+    return DNASequence(
+        parts,
+        alphabet=alphabet,
+        topology=topology,
+        strandedness=strandedness,
+    )
+
+
+__all__: list[str] = []

dnakit/ops/circular.py

@@ -0,0 +1,193 @@
+"""Deterministic origin operations for circular DNA sequences."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal, TypeAlias
+
+from dnakit.core import DNASequence, Topology
+from dnakit.core._json import FrozenDict, to_json_compatible
+from dnakit.exceptions import ConfigurationError, UnsupportedGapOperationError
+from dnakit.ops._common import require_sequence, resolved_span
+from dnakit.ops.edit import _split_at
+
+CircularOperation: TypeAlias = Literal["rotate", "canonical_origin"]
+
+
+@dataclass(frozen=True, slots=True)
+class CircularOperationResult:
+    """A circular sequence with an auditable origin-selection decision."""
+
+    sequence: DNASequence
+    operation: CircularOperation
+    requested_offset: int | None
+    effective_offset: int
+    sequence_span: int
+    rule: str
+    parameters: FrozenDict
+
+    def __post_init__(self) -> None:
+        if self.operation not in {"rotate", "canonical_origin"}:
+            raise ConfigurationError("Unknown circular operation result kind.")
+        if self.sequence.topology is not Topology.CIRCULAR:
+            raise ConfigurationError("A circular operation result must remain circular.")
+        if self.requested_offset is not None and (
+            isinstance(self.requested_offset, bool) or not isinstance(self.requested_offset, int)
+        ):
+            raise ConfigurationError("requested_offset must be an integer or None.")
+        if self.sequence_span <= 0:
+            raise ConfigurationError("A circular operation requires a positive sequence span.")
+        if not 0 <= self.effective_offset < self.sequence_span:
+            raise ConfigurationError("effective_offset must lie within the circular span.")
+        if self.sequence.coordinate_span != self.sequence_span:
+            raise ConfigurationError("sequence_span must match the transformed sequence.")
+        if not isinstance(self.rule, str) or not self.rule.strip():
+            raise ConfigurationError("A circular operation result rule must be non-empty.")
+        if not isinstance(self.parameters, FrozenDict):
+            raise ConfigurationError("Circular operation parameters must be FrozenDict.")
+
+    def to_dict(self) -> dict[str, object]:
+        """Return a JSON-compatible audit payload without flattening explicit gaps."""
+
+        payload = {
+            "operation": self.operation,
+            "requested_offset": self.requested_offset,
+            "effective_offset": self.effective_offset,
+            "sequence_span": self.sequence_span,
+            "rule": self.rule,
+            "parameters": self.parameters,
+        }
+        converted = to_json_compatible(payload)
+        assert isinstance(converted, dict)
+        return converted
+
+
+def _require_circular(sequence: DNASequence, *, operation: str) -> DNASequence:
+    source = require_sequence(sequence)
+    if source.topology is not Topology.CIRCULAR:
+        raise ConfigurationError(
+            f"{operation} requires topology='circular'.",
+            code="CIRCULAR_TOPOLOGY_REQUIRED",
+            context={"operation": operation, "topology": source.topology.value},
+        )
+    return source
+
+
+def rotate(sequence: DNASequence, offset: int) -> CircularOperationResult:
+    """Left-rotate a circular sequence so ``offset`` becomes coordinate zero.
+
+    Offsets are normalized modulo the resolved coordinate span. A rotation may
+    split a nucleotide fragment, but never an explicit Gap. Unknown-length Gaps
+    are rejected because the effective coordinate cannot be determined.
+    """
+
+    source = _require_circular(sequence, operation="rotate")
+    if isinstance(offset, bool) or not isinstance(offset, int):
+        raise ConfigurationError(
+            "Circular rotation offset must be an integer.",
+            code="INVALID_ROTATION_OFFSET",
+            context={"offset": offset},
+        )
+    span = resolved_span(source, operation="rotate")
+    effective = offset % span
+    try:
+        left, right = _split_at(source, effective)
+    except UnsupportedGapOperationError as exc:
+        raise UnsupportedGapOperationError(
+            "A circular origin cannot be placed inside a Gap.",
+            code="ROTATION_ORIGIN_INSIDE_GAP",
+            context={"requested_offset": offset, "effective_offset": effective},
+            hint="Choose a nucleotide or Gap boundary as the circular origin.",
+        ) from exc
+    rotated = DNASequence(
+        (*right, *left),
+        alphabet=source.alphabet,
+        topology=Topology.CIRCULAR,
+        strandedness=source.strandedness,
+    )
+    return CircularOperationResult(
+        rotated,
+        "rotate",
+        offset,
+        effective,
+        span,
+        "left_rotation_offset_modulo_coordinate_span",
+        FrozenDict(
+            {
+                "direction": "left",
+                "offset_normalization": "modulo_coordinate_span",
+                "gap_interior_policy": "error",
+            }
+        ),
+    )
+
+
+def _minimal_rotation_offset(text: str) -> int:
+    """Return the smallest offset having the lexicographically minimal rotation.
+
+    This is Booth's linear-time algorithm with deterministic smallest-index
+    tie-breaking for periodic strings.
+    """
+
+    length = len(text)
+    if length < 2:
+        return 0
+    doubled = text + text
+    first, second, matched = 0, 1, 0
+    while first < length and second < length and matched < length:
+        left = doubled[first + matched]
+        right = doubled[second + matched]
+        if left == right:
+            matched += 1
+            continue
+        if left > right:
+            first = first + matched + 1
+            if first <= second:
+                first = second + 1
+        else:
+            second = second + matched + 1
+            if second <= first:
+                second = first + 1
+        matched = 0
+    return min(first, second)
+
+
+def canonical_origin(sequence: DNASequence) -> CircularOperationResult:
+    """Choose the lexicographically minimal forward rotation as coordinate zero.
+
+    The rule compares normalized DNA symbols using their ordinary code-point
+    order and preserves strand orientation. Equal rotations select the smallest
+    offset. Explicit gaps are rejected because omitting or serializing them into
+    a comparison token would change the sequence model.
+    """
+
+    source = _require_circular(sequence, operation="canonical_origin")
+    if source.is_gapped:
+        raise UnsupportedGapOperationError(
+            "Canonical lexicographic origin selection does not accept explicit Gaps.",
+            code="CANONICAL_ORIGIN_GAPPED_SEQUENCE",
+            hint="Resolve the origin explicitly with rotate() at a Gap boundary.",
+        )
+    span = resolved_span(source, operation="canonical_origin")
+    offset = _minimal_rotation_offset(source.symbols)
+    rotated = rotate(source, offset).sequence
+    return CircularOperationResult(
+        rotated,
+        "canonical_origin",
+        None,
+        offset,
+        span,
+        "lexicographically_minimal_forward_rotation_then_smallest_offset",
+        FrozenDict(
+            {
+                "comparison": "normalized_symbol_code_point_order",
+                "orientation": "forward_only",
+                "tie_break": "smallest_offset",
+                "algorithm": "booth",
+                "algorithm_complexity": "O(n)",
+            }
+        ),
+    )
+
+
+__all__ = ["CircularOperation", "CircularOperationResult", "canonical_origin", "rotate"]

dnakit/ops/concat.py

@@ -0,0 +1,204 @@
+"""Concatenation of immutable linear DNA sequences."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from dnakit.core import DNAAlphabet, DNASequence, Gap, Topology
+from dnakit.exceptions import ConfigurationError, UnsupportedGapOperationError
+from dnakit.ops._common import coerce_fragment, combine_parts, promote_alphabet
+
+
+def concat(
+    sequences: Iterable[DNASequence | str],
+    *,
+    linker: DNASequence | str | None = None,
+    gap: Gap | None = None,
+) -> DNASequence:
+    """Concatenate at least two linear sequences with an optional separator.
+
+    ``linker`` and ``gap`` are mutually exclusive.  No rotation, implicit
+    reverse-complement, or feature synchronization is performed.
+    """
+
+    raw = tuple(sequences)
+    if len(raw) < 2:
+        raise ConfigurationError(
+            "concat requires at least two sequences.",
+            code="INSUFFICIENT_CONCAT_INPUTS",
+            context={"count": len(raw)},
+        )
+    if linker is not None and gap is not None:
+        raise ConfigurationError(
+            "linker and gap are mutually exclusive.",
+            code="MULTIPLE_CONCAT_SEPARATORS",
+        )
+    if gap is not None and not isinstance(gap, Gap):
+        raise ConfigurationError(
+            "gap must be a Gap object.",
+            code="INVALID_CONCAT_GAP",
+        )
+
+    first_raw = raw[0]
+    if isinstance(first_raw, DNASequence):
+        first = first_raw
+    elif isinstance(first_raw, str):
+        first = DNASequence(first_raw, alphabet=_infer_text_alphabet(first_raw))
+    else:
+        raise ConfigurationError(
+            "concat inputs must be DNASequence or normalized DNA text.",
+            code="INVALID_CONCAT_INPUT",
+            context={"index": 0, "type": type(first_raw).__name__},
+        )
+    if first.topology is Topology.CIRCULAR:
+        raise ConfigurationError(
+            "Circular input concatenation is not supported in the MVP.",
+            code="CIRCULAR_CONCAT_NOT_SUPPORTED",
+        )
+    fragments = [
+        coerce_fragment(
+            item,
+            fallback_alphabet=first.alphabet,
+            strandedness=first.strandedness,
+        )
+        for item in raw
+    ]
+    separator: DNASequence | Gap | None
+    if linker is not None:
+        separator = coerce_fragment(
+            linker,
+            fallback_alphabet=first.alphabet,
+            strandedness=first.strandedness,
+        )
+    else:
+        separator = gap
+
+    alphabets = [fragment.alphabet for fragment in fragments]
+    if isinstance(separator, DNASequence):
+        alphabets.append(separator.alphabet)
+    alphabet = promote_alphabet(*alphabets)
+    parts: list[str | Gap] = []
+    for index, fragment in enumerate(fragments):
+        if index and separator is not None:
+            if isinstance(separator, DNASequence):
+                parts.extend(separator.parts)
+            else:
+                parts.append(separator)
+        parts.extend(fragment.parts)
+    return combine_parts(
+        parts,
+        alphabet=alphabet,
+        topology=Topology.LINEAR,
+        strandedness=first.strandedness,
+    )
+
+
+def concat_overlap(
+    sequences: Iterable[DNASequence | str],
+    *,
+    min_overlap: int = 1,
+    max_overlap: int | None = None,
+) -> DNASequence:
+    """Concatenate two linear sequences while retaining an exact overlap once.
+
+    The longest exact suffix/prefix overlap is selected automatically.  IUPAC
+    symbols are compared literally; ambiguity compatibility is not inferred.
+    """
+
+    _validate_overlap_bounds(min_overlap, max_overlap)
+    raw = tuple(sequences)
+    if len(raw) != 2:
+        raise ConfigurationError(
+            "concat_overlap requires exactly two sequences.",
+            code="INVALID_OVERLAP_CONCAT_INPUTS",
+            context={"count": len(raw)},
+        )
+
+    first_raw = raw[0]
+    if isinstance(first_raw, DNASequence):
+        first = first_raw
+    elif isinstance(first_raw, str):
+        first = DNASequence(first_raw, alphabet=_infer_text_alphabet(first_raw))
+    else:
+        raise ConfigurationError(
+            "concat_overlap inputs must be DNASequence or normalized DNA text.",
+            code="INVALID_OVERLAP_CONCAT_INPUT",
+            context={"index": 0, "type": type(first_raw).__name__},
+        )
+    if first.topology is Topology.CIRCULAR:
+        raise ConfigurationError(
+            "Circular input overlap concatenation is not supported.",
+            code="CIRCULAR_CONCAT_NOT_SUPPORTED",
+        )
+
+    fragments = tuple(
+        coerce_fragment(
+            item,
+            fallback_alphabet=first.alphabet,
+            strandedness=first.strandedness,
+        )
+        for item in raw
+    )
+    if any(fragment.is_gapped for fragment in fragments):
+        raise UnsupportedGapOperationError(
+            "concat_overlap cannot silently discard explicit Gap objects.",
+            code="OVERLAP_CONCAT_GAPPED_INPUT",
+            hint="Resolve the gaps first or use concat() when the Gap should be retained.",
+        )
+
+    overlap_length = _find_overlap_length(
+        fragments[0].symbols,
+        fragments[1].symbols,
+        min_overlap=min_overlap,
+        max_overlap=max_overlap,
+    )
+    alphabet = promote_alphabet(*(fragment.alphabet for fragment in fragments))
+    return combine_parts(
+        [fragments[0].symbols + fragments[1].symbols[overlap_length:]],
+        alphabet=alphabet,
+        topology=Topology.LINEAR,
+        strandedness=first.strandedness,
+    )
+
+
+def _validate_overlap_bounds(min_overlap: int, max_overlap: int | None) -> None:
+    if isinstance(min_overlap, bool) or not isinstance(min_overlap, int) or min_overlap < 1:
+        raise ConfigurationError("min_overlap must be a positive integer.")
+    if max_overlap is not None and (
+        isinstance(max_overlap, bool) or not isinstance(max_overlap, int) or max_overlap < 1
+    ):
+        raise ConfigurationError("max_overlap must be a positive integer or None.")
+    if max_overlap is not None and min_overlap > max_overlap:
+        raise ConfigurationError("min_overlap cannot exceed max_overlap.")
+
+
+def _find_overlap_length(
+    left: str,
+    right: str,
+    *,
+    min_overlap: int,
+    max_overlap: int | None,
+) -> int:
+    upper = min(len(left), len(right))
+    if max_overlap is not None:
+        upper = min(upper, max_overlap)
+    for length in range(upper, min_overlap - 1, -1):
+        if left[-length:] == right[:length]:
+            return length
+    raise ConfigurationError(
+        "No exact suffix/prefix overlap satisfies the configured bounds.",
+        code="OVERLAP_NOT_FOUND",
+        context={
+            "left_length": len(left),
+            "right_length": len(right),
+            "min_overlap": min_overlap,
+            "max_overlap": max_overlap,
+        },
+    )
+
+
+def _infer_text_alphabet(text: str) -> DNAAlphabet:
+    return DNAAlphabet.STRICT if set(text) <= set("ACGT") else DNAAlphabet.IUPAC
+
+
+__all__ = ["concat", "concat_overlap"]

dnakit/ops/direction.py

@@ -0,0 +1,27 @@
+"""Direction-changing operations for immutable DNA sequences."""
+
+from __future__ import annotations
+
+from dnakit.core import DNASequence
+from dnakit.ops._common import require_sequence
+
+
+def reverse(sequence: DNASequence) -> DNASequence:
+    """Return a new sequence with part order and nucleotide order reversed."""
+
+    return require_sequence(sequence).reverse()
+
+
+def complement(sequence: DNASequence) -> DNASequence:
+    """Return a new sequence using the complete DNA IUPAC complement table."""
+
+    return require_sequence(sequence).complement()
+
+
+def reverse_complement(sequence: DNASequence) -> DNASequence:
+    """Return a new reverse-complemented sequence, preserving explicit gaps."""
+
+    return require_sequence(sequence).reverse_complement()
+
+
+__all__ = ["complement", "reverse", "reverse_complement"]