scigantic-pubchem 0.3.0__tar.gz

scigantic_pubchem-0.3.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_pubchem-0.3.0/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: scigantic-pubchem
+Version: 0.3.0
+Summary: Query PubChem live via PUG REST, with rate-limit-aware retry, expiring cache, and live similarity/substructure/cross-reference search PubChemPy doesn't have.
+Author: Scigantic
+License: MIT-0
+Project-URL: Homepage, https://scigantic.com
+Project-URL: Repository, https://github.com/Scigantic/scigantic-pubchem
+Project-URL: Issues, https://github.com/Scigantic/scigantic-pubchem/issues
+Keywords: pubchem,cheminformatics,pug-rest,drug-discovery,identifier-resolution
+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: requests>=2.28
+Provides-Extra: bridge
+Requires-Dist: duckdb>=0.10; extra == "bridge"
+Requires-Dist: pandas>=1.5; extra == "bridge"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: types-requests; extra == "dev"
+Requires-Dist: pandas-stubs; extra == "dev"
+Dynamic: license-file
+
+<h1 align="center">scigantic-pubchem</h1>
+
+<p align="center">
+    <a href="https://github.com/Scigantic/scigantic-pubchem/actions/workflows/ci.yml">
+        <img alt="CI" src="https://github.com/Scigantic/scigantic-pubchem/actions/workflows/ci.yml/badge.svg" /></a>
+    <a href="https://pypi.org/project/scigantic-pubchem/">
+        <img alt="PyPI" src="https://img.shields.io/pypi/v/scigantic-pubchem" /></a>
+    <a href="https://pypi.org/project/scigantic-pubchem/">
+        <img alt="PyPI - Python Version" src="https://img.shields.io/pypi/pyversions/scigantic-pubchem" /></a>
+    <a href="https://github.com/Scigantic/scigantic-pubchem/blob/main/LICENSE">
+        <img alt="License" src="https://img.shields.io/github/license/Scigantic/scigantic-pubchem" /></a>
+</p>
+
+Query PubChem live via PUG REST. No mirror, no download, no local database.
+
+```python
+import scigantic_pubchem as pubchem
+
+aspirin = pubchem.resolve("aspirin")
+print(aspirin.cid, aspirin.smiles, aspirin.inchi_key)
+```
+
+## Installation
+
+```console
+$ pip install scigantic-pubchem
+```
+
+## Why this exists
+
+[PubChemPy](https://github.com/mcs07/PubChemPy) has been the standard way to script against PubChem in Python for years, and it covers a lot this package doesn't try to replace: 3D conformers, assays, substances, atoms and bonds. This package is narrower, focused on identifier resolution and cross-referencing, and adds a few things that matter specifically for that: resilience under PubChem's own rate limiting, a cache that keeps a notebook fast without going stale, and live search over PubChem's full corpus rather than a local index.
+
+Measured, not asserted, on 2026-08-27:
+
+| | measured |
+|---|---|
+| Cached lookup vs a live PUG REST round trip | under 1ms vs 250ms-2.4s in testing, roughly 1,000-10,000x depending on the identifier |
+| Batch resolution (50 CIDs) | 30.5s in one request via `resolve_many()`, versus 90.7s across 50 separate requests done one at a time (3.0x) |
+| Live 503 during an 8-thread concurrent test | recovered automatically via retry, no failed lookups |
+| Similarity search corpus size | PubChem's full ~120M compounds, live, versus a precomputed local index bounded to whatever was indexed ahead of time |
+
+The rate-limit handling in particular comes from reading PUG REST's own `X-Throttling-Control` response header, which reports live status across three dimensions (request count, request time, service load) on every call. PubChemPy's source doesn't read this header, so it has no way to back off before hitting a hard limit, and raises immediately on an error with no retry. That's a reasonable design for a general-purpose client; this package leans the other way on purpose, since backing off proactively and retrying transient failures matters more when a notebook is doing dozens of lookups in a loop.
+
+**Caching, on by default, and it expires.** A lookup already made is never re-fetched, cached to `~/.cache/scigantic-pubchem` (override with `enable_cache(cache_dir=...)` or `SCIGANTIC_PUBCHEM_CACHE`). This is a deliberate difference from `scigantic-chembl` and `scigantic-bindingdb`, whose caching defaults off: those read a public S3 mirror with no meaningful rate limit, so caching there is pure convenience. This package calls a rate-limited live API for every lookup, so re-fetching the same identifier in a loop is both slow and the exact thing the throttling-aware client otherwise works to avoid. Entries expire after 30 days by default, so the cache can't quietly turn into a stale snapshot:
+
+```python
+pubchem.disable_cache()               # every call hits the network fresh
+pubchem.enable_cache(ttl_days=7)      # shorter freshness window
+pubchem.enable_cache(ttl_days=None)   # never expire
+```
+
+**Live cross-references, not just structures.**
+
+```python
+pubchem.chembl_id(2244)   # 'CHEMBL25', read live from PubChem's own xrefs, not a static table
+```
+
+PubChem's own `xrefs/RegistryID` endpoint already carries the ChEMBL ID for a compound when one exists (verified live against aspirin, CID 2244 resolves to CHEMBL25). PubChemPy can reach the same endpoint through its low-level `request()`/`get()` functions; this package wraps it as a named, documented function.
+
+**Similarity and substructure search, over PubChem's entire corpus, not a local index.**
+
+```python
+hits = pubchem.similar_compounds("CC(=O)OC1=CC=CC=C1C(=O)O", threshold=95, max_records=5)
+# [Compound(cid=2244, title='Aspirin', ...), Compound(cid=4133, title='Methyl Salicylate', ...), ...]
+
+pubchem.substructure_search("c1ccccc1", query_type="smiles")     # every compound containing a benzene ring
+pubchem.substructure_search("[#6]1[#6][#6][#6][#6][#6]1", query_type="smarts")  # the SMARTS equivalent
+```
+
+`scigantic-chembl`'s `similar_compounds()`/`substructure_search()` precompute fingerprints once and search them locally: fast, but bounded to the roughly 1.68M ChEMBL compounds that carry a comparable measurement. This runs the search on PubChem's own servers, live, over the full ~120M-compound corpus, verified sub-second for a typical query and with no local fingerprint database to build or hold in memory. PubChemPy exposes the same PUG REST capability as a raw `searchtype="similarity"`/`"substructure"` parameter to its generic `get_compounds()`; this package gives it a named function, and keeps `query_type="smiles"` and `"smarts"` as separate, explicit paths rather than guessing between them, since they're genuinely different endpoints with different matching semantics (verified live: the same ring given as SMILES versus SMARTS returns overlapping but not identical results).
+
+An expensive search can respond asynchronously, with PubChem handing back a job to poll rather than blocking the connection; handled transparently, using the same protocol PubChemPy implements. Every live query tried during development resolved synchronously, even a maximally broad single-carbon substructure search, so the polling loop itself is verified with a scripted mock response sequence rather than left checked only against documentation.
+
+## Thread safety
+
+Safe to call from multiple threads, a plausible real pattern: resolving a list of names via a `ThreadPoolExecutor`, say. The shared HTTP session is created once behind a lock rather than raced into existence by whichever thread gets there first. `enable_cache()`/`disable_cache()` are not synchronized against concurrent reads, the same way mutating `os.environ` isn't: call them once at the start of a script, not from multiple threads at once.
+
+## Live bridge into scigantic-chembl and scigantic-bindingdb
+
+```python
+pubchem.chembl_context(2244)
+# {'molregno': ..., 'chembl_id': 'CHEMBL25', 'pref_name': 'ASPIRIN', 'max_phase': 4}
+
+pubchem.bindingdb_measurements(2244)
+# DataFrame of every BindingDB measurement recorded against this CID
+```
+
+Both are on-demand DuckDB queries against the public [scigantic-chembl](https://github.com/Scigantic/scigantic-chembl) and [scigantic-bindingdb](https://github.com/Scigantic/scigantic-bindingdb) mirrors. `chembl_context` resolves the ChEMBL ID live (see above), then looks up its assay context; `bindingdb_measurements` filters BindingDB's own `pubchem_cid` column directly, since BindingDB already carries that mapping natively. Neither needs a precomputed bridge table, and neither goes stale the way a static one would. Needs `duckdb`:
+
+```console
+$ pip install "scigantic-pubchem[bridge]"
+```
+
+## Batch resolution
+
+```python
+compounds = pubchem.resolve_many([2244, 2519, 1983])  # aspirin, caffeine, acetaminophen
+```
+
+PUG REST accepts a comma-separated CID list in a single request (verified live); this chunks at 200 CIDs per call rather than sending one unbounded URL for a long list.
+
+## Command line
+
+```console
+$ scigantic-pubchem resolve aspirin
+$ scigantic-pubchem chembl-id 2244
+$ scigantic-pubchem xrefs 2244 --type RegistryID
+$ scigantic-pubchem similar "CC(=O)OC1=CC=CC=C1C(=O)O" --threshold 95
+$ scigantic-pubchem substructure c1ccccc1
+```
+
+## License
+
+MIT-0. See [LICENSE](LICENSE).

scigantic_pubchem-0.3.0/README.md

@@ -0,0 +1,114 @@
+<h1 align="center">scigantic-pubchem</h1>
+
+<p align="center">
+    <a href="https://github.com/Scigantic/scigantic-pubchem/actions/workflows/ci.yml">
+        <img alt="CI" src="https://github.com/Scigantic/scigantic-pubchem/actions/workflows/ci.yml/badge.svg" /></a>
+    <a href="https://pypi.org/project/scigantic-pubchem/">
+        <img alt="PyPI" src="https://img.shields.io/pypi/v/scigantic-pubchem" /></a>
+    <a href="https://pypi.org/project/scigantic-pubchem/">
+        <img alt="PyPI - Python Version" src="https://img.shields.io/pypi/pyversions/scigantic-pubchem" /></a>
+    <a href="https://github.com/Scigantic/scigantic-pubchem/blob/main/LICENSE">
+        <img alt="License" src="https://img.shields.io/github/license/Scigantic/scigantic-pubchem" /></a>
+</p>
+
+Query PubChem live via PUG REST. No mirror, no download, no local database.
+
+```python
+import scigantic_pubchem as pubchem
+
+aspirin = pubchem.resolve("aspirin")
+print(aspirin.cid, aspirin.smiles, aspirin.inchi_key)
+```
+
+## Installation
+
+```console
+$ pip install scigantic-pubchem
+```
+
+## Why this exists
+
+[PubChemPy](https://github.com/mcs07/PubChemPy) has been the standard way to script against PubChem in Python for years, and it covers a lot this package doesn't try to replace: 3D conformers, assays, substances, atoms and bonds. This package is narrower, focused on identifier resolution and cross-referencing, and adds a few things that matter specifically for that: resilience under PubChem's own rate limiting, a cache that keeps a notebook fast without going stale, and live search over PubChem's full corpus rather than a local index.
+
+Measured, not asserted, on 2026-08-27:
+
+| | measured |
+|---|---|
+| Cached lookup vs a live PUG REST round trip | under 1ms vs 250ms-2.4s in testing, roughly 1,000-10,000x depending on the identifier |
+| Batch resolution (50 CIDs) | 30.5s in one request via `resolve_many()`, versus 90.7s across 50 separate requests done one at a time (3.0x) |
+| Live 503 during an 8-thread concurrent test | recovered automatically via retry, no failed lookups |
+| Similarity search corpus size | PubChem's full ~120M compounds, live, versus a precomputed local index bounded to whatever was indexed ahead of time |
+
+The rate-limit handling in particular comes from reading PUG REST's own `X-Throttling-Control` response header, which reports live status across three dimensions (request count, request time, service load) on every call. PubChemPy's source doesn't read this header, so it has no way to back off before hitting a hard limit, and raises immediately on an error with no retry. That's a reasonable design for a general-purpose client; this package leans the other way on purpose, since backing off proactively and retrying transient failures matters more when a notebook is doing dozens of lookups in a loop.
+
+**Caching, on by default, and it expires.** A lookup already made is never re-fetched, cached to `~/.cache/scigantic-pubchem` (override with `enable_cache(cache_dir=...)` or `SCIGANTIC_PUBCHEM_CACHE`). This is a deliberate difference from `scigantic-chembl` and `scigantic-bindingdb`, whose caching defaults off: those read a public S3 mirror with no meaningful rate limit, so caching there is pure convenience. This package calls a rate-limited live API for every lookup, so re-fetching the same identifier in a loop is both slow and the exact thing the throttling-aware client otherwise works to avoid. Entries expire after 30 days by default, so the cache can't quietly turn into a stale snapshot:
+
+```python
+pubchem.disable_cache()               # every call hits the network fresh
+pubchem.enable_cache(ttl_days=7)      # shorter freshness window
+pubchem.enable_cache(ttl_days=None)   # never expire
+```
+
+**Live cross-references, not just structures.**
+
+```python
+pubchem.chembl_id(2244)   # 'CHEMBL25', read live from PubChem's own xrefs, not a static table
+```
+
+PubChem's own `xrefs/RegistryID` endpoint already carries the ChEMBL ID for a compound when one exists (verified live against aspirin, CID 2244 resolves to CHEMBL25). PubChemPy can reach the same endpoint through its low-level `request()`/`get()` functions; this package wraps it as a named, documented function.
+
+**Similarity and substructure search, over PubChem's entire corpus, not a local index.**
+
+```python
+hits = pubchem.similar_compounds("CC(=O)OC1=CC=CC=C1C(=O)O", threshold=95, max_records=5)
+# [Compound(cid=2244, title='Aspirin', ...), Compound(cid=4133, title='Methyl Salicylate', ...), ...]
+
+pubchem.substructure_search("c1ccccc1", query_type="smiles")     # every compound containing a benzene ring
+pubchem.substructure_search("[#6]1[#6][#6][#6][#6][#6]1", query_type="smarts")  # the SMARTS equivalent
+```
+
+`scigantic-chembl`'s `similar_compounds()`/`substructure_search()` precompute fingerprints once and search them locally: fast, but bounded to the roughly 1.68M ChEMBL compounds that carry a comparable measurement. This runs the search on PubChem's own servers, live, over the full ~120M-compound corpus, verified sub-second for a typical query and with no local fingerprint database to build or hold in memory. PubChemPy exposes the same PUG REST capability as a raw `searchtype="similarity"`/`"substructure"` parameter to its generic `get_compounds()`; this package gives it a named function, and keeps `query_type="smiles"` and `"smarts"` as separate, explicit paths rather than guessing between them, since they're genuinely different endpoints with different matching semantics (verified live: the same ring given as SMILES versus SMARTS returns overlapping but not identical results).
+
+An expensive search can respond asynchronously, with PubChem handing back a job to poll rather than blocking the connection; handled transparently, using the same protocol PubChemPy implements. Every live query tried during development resolved synchronously, even a maximally broad single-carbon substructure search, so the polling loop itself is verified with a scripted mock response sequence rather than left checked only against documentation.
+
+## Thread safety
+
+Safe to call from multiple threads, a plausible real pattern: resolving a list of names via a `ThreadPoolExecutor`, say. The shared HTTP session is created once behind a lock rather than raced into existence by whichever thread gets there first. `enable_cache()`/`disable_cache()` are not synchronized against concurrent reads, the same way mutating `os.environ` isn't: call them once at the start of a script, not from multiple threads at once.
+
+## Live bridge into scigantic-chembl and scigantic-bindingdb
+
+```python
+pubchem.chembl_context(2244)
+# {'molregno': ..., 'chembl_id': 'CHEMBL25', 'pref_name': 'ASPIRIN', 'max_phase': 4}
+
+pubchem.bindingdb_measurements(2244)
+# DataFrame of every BindingDB measurement recorded against this CID
+```
+
+Both are on-demand DuckDB queries against the public [scigantic-chembl](https://github.com/Scigantic/scigantic-chembl) and [scigantic-bindingdb](https://github.com/Scigantic/scigantic-bindingdb) mirrors. `chembl_context` resolves the ChEMBL ID live (see above), then looks up its assay context; `bindingdb_measurements` filters BindingDB's own `pubchem_cid` column directly, since BindingDB already carries that mapping natively. Neither needs a precomputed bridge table, and neither goes stale the way a static one would. Needs `duckdb`:
+
+```console
+$ pip install "scigantic-pubchem[bridge]"
+```
+
+## Batch resolution
+
+```python
+compounds = pubchem.resolve_many([2244, 2519, 1983])  # aspirin, caffeine, acetaminophen
+```
+
+PUG REST accepts a comma-separated CID list in a single request (verified live); this chunks at 200 CIDs per call rather than sending one unbounded URL for a long list.
+
+## Command line
+
+```console
+$ scigantic-pubchem resolve aspirin
+$ scigantic-pubchem chembl-id 2244
+$ scigantic-pubchem xrefs 2244 --type RegistryID
+$ scigantic-pubchem similar "CC(=O)OC1=CC=CC=C1C(=O)O" --threshold 95
+$ scigantic-pubchem substructure c1ccccc1
+```
+
+## License
+
+MIT-0. See [LICENSE](LICENSE).

scigantic_pubchem-0.3.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "scigantic-pubchem"
+version = "0.3.0"
+description = "Query PubChem live via PUG REST, with rate-limit-aware retry, expiring cache, and live similarity/substructure/cross-reference search PubChemPy doesn't have."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT-0" }
+authors = [{ name = "Scigantic" }]
+keywords = ["pubchem", "cheminformatics", "pug-rest", "drug-discovery", "identifier-resolution"]
+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 = [
+  "requests>=2.28",
+]
+
+[project.optional-dependencies]
+# duckdb is only needed for chembl_context()/bindingdb_measurements(), the
+# live cross-references into scigantic-chembl/scigantic-bindingdb; every
+# other function in this package works without it.
+bridge = ["duckdb>=0.10", "pandas>=1.5"]
+dev = ["pytest>=7", "mypy>=1.10", "types-requests", "pandas-stubs"]
+
+[project.urls]
+Homepage = "https://scigantic.com"
+Repository = "https://github.com/Scigantic/scigantic-pubchem"
+Issues = "https://github.com/Scigantic/scigantic-pubchem/issues"
+
+[project.scripts]
+scigantic-pubchem = "scigantic_pubchem.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+scigantic_pubchem = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.mypy]
+strict = true

scigantic_pubchem-0.3.0/setup.cfg

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

scigantic_pubchem-0.3.0/src/scigantic_pubchem/__init__.py

@@ -0,0 +1,36 @@
+"""Query PubChem live via PUG REST, with caching and rate-limit-aware
+retry PubChemPy doesn't have, plus live cross-references into
+scigantic-chembl and scigantic-bindingdb. No mirror, no download."""
+
+from importlib.metadata import PackageNotFoundError, version as _version
+
+from .bridge import bindingdb_measurements, chembl_context
+from .cache import cache_dir, disable_cache, enable_cache, is_cache_enabled
+from .cache import clear as clear_cache
+from .models import Compound
+from .resolve import resolve, resolve_many
+from .similarity import similar_compounds, substructure_search
+from .xrefs import chembl_id, xrefs
+
+try:
+    __version__ = _version("scigantic-pubchem")
+except PackageNotFoundError:
+    # Running from a source checkout with no install (editable or not).
+    __version__ = "0.0.0"
+
+__all__ = [
+    "resolve",
+    "resolve_many",
+    "similar_compounds",
+    "substructure_search",
+    "xrefs",
+    "chembl_id",
+    "chembl_context",
+    "bindingdb_measurements",
+    "Compound",
+    "enable_cache",
+    "disable_cache",
+    "is_cache_enabled",
+    "cache_dir",
+    "clear_cache",
+]

scigantic_pubchem-0.3.0/src/scigantic_pubchem/__main__.py

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

scigantic_pubchem-0.3.0/src/scigantic_pubchem/_client.py

@@ -0,0 +1,177 @@
+"""HTTP client for PubChem's PUG REST API, with the two things PubChemPy
+does not do: respect PubChem's own live rate-limit signal, and retry
+transient failures instead of raising immediately.
+
+Verified 2026-08-27: every PUG REST response carries an X-Throttling-Control
+header reporting live status across three dimensions, e.g.
+    Request Count status: Green (0%), Request Time status: Green (0%), Service status: Green (27%)
+This is PubChem's own documented, real-time signal for how close a caller is
+to being throttled. PubChemPy 1.0.5's source (inspected directly, not
+assumed) never reads this header at all: on an HTTPError it raises
+immediately with no retry, and it has no rate-awareness beyond that. Every
+call here reads the header and backs off proactively when status is not
+"Green" on any dimension, rather than waiting to be rejected.
+"""
+
+from __future__ import annotations
+
+import re
+import threading
+import time
+import warnings
+from typing import Any
+
+import requests
+
+from . import cache
+
+_BASE = "https://pubchem.ncbi.nlm.nih.gov/rest/pug"
+_USER_AGENT = "scigantic-pubchem/0.1.0 (+https://scigantic.com; mailto:support@scigantic.com)"
+
+_THROTTLE_RE = re.compile(r"(\w[\w ]*?) status: (Green|Yellow|Red) \((\d+)%\)")
+
+# Backoff seconds by worst observed status across the three dimensions.
+_BACKOFF_SECONDS = {"Green": 0.0, "Yellow": 2.0, "Red": 10.0}
+
+_MAX_RETRIES = 5
+_RETRY_STATUS_CODES = {429, 500, 502, 503, 504}
+
+
+class PubChemError(Exception):
+    """Raised for a PUG REST error response (4xx/5xx after retries exhausted)."""
+
+
+class CompoundNotFoundError(PubChemError):
+    """Raised for a 404 (PUGREST.NotFound): a real, expected outcome for
+    an unmatched identifier, not a transient failure. Verified live
+    2026-08-27: PUG REST returns HTTP 404 with a JSON Fault body for a
+    miss, not an empty 200. resolve() catches this and returns None
+    rather than letting every caller handle the exception itself."""
+
+
+def _parse_throttle_header(value: str | None) -> str:
+    """Worst status ('Green'/'Yellow'/'Red') across all reported dimensions."""
+    if not value:
+        return "Green"
+    statuses = [m.group(2) for m in _THROTTLE_RE.finditer(value)]
+    if "Red" in statuses:
+        return "Red"
+    if "Yellow" in statuses:
+        return "Yellow"
+    return "Green"
+
+
+_session: requests.Session | None = None
+_session_lock = threading.Lock()
+
+
+def _get_session() -> requests.Session:
+    """Lazily create the shared Session under a lock, so two threads
+    resolving identifiers concurrently (a real, plausible pattern: a
+    ThreadPoolExecutor over a list of names) can't both see _session as
+    None and each construct one, leaking a connection pool. requests.Session
+    itself is documented thread-safe for issuing requests once constructed;
+    only the lazy-init race needed guarding."""
+    global _session
+    if _session is None:
+        with _session_lock:
+            if _session is None:  # re-check: another thread may have won the race
+                _session = requests.Session()
+                _session.headers["User-Agent"] = _USER_AGENT
+    return _session
+
+
+def request(
+    path: str,
+    params: dict[str, Any] | None = None,
+    method: str = "GET",
+    cacheable: bool = True,
+) -> dict[str, Any]:
+    """GET (or POST, for long identifier lists) a PUG REST path and return
+    the parsed JSON body.
+
+    path is appended to https://pubchem.ncbi.nlm.nih.gov/rest/pug, e.g.
+    "/compound/name/aspirin/property/MolecularWeight/JSON".
+
+    Backs off proactively based on X-Throttling-Control before it becomes a
+    429, and retries 429/5xx with exponential backoff (PubChemPy does
+    neither) rather than raising on the first transient failure.
+
+    Cached (see cache.py) keyed by (path, params) when caching is enabled
+    (the default) and cacheable=True (the default). cacheable=False is for
+    request_search()'s polling calls specifically: caching an intermediate
+    "still waiting" response under the search's own (path, params) key
+    would mean a later, unrelated call to the same search replays that
+    stale in-progress state instead of making a fresh request.
+    """
+    if method == "GET" and cacheable:
+        cached = cache.get(path, params)
+        if cached is not None:
+            return cached
+
+    session = _get_session()
+    url = f"{_BASE}{path}"
+    last_exc: Exception | None = None
+
+    for attempt in range(_MAX_RETRIES):
+        try:
+            if method == "POST":
+                response = session.post(url, data=params, timeout=30)
+            else:
+                response = session.get(url, params=params, timeout=30)
+        except requests.RequestException as exc:
+            last_exc = exc
+            time.sleep(2 ** attempt)
+            continue
+
+        status = _parse_throttle_header(response.headers.get("X-Throttling-Control"))
+        if response.status_code in _RETRY_STATUS_CODES and attempt < _MAX_RETRIES - 1:
+            wait = max(_BACKOFF_SECONDS[status], 2 ** attempt)
+            warnings.warn(
+                f"PUG REST returned {response.status_code} (throttle status {status}); "
+                f"retrying in {wait:.1f}s (attempt {attempt + 1}/{_MAX_RETRIES})",
+                stacklevel=2,
+            )
+            time.sleep(wait)
+            continue
+        if response.status_code == 404:
+            raise CompoundNotFoundError(f"no match for {url}")
+        if response.status_code >= 400:
+            raise PubChemError(f"PUG REST {response.status_code} for {url}: {response.text[:500]}")
+
+        if status != "Green":
+            # Proactive backoff even on success, so a run of calls doesn't
+            # walk itself into a 429 a few requests later.
+            time.sleep(_BACKOFF_SECONDS[status])
+        body: dict[str, Any] = response.json()
+        if method == "GET" and cacheable:
+            cache.put(path, params, body)
+        return body
+
+    raise PubChemError(f"PUG REST request failed after {_MAX_RETRIES} attempts: {last_exc}")
+
+
+def request_search(path: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
+    """Like request(), for PUG REST's search-type endpoints (fastsimilarity_2d,
+    fastsubstructure, fastformula, ...), which can respond either
+    immediately or asynchronously.
+
+    A slow search returns {"Waiting": {"ListKey": "..."}} instead of a
+    result, and this polls /compound/listkey/{key}/cids/JSON every 2s until
+    the real result is ready, the same protocol PubChemPy implements (its
+    source was read directly to confirm this, not assumed from docs).
+
+    Neither the initial call nor the polling calls are cached
+    (cacheable=False): a ListKey is single-use, and caching an
+    intermediate "still waiting" response under the search's own
+    (path, params) key would mean a later, unrelated call to the same
+    search replays that stale in-progress state instead of making a fresh
+    request. Callers that want to avoid repeat searches should cache the
+    resolved CIDs themselves.
+    """
+    body = request(path, params, method="GET", cacheable=False)
+    while "Waiting" in body and "ListKey" in body.get("Waiting", {}):
+        time.sleep(2)
+        listkey = body["Waiting"]["ListKey"]
+        body = request(f"/compound/listkey/{listkey}/cids/JSON", method="GET", cacheable=False)
+    return body

scigantic_pubchem-0.3.0/src/scigantic_pubchem/bridge.py

@@ -0,0 +1,83 @@
+"""Cross-reference a PubChem compound into scigantic-chembl and
+scigantic-bindingdb. Both are live, on-demand DuckDB httpfs queries against
+those public mirrors, not a precomputed table shipped with this package.
+
+Needs duckdb: `pip install "scigantic-pubchem[bridge]"`. Everything else in
+this package works without it.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from .xrefs import chembl_id as _chembl_id
+
+if TYPE_CHECKING:
+    import duckdb
+    import pandas as pd
+
+_CHEMBL_BUCKET = "scigantic-chembl"
+_BINDINGDB_BUCKET = "scigantic-bindingdb"
+
+
+def _connect() -> "duckdb.DuckDBPyConnection":
+    try:
+        import duckdb
+    except ImportError as exc:
+        raise ImportError(
+            "this needs duckdb. Install with: pip install 'scigantic-pubchem[bridge]'"
+        ) from exc
+    con = duckdb.connect()
+    con.execute("SET enable_progress_bar=false")
+    con.execute("INSTALL httpfs")
+    con.execute("LOAD httpfs")
+    con.execute("SET s3_region='us-east-1'")
+    con.execute("CREATE OR REPLACE SECRET anon (TYPE s3, PROVIDER config, KEY_ID '', SECRET '')")
+    return con
+
+
+def chembl_context(
+    identifier: str | int,
+    namespace: str = "cid",
+    chembl_release: str = "chembl_37",
+) -> dict[str, Any] | None:
+    """ChEMBL context for a PubChem compound: resolves the ChEMBL ID via a
+    live PubChem cross-reference (see xrefs.chembl_id), then looks up that
+    compound's pref_name, max_phase and molregno in scigantic-chembl.
+
+    Returns None if PubChem has no ChEMBL cross-reference for this
+    identifier, or if that ChEMBL ID isn't in this mirror's release.
+    """
+    cid = _chembl_id(identifier, namespace=namespace)
+    if cid is None:
+        return None
+    con = _connect()
+    mol = f"s3://{_CHEMBL_BUCKET}/{chembl_release}/parquet/molecule_dictionary.parquet"
+    row = con.execute(
+        f"SELECT molregno, chembl_id, pref_name, max_phase FROM read_parquet('{mol}') "
+        "WHERE chembl_id = ?",
+        [cid],
+    ).fetchone()
+    if row is None:
+        return {"chembl_id": cid, "molregno": None, "pref_name": None, "max_phase": None}
+    return {"molregno": row[0], "chembl_id": row[1], "pref_name": row[2], "max_phase": row[3]}
+
+
+def bindingdb_measurements(
+    cid: int,
+    bindingdb_release: str = "202608",
+) -> "pd.DataFrame":
+    """Binding measurements scigantic-bindingdb has for this PubChem CID.
+
+    BindingDB's own measurements table already carries a pubchem_cid column,
+    so this is a live filter against it, not a precomputed join, and it
+    reflects the mirror as it stands with no separate build step.
+    """
+    con = _connect()
+    path = f"s3://{_BINDINGDB_BUCKET}/{bindingdb_release}/parquet/measurements.parquet"
+    return con.execute(
+        f"SELECT reactant_set_id, ligand_smiles, ki_nm_value, ic50_nm_value, "
+        f"kd_nm_value, ec50_nm_value, curation_source "
+        f"FROM read_parquet('{path}') WHERE pubchem_cid = ?",
+        [cid],
+    ).df()