Metadata-Version: 2.4
Name: ruledwdl
Version: 0.3.3
Summary: Python port of the Web Definition Language (WDL) core component engine
Author-email: Pradeep Dabane <pradeep@ruledweb.com>
License: AGPL-3.0-or-later
Project-URL: Homepage, https://github.com/ruledweb/ruledwdl-python
Project-URL: Repository, https://github.com/ruledweb/ruledwdl-python.git
Keywords: ruledwdl,wdl,web-definition-language,renderer,layout-engine,html
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: fastapi>=0.100.0; extra == "dev"
Requires-Dist: uvicorn>=0.20.0; extra == "dev"
Dynamic: license-file

# Web Definition Language — Python Core Engine (`ruledwdl`)

> Python port of the Web Definition Language (WDL) core component rendering engine.

`ruledwdl` is a pure Python implementation of the WDL component renderer (1:1 replica of `@ruledwdl/csr` / `ruledwdl-php`). It takes `REGISTRY`, `COMPONENTS`, and `DATA` JSON definitions and compiles them into clean HTML markup with zero runtime external dependencies.

---

## Features

- **Zero External Dependencies**: Pure Python 3.8+ implementation with **0 third-party packages required**.
- **WDL Layers Syntax v0.3.x**: Emmet-like layer expressions (`tag.semantic_id`, `>`, `+`, `<`, `<*N`, `<@N`, `*repeat`, `*loopKey`) backed by `WDLDomTree`.
- **Registry Schema V2.1 Support**: Compiles Scoped CSS Rules (`@scope`), inheritance (`uses`), theme variables, and `data-variant` attributes.
- **Component Identifier Attributes**: Automatically emits `wdl-comp="{semantic_id}"` and `data-wdl-index` for precise element targeting.
- **Pluggable Hooks**: Supports custom `transformData` and `transformText` hooks for external text formatting or Markdown parsing.

---

## Installation

```bash
pip install ruledwdl
```

Or install locally:

```bash
pip install -e .
```

---

## Usage Example

### Plain Python

```python
from ruledwdl import render

registry = {
    "$version": "2.1",
    "card": {
        "class": "p-6 bg-slate-800 border border-slate-700 rounded-xl"
    }
}

components = [
    {
        "layers": "div.card > h2.title + p.desc",
        "attr": {
            ".title": {"text": "${title}", "class": "text-xl font-bold text-white"},
            ".desc": {"text": "${desc}", "class": "text-slate-400"}
        }
    }
]

data = {
    "title": "RuledWDL Python",
    "desc": "Native server-side WDL layout rendering in Python."
}

html = render(registry, components, data)
print(html)
```

---

## FastAPI Integration

```python
from fastapi import FastAPI
from fastapi.responses import HTMLResponse
from ruledwdl import render

app = FastAPI()

@app.get("/", response_class=HTMLResponse)
def home():
    components = [
        {
            "layers": "main.container > h1.heading + p.body",
            "attr": {
                ".heading": {"text": "FastAPI + RuledWDL", "class": "text-3xl font-extrabold"},
                ".body": {"text": "Rendered dynamically with Python."}
            }
        }
    ]
    html = render({}, components, {})
    return HTMLResponse(content=html)
```

---

## Running Examples & Tests

### Run Smoke Unit Tests
```bash
python3 -m unittest discover -s tests
```

### Run Plain CLI Demo
```bash
python3 examples/cli.py
```

### Run FastAPI Demo App
```bash
uvicorn examples.fastapi_app:app --reload
```

---

## License

Licensed under [GNU Affero General Public License v3.0 (AGPL-3.0-or-later)](LICENSE).
