Python API#

The public names of the orthonym package. Everything else is internal; the counters of Orthonym (get_validation_stats, get_dispatch_stats and the others) are documented there, under orthonym.namer.

Name	What it is for
`name_compound`	One molecule, one name
`Orthonym`	All options, one engine for many molecules
`Orthonym.name_tiered`	The provenance row: the name, its tier, and every field of how it was checked
`name_with_tree`	The name and the tree of its parts
`NamingResult`, `NameTreeNode`	What `name_with_tree` returns
`classify_limit`, `OrthonymLimitError`	Why a structure is out of scope
`is_failure_name`	Tell a label from a name

Every example below is the engine’s own output.

Input: a SMILES string or an RDKit molecule#

Every function and method here that names a structure takes a SMILES string or an RDKit Chem.Mol: name_compound, name_with_tree, classify_limit, and the Orthonym methods name, name_tiered, name_with_tree and name_with_confidence. The parameter is called smiles for both.

>>> from rdkit import Chem
>>> from orthonym import name_compound
>>> name_compound(Chem.MolFromSmiles("C[C@H](O)CC"))
'(2S)-butan-2-ol'

A Mol is named through RDKit’s SMILES of it. Orthonym writes Chem.MolToSmiles(mol) from a copy of your Mol (your Mol is not changed), checks that this SMILES holds the same molecule and the same stereo as the Mol, and then names the SMILES exactly as it names a string you pass. So a Mol gets the result that Chem.MolToSmiles(mol) gets: the same name, the same provenance row, the same label when there is no name.

The check reads the Mol as RDKit reads it, and the call raises ValueError when RDKit’s SMILES of the Mol holds something else:

RDKit must read the SMILES back.
RDKit’s standard InChI of the Mol must be the InChI of the SMILES. The Mol’s InChI is made from its stereo tags, without its coordinates, and before anything in the Mol is cleaned up.
Atom for atom, the SMILES must have the Mol’s atoms, bonds, hydrogen counts and charges, and every stereocentre and double bond whose configuration the Mol’s tags set must have that configuration in the SMILES, and the SMILES must set no other. This also covers stereo that InChI does not see, such as the C=N of an amidine.
A lone-pair stereocentre (a sulfoxide, a phosphine, an aziridine nitrogen) must read the same in RDKit’s reading of the SMILES as in the standard reading of SMILES, which is how Orthonym names a SMILES string. RDKit reads such a centre otherwise when it is written first or carries a ring-closure digit at some positions.
A Mol with an AND (racemic) or OR (unknown enantiomer) stereo group, from CXSMILES or a V3000 record, is declined, because a SMILES holds no stereo group and the molecule would be named as one enantiomer. A Mol with an atropisomer tag (STEREOATROPCW, STEREOATROPCCW) is declined, because no SMILES holds the configuration of an axis, and so is a Mol with a CHI_OTHER chiral tag. Square-planar, trigonal-bipyramidal and octahedral tags pass: a SMILES holds them, and no name states them, so such a Mol (cisplatin, for one) gets the result of its SMILES.

The message of the ValueError says which part failed. Mols that RDKit’s readers make (MolFromSmiles, MolFromMolBlock, SDMolSupplier, MolFromInchi, with or without hydrogen atoms) almost always pass. Mols built or edited in code fail more often, because RDKit’s own InChI and SMILES writers can read their tags in different ways. Two examples: a double bond whose configuration is only in the / and \ directions of Chem.MolFromSmiles(smiles, sanitize=False) (RDKit’s InChI of that Mol has no configuration, its SMILES has one), and a double bond left open between two double bonds whose configuration is set (any SMILES of the molecule can give the open bond a configuration). Fix the tags, or name a SMILES you have checked yourself.

Stereo comes from the Mol’s stereo tags, not from its coordinates. RDKit sets the tags when it reads a mol block or an SDF record; for a Mol you build from 3D coordinates, call Chem.AssignStereochemistryFrom3D(mol) first. A Mol made by Chem.MolFromSmiles holds RDKit’s reading of the string. At a lone-pair stereocentre written first, as in [S@@](C)(=O)c1ccccc1, RDKit reads the other configuration than the standard reading, so that Mol and that string get the names of two enantiomers.

