turbosnake 1.24.434b7

React.js-like framework with components for native user interfaces

turbosnake - a react.js-like framework for ui in python

Motivation

There are lots of nice graphical applications written in python. But code that creates UI (at least in simple examples I could find and in few projects I tried to contribute to) looks like some sort of imperative mess. And it gets even uglier when UI should be changed dynamically. So, I decided to try to reproduce the declarative approach which I am used to as a professional web-developer.

Installing

$ pip install turbosnake

Syntax

Unlike JavaScript frameworks with JSX, we cannot just modify Python's syntax for our purposes. Instead, turbosnake uses unmodified Python's syntax to represent its concepts.

Instantiating components

Instead of JSX's <Component ... /> turbosnake uses a plain function call:

component(...)

In most cases, return value of such calls is useless. The main effect of such call is a component being appended to a list in specific runtime context. Calls of components outside of proper runtime context are prohibited and will cause error.

Nesting components

Children are added to a component using with operator:

with component1(...):
    component11(...)
    component12(...)

this fragment of code is kinda equivalent to the following JSX:

<Component1 ...>
    <Component11 .../>
    <Component12 .../>
</Component1>

but unlike it, any loops and conditions are allowed within body of with operator. Components that support nesting implement context provider interface. When used in with operator they substitute previously mentioned runtime context with the one that adds all created components to list of their children.

Functional components

The easiest way to compose few components is to create a functional component. In some simple cases (component doesn't use hooks or is always rendered constant number of times within it's parent) a plain function can serve as a functional component:

def foo(**props):
    with component1():
        component2(**props)


...

foo(...)

But a function can be converted into a full-fledged component with its own state using functional_component decorator:

from turbosnake import functional_component

...


@functional_component
def foo(**props):
    with component1():
        component2(**props)


...

foo(...)

Depending on function signature and settings passed to the decorator, it may add (or don't add) support for nesting and hooks.

Hooks

Hooks are supported in functional components (if not disabled explicitly) and in components inheriting ComponentWithHooks. Some of implemented hooks are: use_toggle, use_state, use_memo, use_effect , use_callback, use_previous, use_ref, use_callback_proxy, use_self.

Hooks that accept a function can be used as decorators on a local function:

from turbosnake import functional_component, use_callback

...


@functional_component
def foo():
    ...

    @use_callback([...])
    def callback():
        ...

    ...

UI

Core of turbosnake isn't bound to any UI library or framework. With some effort applied, it can be used with any UI library or even for purposes different from user interface rendering.

Package turbosnake.ttk provides adapters for tkinter (mostly ttk) UI components. For examples see TODO-list application example.

Live preview

Composite turbosnake UI components are not meant to be edited using any sort of visual editor. But, in order to make it easier to create, modify and debug complex layouts turbosnake provides live preview tool. It is inspired by React's Storybook. The tool tracks changes in component file and renders the most recent version in a window.

Current version of preview tool tracks changes only in the preview file itself. Tracking of changes in dependencies may be added later.

See preview_example.py for example of preview tool use.