chython 3.0__cp313-cp313-macosx_10_13_universal2.whl

chython/__init__.py

@@ -0,0 +1,68 @@
+# -*- coding: utf-8 -*-
+#
+#  Copyright 2014-2026 Ramil Nugmanov <nougmanoff@protonmail.com>
+#  Copyright 2014-2019 Timur Madzhidov tmadzhidov@gmail.com features and API discussion
+#  Copyright 2014-2019 Alexandre Varnek <varnek@unistra.fr> base idea of CGR approach
+#  This file is part of chython.
+#
+#  chython is free software; you can redistribute it and/or modify
+#  it under the terms of the GNU Lesser General Public License as published by
+#  the Free Software Foundation; either version 3 of the License, or
+#  (at your option) any later version.
+#
+#  This program is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+#  GNU Lesser General Public License for more details.
+#
+#  You should have received a copy of the GNU Lesser General Public License
+#  along with this program; if not, see <https://www.gnu.org/licenses/>.
+#
+"""chython's public surface: a facade re-exporting the packages below it.
+
+`__all__` is empty by design.  `smarts` is the short spelling of `read_smarts` and the same function
+object.  `smiles` is bidirectional: a string in reads -- a `>` that is not a dative `->` makes it a
+reaction SMILES and the result a `ReactionContainer` -- and a container in writes one.  `pach` is the
+same door for the wire format, and `unpach`/`unpack` its import half under chython 2's two names.
+"""
+from sys import modules as _modules
+from types import ModuleType as _ModuleType
+from .core import *
+from .core import read_smarts as smarts
+from .depict import (Clean2DEngine, DepictStyle, get_clean2d_engine, get_depict_style,
+                     set_clean2d_engine, set_depict_style)
+from .formats import *
+# By full path, not through `formats`' star: `pdb` is that subpackage's name too and the function
+# would shadow it.
+from .formats.pdb import PDBAtom, PDBBond, PDBRecord, build_molecule, mmcif, pdb, read_mmcif, read_pdb
+# Imported for its registration side effect as much as for its names: it calls `_set_standardize_fn`
+# at import time, which is what makes `mol.standardize()` exist.  Not an unused import.
+from .chemistry import *
+# Likewise: `_set_reactions_fns` at import time is what makes `mol.react()` and `mol @ other` exist.
+from .reactions import *
+from .interop import iupac, patch_pandas
+from .interop.config import _facade_alias as _interop_facade_alias
+
+
+class _Facade(_ModuleType):
+    """Gives `chython` itself a property, so `chython.clean2d_engine` forwards both the read and the
+    write to its one home in `depict/_config.py` and the setter validates the name on the spot.
+    """
+    @property
+    def clean2d_engine(self) -> Clean2DEngine:
+        return get_clean2d_engine()
+
+    @clean2d_engine.setter
+    def clean2d_engine(self, engine: Clean2DEngine):
+        set_clean2d_engine(engine)
+
+
+_modules[__name__].__class__ = _Facade
+
+# `conformer_engine` and `class_paths` live in `chython.interop.config`; aliased here rather than
+# copied, or `chython.conformer_engine = 'cdpkit'` would be a silent no-op.  Must run AFTER the
+# `__class__` assignment above: `_facade_alias` subclasses whatever class the module currently has, so
+# the reverse order would replace the aliasing subclass and turn both names into AttributeErrors.
+_interop_facade_alias(__name__, 'conformer_engine', 'class_paths')
+
+__all__ = []

chython/_functions.py