To name the molecules of an SDF file:

from rdkit import Chem
from orthonym import name_compound

for mol in Chem.SDMolSupplier("compounds.sdf"):
    if mol is None:  # RDKit could not read this record
        continue
    print(mol.GetProp("_Name"), name_compound(mol))

Because the SMILES is what gets named, the fields of a result that repeat the input (the smiles of an OrthonymLimitError, and of the limit record of name_with_confidence) hold Chem.MolToSmiles(mol), and atom indices in a result (atom_to_locant_hint, atom_to_locant) refer to the atoms of Chem.MolFromSmiles(Chem.MolToSmiles(mol)), not to your Mol’s own atom order. For a Mol without hydrogen atoms, Chem.MolToSmiles(mol) leaves the property _smilesAtomOutputOrder on mol, which lists your Mol’s atom for each of those indices.

None, a Mol that RDKit cannot sanitize, and a Mol the check declines raise ValueError, as a SMILES that RDKit cannot read does; classify_limit returns None for them. Any other type raises TypeError. An empty Mol is named as the empty string is. These rules apply to the calls your code makes. Orthonym’s own calls to these functions, made while it names a molecule, keep their earlier handling.

Naming#

orthonym.name_compound(smiles, style='pin', include_confidence=False, *, enable_triviality_controller=False, enable_group_splitting=False, trivial_fallback=False, general_fallback=None, general_fallback_unverified=None, allow_aromatic_general=None, full_coverage=None, raise_on_limit=False, binding_proof='off', on_failure='empty')#

Name one molecule.

Reads a structure, written as SMILES or given as an RDKit molecule, and returns its IUPAC name as a string. At the default settings a name is returned only when the strict path for the Preferred IUPAC Name built it and verified it, or when it is one of the default tier’s exceptions (the exact-match list names, the few name formats OPSIN cannot read, a PIN whose stereodescriptors OPSIN cannot read). Where no name passes, the result is the empty string, and one warning on the logger orthonym says why (on_failure below). The wider tiers (general_fallback and the options below) also return names that are not the preferred name. Use Orthonym.name_tiered() to learn which tier a name earned.

Parameters:

