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]) |