Metadata-Version: 2.4
Name: genro-builders
Version: 0.9.0
Summary: Builder system for genro-bag - grammar, validation, compilation
Project-URL: Homepage, https://github.com/genropy/genro-builders
Project-URL: Repository, https://github.com/genropy/genro-builders
Author: Genropy Team
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: builder,compiler,genro,genropy,grammar,validation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: genro-bag>=0.11.0
Requires-Dist: genro-toolbox>=0.6.1
Provides-Extra: all
Requires-Dist: mypy>=1.0; extra == 'all'
Requires-Dist: myst-parser>=4.0.0; extra == 'all'
Requires-Dist: pytest-cov>=4.0; extra == 'all'
Requires-Dist: pytest>=7.0; extra == 'all'
Requires-Dist: ruff>=0.1.0; extra == 'all'
Requires-Dist: sphinx-autodoc-typehints>=3.0.0; extra == 'all'
Requires-Dist: sphinx-rtd-theme>=3.0.0; extra == 'all'
Requires-Dist: sphinx>=8.0.0; extra == 'all'
Requires-Dist: sphinxcontrib-mermaid>=1.0.0; extra == 'all'
Requires-Dist: xmlschema>=3.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: myst-parser>=4.0.0; extra == 'docs'
Requires-Dist: sphinx-autodoc-typehints>=3.0.0; extra == 'docs'
Requires-Dist: sphinx-rtd-theme>=3.0.0; extra == 'docs'
Requires-Dist: sphinx>=8.0.0; extra == 'docs'
Requires-Dist: sphinxcontrib-mermaid>=1.0.0; extra == 'docs'
Provides-Extra: xsd-validate
Requires-Dist: xmlschema>=3.0; extra == 'xsd-validate'
Description-Content-Type: text/markdown

# genro-builders

Builder system for [genro-bag](https://github.com/genropy/genro-bag) — grammar, validation, compilation, and reactive data binding.

## Installation

```bash
pip install genro-builders
```

## Quick start

```python
from genro_builders.builders import HtmlBuilder

builder = HtmlBuilder()
body = builder.source.body()
body.div(id='main').p('Hello, world!')

builder.build()
print(builder.output)
```

### Subclass pattern with `main()` and `store()`

```python
from genro_builders.builders import HtmlBuilder

class MyPage(HtmlBuilder):
    def store(self, data):
        data['title'] = 'Hello, world!'

    def main(self, source):
        body = source.body()
        body.h1(value='^title')
        self.footer(source)

    def footer(self, source):
        source.footer().p('© 2026')

page = MyPage()
page.build()
print(page.output)
```

## Features

- **Domain-specific grammars** — Define elements, validation rules, and components via decorators (`@element`, `@abstract`, `@component`)
- **Named slots** — Components can declare insertion points (`slots=['left', 'right']`) for user content injection
- **Built-in builders** — HTML5, Markdown, XSD (schema-driven XML)
- **Reactive pipeline** — Build source, resolve `^pointer` bindings, render output. Data changes trigger automatic re-render
- **Multi-builder coordination** — `BuilderManager` coordinates multiple builders with a shared data store
- **Renderers and compilers** — `@renderer` for serialized output (HTML, Markdown), `@compiler` for live objects (widgets, workbooks)
- **Node identification** — `node_id` attribute for O(1) lookup via `node_by_id()`
- **Validation** — `sub_tags` cardinality, `parent_tags` constraints, typed attribute validation

## Architecture

A builder owns the full pipeline:

```text
store(data)   →  main(source)  →  build()  →  render() / compile()  →  output
                      │               │                │
                 @element,      components        string (render)
                 @component     expanded,         or live objects
                 as nodes       ^pointers         (compile)
                                resolved
```

- **`store(data)`** — optional: populate the data Bag
- **`main(source)`** — entry point: build the element tree
- **`build()`** — materialize: expand components, resolve `^pointer` bindings
- **`render()`** — produce serialized output via `BagRendererBase`
- **`compile()`** — produce live objects via `BagCompilerBase`

Data changes after build trigger automatic updates via `BindingManager`.

## Documentation

See the [docs/](docs/) directory for full documentation.

## License

Apache License 2.0 — Copyright 2025 Softwell S.r.l.