smiles (str or rdkit.Chem.Mol) – The structure, as a SMILES string or an RDKit Chem.Mol. A Mol is named through RDKit’s SMILES of it, after a check that this SMILES holds the same molecule and stereo (see:ref:python-input).
style ({"pin", "general", "cas"}, default "pin") – Naming style. "pin" aims at the Preferred IUPAC Name. "general" allows general IUPAC forms where the recommendations offer one (for example functional class names such as ‘dimethyl sulfoxide’, hydrate names such as ‘oxalic acid dihydrate’ and the axial descriptors Ra and Sa). The default tier’s PIN-only rule applies to "pin" only, so with "general" or "cas" a name that "pin" declines with NO_VERIFIED_PIN is returned. "cas" is accepted and at present gives the names of "general", except that hydrate names and axial descriptors keep their "pin" form.
include_confidence (bool, default False) – Return a dictionary instead of a string. Its "name" key holds the name, "handler" the part of the engine that built it, and "confidence" and "factors" a coverage score and its parts. "confidence" is None when no measurement was taken.
enable_triviality_controller (bool, default False) – Where the recommendations prefer a retained parent name to the systematic one, use the retained name. Each change is checked by an OPSIN round trip. The environment setting ORTHONYM_ENABLE_TRIVIALITY_CONTROLLER=1 turns this on as well.
enable_group_splitting (bool, default False) – When an ester or thioester group inside a larger molecule has no prefix form, write it as its parts (oxo plus ethoxy, for example) instead of giving up. Each split name must pass an OPSIN round trip. The environment setting ORTHONYM_ENABLE_GROUP_SPLITTING=1 turns this on as well.
trivial_fallback (bool, default False) – When no preferred name can be built, also allow a retained trivial name that is not a preferred name. A molecule whose preferred name can be built keeps it. Turns on enable_triviality_controller.
general_fallback (bool or None, default None) – When the strict path declines, try the general naming engine (the valid tier of the command line). Its names must pass an atom-coverage certificate and a full-InChIKey round trip. None means “off” for a call you make; the engine uses it to pass the setting on when it names parts of a molecule.
general_fallback_unverified (bool or None, default None) – Also switch on the best-effort tier: the last-resort producers, von Baeyer and spiro names for ring systems of up to 100 skeletal atoms and 15 rings (the other tiers build these names for ring systems of up to 40 skeletal atoms and 8 rings), and adducts with a one-atom ion. Their names still have to pass the full-InChIKey round trip, with one exception: a molecule that has no other name gets the name the default tier gives it when OPSIN cannot read the stereodescriptors of that name, with the label the default tier gives it (pin_unverified). None as for general_fallback.
allow_aromatic_general (bool or None, default None) – Let the general engine also name aromatic and heterocyclic ring systems (the complete tier). None as for general_fallback.
full_coverage (bool or None, default None) – Also try the coordination-name builder for metal tetrapyrrole and corrin complexes (the full-coverage tier). It builds a name or declines. None as for general_fallback.
raise_on_limit (bool, default False) – The same as on_failure="raise", and it wins over on_failure.
binding_proof ({"off", "audit", "enforce"}, default "off") – An extra check that every part of a general-engine name still maps onto the atoms it names in the final string. "audit" records the result and never changes the name; "enforce" also declines when the check fails.
on_failure ({"empty", "label", "raise"}, default "empty") – What the call gives for a structure that gets no name. "empty": the empty string, with one warning on the logger orthonym that holds the SMILES, the limit code and the label. "label": the label, such as 'unknown organic compound' (the result before this option). "raise": OrthonymLimitError. With include_confidence the "name" of the dictionary follows it. The limit codes are stable, the texts of labels are not. The choice is the caller’s; the engine’s own calls get labels.

Returns:

str or dict – The name, or what on_failure says for a structure with no name. A dictionary when include_confidence is true.

Raises:

ValueError – If RDKit cannot read the SMILES, smiles is None, a Mol fails the check (RDKit cannot sanitize it, or its SMILES does not hold the same molecule and stereo), or binding_proof or on_failure is not one of its values.
TypeError – If smiles is neither a string nor a Chem.Mol.
OrthonymLimitError – If on_failure is "raise" (or raise_on_limit is true) and the structure is out of scope.

Examples

>>> from orthonym import name_compound
>>> name_compound("CC(C)Cc1ccc(cc1)[C@@H](C)C(=O)O")
'(2R)-2-[4-(2-methylpropyl)phenyl]propanoic acid'
>>> name_compound("O=[U](=O)=O")
''
>>> name_compound("O=[U](=O)=O", on_failure="label")
'inorganic compound (not supported)'

class orthonym.Orthonym(style='pin', *, _disable_grammar_validation=False, _disable_opsin_validity_gate=False, enable_triviality_controller=False, enable_group_splitting=False, trivial_fallback=False, general_fallback=False, general_fallback_unverified=False, allow_aromatic_general=False, full_coverage=False, _principal_group_override=None, _forced_parent_rank=0, _seed_excluded_dispatch_classes=frozenset({}), binding_proof='off')#

Bases: object

The naming engine, with every option.

Build one instance and name as many molecules with it as you like; the options apply to every call.:func:name_compound builds a fresh instance for each call.

Creating an instance checks that the OPSIN and centres jars are present and stops with an error if they are not (run orthonym --fetch-jars). Set ORTHONYM_ALLOW_REDUCED=1 to name without them, with no OPSIN check.

Parameters:

