Metadata-Version: 2.4
Name: dietnb
Version: 0.1.1
Summary: Save matplotlib figures as external files and link them, keeping notebooks tiny.
Author: JinLover
License: MIT
Project-URL: Homepage, https://github.com/JinLover/dietnb
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ipython>=8
Requires-Dist: matplotlib>=3.5
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-mock>=3.10; extra == "dev"
Dynamic: license-file

# `dietnb` (v0.1.1)

[![PyPI version](https://badge.fury.io/py/dietnb.svg)](https://badge.fury.io/py/dietnb)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**`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

```bash
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):

```bash
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:

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

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

```python
# 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:

```python
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:

```python
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](LICENSE) file for details.

---
[한국어 README (Korean README)](README_ko.md) 
