Skip to content

Commit 9b2fe7b

Browse files
dylan-sutton-chavezdylan-sutton-chavez
committed
docs: Clean documentation README's.
1 parent 94da494 commit 9b2fe7b

9 files changed

Lines changed: 175 additions & 680 deletions

File tree

‎cli/README.md‎

Lines changed: 15 additions & 167 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,17 @@
11
# Edge Python CLI
22

3-
The Edge Python developer CLI. Write `.py`, run it, serve it, test it, ship it.
4-
5-
You never compile anything: `edge` hosts the Edge Python runtime in a headless browser provisioned by `install.sh`, then runs your code against it. You just point it at a file.
3+
The Edge Python developer CLI. Write `.py`, run it, serve it, ship it. You never compile anything: `edge` hosts the Edge Python runtime in a headless Chromium provisioned by `install.sh`, then runs your code against it.
64

75
```bash
8-
edge run app.py # run a script
9-
edge serve # dev server with live reload
10-
edge repl # interactive shell
11-
edge test # run your *_test.py files (not implemented yet)
12-
edge init my-app # scaffold a project
13-
edge add network # add a package to packages.json
14-
edge remove network # remove a package from packages.json
15-
edge build # bundle to dist/
16-
edge uninstall # remove the binary, PATH entry, optionally Chromium
6+
edge run app.py # run a script
7+
edge serve # dev server with live reload
8+
edge repl # interactive shell
9+
edge test # run your *_test.py files (not implemented yet)
10+
edge init my-app # scaffold a project
11+
edge add network # add a package to packages.json
12+
edge remove network # remove a package
13+
edge build # bundle to dist/
14+
edge uninstall # remove the binary, PATH entry, optionally Chromium
1715
```
1816

1917
## Install
@@ -22,164 +20,14 @@ edge uninstall # remove the binary, PATH entry, optionally Chromium
2220
# Prebuilt binary (recommended)
2321
curl -fsSL https://dylan-sutton-chavez.github.io/edge-python/install.sh | sh
2422