style ({"pin", "general", "cas"}, default "pin") – Naming style, as for:func:name_compound.
enable_triviality_controller (bool) – As for:func:name_compound. All default to False.
enable_group_splitting (bool) – As for:func:name_compound. All default to False.
trivial_fallback (bool) – As for:func:name_compound. All default to False.
general_fallback (bool) – The switches behind the command line’s --emit-tier. All default to False, which is the default tier. valid sets general_fallback; complete adds allow_aromatic_general; best-effort adds general_fallback_unverified; full-coverage adds full_coverage.
general_fallback_unverified (bool) – The switches behind the command line’s --emit-tier. All default to False, which is the default tier. valid sets general_fallback; complete adds allow_aromatic_general; best-effort adds general_fallback_unverified; full-coverage adds full_coverage.
allow_aromatic_general (bool) – The switches behind the command line’s --emit-tier. All default to False, which is the default tier. valid sets general_fallback; complete adds allow_aromatic_general; best-effort adds general_fallback_unverified; full-coverage adds full_coverage.
full_coverage (bool) – The switches behind the command line’s --emit-tier. All default to False, which is the default tier. valid sets general_fallback; complete adds allow_aromatic_general; best-effort adds general_fallback_unverified; full-coverage adds full_coverage.
binding_proof ({"off", "audit", "enforce"}, default "off") – As for:func:name_compound.

Notes

The parameters whose names start with an underscore are for the engine’s own use and tests; leave them at their defaults.

Examples

>>> from orthonym import Orthonym
>>> namer = Orthonym
>>> namer.name("CCO")
'ethanol'
>>> namer.name("CC(=O)O")
'acetic acid'

name_with_tree(smiles)#

Name one molecule and return the parts of the name.

Parameters:

smiles (str or rdkit.Chem.Mol) – The structure, as a SMILES string or an RDKit Chem.Mol. A Mol is named through RDKit’s SMILES of it, after a check that this SMILES holds the same molecule and stereo (see:ref:python-input).

Returns:

NamingResult – name is what:meth:name returns with on_failure="label"; tree is the NameTreeNode of its parts (a single coarse node when the part of the engine that built the name records no finer structure); atom_to_locant_hint maps atom indices to locants where one was recorded, else None.

Raises:

ValueError – If RDKit cannot read the SMILES, smiles is None, or a Mol fails the check (RDKit cannot sanitize it, or its SMILES does not hold the same molecule and stereo).
TypeError – If smiles is neither a string nor a Chem.Mol.

Examples

>>> from orthonym import Orthonym
>>> Orthonym.name_with_tree("OC1CCCCC1").name
'cyclohexanol'

name(smiles, *, raise_on_limit=False, on_failure='empty')#

Name one molecule with this instance’s options.

Parameters:

smiles (str or rdkit.Chem.Mol) – The structure, as a SMILES string or an RDKit Chem.Mol. A Mol is named through RDKit’s SMILES of it, after a check that this SMILES holds the same molecule and stereo (see:ref:python-input).
raise_on_limit (bool, default False) – The same as on_failure="raise", and it wins over on_failure.
on_failure ({"empty", "label", "raise"}, default "empty") – What a structure with no name gets: "" and a warning on the logger orthonym, the label, or:class:OrthonymLimitError. See:func:name_compound.

Returns:

str – The name, or what on_failure gives for a structure with no name.

Raises:

ValueError – If RDKit cannot read the SMILES, smiles is None, a Mol fails the check (RDKit cannot sanitize it, or its SMILES does not hold the same molecule and stereo), or on_failure is not one of its values.
TypeError – If smiles is neither a string nor a Chem.Mol.
OrthonymLimitError – If on_failure is "raise" and the structure is out of scope. For a ring system the engine cannot name yet the code is UNSUPPORTED_RING_SYSTEM; when that happens inside a part of the molecule, the code can be the more general UNNAMEABLE.

Return type:

str

Examples

>>> from orthonym import Orthonym
>>> Orthonym.name("C/C=C/C")
'(2E)-but-2-ene'

name_with_confidence(smiles)#

Name one molecule and return a coverage score with it.

Parameters:

Returns:

dict – name (the name), confidence (a score from 0 to 1, or None when no measurement was taken), verification, factors (the parts of the score), handler (the part of the engine that built the name), and further keys for the atom-to-locant map and the reason for a decline (limit, abstention, and spelling_failures: the spelling rules of the PIN that the declined name breaks).

