`orthonym.data.hw_heteroatoms`#

Note

Internal API. Names and behaviour may change between releases.

Hantzsch-Widman heteroatom prefix data for systematic heterocycle naming.

The Hantzsch-Widman (HW) system uses ‘a’ term prefixes to denote heteroatoms in systematic ring nomenclature. These prefixes replace the standard carbon skeleton terminology when heteroatoms are present in the ring.

Prefix naming convention: Element symbol -> ‘a’ term

Oxygen (O) -> oxa
Nitrogen (N) -> aza
Sulfur (S) -> thia
etc.

Priority ordering: Used to determine which heteroatom gets position 1 in ring numbering when multiple different heteroatoms are present. Lower priority number = higher priority = gets position 1 or lower locant.

IUPAC priority, Table 2.4’s own “decreasing order of seniority” [BBv2:8236]:

F > Cl > Br > I > O > S > Se > Te > N > P > As > Sb > Bi > Si > Ge > Sn > Pb: > B > Al > Ga > In > Tl

Reference: IUPAC 2013 Blue Book, Table 2.4 [BBv2:8234-8250].

Earlier revisions of this docstring cited “Table 2.3”; that table is the retained-name morpholine entry, not the Hantzsch-Widman prefix table. Corrected against the book.

orthonym.data.hw_heteroatoms.get_hw_prefix(element)#

Get the Hantzsch-Widman ‘a’ term prefix for a heteroatom.

Parameters:: element (str) – Element symbol (e.g., ‘O’, ‘N’, ‘S’)
Returns:: HW prefix string (e.g., ‘oxa’, ‘aza’, ‘thia’), or None if not found.
Return type:: str | None

None means the Hantzsch-Widman system has no prefix for this element, so the caller must refuse – it must not skip the atom and emit the ring stem anyway. Skipping is what produced inane / epane / olane for aluminium rings: the heteroatom vanished from the name while the HW stem still counted it toward the ring size.

This is Table 2.4, the Hantzsch-Widman context only. General skeletal replacement – von Baeyer, spiro, chains, rings > 10 – uses Table 1.5 via rules/ring_replacement.HETEROATOM_PREFIXES, which spells Al and In differently on purpose (alumina/inda vs aluma/indiga, [BBv2:8245] printing aluma with an explicit “(not alumina)”). The two tables must not be merged.

Examples

>>> get_hw_prefix('O')
'oxa'
>>> get_hw_prefix('N')
'aza'
>>> get_hw_prefix('C') # Carbon has no HW prefix
None
>>> get_hw_prefix('Hg') # deleted from HW by
None

orthonym.data.hw_heteroatoms.get_heteroatom_priority(element)#

Get the IUPAC priority for a heteroatom (for ring numbering).

Lower priority number = higher priority = gets position 1 or lower locant. Unknown elements return 999 (lowest priority).

Parameters:: element (str) – Element symbol (e.g., ‘O’, ‘N’, ‘S’)
Returns:: Priority integer (1 = highest priority)
Return type:: int

Examples

>>> get_heteroatom_priority('O')
1
>>> get_heteroatom_priority('N')
5
>>> get_heteroatom_priority('O') < get_heteroatom_priority('N')
True
>>> get_heteroatom_priority('X') # Unknown element
999

orthonym.data.hw_heteroatoms.compare_heteroatom_priority(element1, element2)#

Compare two heteroatoms by IUPAC priority.

Parameters:

element1 (str) – First element symbol
element2 (str) – Second element symbol

Returns:

-1 if element1 has higher priority (lower number): 0 if same priority 1 if element2 has higher priority

Return type:

int

Examples

>>> compare_heteroatom_priority('O', 'N')
-1 # O has higher priority
>>> compare_heteroatom_priority('N', 'O')
1 # O has higher priority
>>> compare_heteroatom_priority('O', 'O')
0 # Same priority

orthonym.data.hw_heteroatoms.sort_heteroatoms_by_priority(elements)#

Sort heteroatom element symbols by IUPAC priority (highest first).

Parameters:: elements (list) – List of element symbols
Returns:: List sorted by priority (O before N before Si, etc.)
Return type:: list

Examples

>>> sort_heteroatoms_by_priority(['N', 'O', 'S'])
['O', 'S', 'N']

orthonym.data.hw_heteroatoms#

`orthonym.data.hw_heteroatoms`#