UzonCalc

中文

UzonCalc is a tool for writing engineering calculation documents using Python. With it, you can write calculation reports as smoothly as writing Python, and benefit from the full Python ecosystem and AI assistance.

Features

1. Write using Python code — no extra syntax to learn
2. Benefit from the Python ecosystem and AI support
3. Focus on calculations, not layout
4. Output beautiful HTML directly; convertible to PDF and Docx

Start

Installation

pip install uzoncalc

Copy Template

# example.py
from uzoncalc import *

@uzon_calc()
def sheet():
    doc_title("uzoncalc example")

    "Hello, UzonCalc!"


if __name__ == "__main__":
    view(sheet)

Execution

python example.py

Example

from numpy import sqrt
from pathlib import Path
import sys

# Ensure project root is on sys.path so `import core` works when running
# this script from the `core` folder.
sys.path.insert(0, str(Path(__file__).resolve().parents[1]))

from uzoncalc import *
from uzoncalc.extension.excel import get_excel_table

@uzon_calc()
async def sheet():
    doc_title("UzonCalc Full Example")
    page_size("A4")

    H1("UzonCalc Full Example")

    "This is a full example demonstrating various features of UzonCalc."

    toc()

    # description:
    # this is a full example of using UzonCalc.

    H2("Auto Table of Contents")
    "You can automatically generate a table of contents for your document."

    H2("Basic Constants")
    # number
    H3("Numbers")
    intNumber = 100
    floatNumber = 3.1415
    scientificNumber = 1.2e3
    complexNumber = 2 + 3j

    H3("Strings")
    helloString = "Hello,"
    uzonCalcString = "UzonCalc!"
    greeting = helloString + uzonCalcString

    H3("String Output")
    # you can output strings directly
    "This is a string output inline."

    """
    This is a string output block.
    It can span multiple lines.
    It will be rendered as paragraph.
    """

    H3("String Formatting")
    name = "Uzon"
    f"Hello, {name}! Welcome to UzonCalc."
    pi = 3.1415926535
    f"Value of pi up to 3 decimal places: {pi:.3f}"

    H3("String Formatting With Equations")
    enable_fstring_equation()
    f"Hello, {name}! Welcome to UzonCalc."
    f"The value of pi is approximately {pi:.3f}, which is useful in calculations."
    disable_fstring_equation()

    H2("Units and Calculations")
    length = 5 * unit.meter
    time = 2 * unit.second
    speed = length / time

    H3("Complex Calculation")

    acceleration = speed / time
    force = 10 * unit.kilogram * acceleration
    stress = force / (length**2)

    H3("Unit Conversion")
    "Original speed in m/s:"
    speed
    hide()
    speedKmh = speed.to(unit.kilometer / unit.hour)
    show()
    f"Speed in km/h: {speedKmh}"

    # use matplotlib to plot a sine wave
    H2("Plotting Example")
    "You can use Matplotlib to create plots within UzonCalc."
    hide()
    import numpy as np
    import matplotlib.pyplot as plt

    x = np.linspace(0, 2 * np.pi, 100)
    y = np.sin(x)
    plt.plot(x, y)
    plt.title("Sine Wave")
    plt.xlabel("x (radians)")
    plt.ylabel("sin(x)")
    plt.legend(["sin(x)"])
    plt.grid(True)
    show()
    Plot(plt)

    # sub
    H2("Variable subscription")

    H3("Default Subscript Rule")

    "if you want to make a word to be subscript, you can use _ after it. For example, H_2 will be rendered as H₂."
    a_x = 10 * unit.meter / unit.second**2
    speed_2 = a_x * 2 * unit.second

    H3("complex Subscript")

    "You can also use other language characters as subscripts, like gamma_混凝土."
    "You can use alias"

    H3("Array Subscript")
    "You can use array subscript like A[i]."

    # 希腊字母
    H2("Greek Letters")
    "You can use Greek letters like 'alpha' (α), 'beta' (β), 'gamma' (γ), 'delta' (δ), etc. in your calculations."
    "When you write 'alpha', it will be rendered as α."
    "Capitalized Greek letters like 'Beta' will be rendered as Β."

    rho_water = 1000 * unit.kilogram / unit.meter**3
    g = 9.81 * unit.meter / unit.second**2
    h = 10 * unit.meter
    pressure = rho_water * g * h
    "Pressure calculated using ρgh:"
    pressure

    H2("Functions Converter")

    "Some functions can automatically convert to math style."

    H3("Square Root")
    "You can use sqrt(x) to represent the square root of x."

    edge1 = 3 * unit.meter
    edge2 = 4 * unit.meter
    diagonal = sqrt(edge1**2 + edge2**2)

    H3("Absolute Value")
    "You can use abs(x) to represent the absolute value of x."
    value = -15 * unit.newton
    absValue = abs(value)

    H2("Tables")

    "You can create tables to organize data."

    Table(
        [
            [
                th("Component", rowspan=3),
                th("Material", rowspan=3),
                th("Elastic Modulus (MPa)", colspan=2),
                th("Design Strength (MPa)", colspan=2),
                th("Standard Strength (MPa)", colspan=2),
            ],
            [
                "Ec/Es",
                "Compressive",
                "Tensile",
                "Compressive",
                "Tensile",
            ],
        ],
        [
            ["Cap Beam", "C60", 3.6e4, 26.5, 1.96, 38.5, 2.85],
            ["Cap Beam 2", "C60", 3.6e4, 26.5, 1.96, 38.5, 2.85],
        ],
        title="Sample Table",
    )

    H2("Call Excel Calculation")

    "You can update values for Excel calculation and get results table back."
    "This is very useful for re-using of existing Excel calculation."

    P(
        get_excel_table(
            excel_path="examples/data/calculation.xlsx",
            values={
                "A3": 6,
                "B3": 10,
                "C3": 2,
            },
            range="A1:D3",
        )
    )

    "Excel table will be cached for faster rendering next time if cache=True and the input values are not changed."

    H2("Saving Document")

    H3("Save as HTML")

    "You can save the document as an HTML file using the save() function."

    H3("Export To Word Document")

    "You can export the html document to a word document by pandoc command."

    from core.utils.doc import save

    save("../output/example.en.html")


if __name__ == "__main__":
    import time

    t0 = time.perf_counter()
    run_async(sheet)
    t1 = time.perf_counter()
    print(f"Execution time: {t1 - t0} seconds")

Preview:

Demo

Source: example.en.py

Compile Result: UzonCalc Full Example

CLI

uzoncalc path/to/your/script.py --output path/to/output.html

Package a report script and its statically imported local Python modules:

uzoncalc zip -p path/to/your/script.py
python path/to/your/script.uzc

The script must contain at least one @uzon_calc entry. If it has no if __name__ == "__main__" block, packaging succeeds only when there is exactly one calculation entry, and the generated archive calls view() for that entry.

The generated .uzc is a 1280×720 PNG thumbnail containing the executable ZIP payload in a private PNG chunk. The thumbnail uses the first calculation entry and resolves its title from H1(...), doc_title(...), the @uzon_calc(...) name, then the script filename. Run it with python script.uzc; PNG-first archives cannot also use a POSIX shebang. Do not resave or optimize a .uzc with an image editor because unknown private chunks may be removed.