collagraph 0.5.2__tar.gz → 0.7.0__tar.gz

collagraph-0.7.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.1
+Name: collagraph
+Version: 0.7.0
+Summary: Reactive user interfaces
+Home-page: https://github.com/fork-tongue/collagraph
+License: MIT
+Author: Berend Klein Haneveld
+Author-email: berendkleinhaneveld@gmail.com
+Requires-Python: >=3.9
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Provides-Extra: pygfx
+Provides-Extra: pyside
+Requires-Dist: observ (>=0.14.1)
+Requires-Dist: pygfx (>=0.1.17) ; extra == "pygfx"
+Requires-Dist: pyside6_essentials (>=6.6,<6.7) ; (python_version < "3.13") 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))
+* Function components
+* 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
+<template>
+  <widget>
+    <label
+      :text="f'Count: {count}'"
+    />
+    <button
+      text="bump"
+      @clicked="bump"
+    />
+  </widget>
+</template>
+
+<script>
+import collagraph as cg
+
+
+class Counter(cg.Component):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        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(cg.h(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
+poetry run collagraph examples/pyside/counter.cgx
+```
+
+For more examples, please take a look at the [examples folder](examples).
+
+Currently there are three 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)
+* [DomRenderer](collagraph/renderers/dom_renderer.py): for rendering to browser DOM through [PyScript](https://pyscript.net) (or rather [Pyodide](https://pyodide.org/en/stable/))
+
+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)
+poetry install
+# Full dev setup
+poetry install --with pyside --extras pyside --extras pygfx
+# Run example:
+poetry run python examples/pyside/layout-example.py
+# Run test suite:
+poetry run pytest
+# Install git pre-commit hooks to make sure tests/linting passes before committing
+poetry 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 cgx files is possible with a flake8 plugin: [flake8-cgx](https://github.com/fork-tongue/flake8-cgx).
+Formatting the contents of the script tag can be done with [black-cgx](https://github.com/fork-tongue/black-cgx).
+

collagraph-0.7.0/README.md

@@ -0,0 +1,122 @@
+[![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))
+* Function components
+* 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
+<template>
+  <widget>
+    <label
+      :text="f'Count: {count}'"
+    />
+    <button
+      text="bump"
+      @clicked="bump"
+    />
+  </widget>
+</template>
+
+<script>
+import collagraph as cg
+
+
+class Counter(cg.Component):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        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(cg.h(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
+poetry run collagraph examples/pyside/counter.cgx
+```
+
+For more examples, please take a look at the [examples folder](examples).
+
+Currently there are three 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)
+* [DomRenderer](collagraph/renderers/dom_renderer.py): for rendering to browser DOM through [PyScript](https://pyscript.net) (or rather [Pyodide](https://pyodide.org/en/stable/))
+
+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)
+poetry install
+# Full dev setup
+poetry install --with pyside --extras pyside --extras pygfx
+# Run example:
+poetry run python examples/pyside/layout-example.py
+# Run test suite:
+poetry run pytest
+# Install git pre-commit hooks to make sure tests/linting passes before committing
+poetry 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 cgx files is possible with a flake8 plugin: [flake8-cgx](https://github.com/fork-tongue/flake8-cgx).
+Formatting the contents of the script tag can be done with [black-cgx](https://github.com/fork-tongue/black-cgx).

collagraph-0.7.0/collagraph/__main__.py

@@ -0,0 +1,131 @@
+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",
+        # TODO: add support for DomRenderer
+        # "DomRenderer": "dom",
+    }.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):
+    Component, _ = cg.cgx.cgx.load(component_path)
+    props = reactive(state or {})
+
+    if renderer_type == "pygfx":
+        import pygfx as gfx
+        from wgpu.gui.auto import run, WgpuCanvas
+
+        canvas = WgpuCanvas(size=(600, 400))
+        wgpu_renderer = gfx.renderers.WgpuRenderer(canvas)
+
+        camera = gfx.PerspectiveCamera(70, 16 / 9)
+        camera.position.z = 15
+
+        controls = gfx.OrbitController(camera.position.clone())
+        controls.add_default_event_handlers(wgpu_renderer, camera)
+
+        container = gfx.Scene()
+
+        def animate():
+            controls.update_camera(camera)
+            wgpu_renderer.render(container, camera)
+
+        gui = cg.Collagraph(renderer=cg.PygfxRenderer())
+        gui.render(
+            cg.h(Component, props),
+            container,
+            callback=lambda: canvas.request_draw(animate),
+        )
+
+        run()
+    elif renderer_type == "pyside":
+        from PySide6 import QtWidgets
+
+        app = QtWidgets.QApplication()
+        gui = cg.Collagraph(renderer=cg.PySideRenderer())
+        gui.render(cg.h(Component, props), app)
+        app.exec()
+    elif renderer_type == "dict":
+        container = {"root": None}
+        gui = cg.Collagraph(
+            renderer=cg.DictRenderer(),
+            event_loop_type=cg.EventLoopType.SYNC,
+        )
+        gui.render(cg.h(Component, props), container)
+        # Start debugger to allow for inspection of container
+        # and manipulation of props
+        breakpoint()
+
+
+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.7.0/collagraph/__pyinstaller/__init__.py

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

collagraph-0.7.0/collagraph/__pyinstaller/hook-collagraph.py

@@ -0,0 +1,57 @@
+import ast
+from pathlib import Path
+
+from PyInstaller.utils.hooks import collect_data_files
+
+from collagraph.cgx.cgx import CGXParser, get_script_ast
+
+
+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)