`orthonym.data.hw_stems`#

Note

Internal API. Names and behaviour may change between releases.

Hantzsch-Widman stem suffix data for systematic heterocycle naming.

The Hantzsch-Widman (HW) system uses stem suffixes to indicate ring size and saturation state. The suffix is appended after the heteroatom prefixes to form the complete heterocycle name.

Suffix structure:

[heteroatom prefix] + [stem suffix] = heterocycle name e.g., oxa + ole = oxole (unsaturated 5-membered O-heterocycle)

aza + iridine = aziridine (saturated 3-membered N-heterocycle)

Special cases for 6-membered rings:

Saturated rings with O, S, Se, Te, Bi, Hg use ‘-ane’ (oxane, thiane)
Saturated rings with N, Si, Ge, Sn, Pb, B, P use ‘-inane’ (azinane)

The ‘n_saturated’ variants use ‘-idine’ suffixes for N-containing saturated rings (e.g., pyrrolidine = 5-membered saturated N-ring, olidine stem). Note: Many N-saturated heterocycles have retained names (piperidine, morpholine).

Reference: IUPAC 2013 Blue Book, Table 2.2 and Section Source: Derived from OPSIN hwSuffixes.xml

orthonym.data.hw_stems.least_senior_six_ring_heteroatom(ring_heteroatoms)#

The heteroatom that selects a six-membered ring’s stem, or None.

(the Blue Book), heading “Selecting Hantzsch-Widman names

for six-membered rings”: “The stem for six-membered rings depends on the least senior heteroatom in the ring, i.e., the heteroatom whose name directly precedes the stem…. The stem is selected in accordance with the group to which the least senior heteroatom belongs.”

Returns None when the ring carries no heteroatom that Table 2.5 classifies (Hg/Zn/Cd are in no group and in no citation sequence). Callers must then fall back rather than treat an unlisted element as least senior – promoting one would silently change a listed atom’s stem.

orthonym.data.hw_stems.get_hw_stem(ring_size, is_saturated, heteroatom='O', ring_heteroatoms=None)#

Get the Hantzsch-Widman stem suffix for a heterocycle.

Parameters:

ring_size (int) – Number of atoms in the ring (3-10)
is_saturated (bool) – True for saturated, False for unsaturated
heteroatom (str) – Principal heteroatom symbol (used for 6-membered ring suffix selection: O/S use ‘ane’, N/P/Si use ‘inane’)
ring_heteroatoms (Set[str] | None) –

OPTIONAL set of ALL heteroatom symbols in the ring.
/ Table 2.7 class 6C (P, As, Sb, B, halogens,

…) gives an UNSATURATED 6-ring the ‘-inine’ ending; that depends on whether ANY 6C atom is present, not on the single dominant heteroatom, so callers pass the full set. When omitted, the single heteroatom is treated as the ring’s only heteroatom (backwards-compatible).

Returns:

HW stem suffix string, or None if ring size not supported

Return type:

str | None

Examples

>>> get_hw_stem(5, False) # Unsaturated 5-ring
'ole'
>>> get_hw_stem(5, True) # Saturated 5-ring
'olane'
>>> get_hw_stem(6, True, 'O') # Saturated 6-ring with O
'ane'
>>> get_hw_stem(6, True, 'N') # Saturated 6-ring with N
'inane'
>>> get_hw_stem(6, False, 'O', {'O', 'P'}) # unsaturated O+P 6-ring
'inine'
>>> get_hw_stem(3, True, 'N') # Saturated 3-ring with N
'iridine'

orthonym.data.hw_stems.get_unsaturated_stem(ring_size)#

Get the unsaturated HW stem suffix for a ring size.

Parameters:: ring_size (int) – Number of atoms in the ring (3-10)
Returns:: Unsaturated stem suffix, or None if not supported
Return type:: str | None

Examples

>>> get_unsaturated_stem(5)
'ole'
>>> get_unsaturated_stem(6)
'ine'

orthonym.data.hw_stems.get_saturated_stem(ring_size, heteroatom='C')#

Get the saturated HW stem suffix for a ring size.

Parameters:

ring_size (int) – Number of atoms in the ring (3-10)
heteroatom (str) – Principal heteroatom (affects 6-membered ring suffix)

Returns:

Saturated stem suffix, or None if not supported

Return type:

str | None

Examples

>>> get_saturated_stem(5)
'olane'
>>> get_saturated_stem(6, 'O')
'ane'
>>> get_saturated_stem(6, 'N')
'inane'

orthonym.data.hw_stems.is_supported_ring_size(ring_size)#

Check if a ring size is supported by HW nomenclature.

Parameters:: ring_size (int) – Number of atoms in the ring
Returns:: True if ring size 3-10 (HW supported range)
Return type:: bool

Examples

>>> is_supported_ring_size(5)
True
>>> is_supported_ring_size(11)
False

orthonym.data.hw_stems.get_supported_ring_sizes()#

Get list of ring sizes supported by HW nomenclature.

Returns:: List of integers [3, 4, 5, 6, 7, 8, 9, 10]
Return type:: list

orthonym.data.hw_stems#

`orthonym.data.hw_stems`#