ym-handcalcs

Render handcalcs calculations in YMPrint documents.

ym-handcalcs is a handcalcs renderer that produces ReportLab flowables, plus the _hc block that puts them in a YMPrint document: write Python, get typeset calculations with symbolic, substituted and computed values.

Installation

Install it with YMPrint's hc extra:

pip install "ymprint[hc]"

ym-handcalcs needs handcalcs 2.0, which is currently a pre-release. pip installs it automatically; uv only installs a pre-release you name, so add it with --with:

uv tool install "ymprint[hc]" --with "handcalcs>=2.0.0rc1"

YMPrint registers the _hc block automatically when ym-handcalcs is installed.

The _hc block

_vars:
  w_DL: 2.5
  w_LL: 4.0

Beam design:
  - _hc: |
      ## Factored load
      L = 6.0  # span, m
      w_f = 1.25 * w_DL + 1.5 * w_LL
      M_f = w_f * L**2 / 8
  - The factored moment is {{ M_f }} kN·m.

The source runs in the document's _vars, like a _py block: it can use values from _vars and earlier blocks, and later blocks (and {{ }} interpolation) can use its results. As in handcalcs, ## ... comments are headings, # ... comments are prose, inline comments annotate their line, and # hc: commands work as usual.

The value is either the source as a string, or a mapping:

Give a block an id to use it more than once in a mapping: _hc_loads, _hc_moment.

Using the renderer directly

The renderer works without YMPrint. It returns a ReportLab stylesheet and a story:

from handcalcs import HandCalcs
from ym_handcalcs import ReportLabRenderer, build_pdf
from ym_handcalcs.fonts import ensure_dejavu_registered

ensure_dejavu_registered()  # YMPrint registers the DejaVu fonts itself
result = HandCalcs(renderer=ReportLabRenderer(theme_color="#7A1F1F"))("a = 2\nb = a * 3\n")
result["story"]  # list of flowables
build_pdf(result, "calcs.pdf", title="Calcs")

# or straight to a PDF
HandCalcs(renderer=ReportLabRenderer())("a = 2\nb = a * 3\n", destination="calcs.pdf")

Development

uv sync
uv run pytest

Regenerate the golden files with HANDCALCS_UPDATE_GOLDEN=1 uv run pytest and review the diff.

License

Apache-2.0. See LICENSE.