frozen RenderedSubstituentName dataclass

Author: r-fedorov

src/openclatura/assembly_parts.py

@@ -27,15 +27,32 @@ class NameTokenBinding:
     right_context: str = ""
 
 
-class RenderedSubstituentName(str):
-    """A rendered substituent carrying construction-time boundary metadata."""
+@dataclass(frozen=True)
+class RenderedSubstituentName:
+    """Rendered text plus construction-time parenthesis-boundary metadata."""
+
+    text: str
+    outer_parentheses_optional: bool = False
+
+    def __str__(self) -> str:
+        return self.text
+
+
+RenderedSubstituentText = str | RenderedSubstituentName
+
+
+def split_rendered_substituent_name(name: RenderedSubstituentText) -> tuple[str, bool]:
+    """Return plain text and explicit boundary metadata for a rendered name."""
+
+    if isinstance(name, RenderedSubstituentName):
+        return name.text, name.outer_parentheses_optional
+    return name, False
+
 
-    outer_parentheses_optional: bool
+def rendered_substituent_text(name: RenderedSubstituentText) -> str:
+    """Return plain text when boundary metadata is no longer needed."""
 
-    def __new__(cls, value: str, *, outer_parentheses_optional: bool = False):
-        rendered = super().__new__(cls, value)
-        rendered.outer_parentheses_optional = outer_parentheses_optional
-        return rendered
+    return name.text if isinstance(name, RenderedSubstituentName) else name
 
 
 @dataclass
@@ -50,6 +67,7 @@ class SubstituentItem:
     nested_decisions: list[dict] = field(default_factory=list)
     substituent_tree: dict | None = None
     spiro: SpiroAssembly | None = None
+    outer_parentheses_optional: bool = False
 
 
 @dataclass

src/openclatura/assembly_prefixes.py

@@ -3,7 +3,7 @@
 import re
 
 from .assembly_charge import inferred_ionic_retained_parent, single_charged_replacement_locants
-from .assembly_parts import AssemblyParts, RenderedSubstituentName, SubstituentItem
+from .assembly_parts import AssemblyParts, SubstituentItem
 from .assembly_utils import is_fully_enclosed, needs_hyphen, parse_locant
 from .formatting import is_complex_prefix
 from .nomenclature import RULES
@@ -148,6 +148,7 @@ def format_substituent_prefixes(parts: AssemblyParts, spiro_subs) -> str:
     prefix_parts = []
     for name in sorted(grouped.keys(), key=substituent_sort_key):
         items = grouped[name]
+        outer_parentheses_optional = all(item.outer_parentheses_optional for item in items)
         locs = sorted([loc for item in items for loc in item.locants], key=parse_locant)
         attachments_per_group = 2 if ("diyl" in name and "ylidene" not in name) else 1
         count_raw = len(locs) if locs else len(items)
@@ -156,7 +157,14 @@ def format_substituent_prefixes(parts: AssemblyParts, spiro_subs) -> str:
         mult = (multipliers.complex_(count) if is_complex else multipliers.basic(count)) if count > 1 else ""
         loc_str = substituent_locant_string(parts, locs, len(grouped), spiro_subs)
 
-        name_to_use = _omit_optional_outer_parentheses(parts, name, count, loc_str, len(grouped))
+        name_to_use = _omit_optional_outer_parentheses(
+            parts,
+            name,
+            count,
+            loc_str,
+            len(grouped),
+            outer_parentheses_optional=outer_parentheses_optional,
+        )
         if is_complex and not is_fully_enclosed(name_to_use):
             if count > 1 or loc_str:
                 name_to_use = f"({name_to_use})"
@@ -177,6 +185,8 @@ def _omit_optional_outer_parentheses(
     count: int,
     locant_text: str,
     grouped_count: int,
+    *,
+    outer_parentheses_optional: bool,
 ) -> str:
     """Unwrap a directly rendered fragment when its parent boundary is clear."""
 
