Numerous App Engine Elements

💡

Numerous App Engine is an alpha release. It currently supports local development workflows.

Apps

The Numerous App Engine workflow begins by defining an app. The app is the wrapping element where you will define all the content of your Numerous App Engine app.

To define an app, use the @app decorator:

from numerous import app
 
@app
class MyApp
    # content of your app

The most basic app would be an app with just a text parameter. Define fields in your app by simply writing the name and adding a type-hint. Currently, only str and float are supported as type-hints.

Text fields

To create a text field that users can input string values into, define a field annotated with the type-hint str, like below:

@app
class MyTextFieldApp:
    text: str # Becomes a text field in the app's user interface

Number fields

To create a number field that users can input floating point values into, define a field annotated with the type-hint float, like below:

 
@app
class MyNumberFieldApp:
    number: float # Becomes a number field in the app's user interface

Actions

The @action decorator creates a button in your app. You use the @action decorator on functions in the @app class. You define the “action” (the code to be executed on button presses) in the function.

from numerous import action, app
 
@app
class Count:
    count: float
    message: str
 
    @action
    def increment(self) -> None:
        self.count += 1
        self.message = f"Count now: {self.count}"
        print("Incrementing count:", self.count)

The @action button is a versatile method for creating apps where you only want code to run after users explicitly ask for it. This can be long running code or code that is impractical to be running during every update of the input fields, sliders, etc.

Containers

You can use the @container decorator in a similar fashion to the @app decorator. It denotes a class to be a container, and you can use it to group information that is related.

from numerous import action, app, container
 
@container
class MyContainer:
    child: str
 
    def child_updated(self) -> None:
        print("wow")
 
 
@app
class MyContainerApp:
    my_container: MyContainer
 
    @action
    def print_child(self) -> None:
        print(self.my_container.child)

Sliders

To create a slider that can select a number from a range, you can annotate a field with float, like for number fields, and use the slider function to declare that this field is a slider. A slider has a minimum (defined with min_value), and a maximum value (defined with max_value). By default they are 0 and 100 respectively.

To set a default value, use the default keyword argument, like in the example below.

@app
class MySliderApp:
    my_slider: float = slider(default=10.0, min_value=0.0, max_value=100.0)

HTML

To add HTML to the app user interface (UI), define an HTML element. It is defined by annotating a field with the str type, but using the html function to declare it as an HTML field.

@app
class MyHTMLApp:
    my_html: str = html(default="<p>Default HTML here</p>")

You can update the HTML like other elements as a response to a changed element value, for example. Below, we use Python string-formatting to template an HTML element and update it when a text field is changed.

template = "<p>Hi, {name}! I'm an HTML element!"
 
@app
class MyHTMLApp:
    name: str = "No-Name"
    greeting: str = html(default=template.format(name="No-Name"))
 
    def name_updated(self):
        self.greeting = template.format(name=self.name)

Numerous App Engine Marimo