alphafold3-input 0.3.0__py3-none-any.whl

alphafold3_input/__about__.py

@@ -0,0 +1,69 @@
+"""Package metadata for AlphaFold 3 input models.
+
+Provides a normalized interface to distribution metadata for the package.
+
+Exports:
+    - :data:`__title__`: Package title.
+    - :data:`__description__`: Package summary.
+    - :data:`__author__`: Package author.
+    - :data:`__version__`: Installed version.
+    - :data:`__package__`: Distribution name.
+    - :data:`__module_name__`: Import path.
+    - :data:`__repository__`: Repository URL.
+    - :data:`__documentation__`: Documentation URL.
+    - :data:`__issues__`: Issue tracker URL.
+"""
+
+from importlib.metadata import PackageMetadata, metadata, version
+
+__all__: list[str] = [
+    "__author__",
+    "__description__",
+    "__documentation__",
+    "__issues__",
+    "__module_name__",
+    "__package__",
+    "__repository__",
+    "__title__",
+    "__version__",
+]
+
+__package__: str = "alphafold3_input"
+"""Distribution package name."""
+
+__module_name__: str = "alphafold3_input"
+"""Importable top-level module name."""
+
+__version__: str = version(__package__)
+"""Installed package version string."""
+
+__metadata__: PackageMetadata = metadata(__package__)
+"""Raw distribution metadata."""
+
+__title__: str = __metadata__["Name"]
+"""Distribution package name."""
+
+__description__: str = __metadata__.get("Summary", "")
+"""Package summary."""
+
+__author__: str = __metadata__.get("Author", "")
+"""Package author."""
+
+__repository__: str = ""
+"""Repository URL."""
+
+__documentation__: str = ""
+"""Documentation URL."""
+
+__issues__: str = ""
+"""Issue tracker URL."""
+
+for item in __metadata__.json.get("project_url", []):
+    label, url = item.split(", ", 1)
+    match label:
+        case "Repository":
+            __repository__ = url
+        case "Documentation":
+            __documentation__ = url
+        case "Issues":
+            __issues__ = url

alphafold3_input/__init__.py

@@ -0,0 +1,61 @@
+"""AlphaFold 3 input models.
+
+This package provides models for constructing AlphaFold 3 input files.
+
+It offers a Pythonic, object-oriented interface for defining AlphaFold 3
+jobs, abstracting the underlying JSON input format into typed models and
+validated structures. The implementation closely follows the official
+AlphaFold 3 input specification provided by DeepMind.
+
+For full details on the expected input format and supported features,
+refer to the official `AlphaFold 3 input specification
+<https://github.com/google-deepmind/alphafold3/blob/main/docs/input.md>`_.
+
+Exports:
+    - :data:`JSON_SCHEMA_URL`: canonical JSON Schema URL for editor \
+        validation.
+    - :class:`Job`, :class:`Dialect`, :class:`Version`: top-level job model \
+        and input format enums.
+    - :class:`DNA`, :class:`RNA`, :class:`Protein`, :class:`Ligand`: \
+        entity models used under :attr:`Job.entities`.
+    - :class:`Modification`, :class:`Entity`: residue modification model and \
+        its entity-scope enum.
+    - :class:`Template`: structural template specification for proteins.
+    - :class:`Atom`, :class:`Bond`: covalent bond specification models.
+    - :class:`Operation`, :func:`trace`, :func:`reindex`, :func:`realign`: \
+        operation trace generation, reindexing, and realignment utilities.
+    - :func:`ccd`, :func:`component`: generation of custom chemical \
+        component dictionaries.
+"""
+
+from .bond import Atom, Bond
+from .dna import DNA
+from .job import JSON_SCHEMA_URL, Dialect, Job, Version
+from .ligand import Ligand
+from .modification import Entity, Modification
+from .protein import Protein
+from .rna import RNA
+from .template import Template
+from .utils import Operation, ccd, component, realign, reindex, trace
+
+__all__: list[str] = [
+    "DNA",
+    "JSON_SCHEMA_URL",
+    "RNA",
+    "Atom",
+    "Bond",
+    "Dialect",
+    "Entity",
+    "Job",
+    "Ligand",
+    "Modification",
+    "Operation",
+    "Protein",
+    "Template",
+    "Version",
+    "ccd",
+    "component",
+    "realign",
+    "reindex",
+    "trace",
+]

alphafold3_input/bond.py

