vibe-sketcherDocumentation

vibesketcher.document.queries

Read-only, snapshot-scoped queries over drawn atoms (#167).

Matching delegates to RDKit’s VF2 implementation: Cordella et al., “A (sub)graph isomorphism algorithm for matching large graphs”, IEEE TPAMI 26, 1367-1372 (2004), doi:10.1109/TPAMI.2004.75. Native parsing and matching run in a separate, deadline-limited process; no query is executable code.

Functions

query_atoms(document, query, *[, species, ...])

Match actual drawn atoms without editing the document or creating H atoms.

Classes

AtomFilter(*[, elements, charge, aromatic, ...])

Conjunction of simple atom predicates, with OR within elements.

AtomQuery(*[, smarts, filter, species, ...])

Exactly one SMARTS pattern or structured filter.

Exceptions

QueryBusy

Both matching workers are occupied; retry later.

QueryCancelled

The caller cancelled a read; no partial match set is returned.

QueryRefused

A query cannot be completed safely or expressed by this service.

exception vibesketcher.document.queries.QueryRefused[source]

Bases: ValueError

A query cannot be completed safely or expressed by this service.

exception vibesketcher.document.queries.QueryCancelled[source]

Bases: QueryRefused

The caller cancelled a read; no partial match set is returned.

exception vibesketcher.document.queries.QueryBusy[source]

Bases: QueryRefused

Both matching workers are occupied; retry later.

class vibesketcher.document.queries.AtomFilter(*, elements=None, charge=None, aromatic=None, in_ring=None)[source]

Bases: BaseModel

Conjunction of simple atom predicates, with OR within elements.

Parameters:
model_config = {'extra': 'forbid', 'strict': True}

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

elements: list[str] | None
charge: StrictInt | None
aromatic: StrictBool | None
in_ring: StrictBool | None
classmethod elements_known(value)[source]
Parameters:

value (list[str] | None)

Return type:

list[str] | None

nonempty()[source]
Return type:

AtomFilter

class vibesketcher.document.queries.AtomQuery(*, smarts=None, filter=None, species=None, use_chirality=False)[source]

Bases: BaseModel

Exactly one SMARTS pattern or structured filter.

Parameters:
model_config = {'extra': 'forbid', 'strict': True}

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

smarts: str | None
filter: AtomFilter | None
species: list[str] | None
use_chirality: StrictBool
one_query()[source]
Return type:

AtomQuery

vibesketcher.document.queries.query_atoms(document, query, *, species=None, use_chirality=False, timeout=10.0, cancelled=None)[source]

Match actual drawn atoms without editing the document or creating H atoms.

Returned {node, atom} references require the exact source snapshot. species groups can contain several IDs if the stored model has more than one species with the same graph. Distinct drawn occurrences remain distinct. Cancellation/deadline/overflow refuse the whole result.

Parameters:
Return type:

dict[str, Any]