@@ -0,0 +1,113 @@
+# -*- coding: utf-8 -*-
+#
+#  Copyright 2020-2026 Ramil Nugmanov <nougmanoff@protonmail.com>
+#  This file is part of chython.
+#
+#  chython is free software; you can redistribute it and/or modify
+#  it under the terms of the GNU Lesser General Public License as published by
+#  the Free Software Foundation; either version 3 of the License, or
+#  (at your option) any later version.
+#
+#  This program is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+#  GNU Lesser General Public License for more details.
+#
+#  You should have received a copy of the GNU Lesser General Public License
+#  along with this program; if not, see <https://www.gnu.org/licenses/>.
+#
+from functools import wraps
+from itertools import product
+from warnings import warn
+
+
+_SENTINEL = object()
+
+
+def renamed_name(old, new):
+    """Announce a superseded attribute spelling, naming what replaced it.
+
+    ONE FUNCTION SO THE MESSAGE HAS ONE WORDING.  Every alias routes through here, so the text a
+    consumer greps for while porting is the same text in all of them, and the removal is one edit.
+
+    `stacklevel=3` charges the warning to the CALLER, which is the only person who can act on it: the
+    three frames are `warn` -> this function -> the property's fget or fset -> the consumer's line.
+    THE NUMBER IS MEASURED, NOT REASONED.  Its counterpart in the compiled core is 1 for the same
+    intent, because neither a `cdef` helper nor a compiled `def` pushes a Python frame; so the right
+    number is a property of the call chain rather than of the source, and both are asserted by a test
+    on the blamed line rather than trusted.
+    """
+    warn(f'`{old}` was renamed to `{new}` and will be removed in a later release; use `{new}`',
+         DeprecationWarning, stacklevel=3)
+
+
+def cached_method(func):
+    """Cache no-argument method result in instance __dict__. Cleared by flush_cache().
+
+    Thread-safe for concurrent reads without locking:
+    - dict.get/setitem are atomic in CPython 3.14 free-threaded mode
+    - Wrapped functions are pure (deterministic, read-only on self)
+    - Duplicate computation on cold cache is benign (same result)
+    - Mutations must be sequential (caller's responsibility)
+    """
+    key = f'__cached_method_{func.__name__}'
+
+    @wraps(func)
+    def wrapper(self):
+        val = self.__dict__.get(key, _SENTINEL)
+        if val is not _SENTINEL:
+            return val
+        val = func(self)
+        self.__dict__[key] = val
+        return val
+    return wrapper
+
+
+# lazy itertools.product with diagonal combination precedence
+def lazy_product(*args):
+    if len(args) == 1:
+        for x in args[0]:
+            yield x,
+    elif not args:
+        yield ()
+    else:
+        gens = [iter(x) for x in args]
+        empty = [False] * len(args)
+        pools = [[] for _ in range(len(args))]
+        indices = set()
+
+        reached = 0
+        while True:
+            out = []
+            ind = []
+            for n, (p, g, e) in enumerate(zip(pools, gens, empty)):
+                if e:
+                    out.append(p[-1])
+                else:
+                    try:
+                        x = next(g)
+                    except StopIteration:
+                        if not p:  # one of gens empty
+                            return
+                        reached += 1
+                        if reached == len(args):
+                            break
+                        out.append(p[-1])
+                        empty[n] = True
+                    else:
+                        p.append(x)
+                        out.append(x)
+                ind.append(len(p) - 1)
+            else:
+                yield tuple(out)
+                indices.add(tuple(ind))
+                continue
+            break
+
+        for ind in product(*(range(len(p)) for p in pools)):
+            if ind in indices:
+                continue
+            yield tuple(p[x] for x, p in zip(ind, pools))
+
+
+__all__ = ['cached_method', 'lazy_product', 'renamed_name']

chython/chemistry/__init__.py

