Data Models and Exceptions (models)

This module is the core of the library’s data contract, responsible for enforcing data integrity and providing clear error signals. It leverages Pydantic to transform unstructured API responses into robust, type-safe Python objects.

By defining clear data models, this module ensures that all data consumed by the application layer is valid and predictable.

Data Models

class ChemInformant.models.Compound(*, cid: int, input_identifier: str | int, MolecularFormula: str | None = None, MolecularWeight: float | None = None, CanonicalSMILES: str | None = None, IsomericSMILES: str | None = None, IUPACName: str | None = None, XLogP: float | None = None, cas: str | None = None, synonyms: list[str] = <factory>)

Bases: BaseModel

A Pydantic model representing a curated view of a PubChem compound.

This container holds the most commonly used fields for a single compound with runtime type validation. It is intentionally a subset of the full PubChem property catalog; for the complete ~40 properties use ChemInformant.get_properties() with all_properties=True which returns a DataFrame.

cid

The unique PubChem Compound ID.

Type:

int

input_identifier

The original identifier used for the query.

Type:

str | int

molecular_formula

The molecular formula (e.g., “C8H10N4O2”).

Type:

str | None

molecular_weight

The molecular weight (g/mol).

Type:

float | None

canonical_smiles

The canonical SMILES string.

Type:

str | None

isomeric_smiles

The isomeric SMILES string.

Type:

str | None

iupac_name

The IUPAC name.

Type:

str | None

xlogp

The calculated XLogP value.

Type:

float | None

cas

The primary CAS registry number.

Type:

str | None

synonyms

A list of common names and synonyms.

Type:

list[str]

pubchem_url

A computed property with the direct link to the compound’s PubChem page.

cid: int

input_identifier: str | int

molecular_formula: str | None

molecular_weight: float | None

canonical_smiles: str | None

isomeric_smiles: str | None

iupac_name: str | None

xlogp: float | None

cas: str | None

synonyms: list[str]

property pubchem_url: str

Direct URL to the compound’s page on the PubChem website.

classmethod to_float(v: Any) → float | None

Validator to safely convert string values to float.

model_config = {'extra': 'ignore', 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Custom Exceptions

exception ChemInformant.models.NotFoundError(identifier: str | int)

Bases: Exception

Raised when an identifier cannot be found in PubChem.

exception ChemInformant.models.AmbiguousIdentifierError(identifier: str, cids: list[int])

Bases: Exception

Raised when a name or SMILES string maps to multiple PubChem CIDs.