lclang documentation¶

A typed, async-first configuration expression language for Python. Define relationships once, supply the context, and calculate only what you need.

• Quick start — Install lclang and make your first calculation.
• Tutorial series — Learn through complete, executable examples.
• Language & API reference — Look up syntax, APIs, and lifecycle contracts.
• Development guide — Work on the library and run its quality checks.

Start with one expression¶

Requires Python 3.14 or newer. Pure Python, with no third-party runtime dependencies. See installation for environment setup.

python -m pip install lclang

import asyncio

from lclang.lang import define_frame, define_module


TOTAL = define_module("total", {"result": "unit_price * quantity"})


async def main() -> None:
    async with define_frame(
        TOTAL,
        preset={"unit_price": 6, "quantity": 4},
    ) as frame:
        assert await frame.get("result") == 24


asyncio.run(main())

Python supplies unit_price and quantity; LCL owns their relationship. The definition named result multiplies 6 by 4 and returns 24. The Frame supplies canonical builtins and host inputs, caches the requested value, and closes when the async with block ends. asyncio.run() starts the loop at a synchronous application's boundary; async applications await their existing coroutine.

Define once. Evaluate in context.¶

A Module is an immutable collection of named definitions. A Frame combines those definitions with inputs, lazy cached results, and owned asynchronous work for one run. Reuse the Module; create and close a Frame for each independent run.

Module + host inputs → Frame → requested result
                         └── cached dependency snapshots

Names resolve on demand. Concurrent readers share in-flight work, and later reads reuse the snapshot. Changing an input does not automatically invalidate its dependants. The Modules and Frames tutorial walks through this model with runnable Python.

Find your next topic¶

• Reference index
• LCL V1 language specification, including immutable records
• Runtime API, including Frame proxy discovery and records
• Configuration format and API
• Environment, logging, standard, and workflow utilities
• Command-line API
• Tree workflow API
• Business-day calendars
• Unified process logging
• Exceptions and grouped failures

Trust and ownership¶

lclang is a trusted configuration language, not a hostile-code sandbox. Host objects and callables retain the capabilities your application gives them. Keep that boundary narrow, and close caller-owned Frames with async with.

These pages are built from the tested Markdown in docs/. The GitHub Wiki remains an alternative view of the same documentation.