API reference¶

@dataclass(frozen=True, slots=True)
class BindingSite:
    """Where a primer's 3' part anneals to a record.

    Parameters
    ----------
    start, end
        0-based, half-open, as for `Segment`. The primer's 5' tail lies outside.
    strand
        `Strand.FORWARD` when the primer reads along the top strand, towards higher
        coordinates; `Strand.REVERSE` when it reads along the bottom strand.

    Raises
    ------
    ValueError
        Unless ``0 <= start < end`` and `strand` is forward or reverse.
    """

    start: int
    end: int
    strand: Strand

    def __post_init__(self) -> None:
        """Refuse an empty span or a strand that is neither forward nor reverse."""
        _check_span(self.start, self.end)
        if self.strand not in (Strand.FORWARD, Strand.REVERSE):
            raise ValueError(f"a binding site needs a forward or reverse strand, got {self.strand}")

@dataclass(frozen=True, slots=True)
class Feature:
    """A named, typed annotation over one or more segments.

    Parameters
    ----------
    name
        The label shown on a map.
    type
        A GenBank feature key, such as ``"CDS"`` or ``"promoter"``.
    segments
        In top-strand order, whatever the strand.
    strand
        The strand the feature reads along.
    qualifiers
        GenBank-style qualifiers, each holding one or more values.
    color
        ``"#rrggbb"``, or ``None`` for the writer's default.

    Raises
    ------
    ValueError
        If `segments` is empty.
    """

    name: str
    type: str
    segments: tuple[Segment, ...]
    _: KW_ONLY
    strand: Strand = Strand.NONE
    qualifiers: Mapping[str, tuple[str | int, ...]] = field(default_factory=dict, hash=False)
    color: str | None = None

    def __post_init__(self) -> None:
        """Refuse a feature with no segment."""
        if not self.segments:
            raise ValueError(f"feature {self.name!r} has no segment")

@dataclass(frozen=True, slots=True)
class Primer:
    """A named oligonucleotide.

    Parameters
    ----------
    name
        The name it is ordered under.
    sequence
        5' to 3', tail included. Stored upper-case.
    binding_sites
        Where it anneals to the record that carries it.
    description
        Free text.

    Raises
    ------
    ValueError
        If `sequence` holds a letter outside `IUPAC_DNA`.
    """

    name: str
    sequence: str
    _: KW_ONLY
    binding_sites: tuple[BindingSite, ...] = ()
    description: str = ""

    def __post_init__(self) -> None:
        """Upper-case and check the sequence."""
        object.__setattr__(self, "sequence", _dna(self.sequence))

@dataclass(frozen=True, slots=True)
class Segment:
    """One contiguous span of a feature.

    Parameters
    ----------
    start, end
        0-based, half-open. `end` passes the length of a circular record when the segment
        crosses the origin.
    name
        A label for this segment alone, such as a promoter's ``"-10"``.
    color
        ``"#rrggbb"``, or ``None`` to take the feature's colour.

    Raises
    ------
    ValueError
        Unless ``0 <= start < end``.
    """

    start: int
    end: int
    _: KW_ONLY
    name: str = ""
    color: str | None = None

    def __post_init__(self) -> None:
        """Refuse an empty or negative span."""
        _check_span(self.start, self.end)