@@ -0,0 +1,86 @@
+# -*- coding: utf-8 -*-
+#
+#  Copyright 2026 Ramil Nugmanov <nougmanoff@protonmail.com>
+#  This file is part of chython.
+#
+#  chython is free software; you can redistribute it and/or modify
+#  it under the terms of the GNU Lesser General Public License as published by
+#  the Free Software Foundation; either version 3 of the License, or
+#  (at your option) any later version.
+#
+#  This program is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+#  GNU Lesser General Public License for more details.
+#
+#  You should have received a copy of the GNU Lesser General Public License
+#  along with this program; if not, see <https://www.gnu.org/licenses/>.
+#
+"""Chemical knowledge as TSV in `tables/`, and the passes that apply it.
+
+Imports `chython.core` and the standard library only, never the `chython` facade.  Importing it registers
+`standardize()`, `canonicalize()` and friends on the core container by injection, `MoleculeContainer`
+being a `cdef class`.  No pass runs on parse.
+
+`perceive_bonds`, `saturate` and `expand_abbreviations` are the passes with no method.  The first two
+are the two halves of building a molecule out of a coordinate file -- which pairs are bonded, then at
+what order -- so their caller is whoever read that file, and neither runs on read.  The third reads what
+a drawing wrote on an atom, which is a fact about a FILE and not about a structure, so it belongs beside
+the reader that stored the alias rather than on every molecule.
+"""
+from ._abbreviations import expand_abbreviations
+from ._canonicalize import canonicalize
+from ._counts import (hydrogen_bond_acceptors_count, hydrogen_bond_donors_count,
+                      rotatable_bonds_count)
+from ._crippen import crippen_logp, crippen_mr
+from ._hydrogens import explicify_hydrogens, implicify_hydrogens
+from ._implicit import calc_implicit, check_valence
+from ._isomers import standardize_isomers
+from ._maccs import maccs_bit_set, maccs_keys
+from ._perceive import perceive_bonds
+from ._pharmacophore import pharmacophore_invariants
+from ._protomers import neutralize
+from ._qed import alert_count, qed, qed_properties
+from ._residues import (RESIDUE_KINDS, ResidueTemplate, normalize_atom_name, residue_template,
+                        residue_templates)
+from ._resonance import fix_resonance
+from ._salts import SaltComposition, decompose_salts, split_salts
+from ._saturate import saturate
+from ._smarts import SmartsSyntaxError, compile_smarts
+from ._standardize import LogRecord, standardize
+from ._tables import (ACID_ROLES, AbbreviationRow, AcidRow, Endpoint, RESONANCE_ROLES, Rule, SALT_ROLES,
+                      SaltRow, abbreviation_row, abbreviations_rows, acids_rules, acids_rules_by_role,
+                      acids_table_text, groups_rules,
+                      metals_rules, read_table, resonance_rules, resonance_rules_by_role,
+                      resonance_table_text, salts_rows, salts_rows_by_role, salts_species_keys,
+                      salts_table_text, standardize_rules)
+from ._tpsa import tpsa
+from ..core._core import (_set_canonicalize_fn, _set_featurizer_fns, _set_hydrogens_fns,
+                          _set_isomers_fn, _set_protomers_fn, _set_resonance_fn, _set_salts_fns,
+                          _set_standardize_fn, _set_valence_fn)
+
+
+__all__ = ['ACID_ROLES', 'AbbreviationRow', 'LogRecord', 'SALT_ROLES', 'SaltComposition',
+           'abbreviation_row', 'abbreviations_rows', 'alert_count',
+           'calc_implicit', 'canonicalize', 'check_valence', 'crippen_logp', 'crippen_mr',
+           'decompose_salts', 'expand_abbreviations', 'explicify_hydrogens', 'fix_resonance',
+           'hydrogen_bond_acceptors_count',
+           'hydrogen_bond_donors_count', 'implicify_hydrogens', 'maccs_bit_set', 'maccs_keys',
+           'neutralize', 'perceive_bonds', 'pharmacophore_invariants', 'qed', 'qed_properties',
+           'rotatable_bonds_count',
+           'saturate', 'split_salts', 'standardize', 'standardize_isomers', 'tpsa']
+
+_set_standardize_fn(standardize)
+_set_canonicalize_fn(canonicalize)
+_set_hydrogens_fns(implicify_hydrogens, explicify_hydrogens)
+_set_isomers_fn(standardize_isomers)
+_set_valence_fn(check_valence)
+_set_salts_fns(split_salts=split_salts, decompose_salts=decompose_salts)
+_set_protomers_fn(neutralize)
+_set_resonance_fn(fix_resonance)
+_set_featurizer_fns(rotatable_bonds_count=rotatable_bonds_count,
+                    hydrogen_bond_donors_count=hydrogen_bond_donors_count,
+                    hydrogen_bond_acceptors_count=hydrogen_bond_acceptors_count,
+                    tpsa=tpsa, crippen_logp=crippen_logp, crippen_mr=crippen_mr, qed=qed,
+                    maccs_keys=maccs_keys, maccs_bit_set=maccs_bit_set,
+                    pharmacophore_invariants=pharmacophore_invariants)

chython/chemistry/_abbreviations.py

