orthonym.routing.dispatch_table

Note

Internal API. Names and behaviour may change between releases.

a phase dispatch table for class-first routing .

Authoritative source for outer-cascade dispatch decisions. The DISPATCH_TABLE is built at module-import time by 19 explicit _register_dispatch(...) calls (18 outer-cascade entries from internal notes-CFR.md + 1 GENERAL catch-all per internal notes); post-import the table is FROZEN (RuntimeError on further registration via the _REGISTRATION_FROZEN sentinel).

Architecture (158-internal notes): - StoutClass(StrEnum) — explicit type-safe enum; one member per dispatch

class. sibling-phase slots are commented out per // (NOT registered in DISPATCH_TABLE; reserved for a phase / 162 / 163).

• ClassDispatchEntry — frozen dataclass; immutable; serializable for the

  audit log.

• DISPATCH_TABLE: OrderedDict[StoutClass, ClassDispatchEntry] — + priority-ordered; OrderedDict makes priority order explicit even though Python 3.7+ dict preserves insertion order.

• Per-class predicate factories — 1-3-line wrappers around existing detection helpers (pure; line-count discipline).

• Per-class handler shims — 1-line wrappers around existing handler functions in src/orthonym/rules/ (no-logic-in-shim discipline).

• Lazy imports inside predicate / handler bodies (PATTERNS + namer.py:853 pattern) to avoid circular routing -> rules -> routing imports at module-import time.

Anti-pattern hygiene (internal notes-CFR.md AP-block): -: silent fallthrough -> GENERAL @ priority 99999 with lambda *_: True. -: invent-as-you-go entries -> the audit is the locked spec; every entry

here traces 1:1 to a row.

-: predicate body > 3 lines -> all bodies stay 1-3 lines. -: handler logic in shim -> all handler shims are 1-line wrappers (the

ANION_SMALL / POLY_ANION / MULTI_COMPONENT_NEUTRAL shims preserve the byte-identical neutralize-recurse + try/except logic verbatim per the audit + RESEARCH § “Code Examples”).

-: predicate side effects -> side_effect_inventory MUST be ````

for every entry (hard invariant).

-: padding with inner _classify classes -> Path-(b) reconciliation

per RESEARCH; inner classes are a phase / territory.

-: predicate that mutates mol / MolecularFeatures / global state

-> the integrity test test_side_effect_inventory_is_empty (Plan-03) parametrizes over list(StoutClass) and asserts ```` for every entry.

IUPAC P-section cites for each StoutClass live in the per-row docstring (the audit column “iupac_section”).

class orthonym.routing.dispatch_table.StoutClass(*values)

Bases: _StrEnumBase

a phase dispatch class identifiers (internal notes).

Per internal notes + the audit Path-(b) reconciliation: 18 outer-cascade entries (rows 1-18 of the audit) + 1 GENERAL catch-all = 19 enum members.

sibling-phase slots are commented out (the audit) and inserted by

a phase / 162 / 163 as 1-line _register_dispatch(...) additions.

SALT = 'salt'

RADICAL = 'radical'

ZWITTERION = 'zwitterion'

ANION_RETAINED = 'anion_retained'

CATION_RETAINED = 'cation_retained'

CATION_QUATERNARY = 'cation_quaternary'

ESTER_ANION_ZWITTERION = 'ester_anion_zwitterion'

MIXED_SIGN_ZWITTERION = 'mixed_sign_zwitterion'

ANION_SMALL = 'anion_small'

POLY_ANION = 'poly_anion'

MULTI_COMPONENT_NEUTRAL = 'multi_component_neutral'

MULTIPLICATIVE = 'multiplicative'

CARBOHYDRATE_LOOKUP = 'carbohydrate_lookup'

NATURAL_PRODUCT = 'natural_product'

PEPTIDE = 'peptide'

RETAINED_NAME = 'retained_name'

AMINO_ACID = 'amino_acid'

SKELETAL_REPLACEMENT = 'skeletal_replacement'

CYCLOPHANE = 'cyclophane'

DECOMPOSITION_PRE_GENERAL = 'decomposition_pre_general'

GENERAL = 'general'

INORGANIC_ACID = 'inorganic_acid'

ORGANOMETALLIC = 'organometallic'

LIPID = 'lipid'

MONONUCLEAR_HYDRIDE = 'mononuclear_hydride'

CHALCOGEN_CHAIN = 'chalcogen_chain'

POLYAZANE = 'polyazane'

FREE_HOMONUCLEAR_G14_HYDRIDE = 'free_homonuclear_g14_hydride'

DINUCLEAR_HYDRIDE = 'dinuclear_hydride'

KETENE = 'ketene'

RING_CHALCOGEN_OXIDE = 'ring_chalcogen_oxide'

HYDRO_FUSED_PEROXOL = 'hydro_fused_peroxol'

THIOIMIDE = 'thioimide'

NITRAMIDE_SUBSTITUTED = 'nitramide_substituted'

CYCLIC_POLYESTER = 'cyclic_polyester'

AZINIC_DERIVATIVE = 'azinic_derivative'

HETERONE = 'heterone'

SULFINE = 'sulfine'

CUMULATIVE_ZWITTERION = 'cumulative_zwitterion'

YLIDE = 'ylide'

PSEUDOKETONE_HETERO = 'pseudoketone_hetero'

ACYL_CHALCOGENCHAIN_PSEUDOKETONE = 'acyl_chalcogenchain_pseudoketone'

LAMBDA5_PHOSPHANIMINE = 'lambda5_phosphanimine'

HETEROIMINE = 'heteroimine'

LAMBDA_SULFANE_IMINE_OXIDE = 'lambda_sulfane_imine_oxide'

POLYCHALCOGEN_OXIDE = 'polychalcogen_oxide'

CATENATED_HYDRIDE = 'catenated_hydride'

HETEROCHALCOGEN_ABA = 'heterochalcogen_aba'

HOMONUCLEAR_PNICTOGEN_CHAIN = 'homonuclear_pnictogen_chain'

PNICTOGEN_CARBOXYLIC_ACID = 'pnictogen_carboxylic_acid'

MONONUCLEAR_HYDRIDE_ADDED_CARBON = 'mononuclear_hydride_added_carbon'

INOSITOL = 'inositol'

NUCLEOSIDE = 'nucleoside'

class orthonym.routing.dispatch_table.ClassDispatchEntry(class_id, priority, tier, predicate, handler, iupac_section, description, side_effect_inventory=())

Bases: object

a phase +: frozen dataclass row of DISPATCH_TABLE.

side_effect_inventory MUST be ```` per the hard invariant; the integrity test test_side_effect_inventory_is_empty (Plan-03) asserts this for every entry. explicitly bans any predicate that mutates mol, MolecularFeatures, module-global state, or thread-local state.

class_id: StoutClass

priority: int

spaced in 100s for insertability

tier: int

predicate: Callable[[...], bool]

handler: Callable[[...], str | None]

iupac_section: str

description: str

side_effect_inventory: Tuple[str, ...] = ()

class orthonym.routing.dispatch_table.ClassDispatchResult(class_id, handler, audit_record, tier)

Bases: object

a phase: returned by ClassFirstRouter.dispatch.

Caller invokes result.handler(...) to get the name string. Frozen so a single dispatch result can be safely passed across recursive call boundaries (fresh-instance pattern).

class_id: StoutClass

handler: Callable[[...], str | None]

audit_record: dict

tier: int