Wenyan Programming Language in Python

Wenyan.py is a Python implementation of the Wenyan programming language. It is packaged as a small, zero-runtime-dependency interpreter/compiler module and ships two command line entry points:

• wenyan: run Wenyan programs through the Python implementation.
• wywy: run through the self-hosted wenyan.wy path.

Installation

Install the released CLI tools into uv's user tool directory:

uv tool install wenyan

For a local checkout, install the current tree the same way:

uv tool install .

You can also install into an active Python environment:

python -m pip install wenyan

Quick Start

Create a small Wenyan program:

吾有一數。曰三。書之。

Save it as hello.wy, then run:

wenyan hello.wy

Expected output:

3

Run the self-hosted path:

wywy hello.wy

From a checkout, you can run without installing:

uv run wenyan.py examples/helloworld.wy
uv run wenyan.py --help

Benchmarks

Current Snapshot

• Current compiler release result: benchmark/results/wyperformance.release.v2.json
• Current runtime release result: benchmark/results/runtime_matrix.release.json
• Generated compiler compare report: benchmark/results/wyperformance.release.compare.md
• Generated runtime compare report: benchmark/results/runtime_matrix.release.compare.md

Compiler release summary:

Runtime release summary:

Current release highlights:

area	result
compiler full pipeline	compile_total median 0.432147s over 17 workloads
compiler pure Python compile stage	compile_code median 0.037830s
compiler peak memory	compile_total peak 23847.2 KiB
fastest runtime in release profile	cli[bun] at 0.066852s per workload
fastest wenyan.py runtime	wenyan.py[py314] at 0.094772s per workload
fastest self-host path	wywy[node] at 0.133446s per workload

Compiler compare notes:

• release.v2 fixes compile_code so it now measures only Python compile().
• Historical comparisons should therefore use lexer_only, parse_total, preprocess_total, compile_ast, and compile_total.
• See benchmark/results/wyperformance.release.compare.md for the stable-case comparison.
• The report is generated by scripts/wyperformance.py compare, not hand-edited.

Runtime compare notes:

• benchmark/results/runtime_matrix.release.compare.md is generated by scripts/benchmark_runtime_matrix.py compare.
• Its current baseline is the historical examples_runtime_benchmark.json corpus, so ratios are directional only.

Run the pyperf/pyperformance-style Wenyan benchmark suite:

uv run python scripts/wyperformance.py run

Run the quick CI profile or inspect available workloads:

uv run python scripts/wyperformance.py run --profile ci
uv run python scripts/wyperformance.py list_workloads

List benchmarks and groups:

uv run python scripts/wyperformance.py list
uv run python scripts/wyperformance.py list_groups

Run only selected benchmarks/workloads (supports include/exclude):

uv run python scripts/wyperformance.py run --benchmarks compiler,-compile_code --workloads synthetic

Compare two result JSON files (normal or table style):

uv run python scripts/wyperformance.py compare base.json changed.json
uv run python scripts/wyperformance.py compare base.json changed.json -O table

Generate a Markdown compare report and exclude incompatible benchmark definitions:

uv run python scripts/wyperformance.py compare \
  benchmark/results/wyperformance.release.json \
  benchmark/results/wyperformance.release.v2.json \
  --exclude compile_code \
  --note "compile_code benchmark definition changed in release.v2 and now measures only Python compile()." \
  --note "Use lexer_only, parse_total, preprocess_total, compile_ast, and compile_total for historical comparison." \
  --markdown benchmark/results/wyperformance.release.compare.md

Default output:

• benchmark/results/wyperformance.json

Run the runtime matrix benchmark (shared workload manifest):

uv run python scripts/benchmark_runtime_matrix.py

Run the quick runtime profile:

uv run python scripts/benchmark_runtime_matrix.py --profile ci

Compare two runtime matrix results:

uv run python scripts/benchmark_runtime_matrix.py compare base.json contender.json

Generate a Markdown runtime compare report:

uv run python scripts/benchmark_runtime_matrix.py compare \
  benchmark/results/examples_runtime_benchmark.json \
  benchmark/results/runtime_matrix.release.json \
  --output-md benchmark/results/runtime_matrix.release.compare.md \
  --note "Baseline uses the historical examples_runtime_benchmark.json corpus (42 examples), while contender uses the new release workload manifest (17 workloads)." \
  --note "Per-workload ratios are directional only because the workload set and startup probe rounds differ between the two runs."

Generate README-ready SVG charts through Wenyan + matplotlib:

uv run --with matplotlib wenyan.py benchmark/charts/compiler_summary.wy
uv run --with matplotlib wenyan.py benchmark/charts/runtime_matrix_summary.wy

The chart programs read JSON by default. You can override input/output paths with environment variables:

WENYAN_BENCHMARK_INPUT=benchmark/results/wyperformance.json \
WENYAN_BENCHMARK_OUTPUT=benchmark/results/compiler_benchmark_summary.svg \
uv run --with matplotlib wenyan.py benchmark/charts/compiler_summary.wy

For compiler charts, you can also provide a baseline JSON to render a ratio panel:

WENYAN_BENCHMARK_INPUT=benchmark/results/wyperformance.json \
WENYAN_BENCHMARK_BASELINE=/path/to/older-wyperformance.json \
WENYAN_BENCHMARK_OUTPUT=benchmark/results/compiler_benchmark_summary.svg \
uv run --with matplotlib wenyan.py benchmark/charts/compiler_summary.wy

For runtime charts, you can also provide a baseline JSON to render a ratio panel:

WENYAN_BENCHMARK_INPUT=benchmark/results/examples_runtime_benchmark.json \
WENYAN_BENCHMARK_BASELINE=/path/to/older-runtime-matrix.json \
WENYAN_BENCHMARK_OUTPUT=benchmark/results/runtime_matrix_summary.svg \
uv run --with matplotlib wenyan.py benchmark/charts/runtime_matrix_summary.wy

Include free-threading builds and use 100 startup probe runs:

uv run python scripts/benchmark_runtime_matrix.py --include-free-threading --startup-rounds 100

Outputs:

• benchmark/results/examples_runtime_benchmark.json
• benchmark/results/examples_runtime_benchmark.csv
• benchmark/results/examples_runtime_benchmark.md
• benchmark/results/wyperformance.md
• benchmark/results/wyperformance.release.compare.md
• benchmark/results/runtime_matrix.release.compare.md
• benchmark/results/compiler_benchmark_summary.svg
• benchmark/results/runtime_matrix_summary.svg

examples_runtime_benchmark.md is formatted for direct embedding into README as a table/chart-like summary.

wyperformance.json now also includes per-case peak_memory_bytes metadata when tracemalloc is available, writes a Markdown summary, and the compiler SVG can render time, peak memory, and optional baseline ratio.