Command line: handcalcs#

The handcalcs command renders a Python script without writing any Python around it.

$ handcalcs beam.py --renderer excel --output beam.xlsx
Wrote beam.xlsx

python -m handcalcs is the same command (uv run python -m handcalcs in a uv project). Run it with no arguments to see its help, which lists every renderer and its options.

Choosing the output#

handcalcs SCRIPT

prints the render to stdout as text, with the renderer named by the default_renderer option (ASCII unless you change it). - as SCRIPT reads the script from stdin.

-o FILE, --output FILE

writes the render to FILE instead, as HandCalcs(...)(source, destination=FILE) does: a complete document for the LaTeX and HTML renderers, a saved .docx or .xlsx for the Word and Excel renderers. Without --renderer, the renderer is chosen from the extension:

Extension

Renderer

.xlsx

excel

.docx

word

.tex

latex

.md

markdown

.html, .htm

html

.txt

ascii

-r NAME, --renderer NAME

the renderer, by its registered name. The Word and Excel renderers need --output.

$ handcalcs beam.py                     # ASCII text to the terminal
$ handcalcs beam.py -o beam.docx        # Word, from the extension
$ handcalcs beam.py -r latex > beam.tex # a LaTeX document on stdout

Renderer options#

Any other --name VALUE is passed to the renderer as the keyword argument name=VALUE, with dashes in the name becoming underscores. These are the same arguments as the renderer’s constructor in Python:

$ handcalcs beam.py -o beam.xlsx --sheet-name Beam
$ handcalcs beam.py -o beam.html --theme-color '#1d4ed8'
$ handcalcs beam.py -o beam.docx --layout lines --template company.docx
  • A value is read as a Python literal when it is one (3, True, None, {"bold": True}) and as a string otherwise (Beam, #1d4ed8). Quote it for your shell when it has spaces or braces.

  • --name=VALUE works too. --name with no value is True; put such a flag after the script, or write --name=True, so it doesn’t take the script as its value.

  • An option the renderer doesn’t take is an error that lists the ones it does.

The handcalcs options --format-code, --line-values and --hidden-by-default are set the same way, for that run only:

$ handcalcs beam.py --format-code .2f

Inputs#

-i NAME=VALUE, --input NAME=VALUE renders the script with VALUE in place of the value it first assigns NAME, as HandCalcs(...)(source, inputs=...) does (see Rendering many input sets). Repeat it for each input:

$ handcalcs beam.py -i w=7.5 -i L=8 -o beam-case2.docx
  • A number keeps the units of the script’s line: with L = 6 * m, -i L=8 runs and renders L = 8 * m.

  • VALUE may also be an expression using names the script defines before its first input, such as its units. A quantity is converted to the line’s units, so -i L='8000 * mm' renders L = 8 * m too.

  • --no-strict ignores a NAME the script never assigns, which is otherwise an error.

  • --allow-computed allows replacing a value the script computes.

Custom renderers#

A custom renderer is chosen by name once the module that defines it is imported. --import MODULE imports it first (repeat it for several modules):

$ handcalcs beam.py --import my_renderers -r rst -o beam.rst

--list-renderers (with any --import) prints the available renderers and their options.

Other options#

-q, --quiet

don’t report the file written.

-V, --version

print the handcalcs version.

The script runs with its own directory importable, as with python script.py, so it can import the modules beside it.

Source#

src/handcalcs/__main__.py