orthonym.assembly.handlers._enrichment#

Note

Internal API. Names and behaviour may change between releases.

a phase handler enrichment helpers (DECOMP-01).

Substrate commit 02-00: lazy re-export wrappers around the canonical implementations in composer.py. Per internal notes incremental-migration discipline, composer.py STILL OWNS _enrich_handler_name (composer.py:191-277) and _integrate_universal_prefixes (composer.py:109-183) at this commit; those functions stay until Plan-03 commit 03-10 (composer.py thinning).

The substrate ships THIS module so handler files can write the forward-looking import path:

from.._enrichment import enrich_handler_name # eventual public path

while internally the symbols delegate (via lazy import inside each function body) to composer.py. When Plan-03 commit 03-10 lands, the function BODIES move here verbatim and composer.py’s _enrich_handler_name + _integrate_universal_prefixes definitions delete. The re-export shape ensures handler files do NOT need to change import paths at thinning time — only this delegation layer flips.

Per PATTERNS line 474 first-wave guidance: both lazy-from-composer AND eventual-handlers/_enrichment paths work. We choose the lazy-from- composer path now to minimize commit-02-00 risk: zero copy of composer.py logic; zero risk of stale-closure drift; the byte-identical canary delta gate is trivially satisfied.

Anti-pattern hygiene (a phase inheritance): - -04 banned: pure read-only on features; never mutates

features.mol or features.functional_groups. (The lazy delegate inherits composer.py’s purity verbatim.)

  • -23 banned: no regex band-aid / postprocessor on inner-dispatch output — the helpers are pure wrappers.

  • logger.debug for HANDLER_COVERAGE telemetry; default-OFF.

  • IUPAC cite stays in _integrate_universal_prefixes docstring in composer.py (unchanged at this commit).

References: - composer.py:109-183 (_integrate_universal_prefixes) — verbatim source. - composer.py:191-277 (_enrich_handler_name) — verbatim source. - internal notes — analog: composer.py:109-277. - 160-internal notes — incremental-migration discipline.

orthonym.assembly.handlers._enrichment.enrich_handler_name(features, base_name, handler_id='unknown', atom_to_locant=None)#

Enrich a handler’s base name with non-principal substituents.

Lazy delegate to composer.py:_enrich_handler_name (composer.py:191-277). Per internal notes + PATTERNS first-wave guidance, composer.py owns the canonical body at this commit; this wrapper provides the forward-looking import path handlers._enrichment.enrich_handler_name for handler files that want stable paths now.

Parameters:

  • features (Any) – MolecularFeatures object.

  • base_name (str) – The handler’s base name (e.g., “carbamic acid”).

  • handler_id (str) – Handler identifier for logging.

  • atom_to_locant (Any | None) – Optional producer-supplied {atom idx -> locant} numbering — THE one base_name was spelled from. Overrides the features-derived fallback; None keeps existing behaviour.

Returns:

Enriched name with prefixes, or base_name if no enrichment needed.

Return type:

str

See also

composer.py:_enrich_handler_name — canonical implementation;

moves here verbatim at Plan-03 commit 03-10 (composer.py thinning).

orthonym.assembly.handlers._enrichment.integrate_universal_prefixes(mol, parent_atoms, parent_type='auto', oriented_ring=None, principal_chain=None, atom_to_locant=None, ring_atom_to_locant=None, exclude_atoms=None)#

Discover and format all substituents on a parent structure.

Lazy delegate to composer.py:_integrate_universal_prefixes (composer.py:109-183). Per internal notes + PATTERNS first-wave guidance.

Parameters:

  • mol (Any) – RDKit Mol object.

  • parent_atoms (Any) – Set of atom indices defining the parent structure.

  • parent_type (str) – "ring", "chain", or "auto" (auto-detects).

  • oriented_ring (Any | None) – Ring atom indices in IUPAC order (for ring parents).

  • principal_chain (Any | None) – Chain atom indices in order (for chain parents).

  • atom_to_locant (Any | None) – Optional mapping of atom idx -> IUPAC locant (CHAIN parents only).

  • ring_atom_to_locant (Any | None) – Optional inherited mapping for a RING parent — overrides the oriented_ring position arithmetic per atom.

  • exclude_atoms (Any | None) – Atoms already accounted for.

Returns:

Prefix string ready to prepend to the handler’s core name; empty string if no substituents are found.

Return type:

str

See also

composer.py:_integrate_universal_prefixes — canonical implementation.