@dataclass(frozen=True, slots=True)
class SequenceRecord:
    """A DNA sequence with its topology, features, primers and notes.

    Parameters
    ----------
    sequence
        Stored upper-case.
    topology
        ``"linear"`` or ``"circular"``.
    name
        The name shown on a map.
    features, primers
        Every feature segment and primer binding site must fit the sequence under its topology.
    notes
        Descriptive fields, such as ``"Description"``, keyed by name.
    extras
        Format-specific data a reader keeps for its writer. Ignored by ``==``.

    Raises
    ------
    ValueError
        If `sequence` holds a letter outside `IUPAC_DNA`, `topology` is unknown, or a span does
        not fit.
    """

    sequence: str
    _: KW_ONLY
    topology: Topology = "linear"
    name: str = ""
    features: tuple[Feature, ...] = ()
    primers: tuple[Primer, ...] = ()
    notes: Mapping[str, str] = field(default_factory=dict, hash=False)
    extras: Mapping[str, object] = field(default_factory=dict, hash=False, compare=False)

    def __post_init__(self) -> None:
        """Upper-case the sequence and check every span fits."""
        if self.topology not in ("linear", "circular"):
            raise ValueError(f"topology must be 'linear' or 'circular', got {self.topology!r}")
        object.__setattr__(self, "sequence", _dna(self.sequence))
        for feature in self.features:
            for segment in feature.segments:
                self._check_fits(segment.start, segment.end, f"feature {feature.name!r}")
        for primer in self.primers:
            for site in primer.binding_sites:
                self._check_fits(site.start, site.end, f"primer {primer.name!r}")

    def __len__(self) -> int:
        """Return the number of bases."""
        return len(self.sequence)

    def extract(self, span: Feature | Segment) -> str:
        """Return the bases under a feature or segment, reading across the origin.

        A reverse-strand feature reads as the reverse complement of its joined segments. A bare
        segment reads off the top strand.

        Raises
        ------
        ValueError
            If a segment does not fit this record.

        Examples
        --------
        >>> SequenceRecord("AACCGGTTAC", topology="circular").extract(Segment(8, 12))
        'ACAA'
        """
        segments = span.segments if isinstance(span, Feature) else (span,)
        bases = "".join(self._bases(segment) for segment in segments)
        if isinstance(span, Feature) and span.strand == Strand.REVERSE:
            return reverse_complement(bases)
        return bases

    def _bases(self, segment: Segment) -> str:
        self._check_fits(segment.start, segment.end, "extracted")
        n = len(self.sequence)
        if segment.end <= n:
            return self.sequence[segment.start : segment.end]
        return self.sequence[segment.start :] + self.sequence[: segment.end - n]

    def _check_fits(self, start: int, end: int, owner: str) -> None:
        n = len(self.sequence)
        span = f"{owner} span {start}-{end}"
        if self.topology == "linear":
            if end > n:
                raise ValueError(f"{span} runs past the end of a linear record of {n} bases")
        elif start >= n or end - start > n:
            raise ValueError(f"{span} does not fit a circular record of {n} bases")

class Strand(IntEnum):
    """The strand a feature or primer binding site lies on."""

    FORWARD = 1
    REVERSE = -1
    NONE = 0
    #: SnapGene's bidirectional.
    BOTH = 2

@dataclass(frozen=True, slots=True)
class Check:
    """One verdict on a primer, a pair or an assembled product, with the value it judged.

    Parameters
    ----------
    name
        What was measured, such as ``"gc_clamp"``.
    status
        One of `STATUSES`, or ``None`` where no sourced threshold judges it.
    value
        The measurement, in the unit the module that judged it documents.
    detail
        What a reader needs besides the number.
    """

    name: str
    status: Status | None
    value: float
    detail: str = ""

@dataclass(frozen=True, slots=True)
class EditReport:
    """What an edit did to the features and binding sites it did not simply shift.

    Every entry holds the feature or primer as it was **before** the edit.

    Attributes
    ----------
    trimmed
        Features that lost bases, including any that lost a whole segment.
    dropped
        Features left with no bases at all.
    changed
        Features the edit fell inside: kept, and now spanning the new bases.
    dropped_sites
        Binding sites the edit overlapped, with the primer they belong to. A primer no longer
        anneals where its bases changed, so such a site is dropped rather than trimmed.
    """

    trimmed: tuple[Feature, ...] = ()
    dropped: tuple[Feature, ...] = ()
    changed: tuple[Feature, ...] = ()
    dropped_sites: tuple[tuple[Primer, BindingSite], ...] = ()