Raises:

ValueError – If RDKit cannot read the SMILES, smiles is None, or a Mol fails the check (RDKit cannot sanitize it, or its SMILES does not hold the same molecule and stereo).
TypeError – If smiles is neither a string nor a Chem.Mol.

Return type:

dict

Examples

>>> from orthonym import Orthonym
>>> Orthonym.name_with_confidence("CCO")["name"]
'ethanol'

The provenance fields#

Orthonym.name_tiered(smiles)#

Name one molecule and say how the name was made and checked.

This is the row the command line prints with --provenance.

Parameters:

Returns:

dict –

name

The name, or a label when there is none.

tier

How the name was built: pin_verified (the strict path for the Preferred IUPAC Name built it, certified it and OPSIN read it back, or read back a twin spelling of it; or a name from an exact-match list, matched to the input’s exact structure, with verified identity), pin_unverified (a name in preferred-name form that OPSIN read back, but whose preferred status is not certified: a producer outside the strict path built it or a part of it), systematic_verified (a checked systematic name that is not the preferred name, for example from the general engine, a table of retained names, or the strict path when the name contains a part the engine records as not the preferred form), best_effort (the last-resort producers, or a name whose own string no round trip confirmed) or abstain (no name).

is_pin

True only for a certified Preferred IUPAC Name.

source

Which part of the engine produced the name, for example pin_path, general_engine, trivial_retained or abstain.

opsin

What the OPSIN check found: verified, verified_constitution_only, verified_twin (OPSIN has no grammar for the name and read a twin spelling of it back to your structure), verified_acid_split (OPSIN has no grammar for a poly-anhydride name and read each of its acids; the structure built from them is your structure), unverified or n/a.

gates_passed

The checks this name passed, for example self_consistency (OPSIN read the name back to your structure) and atom_coverage.

gate_outcome

What the final OPSIN check did for this name, for example self_consistency_verified, suppressed or not_run, or carveout:<class> for a class OPSIN cannot read, or twin_verified:<rules> for a name read back through its twin, or acid_split_verified:<rule> for a poly-anhydride read through its acids.

formula

The molecular formula, given when there is no name.

limit_code

The reason code when there is no name, for example UNSUPPORTED_ELEMENT, or NO_VERIFIED_PIN when the default tier built a name that is not a verified PIN (a wider tier returns it).

stereo_unexpressed

True when the input configures a stereo element (a stereocentre or a double bond) that the name does not state: OPSIN’s read-back of the name configures fewer elements than the input does. A name of any producer; it changes no name, tier or label. A name OPSIN cannot read has no read-back and is not flagged.

suffix_free_prefix_name

True when the name states the principal characteristic group as a prefix with no suffix.

prefix_order_fallback

True when the name cites its substituent prefixes out of the alphanumerical order because the round trip of the ordered spelling fails at the stereo layer only (a stereocentre read differently by the SMILES hand-off, not by the name); such a name is best_effort, never a PIN.

verified

opsin (OPSIN read the whole name back to the same molecule), opsin_constitution (read back with the same constitution; the stereodescriptors were not confirmed by OPSIN), identity (a name from an exact-match list: a metal-complex name found by the input’s exact InChIKey, or a natural-product parent name found by its exact structure; OPSIN cannot read these names), opsin_split (OPSIN read the whole name back to the drawing of the input without its dative bonds, which has the reference key; the drawing as given has no standard InChIKey), opsin_twin (a PIN spelling OPSIN has no grammar for; OPSIN read a twin spelling of the same structure back to the same molecule), opsin_acids (a di- or poly-anhydride name OPSIN has no grammar for; OPSIN read each acid the name cites and the structure built from those acids is the same molecule) or unverified (no read-back recorded).

spelling_failures

The spelling rules of the PIN a name in PIN form breaks, as {"rule": "", "detail":...} entries (validation.pin_spelling; a round trip cannot see them), and the rule of a recorded non-PIN part that lowered the name (metrics.provenance.record_non_pin_label with a rule, e.g.

for a ring assembly of three or more components with

primed locants). Such a name is systematic_verified at most; the default tier declines it with NO_VERIFIED_PIN and keeps the entries as the reason. Empty otherwise.

