cnotebook 1.2.0__py3-none-any.whl → 2.1.1__py3-none-any.whl

cnotebook/align.py

@@ -132,172 +132,188 @@ def fingerprint_maker(
 ########################################################################################################################
 
 class Aligner(metaclass=ABCMeta):
+    """Abstract base class for 2D molecule aligners.
+
+    Aligners transform molecule 2D coordinates to align with a reference
+    structure or pattern. Subclasses must implement :meth:`validate` and
+    :meth:`align` methods.
+
+    The aligner is callable - calling it with a molecule or display object
+    will validate and then align the molecule if validation passes.
     """
-    Base class for a 2D molecule aligner
-    """
+
     def __call__(self, mol_or_disp: oechem.OEMolBase | oedepict.OE2DMolDisplay) -> bool:
 
         # Get the molecule
         mol = mol_or_disp if isinstance(mol_or_disp, oechem.OEMolBase) else mol_or_disp.GetMolecule()
 
+        try:
+            log.debug("Aligner called for molecule: %s", oechem.OEMolToSmiles(mol) if mol else "None")
+        except TypeError:
+            log.debug("Aligner called for molecule: %s", mol)
+
         # If the molecule validates against the aligner
         if self.validate(mol):
-            return self.align(mol)
+            result = self.align(mol)
+            log.debug("Alignment result: %s", result)
+            return result
 
+        log.debug("Molecule failed validation, skipping alignment")
         return False
 
     @abstractmethod
     def align(self, mol: oechem.OEMolBase) -> bool:
+        """Align the molecule to the reference.
+
+        :param mol: Molecule to align (will be modified in place).
+        :returns: True if alignment was successful.
+        """
         raise NotImplementedError
 
     @abstractmethod
     def validate(self, mol: oechem.OEMolBase) -> bool:
+        """Validate that the molecule can be aligned.
+
+        :param mol: Molecule to validate.
+        :returns: True if the molecule can be aligned.
+        """
         raise NotImplementedError
 
 
-# FIXME: Bug reported OpenEye on 11/30/2025 regarding using OESubSearch matches in OEPrepareMultiAlignedDepiction
-# class OESubSearchAligner(Aligner):
-#     """
-#     2D molecule substructure alignment
-#     """
-#     def __init__(self, ref: oechem.OESubSearch | oechem.OEMolBase, **_kwargs):
-#
-#         # Reference molecule with 2D coordinates
-#         self.refmol = None
-#
-#         # In the future, make these configurable
-#         self.alignment_options = oedepict.OEAlignmentOptions()
-#
-#         if isinstance(ref, (oechem.OESubSearch, str)):
-#             self.ss = oechem.OESubSearch(ref)
-#
-#         else:
-#             self.refmol = oechem.OEGraphMol(ref)
-#             self.ss = oechem.OESubSearch(self.refmol, oechem.OEExprOpts_DefaultAtoms, oechem.OEExprOpts_DefaultBonds)
-#
-#     def validate(self, mol: oechem.OEMolBase) -> bool:
-#         """
-#         Validate that the molecule has a match to this substructure search
-#         :param mol: Molecule to search
-#         :return: True if there is a match to this substructure search
-#         """
-#         oechem.OEPrepareSearch(mol, self.ss)
-#         return self.ss.SingleMatch(mol)
-#
-#     def align(self, mol: oechem.OEMolBase) -> bool:
-#         """
-#         Align to this substructure trying the following
-#
-#         1. If we had a reference molecule, then try to maximize the alignment to that reference molecule using the
-#            OpenEye multiple aligner (this works VERY WELL even if there are multiple matches to the reference)
-#
-#         2. Standard aligned depiction, which fails if there are multiple matches to the substructure
-#
-#         :param mol: Molecule to align
-#         :return: True if the alignment was successful
-#         """
-#         ok = False
-#
-#         if self.refmol is not None:
-#             oechem.OEPrepareSearch(mol, self.ss)
-#             ok = oedepict.OEPrepareMultiAlignedDepiction(
-#                 mol,
-#                 self.refmol,
-#                 self.ss.Match(mol)
-#             )
-#
-#         if not ok:
-#             alignres = oedepict.OEPrepareAlignedDepiction(
-#                 mol,
-#                 self.ss,
-#                 self.alignment_options
-#             )
-#
-#             ok = alignres.IsValid()
-#
-#         return ok
-#
-#
-# FIXME: Bug reported OpenEye on 11/30/2025 regarding using OEMCSSearch matches in OEPrepareMultiAlignedDepiction
-# class OEMCSSearchAligner(Aligner):
-#     """
-#     2D molecule MCS alignment
-#     """
-#     def __init__(
-#             self,
-#             ref: oechem.OEMCSSearch | oechem.OEMolBase,
-#             *,
-#             func: Literal["atoms", "bonds", "atoms_and_cycles", "bonds_and_cycles"] = "bonds_cycles",
-#             min_atoms: int = 1,
-#             **_kwargs
-#     ):
-#
-#         self.refmol = None
-#
-#         # In the future, make these configurable
-#         self.alignment_options = oedepict.OEAlignmentOptions()
-#
-#         if isinstance(ref, oechem.OEMCSSearch):
-#             self.mcss = oechem.OEMCSSearch(ref)
-#
-#         else:
-#             self.refmol = ref.CreateCopy()
-#
-#             # Currently just using default parameters
-#             self.mcss = oechem.OEMCSSearch(oechem.OEMCSType_Approximate)
-#             self.mcss.Init(self.refmol, oechem.OEExprOpts_DefaultAtoms, oechem.OEExprOpts_DefaultBonds)
-#
-#             if func == "atoms":
-#                 self.mcss.SetMCSFunc(oechem.OEMCSMaxAtoms())
-#             elif func == "bonds":
-#                 self.mcss.SetMCSFunc(oechem.OEMCSMaxBonds())
-#             elif func == "atoms_and_cycles":
-#                 self.mcss.SetMCSFunc(oechem.OEMCSMaxAtomsCompleteCycles())
-#             elif func == "bonds_and_cycles":
-#                 self.mcss.SetMCSFunc(oechem.OEMCSMaxBondsCompleteCycles())
-#             else:
-#                 raise ValueError(f'Unknown MCS evaluation function name: {func}')
-#
-#             # Other options
-#             self.mcss.SetMinAtoms(min_atoms)
-#
-#     def validate(self, mol: oechem.OEMolBase) -> bool:
-#         """
-#         Validate that a maximum common substructure exists in a query molecule (within a threshold)
-#         :param mol: Molecule to search
-#         :return: True if the molecule contains the maximum common substructure
-#         """
-#         return self.mcss.SingleMatch(mol)
-#
-#     def align(self, mol: oechem.OEMolBase) -> bool:
-#         ok = False
-#
-#         if self.refmol is not None:
-#
-#             ok = oedepict.OEPrepareMultiAlignedDepiction(
-#                 mol,
-#                 self.refmol,
-#                 self.mcss.Match(mol)
-#             )
-#
-#         if not ok:
-#
-#             alignres = oedepict.OEPrepareAlignedDepiction(
-#                 mol,
-#                 self.mcss,
-#                 self.alignment_options
-#             )
-#
-#             ok = alignres.IsValid()
-#
-#         return ok
+class OESubSearchAligner(Aligner):
+    """Aligner using substructure search for 2D molecule alignment."""
+
+    def __init__(self, ref: oechem.OESubSearch | oechem.OEMolBase | str, **_kwargs):
+        """Create a substructure-based aligner.
+
+        :param ref: Reference for alignment. Can be:
+
+            - ``OESubSearch``: Pre-configured substructure search object.
+            - ``OEMolBase``: Molecule to use as substructure pattern.
+            - ``str``: SMARTS pattern string.
+
+        :param _kwargs: Additional keyword arguments (ignored, for API compatibility).
+        """
+        # Reference molecule with 2D coordinates
+        self.refmol = None
+
+        if isinstance(ref, (oechem.OESubSearch, str)):
+            self.ss = oechem.OESubSearch(ref)
+
+        else:
+            self.refmol = oechem.OEGraphMol(ref)
+            # Ensure the reference molecule has proper 2D depiction coordinates
+            oedepict.OEPrepareDepiction(self.refmol, False)
+            self.ss = oechem.OESubSearch(self.refmol, oechem.OEExprOpts_DefaultAtoms, oechem.OEExprOpts_DefaultBonds)
+
+    def validate(self, mol: oechem.OEMolBase) -> bool:
+        """
+        Validate that the molecule has a match to this substructure search.
+
+        :param mol: Molecule to search.
+        :returns: True if there is a match to this substructure search.
+        """
+        oechem.OEPrepareSearch(mol, self.ss)
+        return self.ss.SingleMatch(mol)
+
+    def align(self, mol: oechem.OEMolBase) -> bool:
+        """
+        Align molecule to the substructure pattern.
+
+        :param mol: Molecule to align.
+        :returns: True if the alignment was successful.
+        """
+        oechem.OEPrepareSearch(mol, self.ss)
+        alignres = oedepict.OEPrepareAlignedDepiction(mol, self.ss)
+        result = alignres.IsValid()
+        log.debug("OEPrepareAlignedDepiction (substructure) returned: %s", result)
+        return result
+
+
+class OEMCSSearchAligner(Aligner):
+    """Aligner using Maximum Common Substructure (MCS) search for 2D molecule alignment."""
+
+    def __init__(
+            self,
+            ref: oechem.OEMCSSearch | oechem.OEMolBase,
+            *,
+            func: Literal["atoms", "bonds", "atoms_and_cycles", "bonds_and_cycles"] = "bonds_and_cycles",
+            min_atoms: int = 1,
+            **_kwargs
+    ):
+        """Create an MCS-based aligner.
+
+        :param ref: Reference for alignment. Can be:
+
+            - ``OEMCSSearch``: Pre-configured MCS search object.
+            - ``OEMolBase``: Reference molecule for MCS calculation.
+
+        :param func: MCS evaluation function to use:
+
+            - ``"atoms"``: Maximize atom count.
+            - ``"bonds"``: Maximize bond count.
+            - ``"atoms_and_cycles"``: Maximize atoms while preserving complete cycles.
+            - ``"bonds_and_cycles"``: Maximize bonds while preserving complete cycles.
+
+        :param min_atoms: Minimum number of atoms required in the MCS.
+        :param _kwargs: Additional keyword arguments (ignored, for API compatibility).
+        """
+        self.refmol = None
+
+        if isinstance(ref, oechem.OEMCSSearch):
+            self.mcss = oechem.OEMCSSearch(ref)
+
+        else:
+            self.refmol = ref.CreateCopy()
+            # Ensure the reference molecule has proper 2D depiction coordinates
+            oedepict.OEPrepareDepiction(self.refmol, False)
+
+            # Currently just using default parameters
+            self.mcss = oechem.OEMCSSearch(oechem.OEMCSType_Approximate)
+            self.mcss.Init(self.refmol, oechem.OEExprOpts_DefaultAtoms, oechem.OEExprOpts_DefaultBonds)
+
+            if func == "atoms":
+                self.mcss.SetMCSFunc(oechem.OEMCSMaxAtoms())
+            elif func == "bonds":
+                self.mcss.SetMCSFunc(oechem.OEMCSMaxBonds())
+            elif func == "atoms_and_cycles":
+                self.mcss.SetMCSFunc(oechem.OEMCSMaxAtomsCompleteCycles())
+            elif func == "bonds_and_cycles":
+                self.mcss.SetMCSFunc(oechem.OEMCSMaxBondsCompleteCycles())
+            else:
+                raise ValueError(f'Unknown MCS evaluation function name: {func}')
+
+            # Other options
+            self.mcss.SetMinAtoms(min_atoms)
+
+    def validate(self, mol: oechem.OEMolBase) -> bool:
+        """
+        Validate that a maximum common substructure exists in a query molecule.
+
+        :param mol: Molecule to search.
+        :returns: True if the molecule contains the maximum common substructure.
+        """
+        return self.mcss.SingleMatch(mol)
+
+    def align(self, mol: oechem.OEMolBase) -> bool:
+        """
+        Align molecule using the maximum common substructure.
+
+        :param mol: Molecule to align.
+        :returns: True if the alignment was successful.
+        """
+        alignres = oedepict.OEPrepareAlignedDepiction(mol, self.mcss)
+        result = alignres.IsValid()
+        log.debug("OEPrepareAlignedDepiction (MCS) returned: %s", result)
+        return result
 
 
 class OEFingerprintAligner(Aligner):
+    """Aligner using fingerprint similarity and overlap for 2D molecule alignment.
+
+    This aligner uses molecular fingerprints to identify common structural
+    features between molecules and aligns based on the fingerprint overlap.
     """
-    Fingerprint aligner
-    """
-    # Just using the default tree fingerprint type for the alignment
 
     def __init__(
             self,
@@ -311,7 +327,20 @@ class OEFingerprintAligner(Aligner):
             atom_type: str | int = oegraphsim.OEFPAtomType_DefaultTreeAtom,
             bond_type: str | int = oegraphsim.OEFPBondType_DefaultTreeBond
     ):
-        # Simiarity threshold to apply alignment
+        """Create a fingerprint-based aligner.
+
+        :param refmol: Reference molecule for alignment.
+        :param threshold: Minimum Tanimoto similarity required to attempt alignment.
+        :param fptype: Fingerprint type ("path", "circular", or "tree").
+        :param num_bits: Number of bits in the fingerprint.
+        :param min_distance: Minimum path/radius distance for fingerprint.
+        :param max_distance: Maximum path/radius distance for fingerprint.
+        :param atom_type: Atom type for fingerprint generation. Can be an integer
+            constant or a string name (e.g., "default", "aromaticity").
+        :param bond_type: Bond type for fingerprint generation. Can be an integer
+            constant or a string name (e.g., "default", "inring").
+        """
+        # Similarity threshold to apply alignment
         self.threshold = threshold
 
         # Fingerprint maker
@@ -326,65 +355,100 @@ class OEFingerprintAligner(Aligner):
         )
 
         # Reference molecule and fingerprint
-        self.refmol = refmol.CreateCopy()
+        self.refmol = oechem.OEGraphMol(refmol)
         self.reffp = None
         self.fptype = None
 
         if self.refmol.IsValid():
+            # Ensure the reference molecule has proper 2D depiction coordinates (but retain existing coordinates)
+            oedepict.OEPrepareDepiction(self.refmol, False)
             self.reffp = self.make_fp(self.refmol)
             self.fptype = self.reffp.GetFPTypeBase()
 
+        else:
+            log.warning("Reference molecule for fingerprint-based alignment is not valid")
+
     def validate(self, mol: oechem.OEMolBase) -> bool:
         if self.reffp is None:
             return False
 
         fp = self.make_fp(mol)
-        return oegraphsim.OETanimoto(fp, self.reffp) >= self.threshold
+        sim = oegraphsim.OETanimoto(fp, self.reffp)
+        log.debug("Fingerprint Tanimoto similarity: %.3f (threshold: %.3f)", sim, self.threshold)
+        return sim >= self.threshold
 
     def align(self, mol: oechem.OEMolBase) -> bool:
         if self.fptype is None:
             return False
 
-        overlaps = oegraphsim.OEGetFPOverlap(mol, self.refmol, self.fptype)
-        return oedepict.OEPrepareMultiAlignedDepiction(mol, self.refmol, overlaps)
+        overlaps = oegraphsim.OEGetFPOverlap(self.refmol, mol, self.fptype)
+        result = oedepict.OEPrepareMultiAlignedDepiction(mol, self.refmol, overlaps)
 
+        log.debug("OEPrepareMultiAlignedDepiction (FP) returned: %s", result)
+        return result
 
-# Substructure aligners
+
+# Aligners registry
 _ALIGNERS = {
-    # "substructure": OESubSearchAligner,
+    "substructure": OESubSearchAligner,
     "fingerprint": OEFingerprintAligner,
-    # "mcss": OEMCSSearchAligner
+    "mcss": OEMCSSearchAligner
 }
 
 
 def create_aligner(
-        ref: oechem.OEMolBase,
-        method: Literal["fp", "fingerprint"] = None,
+        ref: oechem.OEMolBase | oechem.OESubSearch | oechem.OEMCSSearch | str,
+        method: Literal["substructure", "ss", "mcss", "fp", "fingerprint"] = None,
         **kwargs
 ) -> Aligner:
     """
-    Create an aligner for the given reference molecule.
-
-    Note: Only fingerprint alignment is currently supported. Substructure and MCS aligners
-    are disabled due to OpenEye bugs reported on 11/30/2025.
+    Create an aligner for the given reference.
 
-    :param ref: Alignment reference molecule
-    :param method: Alignment method (only "fp" or "fingerprint" supported)
-    :param kwargs: Keyword arguments for the OEFingerprintAligner
-    :return: Configured aligner instance
+    :param ref: Alignment reference - can be a molecule, substructure search, MCS search, or SMARTS string.
+    :param method: Alignment method ("substructure"/"ss", "mcss", "fingerprint"/"fp").
+        If None, the method is auto-detected based on the reference type.
+    :param kwargs: Keyword arguments passed to the aligner constructor.
+    :returns: Configured aligner instance.
     """
     # Normalize the method
     if method is not None:
         _method = method.lower()
 
-        if _method in ("fingerprint", "fp"):
+        if _method in ("substructure", "ss"):
+            method = "substructure"
+        elif _method in ("fingerprint", "fp"):
             method = "fingerprint"
+        elif _method == "mcss":
+            method = "mcss"
+        else:
+            raise ValueError(f'Unknown depiction alignment method: {method}. Valid options: "substructure"/"ss", "mcss", "fingerprint"/"fp".')
+
+    # Auto-detect method based on reference type if not specified
+    if isinstance(ref, str):
+        # SMARTS string - use substructure aligner
+        log.debug("Using substructure aligner for SMARTS string alignment reference")
+        return OESubSearchAligner(ref, **kwargs)
+
+    elif isinstance(ref, oechem.OESubSearch):
+        log.debug("Using substructure aligner for oechem.OESubSearch alignment reference")
+        return OESubSearchAligner(ref, **kwargs)
+
+    elif isinstance(ref, oechem.OEMCSSearch):
+        log.debug("Using MCS aligner for oechem.OEMCSSearch alignment reference")
+        return OEMCSSearchAligner(ref, **kwargs)
+
+    elif isinstance(ref, oechem.OEMolBase):
+        # Use specified method or default to fingerprint
+        if method == "substructure":
+            log.debug("Using substructure aligner for oechem.OEMolBase alignment reference")
+            return OESubSearchAligner(ref, **kwargs)
+        elif method == "mcss":
+            log.debug("Using MCS aligner for oechem.OEMolBase alignment reference")
+            return OEMCSSearchAligner(ref, **kwargs)
         else:
-            raise ValueError(f'Unknown depiction alignment method: {method}. Only "fingerprint"/"fp" is currently supported.')
+            # Default to fingerprint aligner for molecules
+            log.debug("Using fingerprint aligner for oechem.OEMolBase alignment reference")
+            return OEFingerprintAligner(ref, **kwargs)
 
-    # Only fingerprint aligner is currently available
-    if isinstance(ref, oechem.OEMolBase):
-        log.debug("Using fingerprint aligner for oechem.OEMolBase alignment reference")
-        return OEFingerprintAligner(ref, **kwargs)
     else:
-        raise TypeError(f'Unsupported alignment reference type: {type(ref)}. Only oechem.OEMolBase is currently supported.')
+        raise TypeError(f'Unsupported alignment reference type: {type(ref)}.')

cnotebook/context.py

@@ -30,10 +30,18 @@ T = TypeVar('T')
 
 
 class DeferredValue(Generic[T]):
+    """A value that can be deferred to the global CNotebook context.
+
+    When a value is set to ``DEFERRED``, accessing it will look up the
+    corresponding attribute from the global context instead.
     """
-    Value that can be deferred to the global CNotebook context
-    """
+
     def __init__(self, name: str, value: T | _Deferred):
+        """Create a deferred value.
+
+        :param name: Attribute name to look up in global context when deferred.
+        :param value: Initial value, or ``DEFERRED`` to use global context.
+        """
         self.name = name
         self._value = value
         self._initial_value = value
@@ -79,9 +87,14 @@ class DeferredValue(Generic[T]):
 
 
 class CNotebookContext:
+    """Context for rendering OpenEye objects in IPython/Jupyter environments.
+
+    This context controls how molecules and other OpenEye objects are rendered
+    as images. It supports deferred values that fall back to a global context.
+
+    :cvar supported_mime_types: Mapping of image formats to MIME types.
     """
-    Context in which to render OpenEye objects within IPython
-    """
+
     # Supported image formats and their MIME types for rendering
     supported_mime_types = {
         'png': 'image/png',
@@ -97,7 +110,8 @@ class CNotebookContext:
             min_height: float | None | _Deferred = 200.0,
             max_width: float | None | _Deferred = None,
             max_height: float | None | _Deferred = None,
-            structure_scale: int | _Deferred = oedepict.OEScale_Default * 0.9,
+            structure_scale: float | _Deferred = oedepict.OEScale_Default * 0.6,
+            atom_label_font_scale: float | _Deferred = 1.0,
             title_font_scale: float | _Deferred = 1.0,
             image_format: str | _Deferred = "png",
             bond_width_scaling: bool | _Deferred = False,
@@ -105,16 +119,24 @@ class CNotebookContext:
             scope: Literal["local", "global"] = "global",
             title: bool = True
     ):
-        """
-        Create the render context
-        :param width: Image width (default of None means it is determined by the structure scale)
-        :param height: Image height (default of None means it is determined by the structure scale)
-        :param min_width: Minimum image width (prevents tiny images)
-        :param min_height: Minimum image height (prevents tiny images)
-        :param structure_scale: Structure scale
-        :param title_font_scale: Font scaling (valid is 0.5 to 2.0)
-        :param image_format: Image format
-        :param bond_width_scaling: Bond width scaling
+        """Create a rendering context.
+
+        :param width: Image width in pixels. If 0, determined by structure scale.
+        :param height: Image height in pixels. If 0, determined by structure scale.
+        :param min_width: Minimum image width in pixels (prevents tiny images).
+        :param min_height: Minimum image height in pixels (prevents tiny images).
+        :param max_width: Maximum image width in pixels, or None for no limit.
+        :param max_height: Maximum image height in pixels, or None for no limit.
+        :param structure_scale: Scale factor for structure rendering.
+        :param atom_label_font_scale: Scale factor for atom labels (0.5 to 2.0).
+        :param title_font_scale: Scale factor for title font (0.5 to 2.0).
+        :param image_format: Output image format ("png" or "svg").
+        :param bond_width_scaling: Whether to scale bond widths with structure scale.
+        :param callbacks: List of callables to invoke on OE2DMolDisplay before rendering.
+            Each callback receives the display object and can modify it.
+        :param scope: Context scope - "local" defers unset values to global context,
+            "global" uses defaults directly.
+        :param title: Whether to display molecule titles.
         """
         self._width = DeferredValue[float]("width", width)
         self._height = DeferredValue[float]("height", height)
@@ -122,7 +144,8 @@ class CNotebookContext:
         self._min_width = DeferredValue[float | None]("min_width", min_width)
         self._max_width = DeferredValue[float | None]("max_width", max_width)
         self._max_height = DeferredValue[float | None]("max_height", max_height)
-        self._structure_scale = DeferredValue[int]("structure_scale", structure_scale)
+        self._structure_scale = DeferredValue[float]("structure_scale", structure_scale)
+        self._atom_label_font_scale = DeferredValue[float | None]("atom_label_font_scale", atom_label_font_scale)
         self._title_font_scale = DeferredValue[float]("title_font_scale", title_font_scale)
         self._image_format = DeferredValue[str]("image_format", image_format)
         self._bond_width_scaling = DeferredValue[bool]("bond_width_scaling", bond_width_scaling)
@@ -209,13 +232,21 @@ class CNotebookContext:
         self._min_height.set(value)
 
     @property
-    def structure_scale(self) -> int:
+    def structure_scale(self) -> float:
         return self._structure_scale.get()
 
     @structure_scale.setter
-    def structure_scale(self, value: int) -> None:
+    def structure_scale(self, value: float) -> None:
         self._structure_scale.set(value)
 
+    @property
+    def atom_label_font_scale(self) -> float:
+        return self._atom_label_font_scale.get()
+
+    @atom_label_font_scale.setter
+    def atom_label_font_scale(self, value: float) -> None:
+        self._atom_label_font_scale.set(value)
+
     @property
     def title_font_scale(self) -> float:
         return self._title_font_scale.get()
@@ -275,6 +306,7 @@ class CNotebookContext:
         opts.SetScale(self.structure_scale)
         opts.SetTitleFontScale(self.title_font_scale)
         opts.SetBondWidthScaling(self.bond_width_scaling)
+        opts.SetAtomLabelFontScale(self.atom_label_font_scale)
 
         if not self.title:
             opts.SetTitleLocation(oedepict.OETitleLocation_Hidden)

cnotebook/grid/__init__.py

@@ -0,0 +1,56 @@
+"""Interactive molecule grid for Jupyter and Marimo notebooks."""
+
+from cnotebook.grid.grid import MolGrid
+from typing import Iterable, List, Optional, Union
+
+
+def molgrid(
+    mols: Iterable,
+    *,
+    title: Union[bool, str, None] = True,
+    tooltip_fields: Optional[List[str]] = None,
+    n_items_per_page: int = 24,
+    width: int = 200,
+    height: int = 200,
+    image_format: str = "svg",
+    select: bool = True,
+    information: bool = True,
+    data: Optional[Union[str, List[str]]] = None,
+    search_fields: Optional[List[str]] = None,
+    name: Optional[str] = None,
+) -> MolGrid:
+    """Create an interactive molecule grid.
+
+    :param mols: Iterable of OpenEye molecule objects.
+    :param title: Title display mode. True uses molecule's title, a string
+        specifies a field name, None/False hides titles.
+    :param tooltip_fields: List of fields for tooltip.
+    :param n_items_per_page: Molecules per page.
+    :param width: Image width in pixels (default 200).
+    :param height: Image height in pixels (default 200).
+    :param image_format: "svg" or "png" (default "svg").
+    :param select: Enable selection checkboxes.
+    :param information: Enable info button with hover tooltip.
+    :param data: Column(s) to display in info tooltip. If None, auto-detects
+        simple types (string, int, float) from DataFrame.
+    :param search_fields: Fields for text search.
+    :param name: Grid identifier.
+    :returns: MolGrid instance.
+    """
+    return MolGrid(
+        mols,
+        title=title,
+        tooltip_fields=tooltip_fields,
+        n_items_per_page=n_items_per_page,
+        width=width,
+        height=height,
+        image_format=image_format,
+        select=select,
+        information=information,
+        data=data,
+        search_fields=search_fields,
+        name=name,
+    )
+
+
+__all__ = ["MolGrid", "molgrid"]