dietnb 0.1.1

Save matplotlib figures as external files and link them, keeping notebooks tiny.

dietnb (v0.1.1)

dietnb automatically saves your matplotlib figures to disk and embeds them as lightweight links in your Jupyter notebooks, keeping your .ipynb files tiny and manageable.

Say goodbye to bloated notebooks filled with base64-encoded images!

---

The Problem

Jupyter notebooks are fantastic, but they have a common issue:

• matplotlib figures are often embedded directly into the notebook (.ipynb) file as base64-encoded strings.
• This can cause notebook files to become excessively large (megabytes!), making them slow to load, save, and share.
• Accumulated or cached figures can also consume significant memory.
• Manually running plt.close() or using tools like nbstripout for every figure can be cumbersome.

The Solution: dietnb

dietnb offers a simple and automatic solution:

• Figures on Disk, Links in Notebook: When you display a matplotlib plot, dietnb intercepts it. Instead of embedding the image, it saves the figure as a PNG file in a local directory (dietnb_imgs/ by default, relative to your notebook).
• Lightweight Links: A clean HTML <img> tag linking to the external image file is displayed in your notebook output.
• Automatic Operation: Once installed and activated, dietnb works seamlessly in the background.

This keeps your .ipynb files extremely small, typically adding only a few hundred bytes per plot for the link, instead of kilobytes or megabytes for the full image data.

Key Features

• Zero Image Bytes in Notebooks: Drastically reduces .ipynb file sizes.
• Automatic & Transparent: Works behind the scenes after a one-time setup. No changes to your plotting code are needed.
• Unique Naming per Cell & Figure: Figures are named based on cell ID (with a fallback) and an index for multiple figures within the same cell execution (e.g., [cell_hash]_1.png, [cell_hash]_2.png).
• Automatic Cleanup: When a cell is re-executed, previous images generated by that cell are automatically deleted.
• Browser Cache Busting: Image links include a version query (?v=[execution_count]) to help ensure browsers display updated images.
• Manual Cleanup Utility: Provides dietnb.clean_unused() to remove image files that are no longer referenced by the current kernel's state (useful for cleaning up after moving/deleting cells).

Installation

pip install dietnb

Quick Start

There are two ways to get dietnb working:

1. Automatic Activation (Recommended)

After installing dietnb, run the following command in your terminal (ensure your virtual environment is activated if you're using one):

dietnb install

This registers a startup script with IPython. You'll need to restart your Jupyter kernel(s) for this to take effect. After restarting, dietnb will automatically be active in all your new notebook sessions.

2. Manual Activation (Per Notebook)

If you prefer not to modify your IPython startup files, or if the automatic setup fails, you can activate dietnb manually at the beginning of each notebook:

# Option A: Python code
import dietnb
dietnb.activate()

Or, if you're in an IPython/Jupyter environment:

# Option B: IPython magic command
%load_ext dietnb

Basic Usage Example

Once dietnb is active (either automatically or manually), simply create your plots as usual:

import matplotlib.pyplot as plt
import numpy as np

# Generate a simple plot
x = np.linspace(0, 2 * np.pi, 100)
y = np.sin(x)

plt.figure()
plt.plot(x, y)
plt.title("A Simple Sine Wave")
plt.xlabel("X-axis")
plt.ylabel("Y-axis")
plt.show() # dietnb saves this as an external image and shows a link

What happens:

• The plot will be displayed in your notebook.
• Instead of being embedded, the image (e.g., abcdef123456_1.png) will be saved in a dietnb_imgs folder in the same directory as your notebook.
• Your notebook file (.ipynb) will remain small!

Cleaning Unused Images

If you've run many cells, deleted cells, or moved notebooks, you might have orphaned image files in your dietnb_imgs folders. You can clean these up using:

import dietnb
dietnb.clean_unused()

This function will remove any PNG files in the active dietnb_imgs directory that are not associated with the current state of figures tracked by dietnb in the kernel.

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

한국어 README (Korean README)