25-
# Or from source (any platform with a Rust and Cargo tools)
23+
# Or from source (any platform with Rust + Cargo)
2624
cargo install --path cli
2725
```
2826

29-
`install.sh` drops the binary at `~/.local/bin/edge` and appends that directory to your `~/.bashrc` or `~/.zshrc` if it is not already on `PATH`. Open a new shell (or `source` the file it printed) and `edge --version` should work. Re-run the same `curl … | sh` line any time to upgrade. To remove everything later: `curl -fsSL https://dylan-sutton-chavez.github.io/edge-python/uninstall.sh | sh` (asks before touching Chromium).
30-
31-
`install.sh` also provisions Chromium if it is not already on `PATH`. It reads `/etc/os-release` and uses the host's package manager (`apt`, `dnf`, `pacman`, `zypper`, `apk`, or `brew --cask` on macOS); `sudo` is invoked only when not running as root. If your distro is unsupported, install Chrome/Chromium manually or set `EDGE_CHROME_PATH=/path/to/chrome`.
32-
33-
---
34-
35-
## Run a Python File
36-
37-
Run a script and stream its output to the terminal. Imports resolve through `packages.json`; uncaught errors print a traceback to stderr and exit with code 1. A `raise SystemExit(code)` with an integer (or no argument) exits cleanly with that code (no traceback); a string argument is reported as an error and exits 1. The REPL treats SystemExit the same and quits the session.
38-
39-
```text
40-
$ edge run hello.py
41-
Hello from Edge Python
42-
the sum is 42
43-
```
44-
45-
```text
46-
$ edge run broken.py
47-
before
48-
error: ZeroDivisionError: division by zero
49-
--> <input>:2:1
50-
|
51-
2 | x = 1 / 0
52-
| ^
53-
```
54-
55-
Flags: `--packages <file>` (custom manifest). When no path is given, reads from stdin if it is piped (e.g., `cat hello.py | edge run`); errors out if stdin is a terminal.
56-
57-
---
58-
59-
## Start an Edge Python Shell (Demo)
60-
61-
An interactive Edge Python shell for quick experiments.
62-
63-
```text
64-
$ edge repl
65-
Edge Python 0.1.0 · .exit, Ctrl+C or Ctrl+D to quit
66-
>>> from math import sqrt, pi
67-
>>> print(sqrt(2))
68-
1.4142135623730951
69-
>>> print([n * n for n in range(5)])
70-
[0, 1, 4, 9, 16]
71-
>>> .exit
72-
```
73-
74-
History (arrow keys) and multi-line blocks (a line ending in `:` continues until a blank line) are supported. `.exit` or `Ctrl+C` quits; `Ctrl+D` also exits; `.reset` wipes the accumulated session. Expression results are not auto-printed; use `print()` explicitly.
75-
76-
State is preserved by **recompiling and rerunning the accumulated session on every prompt**. The runtime resets its VM on each `run_start`, so imports and definitions only persist by replay. Trade-offs: side effects (`time()`, `random()`, network, IO) re-fire on every input, the runtime's chunk heap grows linearly with session length, and each eval pays the recompile cost. A first-class incremental compile path in the VM is the proper fix and tracked for a future runtime change; for long sessions or side-effect-heavy code, prefer `edge run` on a script.
77-
78-
*Under development, this is just a demo because actual cost is o(n^2)*
79-
80-
---
81-
82-
## Setup a Local Server for your Browser App
83-
84-
A dev server for browser apps. Serves your project directory and reloads the page on any file change via an injected polling client.
85-
86-
```text
87-
$ edge serve
88-
http://localhost:5173
89-
watching .
90-
```
91-
92-
Flags: `--port <n>` (default `5173`), `--open` (open the browser).
93-
94-
---
95-
96-
## Edge Python Test
97-
98-
The `edge test` runner is not implemented yet. The `test` package itself (the harness you import) is available: `edge add test` writes it to `packages.json`, and `edge run` / `edge serve` resolve it by default, so a script can already `from test import fixture, test, raises, run` and call `run()` itself.
99-
100-
---
101-
102-
## Initialize a Workspace
103-
104-
Scaffolds a ready-to-run project: an entry script, an HTML host page, and a manifest.
105-
106-
```text
107-
$ edge init my-app
108-
created my-app/
109-
├─ index.html
110-
├─ main.py
111-
└─ packages.json
112-
113-
next:
114-
cd my-app && edge serve
115-
```
116-
117-
`--bare` skips `index.html` for script-only projects.
118-
119-
---
120-
121-
## Packages Manager
122-
123-
Manage `packages.json` by name. `edge` knows the official std (`json`, `re`, `math`, `test`) and host (`dom`, `network`, `storage`, `time`) packages, so you do not paste URLs. Most std packages are `.wasm`; `test` is pure Edge Python, so it resolves to `test.py`.
124-
125-
```text
126-
$ edge add math network
127-
+ math std
128-
+ network host
129-
130-
updated packages.json
131-
```
132-
133-
```text
134-
$ edge remove network
135-
- network
136-
137-
updated packages.json
138-
```
139-
140-
Point a package at a custom URL with `edge add foo=https://example.com/foo.wasm`.
141-
142-
---
143-
144-
## Build an Application to Create a Portable Version
145-
146-
Bundles your app into a self-contained `dist/` for offline use or self-hosting: the runtime, the `compiler.wasm`, your scripts, and every package vendored locally so nothing is fetched at runtime.
147-
148-
```text
149-
$ edge build
150-
(successful) vendored runtime
151-
(successful) fetched compiler.wasm
152-
(successful) vendored packages
153-
154-
bundled to dist/
155-
156-
13 runtime files + compiler.wasm
157-
2 packages
158-
3 scripts
159-
160-
1.24 MB · 5.3s
161-
```
162-
163-
Flags: `--out <dir>` (default `dist/`).
164-
165-
---
166-
167-
## Global flags
168-
169-
| Flag | Effect |
170-
|------|--------|
171-
| `--packages <file>` | Use a specific manifest instead of `./packages.json` |
172-
| `--no-color` | Disable colored output |
173-
| `--version` / `-V` | Print version |
174-
175-
`Ctrl+C` cancels any running command cleanly.
176-
177-
## Bring your own browser
178-
179-
`edge` drives whatever system Chrome/Chromium is on `PATH` (`chromium`, `chromium-browser`, `google-chrome`, or `microsoft-edge`). `install.sh` provisions it for you on supported distros and macOS; on anything else, install it manually or point `EDGE_CHROME_PATH=/path/to/chrome` at the binary.
27+
`install.sh` drops the binary at `~/.local/bin/edge`, puts it on `PATH`, and provisions Chromium via the host package manager if it is not already present. Re-run the same line to upgrade. Point `EDGE_CHROME_PATH=/path/to/chrome` at a custom browser.
18028

