trame.start(layout=None, name=None, favicon=None, on_ready=None, port=None, debug=False)[source]

Start the web server for your application

  • layout (None | str | trame.layouts.*) – UI content that should be used for your application

  • name (None | str) – “Title” that you can see in your tab browser. This will be filled automatically if a trame.layouts.* layout was provided.

  • favicon (None | str) – Relative path to a png image that should be used as favicon

  • port (None | Number) – Port on which the server should run on. Default is 8080. This overrides a port from the command line --port/-p option.

  • on_ready (None | function) – Function called once the server is ready

  • debug (bool) – Whether to print debugging information

>>> start(on_ready=initialize)
trame.state = <trame.internal.state.core.State object>

This object provides pythonic access to the state

For instance, these getters are the same:

>>> field, = get_state("field")
>>> field = state.field

As are these setters:

>>> update_state("field", value)
>>> state.field = value

get_state() should be used instead if more than one argument is to be passed, and update_state() should be used instead to specify additional arguments (e.g. force=True).

The state may also be accessed and updated similar to dictionaries:

>>> value = state["field"]
>>> state["field"] = value
>>> state.update({"field": value})

This object may be imported via

>>> from trame import state
trame.update_state(key, value=None, force=False)[source]

Updating the current application state that is shared with the Web UI

  • key (str) – The key for the value we wish to update

  • value (Any) – The new value

  • force (bool) – Set to True when you want to force push a new or same value to the client.

>>> update_state("workload_finished",  True)

update_state() may not detect a change if the same reference is passed even if its content has change. You have the option to let the system know that you want to force the update.

>>> a = { "x": 1 }
>>> update_state("a", a)
>>> a["x"] = 2
>>> update_state("a", a, force=True)

Sometime you may want to update a set of variables at once without triggering any @change callback. To do so, just provide a dictionary. Even if no @change is called, the client will receive the updated modified change.

>>> change_set = { "a": 1, "b": 2 }
>>> update_state(change_set)

Return the list of values of the given state keys or the full state dictionary if no key names were provided.


names (list[str]) – List of names of state values to retreive

Return type

List[Any] | dict[str, Any]


Either a list of values matching the given state property names or the full state dict

>>> greeting, name  = get_state("greeting", "name")
>>> f'{greeting}, {name}!'
"Hello, Trame!"
>>> greeting, = get_state("greeting")
>>> greeting
>>> full_state = get_state()
>>> full_state.get("greeting")

Force push selected keys of the server state to the client


args (list[str]) – Which keys to flush

>>> flush_state('myNestedDict')

Check if a set of keys in an @change have been modified


args (list[str]) – Which keys to check for modification


True if any of the keys in args are modified

>>> @change('sound_settings', 'picture_settings')
... def show_changed_settings(sound_settings, picture_settings, **kwargs):
...     if is_dirty('sound_settings'):
...         print(sound_settings)
...     if is_dirty('picture_settings'):
...         print(picture_settings)

See whether all keys in an @change have been modified


args (list[str]) – Which keys to check for modification


True if all of the keys in args are modified

>>> @change('sound_settings', 'picture_settings')
... def save_changed_settings(sound_settings, picture_settings, **kwargs):
...     if is_dirty_all('sound_settings', 'picture_settings'):
...         print("Cannot save both sound and picture settings at once")
...         raise
trame.change(*_args, **_kwargs)[source]

The @change decorator allows us to register a function so that it will be automatically called when any of the given list of state names gets modified.

The decorated function is passed the full state as **kwargs when possible. This means you should have a method profile similar to fn(..., **kwargs)


_args (list[str]) – List of names that your function should listen to

>>> @change('settings')
... def show_settings(settings, user, **kwargs):
...     print(settings, "for", user)

The @trigger decorator allows you to register a function as a trigger with a given name.


name (str) – Name which this trigger function should listen to.

<v-btn @click=”blue_button_clicked”>Blue Button</v-btn>

>>> @trigger('blue_button_clicked')
... def log_clicks():
...     print("The blue button was clicked")
trame.controller = <trame.internal.triggers.controller.Controller object>

The controller is a container for function proxies

The function proxies may be used as callbacks even though the function has not yet been defined. The function may also be re-defined. For example:

>>> from trame import controller as ctrl
>>> layout = SinglePage("Controller test")
>>> with layout.toolbar:
...     vuetify.VSpacer()
...     vuetify.VBtn("Click Me", click=ctrl.on_click)  # not yet defined
>>> ctrl.on_click = lambda: print("Hello, Trame!")  # on_click is now defined

This can be very useful for large projects where the functions may be defined in separate files after the UI has been constructed, or for re-defining callbacks when conditions in the application change.


Flush layout to the client


layout (str | trame.layouts.*) – UI content for your application

>>> layout.title.set_text("Workload finished!")
>>> update_layout(layout)

Run or add args to CLI parser


Parser from argparse

>>> parser = get_cli_parser()
>>> parser.add_argument("-o", "--output", help="Working directory")
>>> args, unknown = parser.parse_known_args()
>>> print(args.output)
trame.setup_dev(*reload_list, clear_changes=False, clear_triggers=True)[source]

Set up a development environment for the trame app if –dev was passed as a command line argument. If enabled, a reload button will appear at the bottom of the web browser which will reload the modules that were passed as arguments.

  • reload_list (python modules) – positional arguments of the modules to reload when the reload button is pressed.

  • clear_changes (bool) – whether or not to clear changes on reload

  • clear_triggers (bool) – whether or not to clear triggers on reload

Return type



whether the program is running in dev mode or not

class trame.RemoteFile(local_path=None, remote_url=None, local_base=None)[source]

Bases: trame.internal.utils.remote_data.AbstractRemoteFile

class trame.GoogleDriveFile(local_path=None, google_id=None, local_base=None)[source]

Bases: trame.internal.utils.remote_data.AbstractRemoteFile

class trame.AssetManager(base_path)[source]

Bases: object

base64(key, file_path=None)[source]
url(key, file_path)[source]
txt(key, file_path)[source]
property assets
class trame.Singleton(cls: Type[trame.internal.utils.singleton.T])[source]

Bases: Generic[trame.internal.utils.singleton.T]

Singleton decorator