collagraph 0.8.6__tar.gz

collagraph-0.8.6/.coveragerc

@@ -0,0 +1,3 @@
+[run]
+omit =
+    collagraph/renderers/dom_renderer.py

collagraph-0.8.6/.github/workflows/ci.yml

@@ -0,0 +1,119 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - master
+    tags:
+      - "v*"
+  pull_request:
+    branches:
+      - master
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: "pyproject.toml"
+      - name: Install only dev dependencies
+        run: uv sync --only-group dev
+      - name: Lint
+        run: uv run --no-sync ruff check .
+      - name: Format
+        run: uv run --no-sync ruff format --check .
+
+  test:
+    name: Test on ${{ matrix.name }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: Linux py310
+            pyversion: "3.10"
+          - name: Linux py311
+            pyversion: "3.11"
+          - name: Linux py312
+            pyversion: "3.12"
+          - name: Linux py313
+            pyversion: "3.13"
+          - name: Linux py314
+            pyversion: "3.14"
+    steps:
+      - uses: actions/checkout@v5
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+      - name: Set up Python ${{ matrix.pyversion }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.pyversion }}
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update -y -qq
+          sudo apt-get install -y libgles2-mesa-dev
+      - name: Install dependencies
+        run: uv sync --all-groups
+      - name: Test
+        run: uv run pytest -v --cov=collagraph --cov-report=term-missing
+        env:
+          QT_QPA_PLATFORM: offscreen
+
+  build:
+    name: Build and test wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+      - name: Set up Python 3.10
+        uses: actions/setup-python@v2
+        with:
+          python-version: "3.10"
+      - name: Install dependencies
+        run: uv sync
+      - name: Build wheel
+        run: uv build
+      - name: Twine check
+        run: uv run twine check dist/*
+      - name: Upload wheel artifact
+        uses: actions/upload-artifact@v4
+        with:
+          path: dist
+          name: dist
+
+  publish:
+    name: Publish to Github and Pypi
+    runs-on: ubuntu-latest
+    needs: [lint, test, build]
+    if: success() && startsWith(github.ref, 'refs/tags/v')
+    environment:
+      name: pypi
+      url: https://pypi.org/p/collagraph
+    permissions:
+      id-token: write
+      contents: write
+    steps:
+      - uses: actions/checkout@v5
+      - name: Download wheel artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+      - name: Release to GitHub
+        uses: softprops/action-gh-release@v2
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          files: |
+            dist/*.tar.gz
+            dist/*.whl
+          draft: true
+          prerelease: false
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

collagraph-0.8.6/.gitignore

@@ -0,0 +1,8 @@
+*.egg-info/
+__pycache__
+.vscode
+.coverage
+dist
+build
+uv.lock
+.venv

collagraph-0.8.6/.pre-commit-config.yaml

@@ -0,0 +1,32 @@
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+repos:
+  # -   repo: https://github.com/pre-commit/pre-commit-hooks
+  #     rev: v3.2.0
+  #     hooks:
+  #     -   id: trailing-whitespace
+  #     -   id: end-of-file-fixer
+  #     -   id: check-yaml
+  #     -   id: check-added-large-files
+  - repo: local
+    hooks:
+      - id: lint
+        name: lint
+        entry: uv run ruff check
+        language: system
+        types: [python]
+        require_serial: true
+      - id: format
+        name: format
+        entry: uv run ruff format --check
+        language: system
+        types: [python]
+        require_serial: true
+      - id: test
+        name: pytest
+        entry: uv run pytest tests
+        language: system
+        types: [text]
+        files: \.(py|cgx)$
+        require_serial: true
+        pass_filenames: false

collagraph-0.8.6/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright © 2022-2025 collagraph authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

collagraph-0.8.6/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: collagraph
+Version: 0.8.6
+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.14.1
+Provides-Extra: pygfx
+Requires-Dist: pygfx>=0.9.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)
+
+# 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.
+
+
+## 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](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)
+* 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
+    :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`:
+```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
+```
+
+For more examples, please take a look at the [examples folder](examples).
+
+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 pre-commit install
+```
+
+
+### Syntax Highlighting
+
+Syntax highlighting for single-file components (`.cgx`) is supported for VSCode and Sublime Text:
+
+* [CGX syntax highlight for Sublime Text](https://github.com/fork-tongue/cgx-syntax-highlight-sublime)
+* [CGX syntax highlight for VSCode](https://github.com/fork-tongue/cgx-syntax-highlight-vscode)
+
+
+### Formatting and linting
+
+Linting and formatting cgx files is possible with: [ruff-cgx](https://github.com/fork-tongue/ruff-cgx).

collagraph-0.8.6/README.md

@@ -0,0 +1,116 @@
+[![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)
+
+# 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.
+
+
+## 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](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)
+* 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
+    :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`:
+```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
+```
+
+For more examples, please take a look at the [examples folder](examples).
+
+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 pre-commit install
+```
+
+
+### Syntax Highlighting
+
+Syntax highlighting for single-file components (`.cgx`) is supported for VSCode and Sublime Text:
+
+* [CGX syntax highlight for Sublime Text](https://github.com/fork-tongue/cgx-syntax-highlight-sublime)
+* [CGX syntax highlight for VSCode](https://github.com/fork-tongue/cgx-syntax-highlight-vscode)
+
+
+### Formatting and linting
+
+Linting and formatting cgx files is possible with: [ruff-cgx](https://github.com/fork-tongue/ruff-cgx).

collagraph-0.8.6/collagraph/__init__.py

@@ -0,0 +1,9 @@
+from importlib.metadata import version
+
+from .collagraph import Collagraph  # noqa: F401
+from .component import Component  # noqa: F401
+from .constants import EventLoopType  # noqa: F401
+from .renderers import *  # noqa: F403
+from .sfc import importer  # noqa: F401
+
+__version__ = version("collagraph")

collagraph-0.8.6/collagraph/__main__.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+import argparse
+import importlib
+import json
+from pathlib import Path
+
+from observ import reactive
+
+import collagraph as cg
+
+
+def available_renderers():
+    result = set()
+    for renderer_type, name in {
+        "PySideRenderer": "pyside",
+        "PygfxRenderer": "pygfx",
+        "DictRenderer": "dict",
+    }.items():
+        try:
+            importlib.import_module("collagraph", renderer_type)
+            result.add(name)
+        except ImportError:
+            continue
+    return result
+
+
+def init_collagraph(
+    renderer_type: str, component_path: Path, state: dict | None = None
+):
+    file_as_module = ".".join([*component_path.parts[:-1], component_path.stem])
+    component_module = importlib.import_module(file_as_module)
+    component_class = component_module.__component_class
+    props = reactive(state or {})
+
+    if renderer_type == "pygfx":
+        import pygfx as gfx
+        from wgpu.gui.auto import WgpuCanvas, run
+
+        canvas = WgpuCanvas(size=(600, 400))
+        wgpu_renderer = gfx.renderers.WgpuRenderer(canvas)
+
+        camera = gfx.PerspectiveCamera(70)
+        camera.local.z = 15
+        camera.show_pos((0, 0, 0))
+
+        controls = gfx.OrbitController(camera)
+        controls.register_events(wgpu_renderer)
+
+        container = gfx.Scene()
+
+        def animate():
+            wgpu_renderer.render(container, camera)
+
+        renderer = cg.PygfxRenderer()
+        renderer.add_on_change_handler(lambda: canvas.request_draw(animate))
+        gui = cg.Collagraph(renderer=renderer)
+        gui.render(component_class, container, state=props)
+
+        run()
+    elif renderer_type == "pyside":
+        from PySide6 import QtWidgets
+
+        app = QtWidgets.QApplication()
+        gui = cg.Collagraph(renderer=cg.PySideRenderer())
+        gui.render(component_class, app, state=props)
+        app.exec()
+    elif renderer_type == "dict":
+        container = {"root": None}
+        gui = cg.Collagraph(
+            renderer=cg.DictRenderer(),
+            event_loop_type=cg.EventLoopType.SYNC,
+        )
+        gui.render(component_class, container, state=props)
+        # Start debugger to allow for inspection of container
+        # and manipulation of props
+        breakpoint()  # noqa: T100
+
+
+def existing_component_file(value):
+    path = Path(value)
+    if not path.exists():
+        raise argparse.ArgumentTypeError(f"{value} does not exist")
+    if not path.is_file():
+        raise argparse.ArgumentTypeError(f"{value} is not a file")
+    if path.suffix != ".cgx":
+        raise argparse.ArgumentTypeError(f"{value} is not a collagraph component")
+    return path
+
+
+def json_contents(value):
+    path = Path(value)
+    if path.is_file():
+        with path.open(mode="r", encoding="utf-8") as fh:
+            try:
+                return json.load(fh)
+            except Exception:
+                raise argparse.ArgumentTypeError(f"{value} is not valid json")
+    else:
+        try:
+            return json.loads(value)
+        except Exception:
+            raise argparse.ArgumentTypeError(f"{value} is not valid json")
+
+
+def run():
+    parser = argparse.ArgumentParser(
+        description="Run collagraph components directly",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    parser.add_argument(
+        "--renderer",
+        default="pyside",
+        choices=available_renderers(),
+        help="The type of renderer to use",
+    )
+    parser.add_argument(
+        "--state",
+        type=json_contents,
+        help="Optional state/props to load (json file or string)",
+    )
+    parser.add_argument(
+        "component",
+        type=existing_component_file,
+        help="Path to component to render",
+    )
+    args = parser.parse_args()
+
+    init_collagraph(args.renderer, args.component, args.state)
+
+
+if __name__ == "__main__":
+    run()

collagraph-0.8.6/collagraph/__pyinstaller/__init__.py

@@ -0,0 +1,7 @@
+from os.path import dirname
+
+HERE = dirname(__file__)
+
+
+def get_hook_dirs():
+    return [HERE]

collagraph-0.8.6/collagraph/__pyinstaller/hook-collagraph.py

@@ -0,0 +1,58 @@
+import ast
+from pathlib import Path
+
+from PyInstaller.utils.hooks import collect_data_files
+
+from collagraph.sfc.compiler import get_script_ast
+from collagraph.sfc.parser import CGXParser
+
+
+def hook(hook_api):
+    collagraph_uses = hook_api.analysis.graph.get_code_using("collagraph")
+
+    hidden_imports = set()
+    datas = []
+    for package, code in collagraph_uses.items():
+        filename = Path(code.co_filename)
+        hidden_imports |= collect_hidden_imports(filename.parent)
+        datas += collect_data_files(package, includes=["**/*.cgx"])
+
+    hook_api.add_imports(*hidden_imports)
+    hook_api.add_datas(datas)
+
+
+def collect_hidden_imports(folder):
+    folder = Path(folder)
+
+    hidden_imports = set()
+    for path in folder.glob("**/*.cgx"):
+        template = path.read_text()
+        # Parse the file component into a tree of Node instances
+        parser = CGXParser()
+        parser.feed(template)
+
+        # Get the AST from the script tag
+        script_tree = get_script_ast(parser, path)
+
+        # Find a list of imported names (or aliases, if any)
+        # Those names don't have to be wrapped by `_lookup`
+        imported_names = ImportsCollector()
+        imported_names.visit(script_tree)
+
+        hidden_imports |= imported_names.names
+
+    return hidden_imports
+
+
+class ImportsCollector(ast.NodeVisitor):
+    def __init__(self):
+        self.names = set()
+
+    def visit_ImportFrom(self, node):
+        for alias in node.names:
+            self.names.add(".".join([node.module, alias.name]))
+        self.names.add(node.module)
+
+    def visit_Import(self, node):
+        for alias in node.names:
+            self.names.add(alias.name)

