Metadata-Version: 2.4
Name: wenyan
Version: 0.1.0
Summary: Wenyan programming language in Python
Project-URL: Homepage, https://github.com/tcztzy/wenyan
Project-URL: Source, https://github.com/tcztzy/wenyan
Project-URL: Issues, https://github.com/tcztzy/wenyan/issues
Author-email: Tang Ziya <tcztzy@gmail.Com>
License-File: LICENSE
Classifier: Development Status :: 1 - Planning
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: Chinese (Traditional)
Classifier: Programming Language :: Other
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Free Threading
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.10
Description-Content-Type: text/markdown

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:

```bash
uv tool install wenyan
```

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

```bash
uv tool install .
```

You can also install into an active Python environment:

```bash
python -m pip install wenyan
```

Quick Start
-----------

Create a small Wenyan program:

```wenyan
吾有一數。曰三。書之。
```

Save it as `hello.wy`, then run:

```bash
wenyan hello.wy
```

Expected output:

```text
3
```

Run the self-hosted path:

```bash
wywy hello.wy
```

From a checkout, you can run without installing:

```bash
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:

![Compiler benchmark summary](https://raw.githubusercontent.com/tcztzy/wenyan/master/benchmark/results/compiler_benchmark_summary.svg)

Runtime release summary:

![Runtime matrix summary](https://raw.githubusercontent.com/tcztzy/wenyan/master/benchmark/results/runtime_matrix_summary.svg)

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:

```bash
uv run python scripts/wyperformance.py run
```

Run the quick CI profile or inspect available workloads:

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

List benchmarks and groups:

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

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

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

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

```bash
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:

```bash
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):

```bash
uv run python scripts/benchmark_runtime_matrix.py
```

Run the quick runtime profile:

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

Compare two runtime matrix results:

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

Generate a Markdown runtime compare report:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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.
