Repository layout

src/handcalcs

Module	Contents
handcalcs	The public API: HandCalcs, handcalc, the config functions, BaseRenderer, get_renderer. Imports the Jupyter interface when IPython is available.
config	Global options: defaults, set_option/save_config, the config file location (platformdirs, HANDCALCS_CONFIG).

interfaces/

Module	Contents
object_oriented	HandCalcs: read source or a path, run it, parse, render, complete; demo().
decorator	@handcalc: run the function with innerscope, parse its source, render.
jupyter	%%render, %hc_default_renderer, %hc_format_code; the display class for each renderer. Only importable inside IPython.

parsing/

Module	Contents
line_values	Records each statement’s values while the source runs.
ast_parser	AST_Parser: Python ast → handcalcs nodes, comment classification, parameter grids. The largest module.
sequence	HcSequence (the root) and the post-parse passes: convert_if_tree, group_lines, set_levels.
nodes	Value nodes: Name, Attribute, Constant, collections.
line_nodes	CalcLine, ExprLine, CommentLine, Heading, CommentCommand, Import.
block_nodes	IfBlock, ElifBlock, ElseBlock, ForBlock, ParamsBlock, CalcsBlock, CommentsBlock.
inline_nodes	FunctionCall, Keyword, Compare, InlineComment, InlineCommand, comprehensions.
operator_nodes	Binary, unary, comparison and boolean operators.
comment_parser	Is a comment a heading, a command? Splitting and executing command text.
commands	The argparse parser for # hc: flags.
null_values	NoValue, HcNotImplemented.

renderers/

Module	Contents
base	RenderContext, BaseRenderContext, the registry, BaseRenderer and every base handler and rule. The core of the package.
identifiers	Identifier parsing shared by every renderer: the Greek table, parse_identifier (→ Symbol tree), parse_spec for the symbols option, identifier_options.
ascii	ASCIIRenderer.
latex	LatexRenderer, latex_identifier, latex_prose, the symbol tables.
markdown	MarkdownRenderer (subclass of LatexRenderer).
html	HTMLRenderer and its stylesheet.
excel	ExcelRenderer, split into renderer, formulas, names, rows, conditionals, units, writer, symbolic, rich_text, number_formats, evaluate, compat, options.
demo	The source rendered by HandCalcs.demo().

Elsewhere

Path	Contents
tests/	The pytest suite (see Tests).
tests/golden/	Golden output files for the LaTeX and Markdown renderers.
scripts/	latex_demo_check.py (compile the demo with pdflatex, report overfull boxes), markdown_demo_check.py, excel_demo.py.
docs/	These docs. _ext/ holds the local Sphinx extensions, _examples/ the example renderers the docs run.
.github/workflows/	CI: tests on Linux/macOS/Windows × Python 3.11–3.14; publish to PyPI on release.