lclang

中文说明

lclang is a pure-Python, async-first configuration expression language for Python 3.14+. The 0.3.0 language, runtime, .lclcfg, and typed CLI release candidate is verified; publication is a separate maintainer action. See CHANGELOG.md.

The distribution and import name is lclang; production code lives under src/lclang.

Project status

• Target: 0.4.0 development release
• Latest completed milestone: M008 — lclang identity and src package layout
• Next planned milestone: M100 — trusted-input security boundary audit
• Implemented: foundation, enforced English rST API docs, source-aware lexer, immutable AST, complete expression/comprehension parsing, all planned V1 expression forms, deterministic AST-to-source rendering, semantic f-string parsing, stable root parse/print APIs, async expression evaluation with recursively awaited sync/async iterable items, lexical closures, structured failures, assertions, try recovery, finalization, and synchronous/asynchronous context management, semantic f-string evaluation, immutable runtime modules, and hierarchical single-flight Frame caching with structured cycle detection, cancellation isolation, and atomic targeted recalculation without dependant invalidation, plus task-local depth, work, and materialized-collection limits, deterministic Frame close/resource cleanup, scope-aware eager/conditional/deferred dependency analysis, immutable module dependency graphs, filtered queries, deterministic topological ordering, bounded runtime lookup tracing, static/dynamic edge reconciliation, and owner-aware immutable Frame dependency snapshots with atomic refresh semantics, plus shallow immutable host presets, reusable independent Frame factories, manifest-driven read-only attribute namespaces, and reviewed async iterable, text, immutable data, and strict JSON helpers in a standard preset, exposed through a focused root API for the complete runtime workflow, plus preferred source-string define_module/define_frame shortcuts and the canonical LCL_ROOT -> LCL_BUILTINS -> LCL_RUNTIME -> LCL_IMPORTS -> user hierarchy, preferred Frame.derive child construction, non-evaluating has and get_definition lookup inspection, side-effect-free inspect_variable dependency trees with first-seen direct-name deduplication and source-oriented one-line representations with typed value/error payloads, including canonical <node-type>: <LCL expression> payloads for AST values and canonical source reprs for evaluated LCL function closures, plus controlled right-biased Frame.mixin host-value updates, definition-scoped lhs(), strict YYYYMMDD date builtins, the native variadic fixed-point builtin recursive, and non-evaluating Frame-qualified dependency graphs with value terminals and lookup paths, lexical closure ownership for lhs(), source-string evaluate_sync, deterministic direct/FrameFactory IDs, and a dependency analytics tutorial backed by audited nested dependency and Frame packages, plus immutable CLI values, exact async command decorators, nested snake_case groups, full-argv parsing, structured help, lazy preset/default/config/override Frame layering, handler-owned dryrun, isolated logging, result/cleanup mapping, concise CliResult.success/fail constructors, valueless override keys as boolean True, and built-in parse_lcl with optional evaluated inspection, lazy eval_lcl, and deterministic nested builtins module commands, with canonical lclang builtins and standard namespaces identified as NativeProvided and rendered uniformly as Builtin Function or Builtin Namespace, plus structured failures carrying direct-to-failing variable evaluation stacks, plus ordered workflow execution-status trees, shared sub-task manager cursors, deterministic parent aggregation, subtree locking, exception-transparent with finalization, and scoped steps with atomic description/status updates and clean auto-success, packaged with the lclang identity from the src/lclang source tree
• Test status: 844 tests pass at 100.00% branch coverage; strict mypy, Ruff, exhaustive source/docstring policy, executable documentation, and artifact gates pass

The authoritative milestone ledger is in progress.md. Planned features are deliberately not presented as implemented features.

Quickstart

Run from a checkout with its development environment installed. The example is extracted and executed by the test suite.

import asyncio

import lclang


async def main() -> None:
    module = lclang.define_module(
        "quickstart",
        {"result": 'json.encode({"message": "hello lclang"})'},
    )
    frame = lclang.define_frame(module)
    try:
        print(await frame.get("result"))
        snapshot = frame.dependency_snapshot("result")
        print(",".join(str(edge.target) for edge in snapshot.dynamic_edges))
    finally:
        await frame.close()


asyncio.run(main())

Inspect an override-defined result without evaluating it, or evaluate it through the same lazy Frame pipeline:

python -m lclang.cli builtins
python -m lclang.cli parse_lcl -o a 100 -o b 200 -o RESULT "LCL[a+b]"
python -m lclang.cli eval_lcl -o a 100 -o b 200 -o RESULT "LCL[a+b]"

The first command lists canonical builtins and nested namespace methods. The second prints the static RESULT -> a, b inspection tree. The third prints 100200 because ordinary CLI override values are literal strings.

Continue with the tutorial index, then choose the runtime guide, LCL examples gallery, or configuration-file guide. Use the dependency analytics tutorial for static graphs, Frame paths, runtime traces, and reconciliation. The CLI tutorial shows how to build a configuration-driven Python script. The workflow-status tutorial explains task/step trees, aggregation, descriptions, locking, and scoped error capture for both tasks and steps. The runtime API guide remains the detailed reference.

Intended capability

The 0.4 target comprises:

• a versioned Python-like expression grammar with a custom AST;
• an async-first interpreter and cached hierarchical runtime frames;
• dependency analysis with eager, conditional, deferred, and dynamic edges;
• UTF-8 .lclcfg files with versioned using expansion and source-aware diagnostics;
• a typed framework for building configuration-driven command-line tools;
• strict typing, branch coverage, parser differential tests, stress tests, memory-leak checks, and portable package verification.

Engineering policy

Development is documentation-first and test-driven. Every implementation milestone starts with an executable behavioural contract, demonstrates a failing test, implements the behaviour, passes the complete quality gate, and then updates both README files and the progress ledger. Production and unit-test submodules mirror one another as defined in the module-layout specification.

The language is intended for trusted application configuration. It is not a security sandbox for hostile expressions.

Documentation

• Durable development rules: AGENTS.md
• Progress and verification evidence: progress.md
• English specifications: docs/specs/
• Complete LCL syntax: docs/lcl-lang.md
• English tutorial index: docs/tutorials/README.md
• Runtime tutorial: docs/tutorials/runtime.md
• LCL examples gallery: docs/tutorials/lcl_examples.md
• Configuration-file tutorial: docs/tutorials/config_file.md
• Dependency analytics tutorial: docs/tutorials/dependency-analytics.md
• Python-script CLI tutorial: docs/tutorials/cli.md
• Workflow-status tutorial: docs/tutorials/workflow-status.md
• Chinese CLI tutorial: doc_cn/cli_cn.md
• Chinese tutorials: doc_cn/

License

MIT. Version 0.3.0 requires Python 3.14+ and has no runtime dependencies.