cnotebook

CNotebook - Ergonomic chemistry visualization in notebooks.

Auto-detects available backends (Pandas/Polars) and environments (Jupyter/Marimo). Only requires openeye-toolkits; all other dependencies are optional.

class cnotebook.LevelSpecificFormatter[source]

Bases: Formatter

A logging formatter that uses level-specific formats.

Uses a simple format for INFO and above, and includes the level name for DEBUG messages to help distinguish debug output.

Variables:

  • NORMAL_FORMAT – Format string for INFO and above.

  • DEBUG_FORMAT – Format string for DEBUG level.

NORMAL_FORMAT = '%(message)s'
DEBUG_FORMAT = '%(levelname)s: %(message)s'
__init__()[source]

Create the formatter with the normal format as default.

format(record)[source]

Format the specified record as text.

The record’s attribute dictionary is used as the operand to a string formatting operation which yields the returned string. Before formatting the dictionary, a couple of preparatory steps are carried out. The message attribute of the record is computed using LogRecord.getMessage(). If the formatting string uses the time (as determined by a call to usesTime(), formatTime() is called to format the event time. If there is exception information, it is formatted using formatException() and appended to the message.

Parameters:

record (LogRecord)

Return type:

str

cnotebook.enable_debugging()[source]

Convenience function for enabling the debug log.

class cnotebook.CNotebookEnvInfo(pandas_version, polars_version, ipython_version, marimo_version, molgrid_available, c3d_available, is_jupyter_notebook, is_marimo_notebook)[source]

Bases: object

Environment information for CNotebook.

This class provides read-only access to detected backend and environment availability. A singleton instance is created at module load time and can be retrieved via get_env().

All properties are read-only to ensure consistency throughout the application lifecycle. Availability is determined by checking if the version string is non-empty.

Parameters:

  • pandas_version (str)

  • polars_version (str)

  • ipython_version (str)

  • marimo_version (str)

  • molgrid_available (bool)

  • c3d_available (bool)

  • is_jupyter_notebook (bool)

  • is_marimo_notebook (bool)

__init__(pandas_version, polars_version, ipython_version, marimo_version, molgrid_available, c3d_available, is_jupyter_notebook, is_marimo_notebook)[source]

Create environment info (typically called once at module load).

Parameters:

  • pandas_version (str) – Detected Pandas version string, or empty if unavailable.

  • polars_version (str) – Detected Polars version string, or empty if unavailable.

  • ipython_version (str) – Detected IPython version string, or empty if unavailable.

  • marimo_version (str) – Detected Marimo version string, or empty if unavailable.

  • molgrid_available (bool) – Whether MolGrid widget dependencies are available.

  • c3d_available (bool) – Whether C3D viewer dependencies are available.

  • is_jupyter_notebook (bool) – Whether running in a Jupyter notebook environment.

  • is_marimo_notebook (bool) – Whether running in a Marimo notebook environment.

property pandas_available: bool

Whether Pandas and OEPandas are available.

property pandas_version: str

Pandas version string, or empty string if not available.

property polars_available: bool

Whether Polars and OEPolars are available.

property polars_version: str

Polars version string, or empty string if not available.

property ipython_available: bool

Whether IPython is available and active.

property ipython_version: str

IPython version string, or empty string if not available.

property marimo_available: bool

Whether Marimo is available and running in notebook mode.

property marimo_version: str

Marimo version string, or empty string if not available.

property molgrid_available: bool

Whether MolGrid is available (requires anywidget).

property c3d_available: bool

Whether C3D viewer is available (requires anywidget).

property is_jupyter_notebook: bool

Whether running in a Jupyter notebook environment.

property is_marimo_notebook: bool

Whether running in a Marimo notebook environment.

cnotebook.get_env()[source]

Get environment information for CNotebook.

Returns a singleton instance containing information about available backends and environments. The environment is detected once at module load time and the same object is returned on subsequent calls.

Returns:

CNotebookEnvInfo instance with read-only properties.

Return type:

CNotebookEnvInfo

Example:

env = cnotebook.get_env()
if env.pandas_available:
    print(f"Pandas {env.pandas_version} is available")
cnotebook.display(obj, ctx=None)[source]

Display an OpenEye molecule, display object, or DataFrame in the current notebook environment.

This function provides a unified way to display chemistry objects in both Jupyter and Marimo notebooks. It automatically detects the environment and uses the appropriate display mechanism.

Parameters:

  • obj – Object to display. Can be: - oechem.OEMolBase - OpenEye molecule - oedepict.OE2DMolDisplay - OpenEye display object - pandas.DataFrame - Pandas DataFrame (if pandas available) - polars.DataFrame - Polars DataFrame (if polars available)

  • ctx (CNotebookContext | None) – Optional rendering context. Only applied to molecules and display objects, not DataFrames. If None, uses the global context.

Returns:

A displayable object appropriate for the current environment.

Raises:

TypeError – If the object type is not supported.

Example:

import cnotebook
from openeye import oechem

mol = oechem.OEGraphMol()
oechem.OESmilesToMol(mol, "c1ccccc1")

# Display with default context
cnotebook.display(mol)

# Display with custom context
ctx = cnotebook.cnotebook_context.get().copy()
ctx.width = 300
ctx.height = 300
cnotebook.display(mol, ctx=ctx)

Package Overview

The cnotebook package provides automatic molecule rendering in Jupyter and Marimo notebooks. Simply importing the package registers formatters for OpenEye molecule objects.

Usage

import cnotebook
from openeye import oechem

mol = oechem.OEGraphMol()
oechem.OESmilesToMol(mol, "c1ccccc1")
mol  # Automatically rendered as chemical structure

Module Attributes

cnotebook.cnotebook_context

Global context variable for rendering configuration. Access the context using cnotebook_context.get().

Environment Detection

Use the get_env() function to retrieve environment information:

import cnotebook

env = cnotebook.get_env()
if env.pandas_available:
    print(f"Pandas {env.pandas_version} is available")