@dataclass(frozen=True, slots=True)
class Enzyme:
    """One restriction enzyme and where it cuts.

    Parameters
    ----------
    name
        The REBASE name, such as ``"BsaI"``.
    site
        The recognition site, IUPAC, 5' to 3'. Stored upper-case.
    top_cut, bottom_cut
        Cut offsets, as described in the module docstring.
    isoschizomers
        Enzymes a supplier sells that read and cut exactly this site. Neoschizomers — the same
        site cut elsewhere, as XmaI cuts SmaI's — are not among them.
    commercial_name, catalog_number, supplier
        The product the other supplier fields describe, such as ``"BsaI-HFv2"``, ``"R3733"``.
    incubation_celsius
        The supplier's digestion temperature, which is not always a protocol's temperature.
    heat_inactivation_celsius, heat_inactivation_minutes
        ``None`` when the supplier says heat does not inactivate the enzyme, and also when it
        says nothing — which is what `unverified` then names.
    methylation
        The supplier's Dam, Dcm and CpG sensitivity, keyed ``"dam"``, ``"dcm"``, ``"cpg"``.
    unverified
        Fields no source stated. Never a guess.

    Raises
    ------
    ValueError
        If `site` is empty or holds a letter outside `IUPAC_DNA`.
    """

    name: str
    site: str
    _: KW_ONLY
    top_cut: int
    bottom_cut: int
    isoschizomers: tuple[str, ...] = ()
    commercial_name: str | None = None
    catalog_number: str | None = None
    supplier: str | None = None
    incubation_celsius: int | None = None
    heat_inactivation_celsius: int | None = None
    heat_inactivation_minutes: int | None = None
    methylation: Mapping[str, str] = field(default_factory=dict, hash=False)
    unverified: tuple[str, ...] = ()

    def __post_init__(self) -> None:
        """Upper-case the site and refuse one that is not IUPAC DNA."""
        site = self.site.upper()
        if not site:
            raise ValueError(f"enzyme {self.name!r} has no recognition site")
        if bad := set(site) - IUPAC_DNA:
            raise ValueError(f"{self.name} site is not IUPAC DNA: {''.join(sorted(bad))}")
        object.__setattr__(self, "site", site)

    @property
    def type(self) -> EnzymeType:
        """``"IIS"`` when either cut falls outside the site, ``"II"`` otherwise."""
        return "IIS" if any(not 0 <= cut <= len(self.site) for cut in self.cut_offsets) else "II"

    @property
    def cut_offsets(self) -> tuple[int, int]:
        """The two cut offsets, top strand first."""
        return self.top_cut, self.bottom_cut

    @property
    def overhang_length(self) -> int:
        """How many bases the two cuts leave single-stranded."""
        return abs(self.bottom_cut - self.top_cut)

    @property
    def supplier_label(self) -> str:
        """The enzyme as its supplier sells it: the commercial name and the catalogue number.

        Examples
        --------
        >>> Enzyme("BsaI", "GGTCTC", top_cut=7, bottom_cut=11).supplier_label
        'BsaI'
        >>> sold = Enzyme("BsaI", "GGTCTC", top_cut=7, bottom_cut=11, commercial_name="BsaI-HFv2",
        ...               catalog_number="R3733")
        >>> sold.supplier_label
        'BsaI-HFv2 (R3733)'
        """
        name = self.commercial_name or self.name
        return f"{name} ({self.catalog_number})" if self.catalog_number else name

    @property
    def end(self) -> EndType:
        """The end left behind: ``"5'"``, ``"3'"`` or ``"blunt"``.

        Examples
        --------
        >>> Enzyme("KpnI", "GGTACC", top_cut=5, bottom_cut=1).end
        "3'"
        """
        if self.bottom_cut == self.top_cut:
            return "blunt"
        return "5'" if self.bottom_cut > self.top_cut else "3'"

    def cut_positions(self, start: int, strand: Strand = Strand.FORWARD) -> tuple[int, int]:
        """Where this enzyme cuts a record holding its site at `start`.

        Parameters
        ----------
        start
            The 0-based index where the site begins on the top strand. A reverse-strand site is
            the reverse complement of `site` there.
        strand
            Which strand carries the site.

        Returns
        -------
        tuple[int, int]
            The top-strand cut and the bottom-strand cut, in record coordinates and in that
            order whatever the strand. Either may fall outside the record, which is what a
            circular record's caller reduces modulo its length.

        Examples
        --------
        >>> Enzyme("BsaI", "GGTCTC", top_cut=7, bottom_cut=11).cut_positions(4)
        (11, 15)
        """
        if strand == Strand.REVERSE:
            end = start + len(self.site)
            return end - self.bottom_cut, end - self.top_cut
        return start + self.top_cut, start + self.bottom_cut

    def overhang(self, record: SequenceRecord, start: int, strand: Strand = Strand.FORWARD) -> str:
        """Return the top-strand bases this enzyme leaves single-stranded, 5' to 3'.

        Empty for a blunt cutter. On a circular record the overhang reads across the origin.

        Raises
        ------
        ValueError
            If either cut falls off the end of a linear record.
        """
        top, bottom = self.cut_positions(start, strand)
        low, high = min(top, bottom), max(top, bottom)
        if low == high:
            return ""
        length = len(record)
        if record.topology == "circular":
            low, high = low % length, low % length + (high - low)
        elif not (low >= 0 and high <= length):
            raise ValueError(f"{self.name} cut at {low}-{high} falls off a linear record")
        return record.extract(Segment(low, high))

