Convert IPYNB to TOML

Why Convert IPYNB to TOML?

Converting IPYNB to TOML is useful when you need to extract structured data from Jupyter Notebooks into a clean, human-readable configuration format. TOML's clear key-value syntax makes it ideal for representing notebook metadata, cell content, and structured information in a format that is easy to read, edit, and version control.

This conversion is especially relevant for Python developers working with pyproject.toml. When notebook analyses produce configuration parameters, model hyperparameters, or project settings, converting to TOML provides a direct path to incorporating those values into Python project configuration files.

TOML's strong typing and clear semantics make it an excellent choice for exporting notebook data that needs to be reliably parsed by other tools. Unlike YAML, TOML has no gotchas with implicit type coercion, and unlike JSON, it supports comments, making the exported content self-documenting.

Key Benefits of Converting IPYNB to TOML:

• Human Readable: TOML output is clear and easy to understand at a glance
• Typed Values: Numbers, strings, booleans, and dates are unambiguously typed
• Comment Support: Add documentation alongside extracted notebook content
• Python Integration: Directly usable in pyproject.toml and Python config files
• No Indentation Issues: TOML parsing is not whitespace-sensitive
• Version Control: Clean diffs in git due to simple, predictable syntax
• Structured Data: Tables and arrays organize notebook content logically

Practical Examples

Example 1: Config Export from Notebook to TOML

Input IPYNB file (notebook.ipynb):

{
  "cells": [
    {
      "cell_type": "markdown",
      "source": ["# Application Configuration\n", "Settings extracted from data analysis pipeline."]
    },
    {
      "cell_type": "code",
      "source": ["batch_size = 64\n", "learning_rate = 0.001\n", "epochs = 50\n", "optimizer = 'adam'"]
    }
  ]
}

Output TOML file (notebook.toml):

# Notebook: notebook.ipynb
# Converted from Jupyter Notebook

[metadata]
title = "notebook"
format = "ipynb"

[[cells]]
cell_type = "markdown"
index = 0
source = """
# Application Configuration
Settings extracted from data analysis pipeline.
"""

[[cells]]
cell_type = "code"
index = 1
source = """
batch_size = 64
learning_rate = 0.001
epochs = 50
optimizer = 'adam'
"""

Example 2: Project Settings to TOML

Input IPYNB file (analysis.ipynb):

{
  "cells": [
    {
      "cell_type": "markdown",
      "source": ["## Database Connection Setup"]
    },
    {
      "cell_type": "code",
      "source": ["DB_HOST = 'localhost'\n", "DB_PORT = 5432\n", "DB_NAME = 'analytics'\n", "POOL_SIZE = 10"]
    },
    {
      "cell_type": "code",
      "source": ["import psycopg2\n", "conn = psycopg2.connect(\n", "    host=DB_HOST, port=DB_PORT,\n", "    dbname=DB_NAME\n", ")"]
    }
  ]
}

Output TOML file (analysis.toml):

# Notebook: analysis.ipynb
# Converted from Jupyter Notebook

[metadata]
title = "analysis"
format = "ipynb"

[[cells]]
cell_type = "markdown"
index = 0
source = "## Database Connection Setup"

[[cells]]
cell_type = "code"
index = 1
source = """
DB_HOST = 'localhost'
DB_PORT = 5432
DB_NAME = 'analytics'
POOL_SIZE = 10
"""

[[cells]]
cell_type = "code"
index = 2
source = """
import psycopg2
conn = psycopg2.connect(
    host=DB_HOST, port=DB_PORT,
    dbname=DB_NAME
)
"""

Example 3: Model Parameters Export to TOML

Input IPYNB file (research.ipynb):

{
  "cells": [
    {
      "cell_type": "markdown",
      "source": ["# Random Forest Hyperparameters\n", "Tuned parameters from grid search."]
    },
    {
      "cell_type": "code",
      "source": ["params = {\n", "    'n_estimators': 200,\n", "    'max_depth': 15,\n", "    'min_samples_split': 5,\n", "    'min_samples_leaf': 2,\n", "    'max_features': 'sqrt'\n", "}"]
    }
  ]
}

Output TOML file (research.toml):

# Notebook: research.ipynb
# Converted from Jupyter Notebook

[metadata]
title = "research"
format = "ipynb"

[[cells]]
cell_type = "markdown"
index = 0
source = """
# Random Forest Hyperparameters
Tuned parameters from grid search.
"""

[[cells]]
cell_type = "code"
index = 1
source = """
params = {
    'n_estimators': 200,
    'max_depth': 15,
    'min_samples_split': 5,
    'min_samples_leaf': 2,
    'max_features': 'sqrt'
}
"""

Frequently Asked Questions (FAQ)

Q: How is notebook content structured in the TOML output?

A: The notebook content is organized using TOML tables. Metadata appears in a [metadata] section, and each cell is represented as an entry in an [[cells]] array of tables, with keys for cell type, source content, and index.

Q: How are multi-line code cells handled in TOML?

A: Multi-line code content is stored using TOML's triple-quoted multi-line strings (""" or '''), which preserve line breaks and indentation. This ensures code cells maintain their original structure in the TOML output.

Q: Can I use the TOML output in a pyproject.toml file?

A: The TOML output uses valid TOML syntax, but the structure represents notebook content rather than project configuration. You can extract specific values from the output and incorporate them into pyproject.toml as needed.

Q: Does TOML support the same data types as JSON in IPYNB?

A: TOML supports strings, integers, floats, booleans, dates/times, arrays, and tables. While JSON used by IPYNB has similar types, TOML adds native datetime support and distinguishes between integers and floats more explicitly.

Q: How are notebook images and binary data handled?

A: Binary data like embedded images cannot be represented directly in TOML. The converter focuses on text-based content (code and markdown cells). Binary outputs from cell executions are omitted from the TOML output.

Q: Can I parse the TOML output with Python's tomllib?

A: Yes, the output is valid TOML that can be parsed by Python's built-in tomllib module (Python 3.11+) or the tomli third-party library. This enables programmatic access to the extracted notebook content.

Q: Is TOML better than YAML for this conversion?

A: TOML offers stronger typing and simpler syntax without YAML's gotchas (like "Norway problem" with boolean coercion). However, YAML is more common for deeply nested data. The choice depends on your target toolchain and preference.

Q: Are cell execution counts and metadata included?

A: Basic cell metadata including cell type and index are included. Execution counts and detailed kernel metadata may be omitted to keep the TOML output clean and focused on the notebook's authored content.