orthonym.validation.pubchem_validator#

Note

Internal API. Names and behaviour may change between releases.

PubChem PUG-REST name-to-structure lookup with local JSON file cache.

Provides a cache-first approach: check local JSON cache before making any network request. Negative results (name not found) are also cached to avoid repeated 404 lookups. Transient errors (timeouts, network issues) are NOT cached so they can be retried.

Rate limiting: 0.25s sleep before each API call (4 req/sec, below PubChem’s 5 req/sec limit).

orthonym.validation.pubchem_validator.load_cache(cache_path=None)#

Load PubChem lookup cache from a JSON file.

Parameters:

cache_path (Path | None) – Path to cache file. Defaults to data/pubchem_cache.json.

Returns:

Dictionary mapping IUPAC names to lookup results (or None for cached negative results). Returns empty dict if file is missing or corrupt.

Return type:

dict

orthonym.validation.pubchem_validator.save_cache(cache, cache_path=None)#

Save PubChem lookup cache to a JSON file.

Parameters:

  • cache (dict) – Dictionary mapping names to results.

  • cache_path (Path | None) – Path to cache file. Defaults to data/pubchem_cache.json.

orthonym.validation.pubchem_validator.lookup_name_pubchem(name, cache, skip_api=False)#

Look up an IUPAC name via PubChem PUG-REST API with cache.

Cache-first: if the name is in cache, the cached value is returned immediately (even if it is None, indicating a previous negative result). Only makes an API call on cache miss.

Parameters:

  • name (str) – IUPAC name to look up.

  • cache (dict) – Mutable cache dictionary (updated in-place on API call).

  • skip_api (bool) – If True, return None on cache miss without calling API. Useful for offline/test mode.

Returns:

Dict with ‘smiles’ and ‘inchi’ keys on success, or None if the name cannot be resolved. Cached negative results also return None.

Return type:

Dict[str, str] | None