181-
## How it runs (the short version)
29+
Full command reference, flags, and examples: [edgepython.com/reference/cli](https://edgepython.com/reference/cli).
18230

183-
`edge` never asks you to compile. It launches a system Chromium headless, serves the Edge Python runtime alongside your code, and runs everything in that headless browser, streaming output back to your terminal. `edge serve` opens the same setup in your own browser for development.
31+
## License
18432

185-
The Edge Python runtime does the actual work; `edge` is the loop around it.
33+
MIT OR Apache-2.0

‎compiler/README.md‎

Lines changed: 9 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -7,18 +7,15 @@ A compact single-pass SSA bytecode compiler and stack VM for a sandboxed Python
77

88
## Architecture
99

10-
Single-pass pipeline: source -> bytecode in an SSA chunk; stack interpreter with adaptive inline caching and pure-function memoization.
10+
Single-pass pipeline: source -> SSA bytecode chunk; stack interpreter with adaptive inline caching and pure-function memoization.
1111

12-
* **Lexer** (`modules/lexer/`), LUT-driven, offset-based tokens. See [Lexical](https://edgepython.com/implementation/lexical).
13-
* **Parser** (`modules/parser/`), Pratt precedence; SSA-versioned bytecode with `Phi` at control-flow joins; no AST. See [Syntax (impl)](https://edgepython.com/implementation/syntax).
14-
* **Optimizer** (`modules/vm/optimizer.rs`), constant folding, Phi-noop elimination, dead-instruction compaction. Preserves `LoadName` for IC.
15-
* **VM** (`modules/vm/`), flat-match dispatch on `(opcode, operand: u16)`; `handlers/` + `handlers/builtin_methods/`. `LoadAttr + Call(0)` fuses into `CallMethod`.
16-
* **Inline caching** (`modules/vm/cache.rs`), scalar IC promotes arith/compare to typed `FastOp` after 4 hits; instance-dunder IC caches `(class_idx, method)`.
17-
* **Template memoization**, pure-function results cached after 2 hits; impurity tagged on `StoreItem` / `StoreAttr` / I/O / `raise` / `yield`.
18-
* **Memory**, NaN-boxed 64-bit `Val` (47-bit inline int, IEEE-754 float, bool, None, 28-bit heap index); mark-and-sweep arena; interned strings/bytes <= 128 B; auto-promote to i128 `LongInt`, capped at +/-2^127.
19-
* **Resolver** (`modules/packages/`), host-injected; `packages.json` walk-up; native imports register for `CallExtern` dispatch.
12+
* **Lexer** (`modules/lexer/`) LUT-driven, offset-based tokens.
13+
* **Parser** (`modules/parser/`) Pratt precedence, SSA-versioned bytecode with `Phi` at joins, no AST.
14+
* **Optimizer** (`modules/vm/optimizer.rs`) constant folding, Phi-noop elimination, dead-code compaction.
15+
* **VM** (`modules/vm/`) flat-match dispatch, scalar + instance-dunder inline caches, pure-function template memoization, NaN-boxed 64-bit `Val` with a mark-and-sweep arena.
16+
* **Resolver** (`modules/packages/`) host-injected; native imports register for `CallExtern` dispatch.
2017

21-
Full rationale, NaN-box patterns, IC thresholds, GC roots, and intentional omissions: [Design](https://edgepython.com/implementation/design).
18+
Full rationale, NaN-box patterns, IC thresholds, GC roots, and intentional omissions: [Design](https://edgepython.com/implementation/design). Lexer and parser internals: [Lexical](https://edgepython.com/implementation/lexical), [Syntax](https://edgepython.com/implementation/syntax).
2219

2320
## Layout
2421

@@ -60,13 +57,12 @@ edge-python = { git = "https://github.com/dylan-sutton-chavez/edge-python", tag
6057
// Downstream build.rs
6158
fn main() {
6259
println!("cargo::rerun-if-changed=build.rs");
63-
let wasm = std::env::var("DEP_COMPILER_LIB_WASM")
64-
.expect("`DEP_COMPILER_LIB_WASM` unset, upstream `edge-python` must declare `links = \"compiler\"`");
60+
let wasm = std::env::var("DEP_COMPILER_LIB_WASM").expect("`DEP_COMPILER_LIB_WASM` unset, upstream `edge-python` must declare `links = \"compiler\"`");
6561
std::fs::copy(&wasm, "runtime/compiler.wasm").expect("copy failed");
6662
}
6763
```
6864

69-
URL is derived from `<repository>/releases/download/v<version>/compiler.wasm`, a tag bump is the only retarget needed. Use `branch = "main"` for unreleased work. Requires `curl` on PATH. Gated by the default-on `prebuilt` feature; producer-side commands pass `--no-default-features` to skip.
65+
The download URL is derived from `CARGO_PKG_VERSION`, so a tag bump is the only retarget. Use `branch = "main"` for unreleased work. Requires `curl` on PATH; gated by the default-on `prebuilt` feature.
7066

7167
## References
7268

0 commit comments

Comments
 (0)