README

Cover art by Joshua Hoiberg


handcalcs:Python calculations,as though you wrote them by hand.

handcalcs turns ordinary Python calculation code into a formatted calculation: the symbolic formula, then the formula with every value substituted in, then the result. Because the substitution step is shown, anyone can check the calculation by hand.

The same calculation can go to different renderers: Markdown and LaTeX for Jupyter and documents, HTML for web pages, ASCII text for terminals and logs, a live, formula-based Excel worksheet and Word documents. You can restyle the built-in renderers or write your own.

 v2.0.0 Pre-release out now!

This readme has been uodated to reflect the changes in 
handcalcs v2. 

As of 2026-11-06, the third release candidate is available for install:

pip install "handcalcs==2.0.0rc3"

or

pip install --pre handcalcs


Read the v2 documentation: getting started, every renderer, a cookbook of
recipes, and how to customize or write a renderer.

 Example

python
from math import sqrt    hc: -i
 Hypotenuse of a right triangle
 Both sides are measured from the site drawings.
a = 2.5   Side a, in m
b = 4.0   Side b, in m
c = sqrt(a2 + b2)


In Jupyter this is typeset as maths. With the ASCII renderer it reads:

text
==============================
Hypotenuse of a right triangle
==============================

Both sides are measured from the site drawings.
a = 2.5 (Side a, in m)
b = 4 (Side b, in m)
c = √(a² + b²) = √(2.5² + 4²) = 4.717


 Installing

console
pip install "handcalcs=2.0.0rc3"


handcalcs 2.0 is a release candidate, so ask for it by version: a plain
pip install handcalcs installs 1.x. handcalcs needs Python 3.11 or newer. Extras add the Excel and Word renderers
(handcalcs[excel], handcalcs[word]) and Jupyter export options
(handcalcs[exporters]). See Installation.

 Quick start

In Jupyter, import handcalcs once, then start any cell with %%render:

python
import handcalcs


python
%%render
a = 2
b = 3
c = 2a + b/3


From a script, render a string or a .py file with any renderer:

python
import pathlib
from handcalcs import HandCalcs
from handcalcs.renderers import LatexRenderer

latex = HandCalcs(LatexRenderer())(pathlib.Path("beam.py"))


On a function, @handcalc(renderer) returns the result and the rendered calculation.

 Renderers

Markdown (the Jupyter default), LaTeX, HTML, ASCII text, a live formula-based Excel
workbook, and Word documents with native equations. Subclass one to change its look, or
write your own. See Renderers.

 Upgrading from handcalcs 1.x

handcalcs 2 is a rewrite around a parsed node tree and pluggable renderers. Most notebooks
need only a few changes: import handcalcs instead of import handcalcs.render, and
 hc: comment commands instead of %%render arguments. See
Coming from handcalcs v1.

 Gotchas

Jupyter cells can run out of order. handcalcs looks up values in the notebook's namespace, so if you re-use variable names, a cell run out of order can render a beautiful but completely