# treebeardtech/nbmake architecture

> Architecture diagram of the GitHub repository treebeardtech/nbmake, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/treebeardtech/nbmake
- Repository: https://github.com/treebeardtech/nbmake

## Overview

nbmake is a pytest plugin that discovers selected Jupyter notebooks, executes them, and reports notebook failures as pytest failures. The main path runs from pytest options and collection through a notebook item into execution and result formatting; optional notebook overwrite is handled by the item. Execution supports README-documented timeout, kernel, import-error, cell-mocking, and post-cell hooks. Parallel execution via pytest-xdist is a documented capability, but its internal integration is not shown in the sampled source.

Main entry points: [`src/nbmake/pytest_items.py`](https://github.com/treebeardtech/nbmake/blob/main/src/nbmake/pytest_items.py) (Notebook item), [`src/nbmake/nb_run.py`](https://github.com/treebeardtech/nbmake/blob/main/src/nbmake/nb_run.py) (Notebook execution), [`src/nbmake/pytest_plugin.py`](https://github.com/treebeardtech/nbmake/blob/main/src/nbmake/pytest_plugin.py) (Plugin hooks), [`src/nbmake/nb_result.py`](https://github.com/treebeardtech/nbmake/blob/main/src/nbmake/nb_result.py) (Execution result)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pytest["Pytest integration"]
  node_plugin["Plugin hooks<br/>[pytest_plugin.py]"]
  node_file_collect["Notebook collection<br/>[pytest_items.py]"]
  node_notebook_item["Notebook item<br/>[pytest_items.py]"]
end

subgraph group_runtime["Notebook runtime"]
  node_runner["Notebook execution<br/>[nb_run.py]"]
  node_engine["nbclient engine"]
end

subgraph group_reporting["Result reporting"]
  node_result["Execution result<br/>[nb_result.py]"]
  node_failure_repr["Failure formatting<br/>[pytest_items.py]"]
end

node_user(("Pytest user"))
node_notebook_doc["Notebook file"]
node_kernel["Jupyter kernel"]
node_xdist["pytest-xdist"]

node_user -->|"sets options"| node_plugin
node_plugin -->|"collects notebooks"| node_file_collect
node_file_collect -->|"creates item"| node_notebook_item
node_notebook_item -->|"reads or overwrites"| node_notebook_doc
node_notebook_item -->|"executes"| node_runner
node_runner -->|"loads notebook"| node_notebook_doc
node_runner -->|"executes cells"| node_engine
node_engine -.->|"runs code"| node_kernel
node_runner -->|"returns result"| node_result
node_notebook_item -->|"checks result"| node_result
node_notebook_item -->|"formats failures"| node_failure_repr
node_user -.->|"parallelizes tests"| node_xdist

click node_plugin "https://github.com/treebeardtech/nbmake/blob/main/src/nbmake/pytest_plugin.py"
click node_file_collect "https://github.com/treebeardtech/nbmake/blob/main/src/nbmake/pytest_items.py"
click node_notebook_item "https://github.com/treebeardtech/nbmake/blob/main/src/nbmake/pytest_items.py"
click node_runner "https://github.com/treebeardtech/nbmake/blob/main/src/nbmake/nb_run.py"
click node_result "https://github.com/treebeardtech/nbmake/blob/main/src/nbmake/nb_result.py"
click node_failure_repr "https://github.com/treebeardtech/nbmake/blob/main/src/nbmake/pytest_items.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_plugin,node_file_collect,node_notebook_item,node_user toneBlue
class node_runner,node_engine toneAmber
class node_result,node_failure_repr toneMint
class node_notebook_doc,node_kernel,node_xdist toneIndigo
```

## Components

### Pytest integration

- [Plugin hooks](https://github.com/treebeardtech/nbmake/blob/main/src/nbmake/pytest_plugin.py): `src/nbmake/pytest_plugin.py`
- [Notebook collection](https://github.com/treebeardtech/nbmake/blob/main/src/nbmake/pytest_items.py): `src/nbmake/pytest_items.py`
- [Notebook item](https://github.com/treebeardtech/nbmake/blob/main/src/nbmake/pytest_items.py): `src/nbmake/pytest_items.py`

### Notebook runtime

- [Notebook execution](https://github.com/treebeardtech/nbmake/blob/main/src/nbmake/nb_run.py): `src/nbmake/nb_run.py`
- **nbclient engine**

### Result reporting

- [Execution result](https://github.com/treebeardtech/nbmake/blob/main/src/nbmake/nb_result.py): `src/nbmake/nb_result.py`
- [Failure formatting](https://github.com/treebeardtech/nbmake/blob/main/src/nbmake/pytest_items.py): `src/nbmake/pytest_items.py`

### Other components

- **Pytest user**
- **Notebook file**
- **Jupyter kernel**
- **pytest-xdist**

## Connections

- Pytest user → Plugin hooks: sets options (evidence: `README.md`)
- Plugin hooks → Notebook collection: collects notebooks (evidence: `src/nbmake/pytest_plugin.py`)
- Notebook collection → Notebook item: creates item (evidence: `src/nbmake/pytest_items.py`)
- Notebook item → Notebook file: reads or overwrites (evidence: `src/nbmake/pytest_items.py`)
- Notebook item → Notebook execution: executes (evidence: `src/nbmake/pytest_items.py`)
- Notebook execution → Notebook file: loads notebook (evidence: `src/nbmake/nb_run.py`)
- Notebook execution → nbclient engine: executes cells (evidence: `src/nbmake/nb_run.py`)
- nbclient engine → Jupyter kernel: runs code
- Notebook execution → Execution result: returns result (evidence: `src/nbmake/nb_run.py`)
- Notebook item → Execution result: checks result (evidence: `src/nbmake/pytest_items.py`)
- Notebook item → Failure formatting: formats failures (evidence: `src/nbmake/pytest_items.py`)
- Pytest user → pytest-xdist: parallelizes tests (evidence: `README.md`)
