structpick 0.1.0__tar.gz

structpick-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,30 @@
+name: publish
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # trusted publishing, no API token stored in the repo
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

structpick-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,40 @@
+name: tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv sync
+      - run: uv run ruff format --check .
+      - run: uv run ruff check .
+      - run: uv run mypy
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv sync
+      - run: uv run pytest --cov=structpick --cov-report=term-missing
+
+  live:
+    # The real APIs, once per run. Allowed to fail: EBI being down shouldn't block a PR.
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv sync
+      - run: uv run pytest -m network

structpick-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+.coverage
+coverage.*
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

structpick-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luís Felipe de Oliveira
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

structpick-0.1.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.5
+Name: structpick
+Version: 0.1.0
+Summary: Pick the best protein structure for docking: ranks PDB entries for a UniProt target, flags bound ligands and falls back to AlphaFold.
+Project-URL: Homepage, https://github.com/felipsoliveira/structpick
+Project-URL: Issues, https://github.com/felipsoliveira/structpick/issues
+Author: Luís Felipe de Oliveira
+License-Expression: MIT
+License-File: LICENSE
+Keywords: alphafold,bioinformatics,docking,drug-discovery,pdb,structural-biology,uniprot
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# structpick
+
+[![tests](https://github.com/felipsoliveira/structpick/actions/workflows/tests.yml/badge.svg)](https://github.com/felipsoliveira/structpick/actions/workflows/tests.yml)
+[![PyPI](https://img.shields.io/pypi/v/structpick)](https://pypi.org/project/structpick/)
+[![Python](https://img.shields.io/pypi/pyversions/structpick)](https://pypi.org/project/structpick/)
+
+Pick a protein structure to dock against.
+
+Given a UniProt accession, `structpick` lists the experimental structures from the PDB ranked by sequence coverage and resolution, shows which ones have a real ligand bound (ignoring glycerol, sulfate, ions and other crystallisation leftovers) and reports the AlphaFold model as a fallback. It's the first step of most structure-based drug design projects, and usually it means clicking through a dozen PDB pages.
+
+```console
+$ structpick list Q27743 --holo --max-resolution 2.0 --top 5
+Q27743: L-lactate dehydrogenase | Plasmodium falciparum (isolate CDC / Honduras) | 316 aa
+rank  pdb_id  chain  method             resolution  coverage  residues  ligands
+1     4plz    A      X-ray diffraction  1.05        100%      1-316     NAI,OXM
+2     1t2d    A      X-ray diffraction  1.10        100%      1-316     NAD,OXL
+3     2a94    A      X-ray diffraction  1.50        100%      2-316     AP0
+4     1t24    A      X-ray diffraction  1.70        100%      1-316     NAD,OXQ
+5     1u4o    A      X-ray diffraction  1.70        100%      2-316     NDD
+AlphaFold: AF-Q27743-F1 v6, mean pLDDT 97.4, 98% of residues very high confidence
+```
+
+Looking for a structure of EGFR with erlotinib (`AQ4`) bound:
+
+```console
+$ structpick list P00533 --method xray --ligand AQ4 --top 3
+P00533 (EGFR): Epidermal growth factor receptor | Homo sapiens | 1210 aa
+rank  pdb_id  chain  method             resolution  coverage  residues  ligands
+1     1m17    A      X-ray diffraction  2.60        28%       695-1022  AQ4
+2     4hjo    A      X-ray diffraction  2.75        28%       696-1022  AQ4
+AlphaFold: AF-P00533-F1 v6, mean pLDDT 75.9, 47% of residues very high confidence
+```
+
+## Install
+
+```bash
+pip install structpick
+```
+
+Python 3.10 or newer. The only dependency is [httpx](https://www.python-httpx.org/).
+
+## Usage
+
+```bash
+structpick list <accession> [filters] [--top N] [--format table|csv|json]
+structpick fetch <accession> [filters] [-o DIR] [--alphafold]
+```
+
+| Option | Meaning |
+|---|---|
+| `--max-resolution 2.0` | drop entries worse than 2.0 Å (also drops NMR, which has no resolution) |
+| `--min-coverage 0.8` | keep chains covering at least 80% of the UniProt sequence |
+| `--method xray` | `xray`, `em`, `nmr` or the full PDBe method name |
+| `--ligand HEM` | only chains with this ligand bound |
+| `--holo` | only chains with any ligand that isn't an additive or ion |
+
+`fetch` downloads the best match as mmCIF from RCSB. If nothing matches the filters, or with `--alphafold`, it downloads the AlphaFold model instead.
+
+`--format csv` and `--format json` are meant for scripts and notebooks:
+
+```bash
+structpick list P00533 --holo --format csv > egfr_structures.csv
+```
+
+### From Python
+
+```python
+from structpick import Filters, select_structures
+from structpick.api import Client
+
+with Client() as client:
+    structures = client.with_ligands(client.structures("P00533"))
+    best = select_structures(structures, Filters(max_resolution=2.5, require_ligand=True))
+    for s in best[:3]:
+        print(s.pdb_id, s.chain, s.resolution, [lig.code for lig in s.bound_ligands])
+```
+
+## How ranking works
+
+1. **Coverage**, compared in 10% steps, so a chain covering 99% and one covering 100% count as equal.
+2. **Resolution**, best first. Entries without a resolution (NMR) go last.
+
+Ligands only count if they sit on the same chain and aren't in the [additive list](src/structpick/models.py) (water, glycerol, ethylene glycol, PEG, sulfate, phosphate, common buffers, ions, detergents). Metal ions are on that list too, so check catalytic metals yourself when they matter.
+
+## Data sources
+
+- [UniProt REST API](https://rest.uniprot.org) for the target name, gene and length
+- [PDBe best structures](https://www.ebi.ac.uk/pdbe/api/doc/sifts.html) (SIFTS mappings) for chain coverage, method and resolution
+- [PDBe ligand monomers](https://www.ebi.ac.uk/pdbe/api/doc/pdb.html) for bound ligands
+- [AlphaFold Protein Structure Database](https://alphafold.ebi.ac.uk/api-docs) for predicted models
+
+Requests time out after 30 s and are retried with exponential backoff on 429 and 5xx responses. Ligands are only looked up for the chains left after the other filters, one request per PDB entry.
+
+## Development
+
+```bash
+git clone https://github.com/felipsoliveira/structpick
+cd structpick
+uv sync                   # or: pip install -e . pytest pytest-cov ruff mypy
+uv run pytest             # offline, uses recorded API responses in tests/fixtures
+uv run pytest -m network  # hits the real APIs
+uv run ruff check . && uv run mypy
+```
+
+## License
+
+MIT

structpick-0.1.0/README.md

@@ -0,0 +1,107 @@
+# structpick
+
+[![tests](https://github.com/felipsoliveira/structpick/actions/workflows/tests.yml/badge.svg)](https://github.com/felipsoliveira/structpick/actions/workflows/tests.yml)
+[![PyPI](https://img.shields.io/pypi/v/structpick)](https://pypi.org/project/structpick/)
+[![Python](https://img.shields.io/pypi/pyversions/structpick)](https://pypi.org/project/structpick/)
+
+Pick a protein structure to dock against.
+
+Given a UniProt accession, `structpick` lists the experimental structures from the PDB ranked by sequence coverage and resolution, shows which ones have a real ligand bound (ignoring glycerol, sulfate, ions and other crystallisation leftovers) and reports the AlphaFold model as a fallback. It's the first step of most structure-based drug design projects, and usually it means clicking through a dozen PDB pages.
+
+```console
+$ structpick list Q27743 --holo --max-resolution 2.0 --top 5
+Q27743: L-lactate dehydrogenase | Plasmodium falciparum (isolate CDC / Honduras) | 316 aa
+rank  pdb_id  chain  method             resolution  coverage  residues  ligands
+1     4plz    A      X-ray diffraction  1.05        100%      1-316     NAI,OXM
+2     1t2d    A      X-ray diffraction  1.10        100%      1-316     NAD,OXL
+3     2a94    A      X-ray diffraction  1.50        100%      2-316     AP0
+4     1t24    A      X-ray diffraction  1.70        100%      1-316     NAD,OXQ
+5     1u4o    A      X-ray diffraction  1.70        100%      2-316     NDD
+AlphaFold: AF-Q27743-F1 v6, mean pLDDT 97.4, 98% of residues very high confidence
+```
+
+Looking for a structure of EGFR with erlotinib (`AQ4`) bound:
+
+```console
+$ structpick list P00533 --method xray --ligand AQ4 --top 3
+P00533 (EGFR): Epidermal growth factor receptor | Homo sapiens | 1210 aa
+rank  pdb_id  chain  method             resolution  coverage  residues  ligands
+1     1m17    A      X-ray diffraction  2.60        28%       695-1022  AQ4
+2     4hjo    A      X-ray diffraction  2.75        28%       696-1022  AQ4
+AlphaFold: AF-P00533-F1 v6, mean pLDDT 75.9, 47% of residues very high confidence
+```
+
+## Install
+
+```bash
+pip install structpick
+```
+
+Python 3.10 or newer. The only dependency is [httpx](https://www.python-httpx.org/).
+
+## Usage
+
+```bash
+structpick list <accession> [filters] [--top N] [--format table|csv|json]
+structpick fetch <accession> [filters] [-o DIR] [--alphafold]
+```
+
+| Option | Meaning |
+|---|---|
+| `--max-resolution 2.0` | drop entries worse than 2.0 Å (also drops NMR, which has no resolution) |
+| `--min-coverage 0.8` | keep chains covering at least 80% of the UniProt sequence |
+| `--method xray` | `xray`, `em`, `nmr` or the full PDBe method name |
+| `--ligand HEM` | only chains with this ligand bound |
+| `--holo` | only chains with any ligand that isn't an additive or ion |
+
+`fetch` downloads the best match as mmCIF from RCSB. If nothing matches the filters, or with `--alphafold`, it downloads the AlphaFold model instead.
+
+`--format csv` and `--format json` are meant for scripts and notebooks:
+
+```bash
+structpick list P00533 --holo --format csv > egfr_structures.csv
+```
+
+### From Python
+
+```python
+from structpick import Filters, select_structures
+from structpick.api import Client
+
+with Client() as client:
+    structures = client.with_ligands(client.structures("P00533"))
+    best = select_structures(structures, Filters(max_resolution=2.5, require_ligand=True))
+    for s in best[:3]:
+        print(s.pdb_id, s.chain, s.resolution, [lig.code for lig in s.bound_ligands])
+```
+
+## How ranking works
+
+1. **Coverage**, compared in 10% steps, so a chain covering 99% and one covering 100% count as equal.
+2. **Resolution**, best first. Entries without a resolution (NMR) go last.
+
+Ligands only count if they sit on the same chain and aren't in the [additive list](src/structpick/models.py) (water, glycerol, ethylene glycol, PEG, sulfate, phosphate, common buffers, ions, detergents). Metal ions are on that list too, so check catalytic metals yourself when they matter.
+
+## Data sources
+
+- [UniProt REST API](https://rest.uniprot.org) for the target name, gene and length
+- [PDBe best structures](https://www.ebi.ac.uk/pdbe/api/doc/sifts.html) (SIFTS mappings) for chain coverage, method and resolution
+- [PDBe ligand monomers](https://www.ebi.ac.uk/pdbe/api/doc/pdb.html) for bound ligands
+- [AlphaFold Protein Structure Database](https://alphafold.ebi.ac.uk/api-docs) for predicted models
+
+Requests time out after 30 s and are retried with exponential backoff on 429 and 5xx responses. Ligands are only looked up for the chains left after the other filters, one request per PDB entry.
+
+## Development
+
+```bash
+git clone https://github.com/felipsoliveira/structpick
+cd structpick
+uv sync                   # or: pip install -e . pytest pytest-cov ruff mypy
+uv run pytest             # offline, uses recorded API responses in tests/fixtures
+uv run pytest -m network  # hits the real APIs
+uv run ruff check . && uv run mypy
+```
+
+## License
+
+MIT

structpick-0.1.0/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "structpick"
+version = "0.1.0"
+description = "Pick the best protein structure for docking: ranks PDB entries for a UniProt target, flags bound ligands and falls back to AlphaFold."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Luís Felipe de Oliveira" }]
+requires-python = ">=3.10"
+dependencies = ["httpx>=0.27"]
+keywords = ["bioinformatics", "structural-biology", "docking", "pdb", "alphafold", "uniprot", "drug-discovery"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/felipsoliveira/structpick"
+Issues = "https://github.com/felipsoliveira/structpick/issues"
+
+[project.scripts]
+structpick = "structpick.cli:main"
+
+[dependency-groups]
+dev = ["pytest>=8", "pytest-cov>=5", "ruff>=0.6", "mypy>=1.11"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM", "RUF"]
+
+[tool.mypy]
+strict = true
+files = ["src", "tests"]
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false
+disallow_untyped_calls = false
+disallow_incomplete_defs = false
+
+[tool.pytest.ini_options]
+addopts = "-m 'not network'"
+markers = ["network: hits the real EBI/UniProt APIs (deselected by default)"]

structpick-0.1.0/src/structpick/__init__.py

@@ -0,0 +1,15 @@
+"""Rank experimental and predicted structures of a protein target for docking."""
+
+from structpick.models import AlphaFoldModel, Ligand, Structure, Target, is_additive
+from structpick.select import Filters, select_structures
+
+__all__ = [
+    "AlphaFoldModel",
+    "Filters",
+    "Ligand",
+    "Structure",
+    "Target",
+    "is_additive",
+    "select_structures",
+]
+__version__ = "0.1.0"

structpick-0.1.0/src/structpick/__main__.py

@@ -0,0 +1,3 @@
+from structpick.cli import main
+
+raise SystemExit(main())

structpick-0.1.0/src/structpick/api.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+import time
+from dataclasses import replace
+from typing import Any
+
+import httpx
+
+from structpick import __version__
+from structpick.models import AlphaFoldModel, Ligand, Structure, Target
+
+PDBE = "https://www.ebi.ac.uk/pdbe/api"
+ALPHAFOLD = "https://alphafold.ebi.ac.uk/api"
+UNIPROT = "https://rest.uniprot.org"
+
+RETRY_STATUS = {429, 500, 502, 503, 504}
+
+
+class TargetNotFoundError(LookupError):
+    pass
+
+
+class Client:
+    """Small wrapper around the UniProt, PDBe and AlphaFold DB REST APIs."""
+
+    def __init__(
+        self,
+        http: httpx.Client | None = None,
+        retries: int = 3,
+        backoff: float = 1.0,
+    ) -> None:
+        self._http = http or httpx.Client(
+            timeout=httpx.Timeout(30.0),
+            headers={"User-Agent": f"structpick/{__version__}"},
+            follow_redirects=True,
+        )
+        self._retries = retries
+        self._backoff = backoff
+
+    def __enter__(self) -> Client:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._http.close()
+
+    def _get(
+        self,
+        url: str,
+        params: dict[str, str] | None = None,
+        missing: frozenset[int] = frozenset({404}),
+    ) -> Any | None:
+        """GET JSON. Returns None for `missing` statuses; retries rate limits and server errors."""
+        for attempt in range(self._retries + 1):
+            try:
+                response = self._http.get(url, params=params)
+            except httpx.TransportError:
+                if attempt == self._retries:
+                    raise
+            else:
+                if response.status_code in missing:
+                    return None
+                if response.status_code not in RETRY_STATUS or attempt == self._retries:
+                    response.raise_for_status()
+                    return response.json()
+            time.sleep(self._backoff * 2**attempt)
+        raise AssertionError("unreachable")
+
+    def target(self, accession: str) -> Target:
+        data = self._get(
+            f"{UNIPROT}/uniprotkb/{accession}",
+            params={
+                "fields": "accession,protein_name,gene_names,organism_name,length",
+                "format": "json",
+            },
+            # UniProt answers 400 for strings that aren't valid accessions.
+            missing=frozenset({400, 404}),
+        )
+        if data is None:
+            raise TargetNotFoundError(f"UniProt has no entry {accession!r}")
+        description: dict[str, Any] = data.get("proteinDescription", {})
+        submissions: list[dict[str, Any]] = description.get("submissionNames", [])
+        name = (
+            description.get("recommendedName", {}).get("fullName", {}).get("value")
+            or (submissions[0].get("fullName", {}).get("value") if submissions else None)
+            or accession
+        )
+        genes = data.get("genes") or []
+        gene = genes[0].get("geneName", {}).get("value") if genes else None
+        return Target(
+            accession=data["primaryAccession"],
+            name=name,
+            gene=gene,
+            organism=data.get("organism", {}).get("scientificName", ""),
+            length=data.get("sequence", {}).get("length", 0),
+        )
+
+    def structures(self, accession: str) -> list[Structure]:
+        data = self._get(f"{PDBE}/mappings/best_structures/{accession}")
+        if not data:
+            return []
+        rows: list[dict[str, Any]] = data.get(accession) or next(iter(data.values()), [])
+        return [
+            Structure(
+                pdb_id=row["pdb_id"],
+                chain=row["chain_id"],
+                method=row.get("experimental_method", ""),
+                resolution=row.get("resolution"),
+                coverage=float(row.get("coverage", 0.0)),
+                unp_start=row.get("unp_start", 0),
+                unp_end=row.get("unp_end", 0),
+            )
+            for row in rows
+        ]
+
+    def ligands(self, pdb_id: str) -> tuple[Ligand, ...]:
+        data = self._get(f"{PDBE}/pdb/entry/ligand_monomers/{pdb_id}")
+        if not data:
+            return ()
+        return tuple(
+            Ligand(
+                code=row["chem_comp_id"], name=row.get("chem_comp_name", ""), chain=row["chain_id"]
+            )
+            for row in data.get(pdb_id, [])
+        )
+
+    def with_ligands(self, structures: list[Structure]) -> list[Structure]:
+        """Attach ligands, fetching each PDB entry once."""
+        cache: dict[str, tuple[Ligand, ...]] = {}
+        result = []
+        for structure in structures:
+            if structure.pdb_id not in cache:
+                cache[structure.pdb_id] = self.ligands(structure.pdb_id)
+            result.append(replace(structure, ligands=cache[structure.pdb_id]))
+        return result
+
+    def alphafold(self, accession: str) -> AlphaFoldModel | None:
+        data = self._get(f"{ALPHAFOLD}/prediction/{accession}")
+        if not data:
+            return None
+        row = next((r for r in data if r.get("uniprotAccession") == accession), data[0])
+        return AlphaFoldModel(
+            accession=row["uniprotAccession"],
+            version=row.get("latestVersion", 0),
+            mean_plddt=row.get("globalMetricValue", 0.0),
+            fraction_very_high=row.get("fractionPlddtVeryHigh", 0.0),
+            start=row.get("sequenceStart", 0),
+            end=row.get("sequenceEnd", 0),
+            cif_url=row["cifUrl"],
+            pdb_url=row["pdbUrl"],
+        )
+
+    def download(self, url: str) -> bytes:
+        response = self._http.get(url)
+        response.raise_for_status()
+        return response.content
+
+
+def entry_url(pdb_id: str, fmt: str = "cif") -> str:
+    return f"https://files.rcsb.org/download/{pdb_id.upper()}.{fmt}"