# PyWasot

Python bindings for the Wasot event-driven markup language.

## Installation

```bash
# From the python directory
pip install maturin
maturin develop --features python
```

## Learning PyWasot

PyWasot offers three API levels. Run the demos in order to understand each approach:

### Demo 000: Raw Events (Low-Level)

```bash
python demos/000_iterate_raw_events.py
```

Direct access to Rust types for maximum performance. Use this when processing large files or when you need minimal overhead.

```python
from pywasot._pywasot import (
    BlockStartedEvent, BlockFinishedEvent, TextEvent,
    parse_wasot_string,
)

for event in parse_wasot_string(content, None):
    if isinstance(event, BlockStartedEvent):
        meta = event.meta_line
        print(f".{meta.type_name} (level={meta.level})")
```

### Demo 001: Wrapped Events (Mid-Level)

```bash
python demos/001_wrapped_events_for_dx.py
```

Pythonic event wrappers with pattern matching, JSON serialization, and cloning.

```python
import pywasot

for event in pywasot.parse(content):
    match event:
        case pywasot.BlockStarted():
            print(f".{event.type_name}")
        case pywasot.Text():
            print(event.content)
        case pywasot.BlockFinished():
            print("done")

# Create events programmatically
event = pywasot.BlockStarted.create("section", level=2, id="intro")
```

### Demo 002: Tree API (High-Level)

```bash
python demos/002_tree_like_interface.py
```

Full tree structure with CSS selectors, navigation, and dict-like access. Best for document manipulation and querying.

```python
import pywasot

root = pywasot.parse(content)

# Dict-like access
title = root['meta']['title'].inline_text

# CSS selectors
sections = root.find('section')
intro = root.find_one('#intro')
items = root.find('list > item')

# Navigation
for child in root:
    print(child.type_name)

# Text extraction
print(intro.text)
```

## Quick Reference

| Use Case | API Level | Entry Point |
|----------|-----------|-------------|
| Large file streaming | Raw Events | `pywasot._pywasot.parse_wasot_string()` |
| Event processing | Wrapped Events | `pywasot.parse()` with iteration |
| Document querying | Tree API | `pywasot.parse()` with selectors |
| JSON serialization | Tree API | `pywasot.loads()` / `pywasot.dumps()` |
