qCalc Api Reference

qCalc API Reference (for calculator authors)

This document summarizes calculator-facing symbols exposed by qCalc, with practical descriptions and examples. You can type help <symbol> in cosole to know more about input and output interface of a symbol.


1) Quantity and Unit APIs

Symbol Kind What it does Example
Qty (alias: q) class Quantity object with value + unit and unit-aware math. Also parses text: Qty.parse("3.5 kg") (None if invalid), Qty.is_valid(text), Qty.compose("1ft, 6 inch"), Qty.kind(text) ('uom', 'qty' or 'text') d = Qty("10 m"); t = Qty("2 s"); v = d / t
UnitRegistry class The built-in units. find(text), parse(text), is_uom(text), named(name), dimension(text), by_dimension(dim), category(dim), categories(), desc(name), read(text), base_units(); read-only data table, info, tree (the registry cannot be changed from a calculator) UnitRegistry.by_dimension(UnitRegistry.dimension("km")), UnitRegistry.find("meter")
QtyRegistry class The special (named) quantities. get(code), entry(code), by_dimension(dim), desc(code), search(term) QtyRegistry.get("th_hair"), QtyRegistry.entry("th_hair")
is_qty, is_unit function Checks whether value is quantity/unit if is_qty(x): ...
base_dims, prefixes data Built-in dimension dictionaries and prefixes base_dims()
lmt_desc function Human-readable limit-category description lmt_desc("L")

2) Date/Time APIs

Symbol Kind What it does Example
QDateTime (alias: qdt in qlib_dict) class Parse/hold date/time values; supports +/- day math and timedelta QDateTime("2026-10-04 10:30 UTC+06:00")
today() function Returns current local date as QDateTime d = today()
now(tz=None) function Returns current time as QDateTime; accepts UTC, +HHMM, +HH:MM, UTC+HH:MM now("UTC"), now("+06:00")
spellnow(tz=None) function Returns human-readable current datetime text via QDateTime.spell() spellnow("UTC")

3) Conditional and CSS-like value helpers

Symbol Kind What it does Example
iif function Inline-if helper iif(score >= 60, "Pass", "Fail")
joinx function Join helper for values/strings joinx(", ", ["A", "B", "C"])
css2floats, css2ints, css2values, css2strs, vals2css, css2set function Convert comma/space separated text to typed values and back css2ints("1,2,3")

4) Safe table / dataframe APIs (qtbl)

qtbl is the safe table type used in qapi:

tbl = {"columns": ["name", "qty"], "data": [["A", 3], ["B", 5]]}
Symbol Kind What it does Example
qdf(tbl) function Wraps qtbl into a safe dataframe facade (limited methods); qdf(tbl)["qty"] returns one column as a list qdf(tbl).sum()
QList(values) class List of converted values (numbers, quantities, dates). Methods: sum(), apply(op), add(x), sub(x), mul(x), div(x), binary(x, op); x is a value or a same-length list QList(["2 m", "30 cm"]).sum()

5) NumPy API (restricted)

Symbol Kind What it does Example
np proxy object Restricted NumPy surface (safe allowlist only) np.sqrt([1,4,9])
np_names() function Lists exposed np.<name> symbols np_names()

6) Symbol discovery/help APIs

Symbol Kind What it does Example
qtypes() function Lists supported qtype annotation names qtypes()
qmodules() function Lists allowed import modules in safe execution context qmodules()
qsymbols(scope='api', name_filter=None) function Discover available symbols/calculators/units qsymbols("api")
qsymstat() function Count summary by symbol category qsymstat()
qsymhelp(name) function Signature/doc help for one symbol qsymhelp("QList")

7) User/environment helpers

Symbol Kind What it does Example
user_name, user_ip function Runtime/user context metadata user_name()

8) Link/UI helpers

Symbol Kind What it does Example
page_link, calurl, cal_link, command_button, addcal_button function Build calculator/page links and action buttons cal_link("my_calc", "Open")

9) File / image / visualization classes

Symbol Kind What it does Example
QFile, qf2bio class/function File wrapper and conversion to bytes stream bio = qf2bio(my_file)
QImage, qf2img, nparray_to_bio class/function Image utilities and conversions img = qf2img(my_file)
QChart class Chart object for calculator output chart = QChart(...)
QGeo, QMap class Geo/map output helpers m = QMap(...)
SmartCalc class Smart calculation helper engine sc = SmartCalc()
dd_list, DotDict (aliases: dd) function/class Dict convenience helpers / dot-access dict cfg = DotDict({"x": 1}); cfg.x

10) qtype annotations (input/output schema types)

These are classes used in calculator function signatures to define UI input/output fields.

10.1 Text, number, and basic input types

qchar, qfl, qin, qdate, qdatetime, qemail, qtext, qtexta, qtexte, qcode, qtime, qurl, qregex, qread

Example:

def bmi(weight: qfl, height_cm: qfl, note: qtexta = ""):
    ...

10.2 Hidden and function/meta fields

qfunc, qhide, qhidex

Example:

def my_calc(op: qfunc, token: qhide = "", internal: qhidex = ""):
    ...

10.3 Units and quantities

quom, quomx, quom2, qtx, qt, qt2, qtc, qtc2

Example:

def convert(value: qt, target_uom: quom2):
    ...

10.4 Collection and table types

qlist, qdict, qtbl

Example:

def totals(rows: qtbl):
    return QList(qdf(rows)["amount"]).sum()

10.5 File/image input

qfile, qimage

Example:

def upload_photo(photo: qimage):
    img = qf2img(photo)
    ...

10.6 Display/output-oriented types

qhtml, qvstr, qpage

Example:

def hello(name: qchar) -> qpage:
    return qpage(f"Hello, {name}")

11) Small utility

Symbol Kind What it does Example
minimum(*args, key=None) function Local alias to Python min (to avoid conflicts with minute unit min) minimum([5, 2, 9])