context

class cnotebook.context.DeferredValue(name, value)[source]

Bases: 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.

Parameters:

  • name (str)

  • value (T | _Deferred)

__init__(name, value)[source]

Create a deferred value.

Parameters:

  • name (str) – Attribute name to look up in global context when deferred.

  • value (T | _Deferred) – Initial value, or DEFERRED to use global context.

reset()[source]

Reset this deferred value to the initial value (when the object was created)

property is_deferred: bool

Check if the value is deferred to the global context :return: True if the value is deferred to the global

get()[source]

If the value is DEFERRED then we defer to the local context :return: Value

Return type:

T

set(value)[source]

Set a value (we never set the global context) :param value: Value to set

Parameters:

value (T | _Deferred)

Return type:

None

class cnotebook.context.CNotebookContext(*, width=0, height=0, min_width=200.0, min_height=200.0, max_width=None, max_height=None, structure_scale=22.5, atom_label_font_scale=1.0, title_font_scale=1.0, image_format='png', bond_width_scaling=False, callbacks=None, scope='global', title=True, max_heavy_atoms=100)[source]

Bases: object

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.

Variables:

supported_mime_types – Mapping of image formats to MIME types.

Parameters:

  • width (float | _Deferred)

  • height (float | _Deferred)

  • min_width (float | None | _Deferred)

  • min_height (float | None | _Deferred)

  • max_width (float | None | _Deferred)

  • max_height (float | None | _Deferred)

  • structure_scale (float | _Deferred)

  • atom_label_font_scale (float | _Deferred)

  • title_font_scale (float | _Deferred)

  • image_format (str | _Deferred)

  • bond_width_scaling (bool | _Deferred)

  • callbacks (Iterable[Callable[[OE2DMolDisplay], None]] | None | _Deferred)

  • scope (Literal['local', 'global'])

  • title (bool)

  • max_heavy_atoms (int | None | _Deferred)

supported_mime_types = {'png': 'image/png', 'svg': 'image/svg+xml'}
__init__(*, width=0, height=0, min_width=200.0, min_height=200.0, max_width=None, max_height=None, structure_scale=22.5, atom_label_font_scale=1.0, title_font_scale=1.0, image_format='png', bond_width_scaling=False, callbacks=None, scope='global', title=True, max_heavy_atoms=100)[source]

Create a rendering context.

Parameters:

  • width (float | _Deferred) – Image width in pixels. If 0, determined by structure scale.

  • height (float | _Deferred) – Image height in pixels. If 0, determined by structure scale.

  • min_width (float | None | _Deferred) – Minimum image width in pixels (prevents tiny images).

  • min_height (float | None | _Deferred) – Minimum image height in pixels (prevents tiny images).

  • max_width (float | None | _Deferred) – Maximum image width in pixels, or None for no limit.

  • max_height (float | None | _Deferred) – Maximum image height in pixels, or None for no limit.

  • structure_scale (float | _Deferred) – Scale factor for structure rendering.

  • atom_label_font_scale (float | _Deferred) – Scale factor for atom labels (0.5 to 2.0).

  • title_font_scale (float | _Deferred) – Scale factor for title font (0.5 to 2.0).

  • image_format (str | _Deferred) – Output image format (“png” or “svg”).

  • bond_width_scaling (bool | _Deferred) – Whether to scale bond widths with structure scale.

  • callbacks (Iterable[Callable[[OE2DMolDisplay], None]] | None | _Deferred) – List of callables to invoke on OE2DMolDisplay before rendering. Each callback receives the display object and can modify it.

  • scope (Literal['local', 'global']) – Context scope - “local” defers unset values to global context, “global” uses defaults directly.

  • title (bool) – Whether to display molecule titles.

  • max_heavy_atoms (int | None | _Deferred) – Maximum number of heavy atoms for a molecule to be rendered. Molecules exceeding this limit show a placeholder image instead. Set to None to disable the limit.

