xenopict.declarative.types module

Type definitions for the declarative API.

This module contains the Pydantic models that define the schema for the declarative API. The schema is used to validate input and generate JSON schema documentation.

class xenopict.declarative.types.MarkSpec(**data)

Bases: BaseModel

Specification for marking parts of a molecule.

This class defines how to highlight or mark specific parts of a molecule using Xenopict’s marking capabilities. All indices are 0-based.

There are two ways to mark a molecule:

• Mark individual atoms with circles using atoms

• Mark a substructure (defined by atoms and optional bonds) using substructure_atoms and optionally substructure_bonds

JSON Examples:

Mark specific atoms with circles:

{
    "smiles": "CCO",
    "mark": {
        "atoms": [0, 1]  # Marks C and C atoms
    }
}

Mark a substructure (all connecting bonds included):

{
    "smiles": "CCO",
    "mark": {
        "substructure_atoms": [0, 1]  # Marks CC substructure
    }
}

Mark substructure with specific bonds:

{
    "smiles": "CCO",
    "mark": {
        "substructure_atoms": [0, 1],
        "substructure_bonds": [[0, 1]]  # Only mark the C-C bond
    }
}

Python Examples:

# Create a MarkSpec for marking atoms
mark = MarkSpec(atoms=[0, 1])
mark.atoms
# [0, 1]
mark.substructure_atoms is None
# True

# Create a MarkSpec for marking a substructure
mark = MarkSpec(substructure_atoms=[0, 1], substructure_bonds=[(0, 1)])
mark.substructure_atoms
# [0, 1]
mark.substructure_bonds
# [(0, 1)]
mark.atoms is None
# True

atoms: Optional[list[int]]

model_config: ClassVar[ConfigDict] = {}

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

substructure_atoms: Optional[list[int]]

substructure_bonds: Optional[list[tuple[int, int]]]

validate_mark_spec()

Validates that the marking specification is valid.

Rules: 1. If using substructure marking: - substructure_atoms must be provided if substructure_bonds is provided - substructure_bonds is optional 2. At least one marking method must be specified (atoms or substructure) 3. Cannot mix atom marking with substructure marking

Return type:

MarkSpec

class xenopict.declarative.types.MoleculeSpec(**data)

Bases: BaseModel

Specification for a single molecule.

Examples

>>> # Basic molecule with just SMILES
>>> spec = MoleculeSpec(smiles="CCO")
>>> spec.smiles
'CCO'
>>> spec.halo is None  # Defaults to None to use XenopictSpec value
True

>>> # Molecule with optional ID and explicitly disabled halo
>>> spec = MoleculeSpec(smiles="CCO", id="ethanol", halo=False)
>>> spec.id
'ethanol'
>>> spec.halo
False

>>> # Molecule with color override
>>> spec = MoleculeSpec(smiles="CCO", color="blue")
>>> spec.color
'blue'

color: Optional[str]

halo: Optional[bool]

id: Optional[str]

mark: Optional[MarkSpec]

model_config: ClassVar[ConfigDict] = {}

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

smiles: str

class xenopict.declarative.types.XenopictSpec(**data)

Bases: BaseModel

Root specification for xenopict visualizations.

This class represents the top-level schema for xenopict visualizations. It can contain either a single molecule or a list of molecules, and provides default styling options that apply to all molecules unless overridden.

Examples

>>> # Single molecule with default styling
>>> spec = XenopictSpec(
...     molecules=MoleculeSpec(smiles="CCO"),
...     color="red",  # All molecules will be red unless overridden
...     halo=True     # All molecules will have halos unless overridden
... )
>>> isinstance(spec.molecules, MoleculeSpec)
True
>>> spec.color
'red'
>>> spec.halo
True

>>> # Multiple molecules with some overriding defaults
>>> spec = XenopictSpec(
...     molecules=[
...         MoleculeSpec(smiles="CCO"),  # Uses default red color
...         MoleculeSpec(smiles="CCCO", color="blue")  # Overrides to blue
...     ],
...     color="red",
...     align=True
... )
>>> isinstance(spec.molecules, list)
True
>>> len(spec.molecules)
2

align: Optional[bool]

color: Optional[str]

halo: bool

model_config: ClassVar[ConfigDict] = {'json_schema_extra': {'description': 'Schema for defining molecule visualizations in xenopict', 'examples': [{'align': True, 'color': 'black', 'halo': True, 'molecules': {'smiles': 'CCO'}}, {'align': True, 'color': 'red', 'halo': True, 'molecules': [{'id': 'ethanol', 'smiles': 'CCO'}, {'color': 'blue', 'id': 'propanol', 'smiles': 'CCCO'}]}]}, 'title': 'Xenopict Specification'}

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

molecules: Union[MoleculeSpec, List[MoleculeSpec]]