@@ -185,8 +195,7 @@ def _omit_optional_outer_parentheses(
         or count != 1
         or locant_text
         or grouped_count != 1
-        or not isinstance(name, RenderedSubstituentName)
-        or not name.outer_parentheses_optional
+        or not outer_parentheses_optional
         or not is_fully_enclosed(name)
     ):
         return name

src/openclatura/component_modifiers.py

@@ -1,6 +1,6 @@
 """Data-driven component modifiers attached after parent numbering."""
 
-from .assembly_parts import AssemblyParts, NameTokenBinding, SubstituentItem
+from .assembly_parts import AssemblyParts, NameTokenBinding, SubstituentItem, split_rendered_substituent_name
 from .formatting import strip_outer_parentheses
 from .group_atom_roles import ester_or_peroxy_single_oxygen
 from .locants import parse_locant
@@ -119,10 +119,12 @@ def add_component_n_substituents(
                         bond_ids_within(mol, {single_n, n_sub}),
                     )
                     if _use_hydrazone_suffix_modifier(parts, principal_key):
+                        branch_text, outer_parentheses_optional = split_rendered_substituent_name(branch_name)
                         parts.principal_suffix_modifiers.append(
                             SubstituentItem(
-                                branch_name,
+                                branch_text,
                                 [],
+                                outer_parentheses_optional=outer_parentheses_optional,
                                 atom_ids=branch_atoms,
                                 bond_ids=bond_ids_within(mol, branch_atoms | {single_n}),
                                 charge_atom_ids=_charged_atoms(mol, branch_atoms),

src/openclatura/component_namer.py

@@ -2,7 +2,7 @@
 
 from collections.abc import Callable
 
-from .assembly_parts import AssemblyParts, NameAtomBinding, SubstituentItem
+from .assembly_parts import AssemblyParts, NameAtomBinding, SubstituentItem, split_rendered_substituent_name
 from .chains import find_all_carbon_paths, find_ring_systems, get_cyclic_atoms
 from .component_group_rules import (
     exclude_nonparent_group_atoms,
@@ -132,13 +132,15 @@ def collect_component_branch_substituents(
                     )
                     branch_trace = []
                     branch_tree = None
+                branch_name, outer_parentheses_optional = split_rendered_substituent_name(branch_name)
                 if branch_name:
                     branch_exclude = sub_exclude | main_set
                     branch_atoms = subgraph_component(mol, n_idx, branch_exclude)
                     subst_mapping.setdefault(c_idx, []).append(
                         SubstituentItem(
                             name=branch_name,
                             locants=[],
+                            outer_parentheses_optional=outer_parentheses_optional,
                             atom_ids=branch_atoms,
                             bond_ids=bond_ids_within(mol, branch_atoms | {c_idx}),
                             charge_atom_ids=_charged_atoms(mol, branch_atoms),
@@ -183,6 +185,7 @@ def add_component_substituents(
                     item.emitted_tokens,
                     substituent_tree=item.substituent_tree,
                     spiro=item.spiro,
+                    outer_parentheses_optional=item.outer_parentheses_optional,
                 )
 
 

src/openclatura/formatting.py

@@ -2,6 +2,7 @@
 
 import re
 
+from .assembly_parts import RenderedSubstituentName, rendered_substituent_text
 from .namer_config import ALKYL_OXY_PREFIXES
 from .rules import multipliers, stems
 
@@ -22,9 +23,10 @@ def is_fully_enclosed(s: str) -> bool:
     return depth == 0
 
 
-def strip_outer_parentheses(name: str) -> str:
+def strip_outer_parentheses(name: str | RenderedSubstituentName) -> str:
     """Remove one balanced outer parenthesis pair from a fragment."""
 
+    name = rendered_substituent_text(name)
     if name.startswith("(") and name.endswith(")"):
         return name[1:-1]
     return name

src/openclatura/functional_prefixes.py

@@ -5,7 +5,7 @@
 from collections.abc import Callable
 from dataclasses import dataclass
 
-from .assembly_parts import NameTokenBinding, SubstituentItem
+from .assembly_parts import NameTokenBinding, SubstituentItem, rendered_substituent_text
 from .formatting import format_counted_prefixes, is_complex_prefix, oxy_prefix_from_branch, strip_outer_parentheses
 from .group_atom_roles import amide_nitrogen, ester_or_peroxy_single_oxygen
 from .molecule import Molecule
@@ -45,6 +45,7 @@ def ester_prefix_from_group(
     branch_name = branch_namer(mol, r_group_c, sub_exclude | {single_o}, upstream_atom=single_o)
     if not branch_name:
         return ""
+    branch_name = rendered_substituent_text(branch_name)
     return f"({oxy_prefix_from_branch(branch_name)}{suffix_text})"
 
 
@@ -62,7 +63,10 @@ def amide_prefix_from_group(
         return ""
     if not n_subs:
         return base
-    sub_names = [branch_namer(mol, x, sub_exclude | {single_n}, upstream_atom=single_n) for x in n_subs]
+    sub_names = [
+        rendered_substituent_text(branch_namer(mol, x, sub_exclude | {single_n}, upstream_atom=single_n))
+        for x in n_subs
+    ]
     return f"({format_counted_prefixes(sub_names)}{base})"
 
 
@@ -87,7 +91,14 @@ def iminium_prefix_handler(context: PrefixContext, group: PerceivedGroup) -> str
     if not n_subs:
         return "iminio"
     sub_names = [
-        context.branch_namer(context.mol, n_sub, context.sub_exclude | {iminium_n}, upstream_atom=iminium_n)
+        rendered_substituent_text(
+            context.branch_namer(
+                context.mol,
+                n_sub,
+                context.sub_exclude | {iminium_n},
+                upstream_atom=iminium_n,
+            )
+        )
         for n_sub in n_subs
     ]
     return f"({format_counted_prefixes(sub_names)}iminio)"

src/openclatura/heteroatom_subgraphs.py

@@ -1,5 +1,6 @@
 """Heteroatom-starting recursive substituent naming."""
 
+from .assembly_parts import split_rendered_substituent_name
 from .formatting import (
     count_names,
     format_counted_prefixes,
@@ -26,6 +27,25 @@
 from .rules import multipliers
 
 
+def _branch_name_text(
+    branch_namer: RecursiveSubgraphNamer,
+    mol: Molecule,
+    start_idx: int,
+    exclude_atoms: set[int],
+    upstream_atom: int,
+) -> str:
+    """Render a nested branch as text, consuming its boundary metadata."""
+
+    rendered = branch_namer(
+        mol,
+        start_idx,
+        exclude_atoms,
+        upstream_atom=upstream_atom,
+    )
+    name, _ = split_rendered_substituent_name(rendered)
+    return name
+
+
 def upstream_bond_order(mol: Molecule, start_idx: int, upstream_atom: int | None) -> int:
     if upstream_atom is None:
         return 0
@@ -152,7 +172,7 @@ def name_branch_or_none(
 ) -> str:
     if branch_idx is None:
         return ""
-    return strip_outer_parentheses(branch_namer(mol, branch_idx, exclude_atoms, upstream_atom))
+    return strip_outer_parentheses(_branch_name_text(branch_namer, mol, branch_idx, exclude_atoms, upstream_atom))
 
 
 def name_carbonyl_like_fragment(
@@ -331,7 +351,7 @@ def name_oxygen_subgraph(
         branch = name_branch_or_none(mol, branch_idx, exclude_atoms | {start_idx, nxt}, nxt, branch_namer)
         return f"({branch}peroxy)" if branch else "hydroperoxy"
 
-    branch = branch_namer(mol, nxt, exclude_atoms | {start_idx}, start_idx)
+    branch = _branch_name_text(branch_namer, mol, nxt, exclude_atoms | {start_idx}, start_idx)
     if branch:
         return oxy_prefix_from_branch(branch)
     return "hydroxy"
@@ -406,7 +426,7 @@ def name_nitrogen_subgraph(
                 if sulfur_imide:
                     branches.append(sulfur_imide)
             else:
-                branch = branch_namer(mol, nxt, exclude_atoms | {start_idx}, start_idx)
+                branch = _branch_name_text(branch_namer, mol, nxt, exclude_atoms | {start_idx}, start_idx)
                 if branch:
                     branches.append(branch)
 
@@ -446,7 +466,7 @@ def _sulfur_imide_branch_name(
         cyclic_name = _cyclic_sulfur_imide_ligand_name(mol, sulfur, nitrogen, next_atoms, s_oxygens)
         if cyclic_name:
             return cyclic_name
-        branches = [br for nxt in next_atoms if (br := branch_namer(mol, nxt, local_exclude, sulfur))]
+        branches = [br for nxt in next_atoms if (br := _branch_name_text(branch_namer, mol, nxt, local_exclude, sulfur))]
         branches.extend(["oxo"] * len(s_oxygens))
         if not branches:
             return "sulfanylidene"
@@ -568,7 +588,7 @@ def name_sulfur_subgraph(
             br
             for nxt in next_atoms
             if (
-                br := branch_namer(mol, nxt, exclude_atoms | {start_idx} | set(s_oxygens) | set(s_nitrogens), start_idx)
+                br := _branch_name_text(branch_namer, mol, nxt, exclude_atoms | {start_idx} | set(s_oxygens) | set(s_nitrogens), start_idx)
             )
         ]
         branches.extend(["oxo"] * len(s_oxygens))
@@ -589,7 +609,7 @@ def name_sulfur_subgraph(
         branches = [
             br
             for nxt in next_atoms
-            if (br := branch_namer(mol, nxt, exclude_atoms | {start_idx} | set(s_oxygens), start_idx))
+            if (br := _branch_name_text(branch_namer, mol, nxt, exclude_atoms | {start_idx} | set(s_oxygens), start_idx))
         ]
         branches.extend(["oxo"] * len(s_oxygens))
         return format_lambda_substituent(
@@ -603,7 +623,7 @@ def name_sulfur_subgraph(
         branches = [
             br
             for nxt in next_atoms
-            if (br := branch_namer(mol, nxt, exclude_atoms | {start_idx} | set(s_nitrogens), start_idx))
+            if (br := _branch_name_text(branch_namer, mol, nxt, exclude_atoms | {start_idx} | set(s_nitrogens), start_idx))
         ]
         if len(s_nitrogens) == 1:
             branches = ["imino", *branches]
@@ -619,7 +639,7 @@ def name_sulfur_subgraph(
         return "thioxo" if is_double else f"{stereo_prefix_text}{unsubstituted_prefix('S') or 'sulfanyl'}"
 
     if len(next_atoms) == 1:
-        branch = branch_namer(mol, next_atoms[0], exclude_atoms | {start_idx}, start_idx)
+        branch = _branch_name_text(branch_namer, mol, next_atoms[0], exclude_atoms | {start_idx}, start_idx)
         if not is_double and mol.atoms[start_idx].charge > 0:
             return f"({stereo_prefix_text}{branch}sulfaniumyl)" if branch else f"{stereo_prefix_text}sulfaniumyl"
         if branch in SIMPLE_SULFANYL_PREFIXES:
@@ -628,7 +648,7 @@ def name_sulfur_subgraph(
             return format_element_substituent(stereo_prefix_text, branch, "sulfanyl", is_double=is_double)
         return f"{stereo_prefix_text}{'sulfanylidene' if is_double else 'sulfanyl'}"
 
-    branches = [br for nxt in next_atoms if (br := branch_namer(mol, nxt, exclude_atoms | {start_idx}, start_idx))]
+    branches = [br for nxt in next_atoms if (br := _branch_name_text(branch_namer, mol, nxt, exclude_atoms | {start_idx}, start_idx))]
     return format_lambda_substituent(
         mol, start_idx, branches, stereo_prefix_text, "sulfanylidene" if is_double else "sulfanyl"
     )
@@ -659,7 +679,7 @@ def name_chalcogen_subgraph(
         branches = [
             br
             for nxt in next_atoms
-            if (br := branch_namer(mol, nxt, exclude_atoms | {start_idx} | set(oxo_ligands), start_idx))
+            if (br := _branch_name_text(branch_namer, mol, nxt, exclude_atoms | {start_idx} | set(oxo_ligands), start_idx))
         ]
         branches.extend(["oxo"] * len(oxo_ligands))
         return format_lambda_substituent(
@@ -676,7 +696,7 @@ def name_chalcogen_subgraph(
             else f"{stereo_prefix_text}{unsubstituted_prefix(mol.atoms[start_idx].symbol) or element_suffix}"
         )
     if len(next_atoms) == 1:
-        branch = branch_namer(mol, next_atoms[0], exclude_atoms | {start_idx}, start_idx)
+        branch = _branch_name_text(branch_namer, mol, next_atoms[0], exclude_atoms | {start_idx}, start_idx)
         if branch and substituent_bonding_number(mol, start_idx) != mol.atoms[start_idx].element.standard_valence:
             return format_lambda_substituent(
                 mol, start_idx, [branch], stereo_prefix_text, element_suffix + ("idene" if is_double else "")
@@ -686,7 +706,7 @@ def name_chalcogen_subgraph(
         if branch:
             return format_element_substituent(stereo_prefix_text, branch, element_suffix, is_double=is_double)
         return f"{stereo_prefix_text}{element_suffix + ('idene' if is_double else '')}"
-    branches = [br for nxt in next_atoms if (br := branch_namer(mol, nxt, exclude_atoms | {start_idx}, start_idx))]
+    branches = [br for nxt in next_atoms if (br := _branch_name_text(branch_namer, mol, nxt, exclude_atoms | {start_idx}, start_idx))]
     return format_lambda_substituent(
         mol, start_idx, branches, stereo_prefix_text, element_suffix + ("idene" if is_double else "")
     )
@@ -714,7 +734,7 @@ def name_phosphorus_subgraph(
     branches = [
         br
         for nxt in next_atoms
-        if (br := branch_namer(mol, nxt, exclude_atoms | {start_idx} | set(p_oxygens), start_idx))
+        if (br := _branch_name_text(branch_namer, mol, nxt, exclude_atoms | {start_idx} | set(p_oxygens), start_idx))
     ]
     return f"({stereo_prefix_text}{format_counted_prefixes(branches)}{suffix})"
 
@@ -734,7 +754,7 @@ def name_group_13_14_subgraph(
     next_atoms = subgraph_neighbors(mol, start_idx, exclude_atoms, upstream_atom)
     if not next_atoms:
         return suffix
-    branches = [br for nxt in next_atoms if (br := branch_namer(mol, nxt, exclude_atoms | {start_idx}, start_idx))]
+    branches = [br for nxt in next_atoms if (br := _branch_name_text(branch_namer, mol, nxt, exclude_atoms | {start_idx}, start_idx))]
     return f"({format_counted_prefixes(branches)}{suffix})"
 
 
@@ -749,7 +769,7 @@ def name_halogen_subgraph(
     next_atoms = subgraph_neighbors(mol, start_idx, exclude_atoms, upstream_atom)
     if not next_atoms:
         return HALOGEN_PREFIXES[symbol]
-    branches = [br for nxt in next_atoms if (br := branch_namer(mol, nxt, exclude_atoms | {start_idx}, start_idx))]
+    branches = [br for nxt in next_atoms if (br := _branch_name_text(branch_namer, mol, nxt, exclude_atoms | {start_idx}, start_idx))]
     valence = sum(mol.get_bond(start_idx, n).order for n in mol.get_neighbors(start_idx))
     return f"({format_counted_prefixes(branches)}lambda^{valence}-{HALOGEN_LAMBDA_SUFFIXES[symbol]})"