@@ -0,0 +1,222 @@
+"""Covalent bond models.
+
+This submodule defines :class:`Atom` and :class:`Bond` for specifying
+covalent bonds between entities in an AlphaFold 3 input.
+
+Exports:
+    - :class:`Atom`: atom specification within an entity.
+    - :class:`Bond`: covalent bond between two atoms.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any, Self
+
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    model_serializer,
+    model_validator,
+)
+
+__all__: list[str] = [
+    "Atom",
+    "Bond",
+]
+
+
+class Atom(BaseModel):
+    """Atom specification within an entity.
+
+    An atom is defined by an :attr:`entity` identifier, a 1-based
+    :attr:`residue` index, and an atom :attr:`name`.
+
+    Attributes:
+        entity (str): Entity identifier.
+        residue (int): Residue index within the entity.
+        name (str): Atom name within the residue.
+
+    Examples:
+        Atom definition.
+
+        >>> Atom(entity="A", residue=1, name="CB")
+    """
+
+    model_config = ConfigDict(
+        extra="forbid",
+        frozen=True,
+        validate_assignment=False,
+        validate_by_name=True,
+        validate_by_alias=True,
+    )
+
+    entity: str = Field(
+        title="entity",
+        alias="entity",
+        description="Entity identifier.",
+        pattern="^[A-Z]+$",
+        validation_alias="entity",
+        serialization_alias="entity",
+    )
+    """Entity identifier."""
+
+    residue: int = Field(
+        title="residue",
+        alias="residue",
+        description="Residue index within the entity.",
+        ge=1,
+        validation_alias="residue",
+        serialization_alias="residue",
+    )
+    """Residue index within the entity."""
+
+    name: str = Field(
+        title="name",
+        alias="name",
+        description="Atom name within the residue.",
+        min_length=1,
+        validation_alias="name",
+        serialization_alias="name",
+    )
+    """Atom name within the residue."""
+
+    @model_validator(mode="before")
+    @classmethod
+    def __validate_model(cls: type[Self], data: Any) -> Any:
+        """Coerce compact atom definitions to a mapping.
+
+        Accepts the AlphaFold 3 list form ``[entity, residue, name]`` and
+        converts it to a mapping compatible with field validation.
+
+        Args:
+            data (Any): Raw input data.
+
+        Returns:
+            Any: A mapping with keys ``entity``, ``residue``, and ``name`` if
+                ``data`` is a sequence, otherwise the original input.
+
+        Raises:
+            ValueError: If ``data`` is a sequence but does not contain exactly
+                three items.
+        """
+        if not isinstance(data, Sequence) or isinstance(
+            data,
+            (str, bytes, bytearray),
+        ):
+            return data
+
+        if len(data) != len(cls.model_fields):
+            msg: str = (
+                "Invalid atom definition: expected `[entity, residue, name]`."
+            )
+            raise ValueError(msg)
+        return {"entity": data[0], "residue": data[1], "name": data[2]}
+
+    @model_serializer(mode="plain")
+    def __serialize_model(self: Self) -> tuple[str, int, str]:
+        """Serialize the atom as ``[entity, residue, name]``.
+
+        Returns:
+            tuple[str, int, str]: Compact AlphaFold 3 atom representation.
+        """
+        return (self.entity, self.residue, self.name)
+
+
+class Bond(BaseModel):
+    """Covalent bond specification.
+
+    Defines a covalent bond between the :attr:`source` and the :attr:`target`
+    atoms as an AlphaFold 3 bonded atom pair.
+
+    Bonds are intended for covalently linked multi-residue :class:`Ligand`
+    entities, for example glycans. Covalent bonds within or between polymer
+    entities such as :class:`DNA`, :class:`RNA`, or :class:`Protein` are not
+    supported by AlphaFold 3.
+
+    Attributes:
+        source (Atom): Source atom address.
+        target (Atom): Target atom address.
+
+    Examples:
+        Covalent bond between two entities.
+
+        >>> Bond(
+        ...     source=Atom(entity="A", residue=1, name="CA"),
+        ...     target=Atom(entity="G", residue=1, name="CHA"),
+        ... )
+
+        Covalent bond within a multi-residue entity.
+
+        >>> Bond(
+        ...     source=Atom(entity="I", residue=1, name="O6"),
+        ...     target=Atom(entity="I", residue=2, name="C1"),
+        ... )
+    """
+
+    model_config = ConfigDict(
+        extra="forbid",
+        frozen=False,
+        validate_assignment=True,
+        validate_by_name=True,
+        validate_by_alias=True,
+    )
+
+    source: Atom = Field(
+        title="source",
+        alias="source",
+        description="Source atom address.",
+        validation_alias="source",
+        serialization_alias="source",
+    )
+    """Source atom address."""
+
+    target: Atom = Field(
+        title="target",
+        alias="target",
+        description="Target atom address.",
+        validation_alias="target",
+        serialization_alias="target",
+    )
+    """Target atom address."""
+
+    @model_validator(mode="before")
+    @classmethod
+    def __validate_model(cls: type[Self], data: Any) -> Any:
+        """Coerce compact bond definitions to a mapping.
+
+        Accepts the AlphaFold 3 list form ``[[...], [...]]`` and converts it
+        to a mapping compatible with field validation.
+
+        Args:
+            data (Any): Raw input data.
+
+        Returns:
+            Any: A mapping with keys ``source`` and ``target`` if ``data`` is
+                a sequence, otherwise the original input.
+
+        Raises:
+            ValueError: If ``data`` is a sequence but does not contain exactly
+                two items.
+        """
+        if not isinstance(data, Sequence) or isinstance(
+            data,
+            (str, bytes, bytearray),
+        ):
+            return data
+
+        if len(data) != len(cls.model_fields):
+            msg: str = "Invalid bond definition: expected `[source, target]`."
+            raise ValueError(msg)
+        return {"source": data[0], "target": data[1]}
+
+    @model_serializer(mode="plain")
+    def __serialize_model(self: Self) -> tuple[Atom, Atom]:
+        """Serialize the bond as an AlphaFold 3 bonded atom pair.
+
+        Returns:
+            tuple[Atom, Atom]: Compact AlphaFold 3 bonded atom pair
+                representation.
+        """
+        return (self.source, self.target)

alphafold3_input/dna.py

@@ -0,0 +1,260 @@
+"""DNA chain entity models.
+
+This submodule defines :class:`DNA`, which can be used to include polymeric DNA
+entities in an AlphaFold 3 input.
+
+Exports:
+    - :class:`DNA`: DNA chain entity model.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Annotated, Any, Self
+
+from pydantic import (
+    AliasPath,
+    BaseModel,
+    ConfigDict,
+    Field,
+    SerializerFunctionWrapHandler,
+    StringConstraints,
+    field_validator,
+    model_serializer,
+    model_validator,
+)
+
+from .modification import Entity, Modification
+
+__all__: list[str] = [
+    "DNA",
+]
+
+
+class DNA(BaseModel):
+    """DNA chain entity specification.
+
+    A DNA chain is defined by its nucleotide :attr:`sequence`, optional
+    :attr:`modifications`, and one or more chain identifiers via :attr:`id`.
+    Multiple copies can be defined either by setting :attr:`copies` or by
+    providing multiple explicit identifiers in :attr:`id`.
+
+    The optional :attr:`description` field is supported only when
+    :attr:`Job.version` is set to :attr:`Version.IV`.
+
+    Attributes:
+        id (str | Sequence[str] | None): DNA chain identifier(s).
+        description (str | None): Free-text DNA chain description.
+        sequence (str): DNA chain nucleotide sequence.
+        modifications (Sequence[Modification]): DNA chain residue
+            modifications.
+        copies (int): Number of DNA chain copies.
+
+    Examples:
+        DNA chain with a description.
+
+        >>> DNA(
+        ...     description="Promoter for bacteriophage T7 RNA polymerase",
+        ...     sequence="TAATACGACTCACTATAGG",
+        ... )
+
+        Multiple copies of a DNA chain.
+
+        >>> DNA(
+        ...     sequence="GAATTC",
+        ...     copies=2,
+        ... )
+
+        DNA chain with modified residues.
+
+        >>> heptamer = DNA(sequence="GACCTCT")
+        >>> heptamer.modify(
+        ...     Modification(type="6OG", position=1),
+        ...     Modification(type="6MA", position=2),
+        ... )
+    """
+
+    model_config = ConfigDict(
+        extra="forbid",
+        frozen=False,
+        validate_assignment=True,
+        validate_by_name=True,
+        validate_by_alias=True,
+        use_enum_values=False,
+    )
+
+    id: (
+        Annotated[str, StringConstraints(pattern="^[A-Z]+$")]
+        | Sequence[Annotated[str, StringConstraints(pattern="^[A-Z]+$")]]
+        | None
+    ) = Field(
+        title="id",
+        alias="id",
+        description="DNA chain identifier(s).",
+        min_length=1,
+        validation_alias=AliasPath("dna", "id"),
+        serialization_alias="id",
+        default=None,
+    )
+    """DNA chain identifier(s)."""
+
+    description: str | None = Field(
+        title="description",
+        alias="description",
+        description="Free-text DNA chain description.",
+        validation_alias=AliasPath("dna", "description"),
+        serialization_alias="description",
+        default=None,
+    )
+    """Free-text DNA chain description."""
+
+    sequence: Annotated[str, StringConstraints(pattern="^[ACGT]+$")] = Field(
+        title="sequence",
+        alias="sequence",
+        description="DNA chain nucleotide sequence.",
+        min_length=1,
+        validation_alias=AliasPath("dna", "sequence"),
+        serialization_alias="sequence",
+    )
+    """DNA chain nucleotide sequence."""
+
+    modifications: Sequence[Modification] = Field(
+        title="modifications",
+        alias="modifications",
+        description="DNA chain residue modifications.",
+        validation_alias=AliasPath("dna", "modifications"),
+        serialization_alias="modifications",
+        default_factory=tuple,
+    )
+    """DNA chain residue modifications."""
+
+    copies: int = Field(
+        title="copies",
+        alias="copies",
+        description="Number of DNA chain copies.",
+        ge=1,
+        validation_alias="copies",
+        exclude=True,
+        repr=False,
+        default=1,
+    )
+    """Number of DNA chain copies."""
+
+    def modify(self: Self, *modifications: Modification) -> Self:
+        """Append residue modifications to the DNA chain.
+
+        Args:
+            *modifications (Modification): One or more modifications to add.
+
+        Returns:
+            Self: DNA chain with appended modifications.
+
+        Raises:
+            TypeError: If no modifications were provided.
+        """
+        if not modifications:
+            msg: str = (
+                "Invalid DNA modification: no modifications were provided."
+            )
+            raise TypeError(msg)
+
+        self.modifications: tuple[Modification, ...] = tuple(
+            self.modifications,
+        ) + tuple(modifications)
+        return self
+
+    @field_validator("modifications", mode="after")
+    @classmethod
+    def __scope_modifications(
+        cls: type[Self],
+        value: Sequence[Modification],
+    ) -> Sequence[Modification]:
+        """Assign DNA scope to each modification.
+
+        Args:
+            value (Sequence[Modification]): Modification entries.
+
+        Returns:
+            Sequence[Modification]: Scoped modification entries.
+        """
+        for modification in value:
+            object.__setattr__(modification, "scope", Entity.DNA)
+        return value
+
+    @model_validator(mode="after")
+    def __validate_modifications(self: Self) -> Self:
+        """Validate residue modifications against the DNA sequence.
+
+        Ensures that each modification position is within the sequence and that
+        no residue is modified more than once.
+
+        Returns:
+            Self: Validated DNA chain instance.
+
+        Raises:
+            ValueError: If a modification position is out of range.
+            ValueError: If multiple modifications target the same position.
+        """
+        length: int = len(self.sequence)
+        modified: set[int] = set()
+
+        for modification in self.modifications:
+            if modification.position > length:
+                msg: str = (
+                    "Invalid DNA modification: modification `position` is out "
+                    f"of range (position={modification.position}, "
+                    f"len(sequence)={length})."
+                )
+                raise ValueError(msg)
+
+            if modification.position in modified:
+                msg: str = (
+                    "Invalid DNA modification list: multiple modifications on "
+                    f"the same `position` (position={modification.position})."
+                )
+                raise ValueError(msg)
+
+            modified.add(modification.position)
+
+        return self
+
+    @model_validator(mode="after")
+    def __validate_copies(self: Self) -> Self:
+        """Validate consistency between ``id`` and ``copies``.
+
+        If :attr:`id` is provided, :attr:`copies` is set to ``len(id)``. If
+        :attr:`copies` was explicitly provided and is inconsistent with
+        :attr:`id`, a :class:`ValueError` is raised.
+
+        Returns:
+            Self: Validated DNA chain instance.
+
+        Raises:
+            ValueError: If ``copies`` is inconsistent with ``id``.
+        """
+        if self.id is None:
+            return self
+
+        n: int = len(self.id) if not isinstance(self.id, str) else 1
+
+        if "copies" in self.model_fields_set and self.copies != n:
+            msg: str = (
+                "Conflicting DNA configuration: `copies` is inconsistent "
+                f"with the length of `id` (copies={self.copies}, len(id)={n})."
+            )
+            raise ValueError(msg)
+
+        object.__setattr__(self, "copies", n)
+        return self
+
+    @model_serializer(mode="wrap")
+    def __wrapped_serialization(
+        self: Self,
+        handler: SerializerFunctionWrapHandler,
+    ) -> dict[str, Any]:
+        """Serialize the entity in wrapped AlphaFold 3 form.
+
+        Returns:
+            dict[str, Any]: Wrapped entity mapping.
+        """
+        return {self.__class__.__name__.lower(): handler(self)}