alphafold3-input 0.3.0__tar.gz

alphafold3_input-0.3.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.3
+Name: alphafold3-input
+Version: 0.3.0
+Summary: AlphaFold 3 input schema models.
+Keywords: alphafold3,pydantic,bioinformatics,job-definition,input-generation,json,json-schema
+Author: Igor Koop
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: rdkit>=2026.3.3
+Requires-Python: >=3.12
+Project-URL: Documentation, https://github.com/igor-koop/alphafold3_input#readme
+Project-URL: Issues, https://github.com/igor-koop/alphafold3_input/issues
+Project-URL: Repository, https://github.com/igor-koop/alphafold3_input
+Description-Content-Type: text/markdown
+
+# alphafold3_input
+
+[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://igor-koop.github.io/alphafold3_input/)
+[![License](https://img.shields.io/github/license/igor-koop/alphafold3_input)](https://github.com/igor-koop/alphafold3_input/blob/main/LICENSE)
+[![Coverage](https://codecov.io/gh/igor-koop/alphafold3_input/graph/badge.svg?token=9906JN8BN0)](https://codecov.io/gh/igor-koop/alphafold3_input)
+[![Lint](https://img.shields.io/badge/linting-ruff-d7ff64)](https://docs.astral.sh/ruff/)
+[![Type](https://img.shields.io/badge/typing-ty-7c3aed)](https://docs.astral.sh/ty/)
+[![Actions](https://github.com/igor-koop/alphafold3_input/actions/workflows/actions.yml/badge.svg)](https://github.com/igor-koop/alphafold3_input/actions/workflows/actions.yml)
+
+
+Pythonic, object-oriented models for constructing **AlphaFold 3** input files.
+
+This package provides typed models and utilities that abstract the AlphaFold 3 JSON input format into a clean, validated Python interface.
+
+For details on the underlying specification, see the official [AlphaFold 3 input specification](https://github.com/google-deepmind/alphafold3/blob/main/docs/input.md).
+
+---
+
+## Installation
+
+Install the latest published release from PyPI:
+
+```bash
+uv add alphafold3_input
+```
+
+or:
+
+```bash
+pip install alphafold3_input
+```
+
+Install the current development version directly from GitHub:
+
+```bash
+uv add git+https://github.com/igor-koop/alphafold3_input
+```
+
+or:
+
+```bash
+pip install "git+https://github.com/igor-koop/alphafold3_input"
+```
+
+## Documentation
+
+Full API documentation is available at: https://igor-koop.github.io/alphafold3_input/
+
+## Development
+
+```bash
+git clone https://github.com/igor-koop/alphafold3_input
+cd alphafold3_input
+
+uv sync --dev
+```
+
+## License
+
+The scripts and documentation in this project are released under the [MIT License](https://github.com/igor-koop/alphafold3_input/blob/main/LICENSE).

alphafold3_input-0.3.0/README.md

@@ -0,0 +1,60 @@
+# alphafold3_input
+
+[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://igor-koop.github.io/alphafold3_input/)
+[![License](https://img.shields.io/github/license/igor-koop/alphafold3_input)](https://github.com/igor-koop/alphafold3_input/blob/main/LICENSE)
+[![Coverage](https://codecov.io/gh/igor-koop/alphafold3_input/graph/badge.svg?token=9906JN8BN0)](https://codecov.io/gh/igor-koop/alphafold3_input)
+[![Lint](https://img.shields.io/badge/linting-ruff-d7ff64)](https://docs.astral.sh/ruff/)
+[![Type](https://img.shields.io/badge/typing-ty-7c3aed)](https://docs.astral.sh/ty/)
+[![Actions](https://github.com/igor-koop/alphafold3_input/actions/workflows/actions.yml/badge.svg)](https://github.com/igor-koop/alphafold3_input/actions/workflows/actions.yml)
+
+
+Pythonic, object-oriented models for constructing **AlphaFold 3** input files.
+
+This package provides typed models and utilities that abstract the AlphaFold 3 JSON input format into a clean, validated Python interface.
+
+For details on the underlying specification, see the official [AlphaFold 3 input specification](https://github.com/google-deepmind/alphafold3/blob/main/docs/input.md).
+
+---
+
+## Installation
+
+Install the latest published release from PyPI:
+
+```bash
+uv add alphafold3_input
+```
+
+or:
+
+```bash
+pip install alphafold3_input
+```
+
+Install the current development version directly from GitHub:
+
+```bash
+uv add git+https://github.com/igor-koop/alphafold3_input
+```
+
+or:
+
+```bash
+pip install "git+https://github.com/igor-koop/alphafold3_input"
+```
+
+## Documentation
+
+Full API documentation is available at: https://igor-koop.github.io/alphafold3_input/
+
+## Development
+
+```bash
+git clone https://github.com/igor-koop/alphafold3_input
+cd alphafold3_input
+
+uv sync --dev
+```
+
+## License
+
+The scripts and documentation in this project are released under the [MIT License](https://github.com/igor-koop/alphafold3_input/blob/main/LICENSE).

alphafold3_input-0.3.0/pyproject.toml

@@ -0,0 +1,93 @@
+[project]
+name = "alphafold3_input"
+version = "0.3.0"
+description = "AlphaFold 3 input schema models."
+authors = [
+    { name = "Igor Koop" },
+]
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "pydantic>=2.13.4",
+    "rdkit>=2026.3.3",
+]
+keywords = [
+    "alphafold3",
+    "pydantic",
+    "bioinformatics",
+    "job-definition",
+    "input-generation",
+    "json",
+    "json-schema",
+]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.12",
+  "License :: OSI Approved :: MIT License",
+  "Intended Audience :: Science/Research",
+  "Topic :: Scientific/Engineering :: Bio-Informatics",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Repository = "https://github.com/igor-koop/alphafold3_input"
+Issues = "https://github.com/igor-koop/alphafold3_input/issues"
+Documentation = "https://github.com/igor-koop/alphafold3_input#readme"
+
+[build-system]
+requires = ["uv_build>=0.8.11,<0.9.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-root = "src"
+module-name = "alphafold3_input"
+
+[dependency-groups]
+dev = [
+    "furo>=2025.12.19",
+    "pytest>=9.0.2",
+    "pytest-cov>=7.0.0",
+    "ruff>=0.15.16",
+    "sphinx>=9.1.0",
+    "sphinx-autobuild>=2025.8.25",
+    "ty>=0.0.44",
+]
+
+[tool.ruff]
+line-length = 80
+target-version = "py312"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["ALL"]
+fixable = ["ALL"]
+ignore = ["COM812"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "pep257"
+
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["D100", "PLR2004", "S101"]
+"docs/**/*.py" = ["A001", "B010", "FBT001", "FBT002", "INP001", "PLR0913"]
+"src/**/*.py" = ["ANN401", "TC001", "TC002", "TC003"]
+
+[tool.pytest.ini_options]
+minversion = "9.0"
+testpaths = ["tests"]
+addopts = [
+    "--strict-config",
+    "--strict-markers",
+    "--cov=alphafold3_input",
+    "--cov-report=term-missing",
+    "--cov-fail-under=100",
+]
+
+[tool.coverage.run]
+source = ["alphafold3_input"]
+
+[tool.coverage.report]
+show_missing = true
+skip_empty = true

alphafold3_input-0.3.0/src/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-0.3.0/src/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-0.3.0/src/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)