@dataclass(frozen=True, slots=True)
class CutSite:
    """One recognition site found in a record, and where its enzyme cuts there.

    Parameters
    ----------
    enzyme
        The enzyme that reads this site.
    start
        0-based index of the first base of the match on the TOP strand, whichever strand the
        site lies on.
    strand
        `Strand.FORWARD` when the top strand spells the recognition site, `Strand.REVERSE` when
        the bottom strand does. A palindromic site is always forward.
    top_cut, bottom_cut
        Where the two strands are severed, in the record's own coordinates and in that order
        whatever the strand. Reduced modulo the length on a circular record; on a linear one
        either may fall outside the record, which is what `overhang` being ``None`` says.
    overhang
        The top-strand bases the two cuts leave single-stranded, 5' to 3'; ``""`` for a blunt
        cutter and ``None`` when a cut falls off the end of a linear record.
    certain
        ``False`` when an IUPAC code in the template, rather than a definite base, is what
        allowed the match.
    """

    enzyme: Enzyme
    start: int
    strand: Strand
    _: KW_ONLY
    top_cut: int
    bottom_cut: int
    overhang: str | None
    certain: bool = True

    @property
    def end(self) -> int:
        """Where the match ends, passing the length when it runs across the origin."""
        return self.start + len(self.enzyme.site)

    @property
    def span(self) -> Segment:
        """The matched bases, as a segment of the top strand."""
        return Segment(self.start, self.end)

    @property
    def cuts(self) -> bool:
        """Whether both cuts land in the record, so the enzyme can actually cut here."""
        return self.overhang is not None

@dataclass(frozen=True, slots=True)
class Domestication:
    """One synonymous codon change, and the site it took away.

    Parameters
    ----------
    site
        The site that was there before the change.
    feature
        The coding sequence the codon belongs to, as it read before the change.
    position
        0-based index on the TOP strand where the codon's three bases begin. A codon of a
        reverse-strand coding sequence reads back from ``position + 2``.
    codon_index
        Which codon of the coding sequence this is, counting from zero.
    old_codon, new_codon
        The codon before and after, read 5' to 3' along the coding sequence.
    amino_acid
        The one-letter amino acid both codons spell.
    """

    site: CutSite
    feature: Feature
    position: int
    codon_index: int
    old_codon: str
    new_codon: str
    amino_acid: str

@dataclass(frozen=True, slots=True)
class DomesticationReport:
    """What domestication changed, and what it left for someone to decide.

    Attributes
    ----------
    changes
        Each site taken away, with the codon change that did it.
    outside_cds
        Sites lying in no coding sequence. Removing one of these changes what the record
        spells, so it is reported and the choice is left to the caller.
    unchanged
        Sites in a coding sequence that no synonymous change could take away.
    """

    changes: tuple[Domestication, ...] = ()
    outside_cds: tuple[CutSite, ...] = ()
    unchanged: tuple[CutSite, ...] = ()

@dataclass(frozen=True, slots=True)
class Fragment:
    """One piece a digest leaves, bounded by the cuts in the top strand.

    Parameters
    ----------
    start, end
        The two top-strand cuts that bound it, 0-based and half-open. A fragment across the
        origin of a circular record keeps ``start < end`` and ends past the record's length.
    left_overhang, right_overhang
        The single-stranded bases at each end, written as the TOP strand reads them 5' to 3',
        and ``""`` for a blunt end. Written that way whether the overhang is 5' or 3', and
        whether it sits on the top strand of this fragment or the bottom, so two ends anneal
        exactly when the two strings are equal.
    """

    start: int
    end: int
    left_overhang: str
    right_overhang: str

    @property
    def length(self) -> int:
        """How many bases of top strand it carries, which is what a gel measures."""
        return self.end - self.start