scigantic-bindingdb 0.2.0__tar.gz

scigantic_bindingdb-0.2.0/LICENSE

@@ -0,0 +1,16 @@
+MIT No Attribution
+
+Copyright 2026 Scigantic
+
+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.
+
+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.

scigantic_bindingdb-0.2.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: scigantic-bindingdb
+Version: 0.2.0
+Summary: Query BindingDB directly from a public S3 mirror with DuckDB, including a ChEMBL cross-reference bridge table and a ready drug-target-interaction training table.
+Author: Scigantic
+License: MIT-0
+Project-URL: Homepage, https://scigantic.com
+Project-URL: Repository, https://github.com/Scigantic/scigantic-bindingdb
+Project-URL: Issues, https://github.com/Scigantic/scigantic-bindingdb/issues
+Keywords: bindingdb,cheminformatics,duckdb,drug-discovery,binding-affinity
+Classifier: License :: OSI Approved :: MIT No Attribution License (MIT-0)
+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: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: duckdb>=0.10
+Requires-Dist: pandas>=1.5
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: pandas-stubs; extra == "dev"
+Dynamic: license-file
+
+<h1 align="center">scigantic-bindingdb</h1>
+
+<p align="center">
+    <a href="https://github.com/Scigantic/scigantic-bindingdb/actions/workflows/ci.yml">
+        <img alt="CI" src="https://github.com/Scigantic/scigantic-bindingdb/actions/workflows/ci.yml/badge.svg" /></a>
+    <a href="https://pypi.org/project/scigantic-bindingdb/">
+        <img alt="PyPI" src="https://img.shields.io/pypi/v/scigantic-bindingdb" /></a>
+    <a href="https://pypi.org/project/scigantic-bindingdb/">
+        <img alt="PyPI - Python Version" src="https://img.shields.io/pypi/pyversions/scigantic-bindingdb" /></a>
+    <a href="https://github.com/Scigantic/scigantic-bindingdb/blob/main/LICENSE">
+        <img alt="License" src="https://img.shields.io/github/license/Scigantic/scigantic-bindingdb" /></a>
+</p>
+
+Query BindingDB directly from a public S3 mirror with DuckDB.
+
+```python
+import scigantic_bindingdb as bindingdb
+
+df = bindingdb.query("""
+    SELECT reactant_set_id, ligand_smiles, ki_nm_value
+    FROM measurements
+    WHERE ki_nm_value IS NOT NULL
+    LIMIT 5
+""")
+```
+
+That query runs against `s3://scigantic-bindingdb` over DuckDB's httpfs extension. Nothing is downloaded first, and there's no local database file sitting on disk afterward.
+
+## Installation
+
+```console
+$ pip install scigantic-bindingdb
+```
+
+## What's different about BindingDB
+
+Every row is one binding measurement (Ki, IC50, Kd or EC50) between one ligand and one protein target, rather than ChEMBL's assay-centric bioactivity record. BindingDB ships no relational database, just a flat TSV; the mirror normalizes it into `measurements` (one row per measurement), `target_chains` (one row per protein chain of the target, since BindingDB's raw format repeats a column block once per chain in a multimer) and `target_chain_names`.
+
+## Measurements, filtered the way that avoids the two sharp edges
+
+```python
+df = bindingdb.measurements(uniprot_id="P00533", endpoint="ki")  # EGFR
+```
+
+Two things this does that a raw query on `measurements` doesn't do for you:
+
+**Censored values stay out unless you ask for them.** Ki/IC50/Kd/EC50 are occasionally reported as `>X` or `<X` rather than an exact value, the same idea as ChEMBL's `standard_relation`. `exact_only=True`, the default, keeps only rows where that endpoint's qualifier is `=`:
+
+```python
+df = bindingdb.measurements(uniprot_id="P00533", endpoint="ic50", exact_only=False)  # include censored bounds too
+```
+
+**Target filtering doesn't fan out on multichain complexes.** `uniprot_id` matches against `target_chains` with an `EXISTS` check, not a `JOIN`, so a target whose accession appears on more than one chain of the same complex still returns each measurement once.
+
+`bindingdb.query()` still reaches the raw tables directly for anything this leaves out.
+
+## Cross-referencing ChEMBL
+
+BindingDB ingests ChEMBL as one of its own curated source feeds (51.3% of measurements in the 202608 release), and ChEMBL separately absorbs some BindingDB patent-derived bioactivity data, so the two archives are not independent corpora. `derived/bindingdb_chembl_bridge.parquet`, built once at mirror time, joins measurements to [scigantic-chembl](https://github.com/Scigantic/scigantic-chembl) by BindingDB's own `chembl_id` column where present (authoritative) and falls back to an exact InChIKey match where it's missing:
+
+```python
+df = bindingdb.chembl_bridge(reactant_set_id="50000001")
+```
+
+`with_names=True` (the default) also reaches into the live `scigantic-chembl` mirror for the matched compound's ChEMBL preferred name, a second public-bucket read over the same connection: not a mount-level dependency between the two archives, just a query-time join across two buckets that are both public and read-only here.
+
+## Drug-target-interaction pairs
+
+BindingDB is the dataset most DTI/proteochemometric tooling (like [DeepPurpose](https://github.com/kexinhuang12345/DeepPurpose)) is built around, specifically because it ships a full protein sequence alongside every affinity measurement, something ChEMBL's bioactivity tables don't do as directly. `derived/dti_pairs.parquet` is BindingDB reshaped into the (ligand, target, affinity) triples a model trains on, done once rather than re-derived by every caller:
+
+```python
+df = bindingdb.dti_pairs(endpoint="ki", single_chain_only=True)
+```
+
+```
+  reactant_set_id  ligand_smiles       target_sequence  uniprot_id  endpoint  affinity_nm  p_affinity
+           764556  Cc1ncoc1-c1nnc...   MASLSQLSSHLN...      P35462        ki         1.74    8.759451
+```
+
+Only exact measurements (never a censored `>X`/`<X` bound treated as a real label), and `p_affinity` is already computed as `-log10(affinity_nm * 1e-9)`, the same transform as ChEMBL's `pchembl_value`. 2,589,053 pairs across the four endpoints in the 202608 release, 1,163,672 distinct ligands, 9,219 distinct UniProt targets.
+
+Multichain targets are represented by chain 1's sequence only, standard practice for DTI benchmarks. Pass `single_chain_only=True` to drop the 5.7% of rows where that simplifies an actual multi-protein complex, if single-chain purity matters for your model. See `derived/DTI_README.md` in the mirror for the exact filters applied.
+
+## Working offline
+
+Off by default, since zero setup is the whole point. Turn it on to run the same queries repeatedly without re-fetching from S3:
+
+```python
+import scigantic_bindingdb as bindingdb
+
+bindingdb.enable_cache()
+df = bindingdb.chembl_bridge()  # downloads the bridge table once, then reads from disk
+```
+
+`chembl_bridge()` and `dti_pairs()` each need exactly one derived file, so caching downloads that one file to `~/.cache/scigantic-bindingdb` (override with `enable_cache(cache_dir=...)` or the `SCIGANTIC_BINDINGDB_CACHE` environment variable) and reuses it after that.
+
+`connect()`, `query()` and `measurements()` don't participate in this: `connect()` registers five core tables as views on every call, so caching them there would mean any call eagerly downloads everything regardless of what the query actually touches. Cache one table yourself if you want it locally: `bindingdb.cache_resolve("202608/parquet/measurements.parquet")` downloads it and returns the local path, usable directly in `read_parquet(...)`.
+
+## What's mirrored
+
+```python
+bindingdb.releases()
+```
+
+| release | raw tables | ChEMBL bridge | DTI pairs |
+|---|---|---|---|
+| 202608 | yes | yes | yes |
+
+This table isn't hardcoded. `releases()` reads a small manifest published alongside each mirror run. If it can't be reached, calls fall back to the snapshot shipped with whatever version you have installed and print a warning, rather than failing outright.
+
+Not mirrored yet: BindingDB's 3D SDF structures and precomputed similarity/substructure search (no fingerprint corpus has been built for this archive). `bindingdb.query()` still reaches every raw table the mirror carries.
+
+## Command line
+
+```console
+$ scigantic-bindingdb info
+$ scigantic-bindingdb query "SELECT count(*) FROM measurements" --release 202608
+```
+
+## License
+
+MIT-0. See [LICENSE](LICENSE).

scigantic_bindingdb-0.2.0/README.md

@@ -0,0 +1,122 @@
+<h1 align="center">scigantic-bindingdb</h1>
+
+<p align="center">
+    <a href="https://github.com/Scigantic/scigantic-bindingdb/actions/workflows/ci.yml">
+        <img alt="CI" src="https://github.com/Scigantic/scigantic-bindingdb/actions/workflows/ci.yml/badge.svg" /></a>
+    <a href="https://pypi.org/project/scigantic-bindingdb/">
+        <img alt="PyPI" src="https://img.shields.io/pypi/v/scigantic-bindingdb" /></a>
+    <a href="https://pypi.org/project/scigantic-bindingdb/">
+        <img alt="PyPI - Python Version" src="https://img.shields.io/pypi/pyversions/scigantic-bindingdb" /></a>
+    <a href="https://github.com/Scigantic/scigantic-bindingdb/blob/main/LICENSE">
+        <img alt="License" src="https://img.shields.io/github/license/Scigantic/scigantic-bindingdb" /></a>
+</p>
+
+Query BindingDB directly from a public S3 mirror with DuckDB.
+
+```python
+import scigantic_bindingdb as bindingdb
+
+df = bindingdb.query("""
+    SELECT reactant_set_id, ligand_smiles, ki_nm_value
+    FROM measurements
+    WHERE ki_nm_value IS NOT NULL
+    LIMIT 5
+""")
+```
+
+That query runs against `s3://scigantic-bindingdb` over DuckDB's httpfs extension. Nothing is downloaded first, and there's no local database file sitting on disk afterward.
+
+## Installation
+
+```console
+$ pip install scigantic-bindingdb
+```
+
+## What's different about BindingDB
+
+Every row is one binding measurement (Ki, IC50, Kd or EC50) between one ligand and one protein target, rather than ChEMBL's assay-centric bioactivity record. BindingDB ships no relational database, just a flat TSV; the mirror normalizes it into `measurements` (one row per measurement), `target_chains` (one row per protein chain of the target, since BindingDB's raw format repeats a column block once per chain in a multimer) and `target_chain_names`.
+
+## Measurements, filtered the way that avoids the two sharp edges
+
+```python
+df = bindingdb.measurements(uniprot_id="P00533", endpoint="ki")  # EGFR
+```
+
+Two things this does that a raw query on `measurements` doesn't do for you:
+
+**Censored values stay out unless you ask for them.** Ki/IC50/Kd/EC50 are occasionally reported as `>X` or `<X` rather than an exact value, the same idea as ChEMBL's `standard_relation`. `exact_only=True`, the default, keeps only rows where that endpoint's qualifier is `=`:
+
+```python
+df = bindingdb.measurements(uniprot_id="P00533", endpoint="ic50", exact_only=False)  # include censored bounds too
+```
+
+**Target filtering doesn't fan out on multichain complexes.** `uniprot_id` matches against `target_chains` with an `EXISTS` check, not a `JOIN`, so a target whose accession appears on more than one chain of the same complex still returns each measurement once.
+
+`bindingdb.query()` still reaches the raw tables directly for anything this leaves out.
+
+## Cross-referencing ChEMBL
+
+BindingDB ingests ChEMBL as one of its own curated source feeds (51.3% of measurements in the 202608 release), and ChEMBL separately absorbs some BindingDB patent-derived bioactivity data, so the two archives are not independent corpora. `derived/bindingdb_chembl_bridge.parquet`, built once at mirror time, joins measurements to [scigantic-chembl](https://github.com/Scigantic/scigantic-chembl) by BindingDB's own `chembl_id` column where present (authoritative) and falls back to an exact InChIKey match where it's missing:
+
+```python
+df = bindingdb.chembl_bridge(reactant_set_id="50000001")
+```
+
+`with_names=True` (the default) also reaches into the live `scigantic-chembl` mirror for the matched compound's ChEMBL preferred name, a second public-bucket read over the same connection: not a mount-level dependency between the two archives, just a query-time join across two buckets that are both public and read-only here.
+
+## Drug-target-interaction pairs
+
+BindingDB is the dataset most DTI/proteochemometric tooling (like [DeepPurpose](https://github.com/kexinhuang12345/DeepPurpose)) is built around, specifically because it ships a full protein sequence alongside every affinity measurement, something ChEMBL's bioactivity tables don't do as directly. `derived/dti_pairs.parquet` is BindingDB reshaped into the (ligand, target, affinity) triples a model trains on, done once rather than re-derived by every caller:
+
+```python
+df = bindingdb.dti_pairs(endpoint="ki", single_chain_only=True)
+```
+
+```
+  reactant_set_id  ligand_smiles       target_sequence  uniprot_id  endpoint  affinity_nm  p_affinity
+           764556  Cc1ncoc1-c1nnc...   MASLSQLSSHLN...      P35462        ki         1.74    8.759451
+```
+
+Only exact measurements (never a censored `>X`/`<X` bound treated as a real label), and `p_affinity` is already computed as `-log10(affinity_nm * 1e-9)`, the same transform as ChEMBL's `pchembl_value`. 2,589,053 pairs across the four endpoints in the 202608 release, 1,163,672 distinct ligands, 9,219 distinct UniProt targets.
+
+Multichain targets are represented by chain 1's sequence only, standard practice for DTI benchmarks. Pass `single_chain_only=True` to drop the 5.7% of rows where that simplifies an actual multi-protein complex, if single-chain purity matters for your model. See `derived/DTI_README.md` in the mirror for the exact filters applied.
+
+## Working offline
+
+Off by default, since zero setup is the whole point. Turn it on to run the same queries repeatedly without re-fetching from S3:
+
+```python
+import scigantic_bindingdb as bindingdb
+
+bindingdb.enable_cache()
+df = bindingdb.chembl_bridge()  # downloads the bridge table once, then reads from disk
+```
+
+`chembl_bridge()` and `dti_pairs()` each need exactly one derived file, so caching downloads that one file to `~/.cache/scigantic-bindingdb` (override with `enable_cache(cache_dir=...)` or the `SCIGANTIC_BINDINGDB_CACHE` environment variable) and reuses it after that.
+
+`connect()`, `query()` and `measurements()` don't participate in this: `connect()` registers five core tables as views on every call, so caching them there would mean any call eagerly downloads everything regardless of what the query actually touches. Cache one table yourself if you want it locally: `bindingdb.cache_resolve("202608/parquet/measurements.parquet")` downloads it and returns the local path, usable directly in `read_parquet(...)`.
+
+## What's mirrored
+
+```python
+bindingdb.releases()
+```
+
+| release | raw tables | ChEMBL bridge | DTI pairs |
+|---|---|---|---|
+| 202608 | yes | yes | yes |
+
+This table isn't hardcoded. `releases()` reads a small manifest published alongside each mirror run. If it can't be reached, calls fall back to the snapshot shipped with whatever version you have installed and print a warning, rather than failing outright.
+
+Not mirrored yet: BindingDB's 3D SDF structures and precomputed similarity/substructure search (no fingerprint corpus has been built for this archive). `bindingdb.query()` still reaches every raw table the mirror carries.
+
+## Command line
+
+```console
+$ scigantic-bindingdb info
+$ scigantic-bindingdb query "SELECT count(*) FROM measurements" --release 202608
+```
+
+## License
+
+MIT-0. See [LICENSE](LICENSE).

scigantic_bindingdb-0.2.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "scigantic-bindingdb"
+version = "0.2.0"
+description = "Query BindingDB directly from a public S3 mirror with DuckDB, including a ChEMBL cross-reference bridge table and a ready drug-target-interaction training table."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT-0" }
+authors = [{ name = "Scigantic" }]
+keywords = ["bindingdb", "cheminformatics", "duckdb", "drug-discovery", "binding-affinity"]
+classifiers = [
+  "License :: OSI Approved :: MIT No Attribution License (MIT-0)",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Typing :: Typed",
+  "Topic :: Scientific/Engineering :: Bio-Informatics",
+  "Topic :: Scientific/Engineering :: Chemistry",
+]
+
+dependencies = [
+  "duckdb>=0.10",
+  "pandas>=1.5",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "mypy>=1.10", "pandas-stubs"]
+
+[project.urls]
+Homepage = "https://scigantic.com"
+Repository = "https://github.com/Scigantic/scigantic-bindingdb"
+Issues = "https://github.com/Scigantic/scigantic-bindingdb/issues"
+
+[project.scripts]
+scigantic-bindingdb = "scigantic_bindingdb.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+scigantic_bindingdb = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.mypy]
+strict = true

scigantic_bindingdb-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

scigantic_bindingdb-0.2.0/src/scigantic_bindingdb/__init__.py

@@ -0,0 +1,41 @@
+"""Query BindingDB directly from a public S3 mirror. No download, no local database."""
+
+from importlib.metadata import PackageNotFoundError, version as _version
+
+from .cache import cache_dir, disable_cache, enable_cache, is_cache_enabled
+from .cache import resolve as cache_resolve
+from .chembl_bridge import chembl_bridge
+from .connection import connect, query
+from .dti_pairs import dti_pairs
+from .measurements import measurements
+from .releases import (
+    ReleaseCapabilityError,
+    ReleaseInfo,
+    UnknownReleaseError,
+    latest,
+    releases,
+)
+
+try:
+    __version__ = _version("scigantic-bindingdb")
+except PackageNotFoundError:
+    # Running from a source checkout with no install (editable or not).
+    __version__ = "0.0.0"
+
+__all__ = [
+    "chembl_bridge",
+    "connect",
+    "query",
+    "measurements",
+    "dti_pairs",
+    "releases",
+    "latest",
+    "enable_cache",
+    "disable_cache",
+    "is_cache_enabled",
+    "cache_dir",
+    "cache_resolve",
+    "ReleaseInfo",
+    "ReleaseCapabilityError",
+    "UnknownReleaseError",
+]

scigantic_bindingdb-0.2.0/src/scigantic_bindingdb/__main__.py

@@ -0,0 +1,8 @@
+"""Enables `python -m scigantic_bindingdb`, same commands as the `scigantic-bindingdb` console script."""
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

scigantic_bindingdb-0.2.0/src/scigantic_bindingdb/_constants.py

@@ -0,0 +1,7 @@
+"""Shared constants: where the mirror lives."""
+
+BUCKET = "scigantic-bindingdb"
+REGION = "us-east-1"
+
+# The scigantic-chembl mirror this package's chembl_bridge() cross-references.
+CHEMBL_BUCKET = "scigantic-chembl"

scigantic_bindingdb-0.2.0/src/scigantic_bindingdb/cache.py

@@ -0,0 +1,113 @@
+"""Optional local caching: download once, then work with no network.
+
+Off by default. This package's whole pitch is zero setup, so caching stays
+opt-in rather than something that changes the default behavior:
+
+    import scigantic_bindingdb as bindingdb
+    bindingdb.enable_cache()
+
+chembl_bridge() then reads its one derived file from a local cache directory
+instead of S3, downloading it the first time it's needed and reusing it
+after that.
+
+connect() / query() / measurements() deliberately do NOT use this:
+connect() registers five core tables as views on every call, so caching
+them there would mean any call eagerly downloads everything regardless of
+what the query actually touches. Cache a specific table yourself if you
+want it locally: cache_resolve("<release>/parquet/<table>.parquet")
+downloads it and returns the local path, usable directly in
+read_parquet(...).
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import urllib.request
+from pathlib import Path
+
+from ._constants import BUCKET, REGION
+
+_enabled = False
+_cache_dir: Path | None = None
+
+_CHUNK_BYTES = 1024 * 1024
+
+
+def _default_cache_dir() -> Path:
+    if sys.platform == "win32":
+        base = os.environ.get("LOCALAPPDATA") or str(Path.home() / "AppData" / "Local")
+    elif sys.platform == "darwin":
+        base = str(Path.home() / "Library" / "Caches")
+    else:
+        base = os.environ.get("XDG_CACHE_HOME") or str(Path.home() / ".cache")
+    return Path(base) / "scigantic-bindingdb"
+
+
+def enable_cache(cache_dir: str | None = None) -> Path:
+    """Turn on local caching for every function in this package that uses it.
+
+    Cache location: `cache_dir` if given, else the
+    SCIGANTIC_BINDINGDB_CACHE environment variable, else a
+    platform-appropriate user cache directory. Returns the resolved
+    directory.
+    """
+    global _enabled, _cache_dir
+    if cache_dir is not None:
+        resolved = Path(cache_dir)
+    elif os.environ.get("SCIGANTIC_BINDINGDB_CACHE"):
+        resolved = Path(os.environ["SCIGANTIC_BINDINGDB_CACHE"])
+    else:
+        resolved = _default_cache_dir()
+    resolved.mkdir(parents=True, exist_ok=True)
+    _cache_dir = resolved
+    _enabled = True
+    return resolved
+
+
+def disable_cache() -> None:
+    """Turn caching back off. Later calls go straight to S3 again.
+
+    Anything already downloaded stays on disk; this only stops using it.
+    """
+    global _enabled
+    _enabled = False
+
+
+def is_cache_enabled() -> bool:
+    return _enabled
+
+
+def cache_dir() -> Path | None:
+    """The resolved cache directory, or None if caching has never been enabled."""
+    return _cache_dir
+
+
+def resolve(key: str) -> str:
+    """An S3 URL, or a local cached file path if caching is on.
+
+    `key` is a path relative to the bucket root, e.g.
+    "202608/derived/bindingdb_chembl_bridge.parquet". Downloads to the
+    cache on first access; later calls for the same key reuse the local
+    file without touching the network.
+    """
+    if not _enabled:
+        return f"s3://{BUCKET}/{key}"
+
+    assert _cache_dir is not None
+    local_path = _cache_dir / key
+    if local_path.exists():
+        return str(local_path)
+
+    local_path.parent.mkdir(parents=True, exist_ok=True)
+    url = f"https://{BUCKET}.s3.{REGION}.amazonaws.com/{key}"
+    # Download to a sibling temp file and rename into place atomically, so a
+    # download killed partway through never leaves a file that looks cached
+    # but isn't.
+    tmp_path = local_path.with_name(local_path.name + ".part")
+    print(f"scigantic-bindingdb: caching {key} ...", file=sys.stderr, flush=True)
+    with urllib.request.urlopen(url) as response, open(tmp_path, "wb") as fh:
+        while chunk := response.read(_CHUNK_BYTES):
+            fh.write(chunk)
+    os.replace(tmp_path, local_path)
+    return str(local_path)

scigantic_bindingdb-0.2.0/src/scigantic_bindingdb/chembl_bridge.py

@@ -0,0 +1,87 @@
+"""Cross-reference BindingDB measurements to ChEMBL, through the precomputed
+bridge table rather than re-deriving the join yourself.
+
+BindingDB ingests ChEMBL as one of its own curated source feeds (51.3% of
+measurements in the 202608 release), and ChEMBL separately absorbs some
+BindingDB patent-derived bioactivity data, so the two archives are not
+independent corpora. derived/bindingdb_chembl_bridge.parquet, built once at
+mirror time, joins measurements to s3://scigantic-chembl by BindingDB's own
+chembl_id column where present (authoritative) and falls back to an exact
+InChIKey match where it's missing. This module wraps that file, and
+optionally reaches into the live scigantic-chembl mirror over the same
+DuckDB connection for compound/target names: a read-only cross-bucket SQL
+join at query time, not a mount-level dependency between the two archives.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ._constants import CHEMBL_BUCKET
+from .cache import resolve as _resolve
+from .connection import connect
+from .releases import _require, latest
+
+if TYPE_CHECKING:
+    import pandas as pd
+
+
+def chembl_bridge(
+    release: str | None = None,
+    chembl_release: str = "chembl_37",
+    reactant_set_id: str | None = None,
+    with_names: bool = True,
+    limit: int | None = None,
+) -> "pd.DataFrame":
+    """BindingDB measurements joined to their ChEMBL cross-reference.
+
+    with_names (default True) also pulls in compound_chembl_id's pref_name
+    from s3://scigantic-chembl/<chembl_release>, a second public bucket read
+    over the same connection. Set False to skip that join and get just the
+    bridge table's own columns (reactant_set_id, chembl_molregno, chembl_id,
+    match_method) plus the measurement's SMILES.
+
+    release defaults to the manifest's current latest(). Only that release
+    is guaranteed to carry the bridge table; call releases() to check.
+    """
+    release = release or latest()
+    _require(release, "chembl_bridge")
+    con = connect(release)
+    try:
+        bridge_path = _resolve(f"{release}/derived/bindingdb_chembl_bridge.parquet")
+        con.execute(
+            "CREATE OR REPLACE VIEW chembl_bridge AS "
+            f"SELECT * FROM read_parquet('{bridge_path}')"
+        )
+
+        where: list[str] = []
+        params: list[str | int] = []
+        if reactant_set_id is not None:
+            where.append("b.reactant_set_id = ?")
+            params.append(reactant_set_id)
+        clause = f"WHERE {' AND '.join(where)}" if where else ""
+
+        if with_names:
+            mol_dict = f"s3://{CHEMBL_BUCKET}/{chembl_release}/parquet/molecule_dictionary.parquet"
+            sql = f"""
+                SELECT b.reactant_set_id, b.chembl_molregno, b.chembl_id, b.match_method,
+                       m.ligand_smiles, d.pref_name AS chembl_pref_name
+                FROM chembl_bridge b
+                JOIN measurements m ON m.reactant_set_id = b.reactant_set_id
+                LEFT JOIN read_parquet('{mol_dict}') d ON d.molregno = b.chembl_molregno
+                {clause}
+            """
+        else:
+            sql = f"""
+                SELECT b.reactant_set_id, b.chembl_molregno, b.chembl_id, b.match_method,
+                       m.ligand_smiles
+                FROM chembl_bridge b
+                JOIN measurements m ON m.reactant_set_id = b.reactant_set_id
+                {clause}
+            """
+        if limit is not None:
+            sql += " LIMIT ?"
+            params.append(int(limit))
+        return con.execute(sql, params).df()
+    finally:
+        con.close()

scigantic_bindingdb-0.2.0/src/scigantic_bindingdb/cli.py

@@ -0,0 +1,55 @@
+"""Command-line interface: `scigantic-bindingdb info` and `scigantic-bindingdb query`."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Sequence, cast
+
+from .connection import query as run_query
+from .releases import releases
+
+
+def _cmd_info(_args: argparse.Namespace) -> int:
+    for info in releases():
+        derived = [
+            name
+            for name, present in (
+                ("chembl_bridge", info.chembl_bridge),
+                ("dti_pairs", info.dti_pairs),
+            )
+            if present
+        ]
+        suffix = f" + {', '.join(derived)}" if derived else " (raw tables only)"
+        print(f"{info.release}{suffix}")
+    return 0
+
+
+def _cmd_query(args: argparse.Namespace) -> int:
+    df = run_query(args.sql, release=args.release)
+    print(df.to_csv(sep="\t", index=False), end="")
+    return 0
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="scigantic-bindingdb")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    info_parser = subparsers.add_parser(
+        "info", help="list mirrored releases and what each one supports"
+    )
+    info_parser.set_defaults(func=_cmd_info)
+
+    query_parser = subparsers.add_parser(
+        "query", help="run SQL against a release and print tab-separated output"
+    )
+    query_parser.add_argument("sql")
+    query_parser.add_argument("--release", default=None, help="defaults to the current release")
+    query_parser.set_defaults(func=_cmd_query)
+
+    args = parser.parse_args(argv)
+    return cast(int, args.func(args))
+
+
+if __name__ == "__main__":
+    sys.exit(main())