collagraph 0.9.2

Reactive user interfaces

Collagraph 📓

Reactive user interfaces.

The word Collagraphy is derived from the Greek word koll or kolla, meaning glue, and graph, meaning the activity of drawing.

Inspired by Vue and React.

Features

Write your Python interfaces in a declarative manner with plain render functions, component classes or even single-file components using Vue-like syntax, but with Python!

• Reactivity (made possible by leveraging observ)
• Class components with local state and life-cycle methods/hooks
• Single-file components with Vue-like template syntax (.cgx files)
• Custom renderers

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

Contents of counter.cgx:

<widget>
  <label
    :text="f'Count: {count}'"
  />
  <button
    text="bump"
    @clicked="bump"
  />
</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:

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:

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

uv run collagraph examples/pyside/counter.cgx

For more examples, please take a look at the examples folder.

Currently there are two renderers:

• PysideRenderer: for rendering PySide6 applications
• PygfxRenderer: for rendering 3D graphic scenes with Pygfx

It is possible to create a custom Renderer using the Renderer interface, to render to other UI frameworks, for instance wxPython.

Development

To try out Collagraph or start development, run:

# 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 pre-commit 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
• Collagraph-lsp plugin for Sublime Text
• Collagraph-lsp plugin for VSCode

These plugins use collagraph-lsp for editor integration and ruff-cgx for formatting and linting capabilities.