Introduction to Notebook Shim
Notebook Shim is a lightweight and highly versatile library that serves as a bridge for creating smooth interoperability between different notebook environments like Jupyter Notebook, Google Colab, and VS Code Notebooks. It simplifies cross-platform notebook usage and provides utilities to enhance the development workflow. In this blog, we explore its key features, APIs, and practical examples.
Why Use Notebook Shim?
As notebook environments evolve, developers often face challenges when switching between platforms. Notebook Shim resolves this by providing a unified interface and tools for seamless transitions. Additionally, it offers utilities like metadata handling, cell manipulation, and content transformations to streamline notebook data processing.
Key APIs and Features
1. read_notebook(file_path)
Load a notebook file into a Python dictionary for easier manipulation.
from notebook_shim import read_notebook notebook = read_notebook("example_notebook.ipynb") print(notebook["cells"])
2. write_notebook(data, output_path)
Save a manipulated dictionary representation of a notebook back to a file.
from notebook_shim import write_notebook modified_notebook = { "metadata": {}, "cells": [ {"cell_type": "code", "source": "print('Hello, World!')"} ] } write_notebook(modified_notebook, "output_notebook.ipynb")
3. convert_nb_format(data, target_version)
Upgrade or downgrade a notebook to a specific notebook format version.
from notebook_shim import convert_nb_format upgraded_notebook = convert_nb_format(notebook, target_version=4)
4. add_cell(data, cell_content)
Insert a new cell to the notebook dynamically.
from notebook_shim import add_cell added_notebook = add_cell(data=notebook, cell_content={ "cell_type": "markdown", "source": "# This is a dynamically added markdown cell." })
5. execute_cell(cell_source)
Run a cell’s code content locally and fetch its output.
from notebook_shim import execute_cell output = execute_cell(cell_source="print('Executed Successfully')") print(output)
6. extract_metadata(notebook)
Retrieve notebook-level metadata without reading the entire file structure manually.
from notebook_shim import extract_metadata metadata = extract_metadata(notebook) print(metadata)
7. find_cells(cell_type)
Filter notebook cells based on their type (e.g., code, markdown).
from notebook_shim import find_cells code_cells = find_cells(notebook, cell_type="code") print(f"Number of code cells: {len(code_cells)}")
Building an Application With Notebook Shim
Let us build an application that processes a Jupyter Notebook, inserts a new cell, and saves the modified notebook.
from notebook_shim import read_notebook, write_notebook, add_cell def process_notebook(input_path, output_path): # Read the notebook notebook = read_notebook(input_path) # Add a new markdown cell notebook = add_cell(notebook, { "cell_type": "markdown", "source": "# Auto-added Cell\\nThis cell was added programmatically!" }) # Save the notebook write_notebook(notebook, output_path) # Execute the application process_notebook("example_notebook.ipynb", "processed_notebook.ipynb") print("Notebook processing complete!")
With just a few lines of code, you can manipulate and enhance functionality in Jupyter Notebooks using Notebook Shim.
Conclusion
Notebook Shim is a powerful tool for anyone looking to simplify notebook workflows or build applications that interact with notebook documents. Its rich set of APIs makes it an indispensable asset for developers dealing with notebook environments.