orthonym.data.triviality_controller_seed

Note

Internal API. Names and behaviour may change between releases.

a phase Plan-01: Triviality-controller seed-table loader.

Loads triviality_controller_seed.json (the locked PIN-authority seed per internal notes) into a Dict[str, SeedEntry] keyed by canonical SMILES, with:

• the a phase _PIN_DENY gate enforced at LOAD time (internal notes — deny-list-by-data; a deny-listed name in the JSON is a hard load error),

• canonicalization-idempotence enforced per entry (internal notes — Chem.CanonSmiles is the single source of truth for the match key),

• an optional design-time OPSIN L1 round-trip pre-validator (internal notes T1; validate=True / scripts/lint_triviality_controller_seed.py --rt).

Frozen-dataclass discipline mirrors a phase SACRED: SeedEntry is @dataclass(frozen=True) and is never mutated after construction.

Graceful degradation (a phase): a missing JSON or schema error degrades SEED_TABLE to {} so the downstream controller becomes a no-op, never a crash.

Source: 168-internal notes,,,; internal notes section 5.4; internal notes “NEW: src/orthonym/data/triviality_controller_seed.py”.

class orthonym.data.triviality_controller_seed.SubstitutionType(*values)

Bases: str, Enum

IUPAC 2013 -.3 retained-name substitution Types (internal notes).

• TYPE_1 —: unlimited substitution (benzene, pyridine,…).

• TYPE_2A —: substitution requires the senior group be expressed; principal-group-bound (phenol, aniline, benzoic acid,…).

• TYPE_2B —: closed compulsory-prefix-only list (formic acid + halogen/nitro/nitroso/alkoxy).

• TYPE_2C —: per-name-specific permission (anisole, hydroxylamine); defaults to Type 3 unless a locus override is set.

• TYPE_3 —: no substitution except functionalisation (toluene, the xylene isomers).

TYPE_1 = 'type_1'

TYPE_2A = 'type_2a'

TYPE_2B = 'type_2b'

TYPE_2C = 'type_2c'

TYPE_3 = 'type_3'

class orthonym.data.triviality_controller_seed.SeedEntry(canonical_smiles, retained_pin_name, substitution_type, iupac_p_section, locant_context, compulsory_prefix_smarts, principal_group_required, locus_override_rule_id, stereo_in_key, notes, opsin_rt_verified_at)

Bases: object

One locked seed-table entry (internal notes +).

Immutable by a phase SACRED discipline. canonical_smiles is the Chem.CanonSmiles-stable match key; retained_pin_name is the substitution target the controller emits.

canonical_smiles: str

retained_pin_name: str

substitution_type: SubstitutionType

iupac_p_section: str

locant_context: Tuple[int, ...] | None

compulsory_prefix_smarts: Tuple[str, ...] | None

principal_group_required: str | None

locus_override_rule_id: str | None

stereo_in_key: bool

notes: str

opsin_rt_verified_at: str

orthonym.data.triviality_controller_seed.load_seed_table(json_path, *, validate=False)

Load + validate the seed JSON into a canonical-SMILES-keyed dict.

Enforces the deny gate and the canonicalization-idempotence gate at load. With validate=True additionally runs the OPSIN-RT design-time pre-validator (off by default — runs at CI lint time, not at every import).

Raises ValueError on a deny-list leak, a non-idempotent canonical SMILES, or (when validate=True) an OPSIN-RT failure. Raises the JSON-load errors on a malformed file (caught by the module-load wrapper below).