producer

The code that built the name that ships (inner:tier_a_ring, engine:general,…), or None when no name ships. A diagnostic id: it follows the code and can change in any release.

Raises:

ValueError – If RDKit cannot read the SMILES, smiles is None, or a Mol fails the check (RDKit cannot sanitize it, or its SMILES does not hold the same molecule and stereo).
TypeError – If smiles is neither a string nor a Chem.Mol.

Return type:

dict

Examples

>>> from orthonym import Orthonym
>>> row = Orthonym.name_tiered("Cn1cnc2c1c(=O)n(C)c(=O)n2C")
>>> row["name"], row["tier"], row["verified"]
('1,3,7-trimethyl-3,7-dihydro-1H-purine-2,6-dione', 'pin_verified', 'opsin')

The parts of a name#

orthonym.name_with_tree(smiles, style='pin')#

Name one molecule and return the parts of the name.

A shortcut for Orthonym(style=style).name_with_tree(smiles).

Parameters:

smiles (str or rdkit.Chem.Mol) – The structure, as a SMILES string or an RDKit Chem.Mol. A Mol is named through RDKit’s SMILES of it, after a check that this SMILES holds the same molecule and stereo (see:ref:python-input).
style ({"pin", "general", "cas"}, default "pin") – Naming style, as for:func:name_compound.

Returns:

NamingResult – The name (what:func:name_compound returns with on_failure="label"), the tree of its parts as a:class:NameTreeNode, and a map from atom index to locant where one was recorded.

Raises:

ValueError – If RDKit cannot read the SMILES, smiles is None, or a Mol fails the check (RDKit cannot sanitize it, or its SMILES does not hold the same molecule and stereo).
TypeError – If smiles is neither a string nor a Chem.Mol.

Examples

>>> from orthonym import name_with_tree
>>> result = name_with_tree("OC1CCCCC1")
>>> result.name
'cyclohexanol'
>>> result.tree.parent_stem
'cyclohex'
>>> result.tree.suffix
'ol'

class orthonym.NamingResult(name, tree=None, atom_to_locant_hint=None)#

Bases: NamedTuple

A name together with the tree of its parts.

Returned by:func:orthonym.name_with_tree and orthonym.Orthonym.name_with_tree(). It is a named tuple of three fields.

Variables:

name (str) – The name: what:func:orthonym.name_compound returns with on_failure="label", so the label for a structure with no name.
tree (NameTreeNode or None) – The parts of the name.
atom_to_locant_hint (dict of int to int or None) – Atom index to locant, where the part of the engine that built the name recorded it.

Examples

>>> from orthonym import name_with_tree
>>> name, tree, hint = name_with_tree("OC1CCCCC1")
>>> name
'cyclohexanol'

class orthonym.NameTreeNode(parent_stem, locants=(), suffix=None, prefixes=(), stereo=None, indicated_h=(), unsaturation_locants=((), ()), class_id='', multiplicative_prefix=None, parenthesization_hint=False, iupac_section_cite=None, fragment_legacy=None)#

Bases: object

One part of a name, and the parts inside it.