collagraph-0.8.6/collagraph/collagraph.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from observ import scheduler
+
+from collagraph.component import Component
+from collagraph.constants import EventLoopType
+from collagraph.renderers import Renderer
+
+
+class Collagraph:
+    def __init__(
+        self, renderer: Renderer, *, event_loop_type: EventLoopType | None = None
+    ):
+        if not isinstance(renderer, Renderer):
+            raise TypeError(f"Expected a Renderer but got a {type(renderer)}")
+        self.renderer = renderer
+        if not event_loop_type:
+            event_loop_type = (
+                renderer.preferred_event_loop_type() or EventLoopType.DEFAULT
+            )
+        self.event_loop_type = event_loop_type
+        if self.event_loop_type is EventLoopType.DEFAULT:
+            scheduler.register_asyncio()
+            renderer.register_asyncio()
+        else:
+            scheduler.register_request_flush(scheduler.flush)
+
+    def render(
+        self,
+        component_class: Callable[[dict], Component],
+        target: Any,
+        state: dict | None = None,
+    ):
+        """
+        target: DOM element/instance to render into.
+        state: state that gets passed into the component as top-level props.
+        """
+        # Here is the 'root' component which will carry the state
+        component = component_class(state or {})
+
+        # component.render() returns a fragment which is then mounted
+        # into the target (DOM) element
+        self.fragment = component.render(renderer=self.renderer)
+        self.fragment.component = component
+        self.fragment.mount(target)