API Reference

This section contains the complete API reference for CMX.

Core Module

The main module provides the global doc object and data utilities.

Backends

CMX supports multiple output backends for different use cases.

Markdown Backend

The primary backend for generating markdown documents.

The CommonMark document – the object exported as cmx.doc.

A CommonMark is an Article (so it inherits the component factories: table, image, figure, row, video, savefig) plus the live-document machinery: the @ / | / call operators for adding markdown, with doc: source capture, and flush to write out.

class cmx.backends.markdown.CommonMark(filename=None, overwrite=True, root=None, prefix=None, logger=None)

Bases: Article

counter = 0

property hide

with doc.hide: runs its body but does not capture the source as a code block – handy for boilerplate you want to execute but not show.

property skip

with doc.skip: skips execution of its body entirely.

Implemented via frame tracing (see SkipContextManager); this can interfere with debuggers such as PyCharm’s pydev.

config(filename=None, overwrite=True, src_prefix=None, logger=None)

new(filename=None, **kwargs)

property filename

write(text, overwrite=None)

clear()

md(*snippets, dedent=True, **kwargs)

Add markdown text: doc("# Title").

pre(text, lang=None, **kwargs)

yaml(data, **kwargs)

csv(csv, show_index=False, **kwargs)

print(*args, sep=' ', end='\n')

flush(*args)

class cmx.backends.markdown.Github(filename=None, overwrite=True, root=None, prefix=None, logger=None)

Bases: CommonMark

Uses tables for the layout.

class cmx.backends.markdown.Gist(filename=None, overwrite=True, root=None, prefix=None, logger=None)

Bases: CommonMark

Saves everything inside a folder.

Components

Base components used across all backends.

Render components for the CMX markdown backend.

Each component knows how to render itself as Markdown (_md) and HTML (_html). Components form a tree: an Article holds children, some of which (Table, FigureRow, Row) hold children of their own.

This module is dependency-inverted the simple way: there is no class registry or __getattribute__ proxy. Parents create their children by calling the component classes directly, and the optional file-writing logger is threaded down explicitly. Anything that needs heavy third-party libraries (numpy, PIL, pyyaml) imports them lazily so import cmx stays cheap.

cmx.backends.components.attrs(class_name=None, **kwargs)

cmx.backends.components.styles(**kwargs)

class cmx.backends.components.Component(tag=None, children=None, logger=None, **kwargs)

Bases: object

Base node in the document tree.

A component renders to Markdown via _md and to HTML via _html. The default implementation emits a generic <tag>...children...</tag>; most subclasses override one or both properties.

data = None

class_name = None

tag = None

now(fmt=None)

class cmx.backends.components.Container(tag=None, children=None, logger=None, **kwargs)

Bases: Component

A holder that is rendered by its parent, never on its own.

class cmx.backends.components.Div(tag=None, children=None, logger=None, **kwargs)

Bases: Component

tag = 'div'

class cmx.backends.components.Span(*args, sep=' ', dedent=None, **kwargs)

Bases: Component

tag = 'span'

cmx.backends.components.Text

alias of Span

class cmx.backends.components.Bold(*args, sep=' ', dedent=None, **kwargs)

Bases: Span

tag = 'b'

class cmx.backends.components.Pre(text, lang=None, **kwargs)

Bases: Component

tag = 'pre'

class cmx.backends.components.Link(href='', text='', **kwargs)

Bases: Component

tag = 'span'

class cmx.backends.components.Img(src=None, zoom=None, alt=None, **kwargs)

Bases: Component

tag = 'img'

zoom = None

class cmx.backends.components.Image(image=None, src=None, logger=None, normalize=False, **kwargs)

Bases: Img

An image that can reference a file, save data to a file, or inline base64.

• src only -> reference the file path.

• src + image + a logger -> write the file, then reference it.

• image only -> inline the data as a base64 data: URI.

data = None

property base64

class cmx.backends.components.Video(src=None, width=320, height=240, controls=True, **kwargs)

Bases: Component

cmx.backends.components.video(frames=None, *, src, logger=None, **kwargs)

Save video frames (if given) and return the matching component.

.gif sources render as an Image; everything else as a Video.

class cmx.backends.components.Figure(image=None, src=None, title=None, caption=None, logger=None, **kwargs)

Bases: Component

tag = 'div'

