orthonym.assembly.handlers.organometallic#

Note

Internal API. Names and behaviour may change between releases.

a phase organometallic handler — + + Salzer 1999.

SECOND tree-emitting handler in Orthonym (first was simple_molecule.py from a phase Plan-10). Mirrors that file’s shape per internal notes +

  • internal notes-ORGM.md

The handler is OUTER-CFR-only (per + a phase): it does NOT add an inner-dispatch entry; the CFR-level ORGANOMETALLIC entry at priority 50 routes here BEFORE SALT@100.

Byte-identical contract per internal notes: name_tree_to_string(result.tree) == result.name for ALL non-None returns.

Cascade-continuation on None preserved per internal notes: any failure (mol is None; metal_complex is None; multimetal compound; ValueError from hapticity; result is None) returns None so CFR cascade falls through to SALT@100 →… → GENERAL.

Anti-patterns to avoid (PATTERNS lines 499-503): - NEVER mutate features or mol inside the handler — predicate + handler

purity (hard invariant).

  • NEVER catch ALL exceptions; only catch ValueError from compute_hapticity per RESEARCH lines 540-544 to signal cascade-continuation.

  • NEVER emit a tree whose name_tree_to_string(tree) does NOT byte-equal result.name — internal notes + RESEARCH line 757 byte-identical contract.

orthonym.assembly.handlers.organometallic.name_organometallic(features, mol=None, style='pin')#

a phase ORGM handler; CFR-routed at priority 50.

Per internal notes: returns Optional[NamingResult] with tree populated when result is non-None. The CFR shim _handle_organometallic in routing/dispatch_table.py extracts result.name as Optional[str].

Tier-1 fast path: retained-PIN lookup for style=”pin” — ferrocene, ruthenocene, etc. Tier-1 systematic + Tier-2/3/4 forms go through the systematic-assembly path.

Cascade-continuation on None per internal notes: any failure (mol is None; metal_complex is None; multimetal; ValueError from hapticity; result is None) returns None so CFR cascade falls through to SALT@100 →… → GENERAL.