@@ -0,0 +1,127 @@
+# -*- coding: utf-8 -*-
+#
+#  Copyright 2026 Ramil Nugmanov <nougmanoff@protonmail.com>
+#  This file is part of chython.
+#
+#  chython is free software; you can redistribute it and/or modify
+#  it under the terms of the GNU Lesser General Public License as published by
+#  the Free Software Foundation; either version 3 of the License, or
+#  (at your option) any later version.
+#
+#  This program is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+#  GNU Lesser General Public License for more details.
+#
+#  You should have received a copy of the GNU Lesser General Public License
+#  along with this program; if not, see <https://www.gnu.org/licenses/>.
+#
+"""Expansion of a contracted group drawn as one labelled atom.
+
+A file that draws one atom and writes `OMe` on it has stated a methoxy group.  The reader stores the
+label as the atom's alias and the atom as an R -- neither invents a structure -- and this pass turns the
+ones `tables/abbreviations.tsv` knows into atoms.  A label the table does not know is left alone with its
+alias, which is what makes the table safe to grow.
+
+THE LABELLED ATOM IS TRANSMUTED, NOT REPLACED.  `set_element` keeps its stable id, its bonds and its
+neighbours' parities; deleting it and adding the fragment's attachment atom instead would reorder a
+neighbouring stereocentre's references and invalidate a parity nothing here restated.
+"""
+from ._tables import abbreviation_row
+from ..core import H_UNKNOWN, LogRecord, MoleculeContainer, REFUSED, REPAIRED, recording
+
+
+__all__ = ['expand_abbreviations']
+
+
+#: Neither exactly one neighbour nor a single bond to it: the marker in the table states the one single
+#: bond a contracted group hangs by, and a site that is not that is not this group.
+_RULE_ATTACHMENT = 'abbreviations:attachment'
+
+#: The file stated a charge, a radical or an isotope on the labelled atom, and the label states one too.
+#: Nothing here ranks the two, so the site keeps the label.
+_RULE_STATED = 'abbreviations:stated-atom'
+
+
+def expand_abbreviations(molecule: MoleculeContainer) -> bool:
+    """Replace every atom whose alias names a row of `tables/abbreviations.tsv` with that fragment.
+
+    All-or-nothing per site.  A site that survives every check is expanded and its alias dropped; a site
+    that fails one is left exactly as the file drew it, alias included, and the reason is a REFUSED
+    record.  Returns True when at least one site was expanded.
+
+    | Outcome | Rule | Severity |
+    | --- | --- | --- |
+    | expanded | the row's own id, `abbreviations:OMe` | REPAIRED |
+    | not one single bond to one neighbour | `abbreviations:attachment` | REFUSED |
+    | charge, radical or isotope stated on the labelled atom | `abbreviations:stated-atom` | REFUSED |
+
+    The grafted atoms take the labelled atom's coordinates, so a record with a depiction needs
+    `clean2d()` afterwards; the message says so where there was one to disturb.
+    """
+    with recording(molecule, stage='abbreviations') as log:
+        aliases = molecule.aliases
+        if not aliases:
+            return False
+
+        sites = []
+        for n, text in aliases.items():
+            try:
+                label = text.decode('utf-8')
+            except UnicodeDecodeError:                 # not a spelling any table holds
+                continue
+            row = abbreviation_row(label)
+            if row is None:
+                continue
+
+            neighbors = list(molecule.neighbors_of(n))
+            if len(neighbors) != 1 or molecule.order_of(n, neighbors[0]) != 1:
+                log.append(LogRecord(_RULE_ATTACHMENT, (n,),
+                                     f'atom {n}: {label} hangs by one single bond and this atom has '
+                                     f'{len(neighbors)} neighbours; the label is kept', REFUSED))
+                continue
+            atom = molecule.atom(n)
+            if atom.charge or atom.is_radical or atom.isotope:
+                log.append(LogRecord(_RULE_STATED, (n,),
+                                     f'atom {n}: the record states charge {atom.charge}, radical '
+                                     f'{atom.is_radical} and isotope {atom.isotope} here, and {label} '
+                                     f'states its own; the label is kept', REFUSED))
+                continue
+            sites.append((n, label, row, atom.r_index, molecule.xy_of(n)))
+
+        if not sites:
+            return False
+
+        with molecule.edit():
+            for n, _, row, r_index, xy in sites:
+                fragment = row.fragment
+                anchor = fragment.atom(row.attachment)
+                if r_index:                            # an R index is only settable on element 0
+                    molecule.set_r_index(n, 0)
+                molecule.set_element(n, anchor.element)
+                molecule.set_charge(n, anchor.charge)
+                molecule.set_radical(n, anchor.is_radical)
+                molecule.set_isotope(n, anchor.isotope)
+                molecule.set_hydrogens(n, H_UNKNOWN if anchor.implicit_h is None else anchor.implicit_h)
+
+                grafted = {row.attachment: n}
+                for a in fragment.atoms():
+                    if a.n == row.marker or a.n == row.attachment:
+                        continue
+                    grafted[a.n] = molecule.add_atom(a.element, charge=a.charge, isotope=a.isotope,
+                                                     radical=a.is_radical, implicit_h=a.implicit_h)
+                    if xy is not None:
+                        molecule.set_xy(grafted[a.n], xy[0], xy[1])
+                for bond in fragment.bonds():
+                    if bond.n == row.marker or bond.m == row.marker:
+                        continue
+                    molecule.add_bond(grafted[bond.n], grafted[bond.m], bond.order)
+
+        molecule.set_aliases({n: text for n, text in aliases.items()
+                              if n not in {n for n, _, _, _, _ in sites}})
+        for n, label, row, _, xy in sites:
+            drawn = ', and the grafted atoms share its coordinates, so the record needs a 2D clean' \
+                if xy is not None else ''
+            log.append(LogRecord(row.id, (n,), f'atom {n}: the label {label} named a contracted group '
+                                              f'and was expanded to {row.smiles}{drawn}', REPAIRED))
+        return True

