nhandu 0.1.1

A literate programming tool for Python that weaves code and documentation into scientific reports

Nhandu

Nhandu (/ɲãndu/, approximately "NYAN-doo") means "spider" in many Tupi-Guarani languages, a fitting name for a tool that weaves together code and documentation, much like Knuth's original vision of literate programming.

Literate programming for Python: Write executable documents in plain .py files.

Nhandu transforms ordinary Python files with markdown comments into beautiful, reproducible reports. It's lighter than Jupyter, simpler than Quarto, and perfectly git-friendly.

Why Nhandu?

Contemporary literate programming in Python faces a documentation dilemma:

• Jupyter notebooks are powerful but use JSON format (git diffs are messy), require a browser/server, and mix code with metadata
• Quarto is feature-rich but complex, with many configuration options and a learning curve
• Pweave has not been maintained for many years and is incompatible with currently supported Python versions.
• Traditional scripts lack integrated documentation and visualization

Nhandu offers a different solution:

• Write literate programs in normal .py files: no special format, just comments
• Perfect git diffs: plain text, not JSON, no timestamps, no hashes
• No server or browser required—just run the command
• Zero configuration needed: smart defaults get you started immediately
• Python-native: designed specifically for the Python ecosystem

Nhandu also supports traditional .md files with code blocks if you prefer that style.

Quick Start

Your First Literate Program

Create a file analysis.py:

#' # My First Analysis
#'
#' This is a literate Python program. Lines starting with `#'` are markdown.
#' Everything else is regular Python code.

import numpy as np

# Generate some data
data = np.random.normal(0, 1, 1000)

#' ## Results
#'
#' Let's compute some statistics:

print(f"Mean: {data.mean():.3f}")
print(f"Std Dev: {data.std():.3f}")

#' The data looks normally distributed, as expected.

Generate Your Report

nhandu analysis.py

This creates analysis.html with your code, output, and nicely formatted documentation, from a plain Python script.

Features

Smart Output Capture

Nhandu automatically captures:

• Print statements and stdout
• Matplotlib plots (no plt.show() needed!)
• Expression results (like Jupyter cells)
• Rich objects (DataFrames render as tables in HTML)

Syntax Highlighting

Server-side syntax highlighting with 50+ themes via Pygments. Popular themes include: github-dark (default), monokai, dracula, one-dark, vs, and solarized-light.

Multiple Output Formats

Markdown output can be converted to PDF, Word, LaTeX, and more using pandoc or similar tools. Native HTML support is implemented out-of-the-box.

Configuration (Optional)

Power users can customize their reports via YAML frontmatter:

#' ---
#' title: My Scientific Report
#' output: html
#' code_theme: dracula
#' plot_dpi: 150
#' ---
#'
#' # Introduction
#' ...

It is also possible to use a configuration file (nhandu.yaml) or CLI arguments.

How It Works

Literate Python Format (.py files)

Nhandu treats Python files specially when they contain markdown comments:

#' # This is a markdown heading
#'
#' Any line starting with #' is treated as **markdown**.
#' You can use all standard markdown features.

# This is a regular Python comment
x = 42  # Regular code continues to work normally

#' Back to documentation. Variables persist across blocks:

print(f"x = {x}")

Hidden code blocks let you run setup code without cluttering your report:

#| hide
import pandas as pd
import matplotlib.pyplot as plt
# Configuration code here—runs but doesn't appear in output
#|

#' Now let's analyze our data:
# This code WILL appear in the output
data = pd.read_csv("data.csv")

Traditional Markdown Format (.md files)

You can also use standard markdown files with code blocks:

# My Analysis

Here's some Python code:

```python
import numpy as np
x = np.linspace(0, 10, 100)
print(f"Generated {len(x)} points")
```

The output will appear in your rendered document. In case of HTML output, any figures are embedded in the file, so that you have a single file to distribute.

Execution Model

• Shared namespace: All code blocks share the same Python environment
• Sequential execution: Blocks run in document order
• Output capture: stdout, plots, and expression results are all captured
• Rich formatting: Automatic handling of matplotlib figures, pandas DataFrames, and more

Examples

Check out the examples/ directory for complete demonstrations:

• 01_hello_world.py - Basic syntax and concepts [OUTPUT]
• 02_data_analysis.py - Working with data using standard library [OUTPUT]
• 03_plotting.py - Creating visualizations with matplotlib [OUTPUT]
• 04_scientific_computation.py - Numerical computing with NumPy [OUTPUT]
• 05_advanced_report.py - Complex report with pandas and multiple visualizations [OUTPUT]

Installation & Usage

Install from PyPI

pip install nhandu

Install from Source

git clone https://github.com/tresoldi/nhandu.git
cd nhandu
pip install -e .

Basic Usage

nhandu document.py                       # Process literate Python file → document.html
nhandu document.md                       # Process markdown file → document.html
nhandu document.py -o report.html        # Specify output file
nhandu document.py --format md           # Output as markdown
nhandu document.py --code-theme monokai  # Custom syntax theme
nhandu document.py --verbose             # Show processing details

CLI Options

nhandu [OPTIONS] INPUT

Options:
  -o, --output PATH           Output file path
  --format {html,md}          Output format (default: html)
  --config PATH               Configuration file (YAML)
  --working-dir PATH          Working directory for code execution
  --timeout SECONDS           Execution timeout
  --code-theme THEME          Syntax highlighting theme
  --verbose, -v               Enable verbose output
  --version                   Show version
  --help                      Show help message

Roadmap

Current priorities:

• Native PDF output support
• Inline code evaluation (<%= expression %> syntax)
• Custom HTML templates (Jinja2)
• Watch mode for live development
• Rich display for more object types (NumPy arrays, scikit-learn models)
• Caching system for faster re-renders

See issues for more details and to suggest features.

Project Information

Citation and Acknowledgements

If you use Nhandu in your research, please cite:

@software{tresoldi2025nhandu,
  author = {Tresoldi, Tiago},
  title = {Nhandu: Literate Programming for Python},
  year = {2025},
  publisher = {Department of Linguistics and Philology, Uppsala University},
  address = {Uppsala, Sweden},
  url = {https://github.com/tresoldi/nhandu},
  orcid = {0000-0002-2863-1467}
}

The earliest stages of development took place within the context of the Cultural Evolution of Texts project, with funding from the Riksbankens Jubileumsfond (grant agreement ID: MXM19-1087:1).

License

MIT License - see LICENSE file for details.

Acknowledgments

Nhandu is inspired by:

• Donald Knuth's original literate programming vision
• knitr and R Markdown's approach to reproducible research
• Jupyter's interactive computing paradigm
• Quarto's modern scientific publishing tools
• Pweave's Python implementation (though no longer maintained)

Special thanks to the scientific Python community for building the ecosystem that makes tools like this possible.