class cmx.backends.components.Savefig(key, caption=None, width=None, height=None, zoom=None, logger=None, **kwargs)

Bases: Figure

Save the current matplotlib figure to key and reference it inline.

key is the destination path (an optional ?... query suffix is stripped before writing, so it can double as a cache-buster in the src). title/caption/width/height/zoom control how the figure is displayed; every other keyword (dpi, bbox_inches, transparent, facecolor, format …) is forwarded untouched to matplotlib’s savefig and is not leaked into the <img> tag.

class cmx.backends.components.Row(wrap=False, styles=None, logger=None, **kwargs)

Bases: Component

styles = {'display': 'flex', 'flex_direction': 'row', 'item_align': 'center'}

class cmx.backends.components.FigureRow(header=None, n_cols=None, logger=None, **kwargs)

Bases: Container

A horizontal band of figures rendered by its parent Table as up to three Markdown rows: titles, images, and captions (empty bands are dropped).

figure(image=None, src=None, title=None, caption=None, **kwargs)

video(frames=None, src=None, title=None, caption=None, **kwargs)

column(title=None, text=None, footer=None)

savefig(key, title=None, caption=None, **kwargs)

property rows

class cmx.backends.components.Table(table=None, show_index=None, format='github', sep=',*', logger=None, **kwargs)

Bases: Component

A Markdown/HTML table.

Pass tabular data (a DataFrame, CSV string, or anything pandas accepts) for a data table, or build a figure grid with figure_row().

data = None

figure_row(**kwargs)

class cmx.backends.components.Html(tag=None, children=None, logger=None, **kwargs)

Bases: _Factory, Component

tag = 'body'

class cmx.backends.components.Article(tag=None, children=None, logger=None, **kwargs)

Bases: Html

tag = 'article'

class_name = 'commonmark'

class cmx.backends.components.Print(*args, sep=' ', end='\n', **kwargs)

Bases: Pre

HTML Backend

HTML output support.

LaTeX Backend

LaTeX output support for academic papers and publications.

Utilities

Utils Module

Helper functions and utilities.

class cmx.utils.F(fn=None)

Bases: object

Functional notation wrapper - allows using @ operator for function composition

Usage: - F @ function - wraps a function - (F @ function)(args) - calls the wrapped function

cmx.utils.is_empty(line)

cmx.utils.get_indent(text)

cmx.utils.dedent(text)

cmx.utils.get_block(filename, line_number)

cmx.utils.is_subclass(obj, cls)

cmx.utils.to_snake(name)

class cmx.utils.SimpleLogger(root=None, prefix=None)

Bases: object

A simple logger replacement for ml-logger functionality used in cmx.

This provides basic file I/O operations for saving images, videos, and text that were previously handled by ml-logger.

save_image(image, filename, normalize=False)

Save an image to disk.

Args:

image: Image array (numpy array or PIL Image) filename: Path where to save the image normalize: Whether to normalize the image values

save_video(frames, filename)

Save video frames to a file.

Args:

frames: List of image frames (numpy arrays) filename: Path where to save the video

savefig(filename, **kwargs)

Save the current matplotlib figure.

Args:

filename: Path where to save the figure kwargs: Additional arguments passed to matplotlib’s savefig

log_text(text, filename, overwrite=False)

Log text to a file.

Args:

text: Text content to write filename: Path where to save the text overwrite: If True, overwrite the file; if False, append

get_dash_url()

Get a URL for the dashboard (returns file:// URL for local files).

load_json(filename)

Load a JSON file.

Args:

filename: Path to the JSON file

Returns:

Parsed JSON data

load_file(filename)

Load a file and return a file-like object.

Args:

filename: Path to the file

Returns:

File-like object (BytesIO)

static now()

Get the current timestamp as a string.

Returns:

ISO formatted timestamp string

job_started()

Mark a job as started (no-op for simple logger).

Data Module

Data processing utilities.

Context Managers

Advanced context management utilities.

exception cmx.with_hack.SkipException

Bases: Exception

class cmx.with_hack.SkipContextManager(skip)

Bases: object

trace(frame, event, arg)

Server

Optional server components for live document serving.

async cmx.server.echo(request, ws)

Parameters:

• request (sanic.Request)

• ws (sanic.Websocket)

async cmx.server.log(request, ws)

Parameters:

• request (sanic.Request)

• ws (sanic.Websocket)