Configuration

handcalcs has a small global configuration. Change it for the current session with set_option, and make the change permanent with save_config.

import handcalcs

handcalcs.set_option("format_code", ".3g")   # this session
handcalcs.save_config()                      # and every session after

Options

Option	Default	Used by
format_code	".5g"	Every renderer: the default number format.
default_renderer	"ascii"	HandCalcs() and @handcalc() with no renderer argument. The name of a renderer.
jupyter_renderer	"markdown"	The %%render cell magic. Also set by %hc_default_renderer.
line_values	True	HandCalcs, %%render and @handcalc: record each line’s values while the code runs. See line values.

Renderer names are base, ascii, latex, markdown, html and excel, plus the name of any custom renderer that has been imported.

Custom options

Any other option name is accepted, with any value:

handcalcs.set_option("highlight_results", True)

Every option except default_renderer, jupyter_renderer and line_values is copied onto the render context of every render. Built-in renderers ignore names they don’t know; a custom renderer can read them. This is how a renderer gets settings that differ per user or per project.

Line values

While your code runs, handcalcs records the values of its variables at each line, so a line shows the values it ran with even when a name is assigned again later (see How handcalcs reads your code). Recording costs a little time for every line of your code that runs: a fraction of a millisecond for a typical calculation, but a loop that runs thousands of times takes several times longer. Code in the libraries you call (numpy, pint) is not slowed down on Python 3.12 and later.

To trade that for speed, turn it off:

handcalcs.set_option("line_values", False)

The code then runs with a single exec, and every line shows the values from after the code has run, so a name assigned more than once shows its final value everywhere.

Functions

All of these are available from the top-level handcalcs package.

set_option(option, value)

Set an option for the current session. The three built-in options must be strings.

get_option(option, default=None)

The current value of an option.

get_config()

A copy of the whole configuration, as a dict.

reset_option(option)

Restore a built-in option to its default, or remove a custom option. Session only.

reset_config()

Restore every option to the defaults. Session only.

save_config()

Write the current configuration to the config file, so it loads automatically next time handcalcs is imported.

Important

The configuration is read when handcalcs is imported, and each HandCalcs object copies it when it is created. Set options before creating the HandCalcs objects that should use them.

The config file

save_config() writes JSON to the per-user config directory for your operating system:

OS	Location
Linux	~/.config/handcalcs/hc_config.json
macOS	~/Library/Application Support/handcalcs/hc_config.json
Windows	%LOCALAPPDATA%\handcalcs\hc_config.json

To use a different file, for example one per project, set the HANDCALCS_CONFIG environment variable to its path before importing handcalcs.

A missing file is normal (the defaults are used). A file that cannot be read produces a warning and the defaults.

Next: Units.