chython/chemistry/_canonicalize.py

@@ -0,0 +1,152 @@
+# -*- coding: utf-8 -*-
+#
+#  Copyright 2026 Ramil Nugmanov <nougmanoff@protonmail.com>
+#  This file is part of chython.
+#
+#  chython is free software; you can redistribute it and/or modify
+#  it under the terms of the GNU Lesser General Public License as published by
+#  the Free Software Foundation; either version 3 of the License, or
+#  (at your option) any later version.
+#
+#  This program is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+#  GNU Lesser General Public License for more details.
+#
+#  You should have received a copy of the GNU Lesser General Public License
+#  along with this program; if not, see <https://www.gnu.org/licenses/>.
+#
+"""`canonicalize()` -- the pre-pass that makes `canonical_bytes` a compound identity rather than a
+drawing identity, so equal compounds hash equal and a corpus deduplicates by hash.  The stage order
+is a correctness constraint, not taste: `kekule()`, `standardize()`, `implicify_hydrogens()`,
+`neutralize()`, `thiele()`, `standardize_isomers()`, and `kekule()` again only under
+`keep_kekule=True`.  Each ordering pair is justified at its numbered step below.
+
+The order alone is not enough, because the last stage can unblock the second one: a `tautomer` row
+wanting a free ring nitrogen cannot fire while the mobile hydrogen sits on it, and the placement is
+what moves that hydrogen off.  So steps 2 to 6 run to a fixed point rather than once -- step 7.
+"""
+from ._hydrogens import implicify_hydrogens
+from ._isomers import standardize_isomers
+from ._protomers import neutralize
+from ._standardize import standardize
+from ..core import LOST, LogRecord, MoleculeContainer, recording
+
+
+__all__ = ['canonicalize']
+
+
+_RULE_ROUNDS = 'canonicalize:rounds'
+
+#: How many times steps 2 to 6 may be re-run before the pipeline gives up and says so.  Every shape
+#: measured converges in two, and the loop cannot cycle in principle: the `tautomer` rows move a
+#: hydrogen from oxygen or sulfur to nitrogen and never back, and the placement stage never makes an
+#: oxygen or a sulfur a site.  The cap is here so a rule table that breaks either half is reported as
+#: a loss rather than hanging.
+_ROUNDS_MAX = 5
+
+
+def canonicalize(molecule: MoleculeContainer, *, fix_tautomers: bool = True,
+                 keep_kekule: bool = False) -> bool:
+    """Bring `molecule` to the representation two drawings of one compound share.  Did it change?
+
+    Run before deduplicating by `canonical_bytes`, `__hash__` or `__eq__`, which otherwise answer "same
+    drawing" rather than "same compound".
+
+    `molecule.log` gets one record per thing done or declined, tagged with the stage that wrote it, so
+    `mol.log.by_stage('standardize')`, `mol.log.repaired()` and `mol.log.lost()` all answer afterwards.
+    `fix_tautomers` is forwarded to `standardize()`, and switching it off gives up part of the guarantee
+    (`Oc1ccccn1` and `O=c1cccc[nH]1` stop hashing equal); it deliberately does not reach
+    `standardize_isomers()`, which picks between two valid annular forms rather than repairing one.
+    `keep_kekule=True` costs a second kekulisation rather than a skipped `thiele()`, the placement stage
+    needing the aromatic form.
+
+    CHARGES ARE PAIRED OFF, not preserved atom by atom: glycine's zwitterion and its neutral drawing
+    share a key, because step 4 runs `neutralize()`.  The NET charge is untouched, so sodium acetate
+    stays sodium acetate -- there is no proton in it to move -- while ammonium acetate becomes acetic
+    acid and ammonia, both drawings of one salt.
+    """
+    # A refusal at the answer boundary, which is the only place one belongs.  `smiles()` returns
+    # whichever container its string describes, so a `>>` in a structure column arrives here as a
+    # reaction; without this the first read of `canonical_bytes` fails with an `AttributeError` naming
+    # a private attribute, which tells a caller nothing about what the pass takes.
+    if not isinstance(molecule, MoleculeContainer):
+        raise TypeError(f'canonicalize() takes a MoleculeContainer, got '
+                        f'{type(molecule).__name__}; a ReactionContainer has its own canonicalize(), '
+                        f'which runs this pass on each of its molecules')
+
+    # the bool is measured, not accumulated: steps 1 and 5 are a round trip, so summing the stages'
+    # own flags would report a change through both ends of a no-op on an already-canonical molecule.
+    before = molecule.canonical_bytes
+
+    # 1. Kekule first, so the group rules see definite bond orders.  An aromatic system with no Kekule
+    #    form does not stop the pipeline: it is reported and the rest still runs.  `kekule()` also
+    #    heals the hydrogen counts its own orders made derivable, so nothing here does that -- the
+    #    pipeline is literally the manual steps.
+    #    Nothing is recorded here about `result.unresolved`: the kekuliser writes a `LOST` record per
+    #    system to `molecule.log` itself, naming it in `atoms`, so a second one here would summarise an
+    #    event already reported.  `check_valence()` is still how those atoms are found.
+    molecule.kekule()
+
+    # 2. Repair the drawing.
+    standardize(molecule, fix_tautomers=fix_tautomers)
+
+    # 3. Explicit hydrogens are a `canonical_bytes` difference, so they have to go.
+    implicify_hydrogens(molecule)
+
+    # 4. Pair off the charges an acid/base row can pair off, so a zwitterion and its neutral drawing
+    #    hash equal.  AFTER step 3, because `acids.tsv` reads implicit hydrogens: a cation drawn with
+    #    hydrogen ATOMS is invisible to it until they have been folded in.  `keep_charge` stays at its
+    #    default -- the net charge is part of the compound, so a canonical form may move a proton but
+    #    never create or destroy one.  A quaternary ammonium keeps its counterion: it has no proton to
+    #    give, so the pass finds no donor and declines.
+    neutralize(molecule)
+
+    # 5. Back to the aromatic form, which is the representation callers compare.  Ahead of step 6,
+    #    because a mobile hydrogen is a property of the aromatic form: step 1's definite orders already
+    #    say where the hydrogen is, leaving the placement stage nothing to choose.
+    #    `result.refused` is not recorded on top of the pass's own records either, and for the same
+    #    reason -- with the severity the aromatiser itself states, which is `REFUSED` and not a loss.
+    molecule.thiele()
+
+    # 6. Canonical placement of mobile hydrogens and charges -- what makes the two N-H forms of
+    #    4-methylimidazole hash equal.  Not gated by `fix_tautomers`: that flag withholds local repair
+    #    rules, and this picks which of two valid drawings to keep rather than repairing one.
+    moved = standardize_isomers(molecule)
+
+    # 7. Steps 2 to 6 again, while the placement keeps unblocking a repair.  `Oc1[nH]cnc2nncc1-2` is
+    #    the shape: its mobile hydrogen sits on the one ring nitrogen the hydroxy-azine rows need free,
+    #    so step 2 declines, and by the time step 6 has moved it the repair is behind us -- the drawing
+    #    kept its hydroxy form and the same compound drawn the other way got the oxo form and a
+    #    different key.  Only the placement is re-entered from, since it is the one stage that can put
+    #    the molecule back into a shape an earlier stage would have acted on.
+    #
+    #    `kekule()` leads, and not for the reason step 1 does: the `tautomer` rows are written against
+    #    definite bond orders, so on the aromatic form step 5 left behind they match nothing at all and
+    #    re-running step 2 would be a guaranteed no-op.  Step 4 is re-entered only behind a repair,
+    #    which is the only thing that can hand it a charged site it has not already seen.
+    for _ in range(_ROUNDS_MAX):
+        if not moved:
+            break
+        molecule.kekule()
+        changed = standardize(molecule, fix_tautomers=fix_tautomers)
+        if changed:
+            implicify_hydrogens(molecule)
+            neutralize(molecule)
+        molecule.thiele()               # unconditional: step 5's form is what a caller compares, and
+        if not changed:                 # the kekulisation above has to be undone either way
+            break
+        moved = standardize_isomers(molecule)
+    else:
+        with recording(molecule, stage='canonicalize') as log:
+            log.append(LogRecord(_RULE_ROUNDS, (), f'repair and placement were still changing the '
+                                 f'molecule after {_ROUNDS_MAX} rounds; the pipeline stopped there, so '
+                                 f'this molecule is not a fixed point and two drawings of it may not '
+                                 f'share a key', LOST))
+
+    # 8. `keep_kekule` undoes step 5 rather than skipping it: skipping 5 would skip 6 with it, and the
+    #    flag would then decide which tautomer the caller gets.
+    if keep_kekule:
+        molecule.kekule()
+
+    return molecule.canonical_bytes != before