property width: float
property height: float
property min_width: float | None
property max_width: float | None
property max_height: float | None
property min_height: float | None
property structure_scale: float
property atom_label_font_scale: float
property title_font_scale: float
property bond_width_scaling: bool
property image_format: str
property scope: Literal['global', 'local']
property callbacks: tuple[Callable[[OE2DMolDisplay], None], ...]
reset_callbacks()[source]
Return type:

None

property title: bool
property max_heavy_atoms: int | None
property image_mime_type: str
property display_options: OE2DMolDisplayOptions
add_callback(callback)[source]

Add a callback that modifies an oedepict.OE2DMolDisplay to the current context :param callback: Callback to add

Parameters:

callback (Callable[[OE2DMolDisplay], None])

create_molecule_display(mol, min_height=None, min_width=None)[source]

Create a molecule display.

Min/max width/height are only enforced when structure_scale is OEScale_AutoScale. In that mode, the canvas determines the scale, so clamping the canvas to min/max bounds is meaningful. In fixed-scale mode, the structure determines the canvas, so clamping would add whitespace padding (for min) or crop (for max) without changing the drawn structure — users who want bounded sizes should use AutoScale.

Parameters:

  • mol (OEMolBase) – Molecule

  • min_height (float | None) – Minimum image height (only applied under AutoScale)

  • min_width (float | None) – Minimum image width (only applied under AutoScale)

Returns:

Molecule display

Return type:

OE2DMolDisplay

reset()[source]

Reset the rendering context to default values

Return type:

None

copy()[source]

Copy this object :return: Copy of the object

Return type:

CNotebookContext

cnotebook.context.pass_cnotebook_context(func)[source]

Decorator that passes a copy of the current molecule render context :param func: Function to decorate :return: Decorated function

cnotebook.context.create_local_context(width=_Deferred.DEFERRED, height=_Deferred.DEFERRED, min_width=_Deferred.DEFERRED, min_height=_Deferred.DEFERRED, max_width=_Deferred.DEFERRED, max_height=_Deferred.DEFERRED, structure_scale=_Deferred.DEFERRED, title_font_scale=_Deferred.DEFERRED, image_format=_Deferred.DEFERRED, bond_width_scaling=_Deferred.DEFERRED, callbacks=_Deferred.DEFERRED, max_heavy_atoms=_Deferred.DEFERRED)[source]
Parameters:

  • width (float | _Deferred)

  • height (float | _Deferred)

  • min_width (float | None | _Deferred)

  • min_height (float | None | _Deferred)

  • max_width (float | None | _Deferred)

  • max_height (float | None | _Deferred)

  • structure_scale (float | _Deferred)

  • title_font_scale (float | _Deferred)

  • image_format (str | _Deferred)

  • bond_width_scaling (bool | _Deferred)

  • callbacks (Iterable[Callable[[OE2DMolDisplay], None]] | None | _Deferred)

  • max_heavy_atoms (int | None | _Deferred)

Return type:

CNotebookContext

cnotebook.context.get_series_context(metadata, save=False)[source]

Get the series context, else wrap the global context into a series context. This looks for the key “cnotebook” in the metadta. :param metadata: Series metadata :param save: Whether to save any new metadata object that we create :return: Series rendering context

Parameters:
Return type:

CNotebookContext

CNotebookContext Class

The CNotebookContext class manages global rendering settings for molecule visualization.

Usage

import cnotebook

# Get the global context
ctx = cnotebook.cnotebook_context.get()

# Modify settings
ctx.width = 300
ctx.height = 300
ctx.image_format = "svg"

# Reset to defaults
ctx.reset()

Configuration Options

Image Dimensions

  • width: Default image width in pixels (default: 250)

  • height: Default image height in pixels (default: 250)

  • max_width: Maximum allowed width (default: 1200)

  • max_height: Maximum allowed height (default: 800)

Output Format

  • image_format: Output format, either “png” or “svg” (default: “png”)

Scaling

  • scale: Scaling factor for depictions (default: 1.0)