Metadata-Version: 2.4
Name: collagraph
Version: 0.10.0
Summary: Reactive user interfaces
Author-email: Berend Klein Haneveld <berendkleinhaneveld@gmail.com>, Korijn van Golen <korijn@gmail.com>
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: observ>=0.17.1
Provides-Extra: pygfx
Requires-Dist: pygfx>=0.13.0; extra == 'pygfx'
Provides-Extra: pyside
Requires-Dist: pyside6!=6.8.3,!=6.9.0,>=6.6.2; (python_version < '3.15') and extra == 'pyside'
Description-Content-Type: text/markdown

[![PyPI version](https://badge.fury.io/py/collagraph.svg)](https://badge.fury.io/py/collagraph)
[![CI status](https://github.com/fork-tongue/collagraph/workflows/CI/badge.svg)](https://github.com/fork-tongue/collagraph/actions)
[![Docs](https://github.com/fork-tongue/collagraph/workflows/Docs/badge.svg)](https://fork-tongue.github.io/collagraph/)

# Collagraph 📓

Reactive user interfaces.

> The word [Collagraphy](https://en.wikipedia.org/wiki/Collagraphy) is derived from the Greek word _koll_ or _kolla_, meaning glue, and graph, meaning the activity of drawing.

Inspired by Vue and React. Check out the [documentation](https://fork-tongue.github.io/collagraph/) to get started.


## Features

Write your Python interfaces in a declarative manner as single-file components with Vue-like syntax (`.cgx` files), but with Python!

* Fine-grained reactivity (made possible by leveraging [observ](https://github.com/fork-tongue/observ))
* Class components with local state and life-cycle methods/hooks
* Single-file components with Vue-like template syntax (`.cgx` files)
* Renderers for PySide6 and [Pygfx](https://github.com/pygfx/pygfx), with support for custom renderers

Here is an example that shows a counter, made with a component with Vue-like syntax:

Contents of `counter.cgx`:
```html
<widget>
  <label>Count: {{ count }}</label>
  <button @clicked="bump">bump</button>
</widget>

<script>
import collagraph as cg


class Counter(cg.Component):
    def init(self):
        self.state["count"] = 0

    def bump(self):
        self.state["count"] += 1
</script>
```

Contents of `app.py`:
```python
from PySide6 import QtWidgets
import collagraph as cg

# After importing collagraph, it's possible to import
# components directly from .cgx files
from counter import Counter

# Create a Collagraph instance with a PySide renderer
# and register with the Qt event loop
gui = cg.Collagraph(renderer=cg.PySideRenderer())
# Render the component into a container
# (in this case the app but can be another widget)
app = QtWidgets.QApplication()
gui.render(Counter, app)
app.exec()
```

Which looks something like this:

![collagraph example](https://github.com/fork-tongue/collagraph/assets/1000968/4ebae92e-d7be-48ea-b76a-c6eab8d62112)

Instead of using a python file as an entry point to run components, you can run them directly using the collagraph CLI:

```sh
uv run collagraph examples/pyside/counter.cgx
```

To inspect the Python code that is compiled for a component, use the `--show-code` flag:

```sh
uv run collagraph --show-code examples/pyside/counter.cgx
```

For more examples, please take a look at the [examples folder](examples). For guides and API reference, visit the [documentation](https://fork-tongue.github.io/collagraph/).

Currently there are two renderers:

* [PysideRenderer](collagraph/renderers/pyside_renderer.py): for rendering PySide6 applications
* [PygfxRenderer](collagraph/renderers/pygfx_renderer.py): for rendering 3D graphic scenes with [Pygfx](https://github.com/pygfx/pygfx)

It is possible to create a custom Renderer using the [Renderer](collagraph/renderers/__init__.py) interface, to render to other UI frameworks, for instance wxPython.


## Development

To try out Collagraph or start development, run:

```sh
# Basic dev setup (no pygfx or pyside)
uv sync
# Full dev setup
uv sync --all-groups
# Run example:
uv run python examples/pyside/layout-example.py
# Run test suite:
uv run pytest
# Install git pre-commit hooks to make sure tests/linting passes before committing
uv run prek install
```


### Editor Integration

Syntax highlighting, linting and formatting for single-file components (`.cgx`) is supported for Zed, VSCode and Sublime Text:

* [Collagraph-lsp plugin for Zed](https://github.com/fork-tongue/collagraph-lsp-zed)
* [Collagraph-lsp plugin for Sublime Text](https://github.com/fork-tongue/collagraph-lsp-sublime)
* [Collagraph-lsp plugin for VSCode](https://github.com/fork-tongue/collagraph-lsp-vscode)

These plugins use [collagraph-lsp](https://github.com/fork-tongue/collagraph-lsp) for editor integration and [ruff-cgx](https://github.com/fork-tongue/ruff-cgx) for formatting and linting capabilities.
