Metadata-Version: 2.4
Name: wasmon
Version: 0.2
Summary: Wasmon: a Python-first WebAssembly compiler
Author: wasmon contributors
License-Expression: MIT
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: run
Requires-Dist: wasmtime<48,>=47; extra == "run"
Dynamic: license-file

# Wasmon

Wasmon is a small Python-first compiler that turns readable, typed Python
function definitions into compact WebAssembly binaries.

It is deliberately pre-alpha: the supported language is small, direct, and
tested, rather than pretending to compile arbitrary Python.

## Start here

The complete copy-and-adapt reference is the
[WebAssembly Syntax Guide](WebAssembly%20Syntax%20Guide.md). It documents every
currently supported construct, its generated WebAssembly role, and its
important limits.

```python
from wasmon import *

with WebAssembly("sum") as wasm:
    @wasm.func(export=True)
    def sum_except_five(limit: i32) -> i32:
        current = i32(0)
        total = i32(0)

        with loop() as repeat:     # explicit Wasm loop
            with branch(current >= limit):
                repeat.brk()

            current += 1
            with branch(current == 5):
                repeat.cont()
            total += current

        return total               # ordinary Python return syntax


wasm.save('module.wasm')
mod_inst = wasm.instance()
assert mod_inst.sum_except_five(10) == 50
```

`@wasm.func` reads and compiles the function source; it does not run its body
as Python. Python arithmetic operators construct typed Wasm expressions, local
assignment becomes Wasm local assignment, and `branch()`, `loop()`, and
`block()` are explicit structured-control scopes.

`WebAssembly.instance()` compiles the module and exposes its exported functions
as Python callables. It uses Wasmtime, which is available through the runtime
extra or the included requirements file:

```console
pip install "wasmon[run]"
# or, for a source checkout:
pip install -r requirements.txt
```

## Current capabilities

- Typed numeric values: signed/unsigned 8-, 16-, 32-, and 64-bit integers,
  plus `f32` and `f64`; normal arithmetic, bitwise operators, casts, and
  comparisons.
- Typed function declarations and calls, default numeric arguments, exported
  functions, `-> None` functions, and imported host functions.
- One automatic, exported wasm32 linear memory when memory is needed; typed
  pointers, a small allocator, and raw host/Wasm shared-memory interop.
- Explicit Wasm control flow with natural Python `return` syntax.
- Includeable `stdlib` namespace with literal UTF-8 `String` and resizable
  numeric `Array[T]` values.
- Module-owned linear-memory structs with padded or packed layouts, nested
  fields, compiled instance methods, typed address ABI lowering, and explicit
  destruction.
- Opt-in persistent numeric globals, an initialized function table for
  indirect calls, a single start function, and optional standard Wasm debug
  name metadata.

Module sections are demand-driven: a function-only module does not pay for
memory, data, global, table, start, or debug sections it does not use.

## Interoperability in one example

Imports are declared before local functions. Wasmon owns the linear memory;
the host reads and writes it through its WebAssembly engine and passes raw
`u32` addresses to exported functions.

```python
from wasmon import *

with WebAssembly("interop") as wasm:
    @wasm.import_func("host", name="record")
    def log(value: i32) -> None:
        ...                         # supplied by the embedding host

    @wasm.func(export=True)
    def add_pair(address: u32) -> i32:
        values = pointer[i32].from_address(address)
        log(values[0])
        return values[0] + values[1]
```

For more examples—including allocation, String, Array, globals, indirect
calls, and start initialization—use the
[syntax guide](WebAssembly%20Syntax%20Guide.md).

## Structs

Structs are named linear-memory layouts, not Python objects or Wasm GC values.
Declare them before local functions, then use fields and methods naturally:

```python
from wasmon import *

with WebAssembly("geometry") as wasm:
    @wasm.struct
    class Vec2:
        x: f32
        y: f32

        def __init__(self, x: f32, y: f32) -> None:
            self.x = x
            self.y = y
            return

        def length_squared(self) -> f32:
            return self.x * self.x + self.y * self.y

    @wasm.func(export=True)
    def squared() -> f32:
        point = Vec2(3.0, 4.0)
        result = point.length_squared()
        point.free()
        return result
```

Fields may be numeric Wasmon types or earlier structs, which are embedded by
value. `StructType.from_address(address)` creates a typed view over shared
linear memory. Struct function parameters and results are `u32` addresses in
the Wasm ABI. See the [syntax guide](WebAssembly%20Syntax%20Guide.md#generic-structs)
for padding, nested copies, index dunders, and lifetime rules.

## Boundaries and safety

This compiler is intentionally not a Python runtime. Native Python `if`,
`while`, `for`, exceptions, Python containers, arbitrary classes other than
`@wasm.struct`, and imports inside compiled functions are unsupported.
`WebAssembly.instance()` is a thin adapter for executing compiled, trusted
modules with Wasmtime; it does not make arbitrary Python executable as Wasm or
configure Wasmtime resource limits.

Pointers are raw Wasm addresses. Wasmon validates types and static negative
indexes, but does not track allocation size, ownership, or lifetime. A dynamic
overread within linear memory can observe neighboring data; an out-of-range
linear-memory access traps in the Wasm engine. Double-free is unsafe. Imported
host functions are an ABI and trust boundary, too.

The current module model intentionally has one automatic memory and one
initialized table. It does not import host memory, globals, or tables; support
table mutation; or provide bulk-memory/passive-segment features.

## Testing

The public scripts under `tests/scripts/` compile realistic user programs and,
when separately installed, execute them with Wasmtime. `requirements.txt` and
the `run` extra install that execution runtime. They cover algorithms,
numeric behavior, allocator lifecycle, stdlib values, host interop, module
sections, benchmarks, and documented failure cases. See
[tests/README.md](tests/README.md) for commands. Wasmtime is imported only by
`WebAssembly.instance()` and is not required for compiling modules or running
the normal test suite.

## Project status

Wasmon is version `0.2`, pre-alpha. The current WebAssembly API is useful for
small numeric kernels and explicit low-level interop experiments. Expect the
surface to evolve; rely on the syntax guide and tests as the authoritative
description of supported behavior.