A name is written in the order stereodescriptors, prefixes (in alphanumerical order), parent, indicated hydrogen, unsaturation and suffix (IUPAC. A node holds those pieces for one parent; each prefix is a node of its own, so a substituent with its own substituents is a subtree. The node cannot be changed after it is made.

Variables:

parent_stem (str) – The parent, for example 'cyclohex'.
locants (tuple of int) – Locants of the suffix.
suffix (str or None) – The suffix, for example 'ol'.
prefixes (tuple of NameTreeNode) – The substituent prefixes, each a node.
stereo (str or None) – The stereodescriptor part, for example '(2R)'.
indicated_h (tuple of int) – Locants of indicated hydrogen.
unsaturation_locants (tuple of (tuple of int, tuple of int)) – Locants of double and of triple bonds.
class_id (str) – The compound class that built the node.
multiplicative_prefix (str or None) – A multiplying prefix such as 'di'.
parenthesization_hint (bool) – True when the prefix must be written in enclosing marks.
iupac_section_cite (str or None) – The section of the recommendations the node follows, for example ''.
fragment_legacy (object or None) – An older representation of the same part, kept for the engine’s own use.

Examples

>>> from orthonym import name_with_tree
>>> tree = name_with_tree("OC1CCCCC1").tree
>>> tree.parent_stem, tree.suffix
('cyclohex', 'ol')

Declines#

orthonym.classify_limit(smiles)#

Say whether a structure is out of scope, without raising.

A wildcard atom (*) is refused at once. Any other structure is named with the default settings; if that gives a label instead of a name, the reason is returned.

Parameters:: smiles (str or rdkit.Chem.Mol) – The structure, as a SMILES string or an RDKit Chem.Mol. A Mol is named through RDKit’s SMILES of it, after a check that this SMILES holds the same molecule and stereo (see:ref:python-input).
Returns:: OrthonymLimitError or None – The reason, with its code (for example UNSUPPORTED_ELEMENT, WILDCARD_ATOMS, or NO_VERIFIED_PIN when the default settings built a name that is not a verified preferred IUPAC name) and message. None when the structure gets a name, and also when RDKit cannot read the SMILES at all, smiles is None, or a Mol fails the check described under name_compound() (that is a reading error, not a scope limit).
Raises:: TypeError – If smiles is neither a string, a Chem.Mol nor None.
Return type:: OrthonymLimitError | None

Examples

>>> from orthonym import classify_limit
>>> classify_limit("O=[U](=O)=O").code
'UNSUPPORTED_ELEMENT'
>>> classify_limit("CC*").code
'WILDCARD_ATOMS'
>>> classify_limit("CCO") is None
True

exception orthonym.OrthonymLimitError(code, message, design_note_ref=None, smiles=None)#

Bases: Exception

The reason a structure is out of scope.

Returned by:func:orthonym.classify_limit, and raised when you ask for it with on_failure="raise" (or raise_on_limit=True). It tells “cannot handle this structure” apart from a name.

Variables:

code (str) – The reason code: WILDCARD_ATOMS, UNSUPPORTED_ELEMENT, ISOLATED_ATOM, STRUCTURE_TOO_LARGE, UNSUPPORTED_RING_SYSTEM, UNNAMEABLE or NO_VERIFIED_PIN (the default tier built a name but not a verified preferred IUPAC name; a wider tier returns it).
message (str) – The label that on_failure="label" returns in place of a name.
design_note_ref (str or None) – A reference to the design note the code follows.
smiles (str or None) – The input, when known.

Examples

>>> from orthonym import Orthonym, OrthonymLimitError
>>> try:
... Orthonym.name("O=[U](=O)=O", on_failure="raise")
... except OrthonymLimitError as err:
... print(err.code, "|", err.message)
UNSUPPORTED_ELEMENT | inorganic compound (not supported)

orthonym.errors.is_failure_name(name)#

Tell a label, or no name, from a name.

When the engine cannot name a structure, the plain call returns the empty string, and with on_failure="label" a label in place of a name, such as 'inorganic compound (not supported)' or 'unknown organic compound'. This function is true for those labels and for an empty result, and false for a real name. The default result is ""; the limit codes (the keys of LIMIT_CATALOG) are the stable contract, and the texts of labels are not, so test for a code, not for a label.

Parameters:: name (str or None) – What a naming call returned.
Returns:: bool – True when name is empty or a label (it contains unknown or (not supported)).
Return type:: bool

Examples

>>> from orthonym import name_compound
>>> from orthonym.errors import is_failure_name
>>> is_failure_name(name_compound("O=[U](=O)=O"))
True
>>> is_failure_name(name_compound("O=[U](=O)=O", on_failure="label"))
True
>>> is_failure_name(name_compound("CCO"))
False

Version#

orthonym.__version__ is the installed version, a string of the form 'X.Y.Z'.