chython/chemistry/_counts.py

@@ -0,0 +1,81 @@
+# -*- coding: utf-8 -*-
+#
+#  Copyright 2026 Ramil Nugmanov <nougmanoff@protonmail.com>
+#  This file is part of chython.
+#
+#  chython is free software; you can redistribute it and/or modify
+#  it under the terms of the GNU Lesser General Public License as published by
+#  the Free Software Foundation; either version 3 of the License, or
+#  (at your option) any later version.
+#
+#  This program is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+#  GNU Lesser General Public License for more details.
+#
+#  You should have received a copy of the GNU Lesser General Public License
+#  along with this program; if not, see <https://www.gnu.org/licenses/>.
+#
+"""Rotatable bond and H-bond donor/acceptor counts, over `tables/rotatable.tsv` and `tables/hbond.tsv`.
+"""
+from ._standardize import LogRecord
+from ..core import recording
+from ._tables import hbond_rules_by_role, rotatable_rules_by_role
+
+
+def _mapped_bond(row, mapping):
+    """The (low, high) stable-id pair the row's :1 and :2 matched, order-normalised."""
+    a = mapping[row.numbers[1]]
+    b = mapping[row.numbers[2]]
+    return (a, b) if a < b else (b, a)
+
+
+def rotatable_bonds_count(molecule) -> int:
+    """Number of rotatable bonds, by the definition in `tables/rotatable.tsv`.
+
+    A bond is counted once however many ways a pattern maps onto it: row 1 is symmetric in its two
+    atoms and the matcher offers each bond in both directions, so the set is what makes this a count of
+    bonds rather than of matches.  Charged and radical atoms count.
+    """
+    by_role = rotatable_rules_by_role()
+    found = set()
+    excluded = []
+    for row in by_role['rotatable']:
+        for mapping in row.query.get_mapping(molecule):
+            found.add(_mapped_bond(row, mapping))
+    for row in by_role['exclude']:
+        for mapping in row.query.get_mapping(molecule):
+            bond = _mapped_bond(row, mapping)
+            if bond in found:
+                found.discard(bond)
+                excluded.append(LogRecord(row.id, bond, row.description))
+    with recording(molecule, stage='rotatable') as log:
+        log.extend(excluded)
+    return len(found)
+
+
+def hbond_atoms(molecule, role: str) -> frozenset:
+    """Stable ids of the atoms `tables/hbond.tsv` types with `role`.
+
+    Shared by the two counts and by `pharmacophore_invariants`, which is why it returns ids rather
+    than a number.
+    """
+    rules = hbond_rules_by_role()
+    if role not in rules:
+        raise ValueError(f'role {role!r} is not one of {tuple(rules)}')
+    out = set()
+    for row in rules[role]:
+        subject = row.numbers[1]          # the stable id of :1, from compile_smarts at load time
+        for mapping in row.query.get_mapping(molecule):
+            out.add(mapping[subject])
+    return frozenset(out)
+
+
+def hydrogen_bond_donors_count(molecule) -> int:
+    """Count of hydrogen bond donor ATOMS, over `tables/hbond.tsv`."""
+    return len(hbond_atoms(molecule, 'donor'))
+
+
+def hydrogen_bond_acceptors_count(molecule) -> int:
+    """Count of hydrogen bond acceptor ATOMS, over `tables/hbond.tsv`."""
+    return len(hbond_atoms(molecule, 'acceptor'))