notebookx-py 0.1.1

Fast, lightweight notebook conversion library

notebookx

A fast, lightweight notebook conversion library written in Rust with Python bindings.

notebookx is a Rust-based alternative to Python's nbconvert, providing fast notebook conversion between formats like .ipynb and percent format (.pct.py).

Features

• Fast: Written in Rust for maximum performance
• Multiple interfaces: Use as a Rust library, CLI tool (nbx), or Python package
• Format conversion: Convert between ipynb and percent format
• Notebook cleaning: Strip outputs, execution counts, and metadata for version control
• Cross-platform: Works on Linux, macOS, and Windows

Installation

Python

pip install notebookx-py

Rust

Add to your Cargo.toml:

[dependencies]
notebookx = "0.1"

CLI

cargo install notebookx --features cli

Usage

Python

from notebookx import Notebook, Format, CleanOptions

# Load a notebook
nb = Notebook.from_file("example.ipynb")

# Convert to percent format
nb.to_file("example.pct.py")

# Or get as string
percent_content = nb.to_string(Format.Percent)

# Clean notebook for version control
clean_nb = nb.clean(CleanOptions(
    remove_outputs=True,
    remove_execution_counts=True,
))
clean_nb.to_file("clean.ipynb")

# Convenience functions
from notebookx import convert, clean_notebook

convert("input.ipynb", "output.pct.py")
clean_notebook("notebook.ipynb", remove_outputs=True)

CLI (nbx)

# Convert ipynb to percent format
nbx convert notebook.ipynb --to notebook.pct.py

# Convert percent to ipynb
nbx convert notebook.pct.py --to notebook.ipynb

# Clean a notebook (remove outputs)
nbx clean notebook.ipynb --output clean.ipynb --remove-outputs

# Clean in place
nbx clean notebook.ipynb --in-place --remove-outputs --remove-execution-counts

# Use stdin/stdout
cat notebook.ipynb | nbx convert - --from-fmt ipynb --to - --to-fmt percent

Rust

use notebookx::{Notebook, NotebookFormat, CleanOptions};

// Parse from file
let content = std::fs::read_to_string("example.ipynb")?;
let notebook = NotebookFormat::Ipynb.parse(&content)?;

// Convert to percent format
let percent = NotebookFormat::Percent.serialize(&notebook)?;

// Clean notebook
let options = CleanOptions {
    remove_outputs: true,
    remove_execution_counts: true,
    ..Default::default()
};
let clean = notebook.clean(&options);

// Save to file
let output = NotebookFormat::Ipynb.serialize(&clean)?;
std::fs::write("clean.ipynb", output)?;

Supported Formats

Format	Extension	Description
ipynb	.ipynb	Standard Jupyter notebook format (JSON)
percent	.pct.py	Percent format used by Jupytext, VSCode, etc.

Clean Options

When cleaning notebooks, you can control what gets removed:

Option	Description
remove_outputs	Remove all cell outputs
remove_execution_counts	Reset execution counts to null
remove_cell_metadata	Remove cell-level metadata
remove_notebook_metadata	Remove notebook-level metadata
remove_kernel_info	Remove kernel specification
preserve_cell_ids	Keep cell IDs (default: regenerate)
remove_output_metadata	Remove metadata from outputs
remove_output_execution_counts	Remove execution counts from outputs

Presets

Python:

# For version control (removes cell metadata, execution counts, and output metadata)
# Preserves outputs so rendered content remains visible
options = CleanOptions.for_vcs()

# Strip everything (including outputs)
options = CleanOptions.strip_all()

CLI Reference

nbx convert

Convert notebooks between formats.

nbx convert <INPUT> --to <OUTPUT> [OPTIONS]

Options:
  --from-fmt <FORMAT>  Input format (ipynb, percent). Inferred from extension if not specified.
  --to-fmt <FORMAT>    Output format (ipynb, percent). Inferred from extension if not specified.
  -h, --help           Print help

nbx clean

Clean notebooks by removing outputs and metadata.

nbx clean <INPUT> [OPTIONS]

Options:
  -o, --output <FILE>           Output file (default: stdout)
  -i, --in-place                Modify file in place
  -O, --remove-outputs          Remove all outputs
  -e, --remove-execution-counts Remove execution counts
  --remove-cell-metadata        Remove cell metadata
  --remove-notebook-metadata    Remove notebook metadata
  --remove-kernel-info          Remove kernel specification
  -h, --help                    Print help

Development

Building from source

# Clone the repository
git clone https://github.com/lukastk/notebookx.git
cd notebookx

# Build Rust library and CLI
cargo build --release

# Build Python package
pip install maturin
maturin develop

Running tests

# Rust tests
cargo test --workspace

# Python tests
pytest tests/python

License

MIT

Acknowledgements

Example notebooks in nb_format_examples/ are from the Jupytext demo.