trame.app.core module

class trame.app.core.VirtualNode(trame_server=None, **_)

Bases: object

A VirtualNode element allow to logically define UI element that can be filled or used in an independent order and yet update dynamically the layout upon change.

property server

Return the associated server

set_server(v)

Update the associated server

add_child(child)

Add a component to this component’s children

Parameters:

child (str | AbstractElement) – The component to add as a child

add_children(children)

Add components to this component’s children. The provided children is expected to be a list.

Parameters:

children (list) – The list of components to add to the children

property children

Children components

clear()

Remove all children

property html

Return a string representation of the HTML component

clear_layouts()

Remove any reference to previously registered layout

flush_content()

Push VirtualNode content to registered layouts

class trame.app.core.Client(url=None, config=None, translator=None, hot_reload=False)

Bases: object

Client implementation for driving a remote trame server with its shared state and trigger method calls in plain python.

property change

Use as decorator @server.change(key1, key2, …) so the decorated function will be called like so _fn(**state) when any of the listed key name is getting modified from either client or server.

Parameters:

*_args –

A list of variable name to monitor

class trame.app.core.Server(name='trame', vn_constructor=None, translator=None, parent_server=None, **options)

Bases: object

Server implementation for trame. This is the core object that manage client/server communication but also holds a state and controller instance. With trame a server instance should be retrieved by using trame.app.get_server()

Known options:

  • log_network: False (path to log file)

  • ws_max_msg_size: 10000000 (bytes)

  • ws_heart_beat: 30

  • desktop_debug: False

Parameters:

  • name (str, optional (default: trame)) – A name identifier for a given server

  • **options –

    Gather any keyword arguments into options

property http_headers

Return http header helper so they can be applied before the server start.

enable_module(module, **kwargs)

Expend server using a module definition which can be used to serve custom client code or assets, load/initialize resources (js, css, vue), register custom protocols and even execute custom code.

Any previously seem module will be automatically skipped.

The attributes that are getting processed in a module are the following:

  • setup(server, **kwargs): Function called first

  • scripts = [] : List all JavaScript URL that should be loaded

  • module_scripts = [] : List all JavaScript URL as type=module to load

  • styles = [] : List all CSS URL that should be loaded

  • vue_use = [‘libName’, (‘libName2’, { **options })]: List Vue plugin to load

  • state = {} : Set of variable to add to state

  • serve = { data: ‘/path/on/fs’ }: Set of endpoints to serve static content

  • www = ‘/path/on/fs’ : Path served as main web content

Parameters:

  • module – A module to enable or a dict()

  • kwargs – Any optional parameters needed for your module setup() function.

js_call(ref: str | None = None, method: str | None = None, *args)

Python call method on JS element.

Parameters:

  • ref (str) – ref name of the widget element

  • method (str) – name of the method that should be called

  • *args –

    set of parameters needed for the function

property change

Use as decorator @server.change(key1, key2, …) so the decorated function will be called like so _fn(**state) when any of the listed key name is getting modified from either client or server.

Parameters:

*_args –

A list of variable name to monitor

property trigger

Use as decorator @server.trigger(name) so the decorated function will be able to be called from the client by doing click=”trigger(name)”.

Parameters:

name (str) – A name to use for that trigger

property trigger_name

Given a function this method will register a trigger and returned its name. If manually registered, the given name at the time will be returned.

Returns:

The trigger name for that function

Return type:

str

property name: str

Name of server

property root_server: Server

Root server to start

property translator

Translator of the server

property options

Server options provided at instantiation time

property client_type: Literal['vue2', 'vue3']

Specify the client type. Either ‘vue2’ or ‘vue3’ for now.

property cli

argparse parser

property state: State
Returns:

The server shared state

Return type:

trame_server.state.State

property context: State

The server-only context (not shared with the client).

Returns:

The server context state

Return type:

trame_server.state.State

property controller: Controller
Returns:

The server controller

Return type:

trame_server.controller.Controller

property ui: VirtualNodeManager
Returns:

The server VirtualNode manager

Return type:

trame_server.ui.VirtualNodeManager

property running: bool

Return True if the server is currently starting or running.

property network_completion

Return a future to await if you want to ensure that any pending network call have been issued before locking the server

property ready

Return a future that will resolve once the server is ready

get_server_state()

Return the current server state

add_protocol_to_configure(configure_protocol_fn)

Register function that will be called with a wslink.ServerProtocol when the server start and is ready for registering new wslink.Protocol.

Parameters:

configure_protocol_fn – A function to be called later with a wslink.ServerProtocol as argument.

property protocol

Return the server root protocol

protocol_call(method, *args, **kwargs)

Call a registered protocol method

Parameters:

  • method (str) – Method registration name

  • *args –

    Set of args to use for that method call

  • **kwargs –

    Set of keyword arguments to use for that method call

Returns:

transparently return what the called function returns

force_state_push(*key_names)

Should only be needed when client corrupted its data and need the server need to send it again.

Parameters:

*args –

Set of key names to be send again to the client.

start(port: int | None = None, thread: bool = False, open_browser: bool | None = None, show_connection_info: bool = True, disable_logging: bool = False, backend: Literal['aiohttp', 'generic', 'tornado', 'jupyter'] | None = None, follow_symlinks: bool | None = None, exec_mode: Literal['main', 'desktop', 'task', 'coroutine'] = 'main', timeout: int | None = None, host: str | None = None, **kwargs)

Start the server by listening to the provided port or using the –port, -p command line argument. If the server is already starting or started, any further call will be skipped.

When the exec_mode=”main” or “desktop”, the method will be blocking. If exec_mode=”task”, the method will return a scheduled task. If exec_mode=”coroutine”, the method will return a coroutine which will need to be scheduled by the user.

Parameters:

  • port – A port number to listen to. When 0 is provided the system will use a random open port.

  • thread – If the server run in a thread which means we should disable interruption listeners

  • open_browser – Should we open the system browser with app url. Using the –server command line argument is similar to setting it to False.

  • show_connection_info – Should we print connection URL at startup?

  • disable_logging – Ask wslink to disable logging

  • backend – aiohttp by default but could be generic or tornado. This can also be set with the environment variable TRAME_BACKEND. Defaults to 'aiohttp'.

  • exec_mode – main/desktop/task/coroutine specify how the start function should work

  • timeout – How much second should we wait before automatically stopping the server when no client is connected. Setting it to 0 will disable such auto-shutdown.

  • host – The hostname used to bind the server. This can also be set with the environment variable TRAME_DEFAULT_HOST. Defaults to 'localhost'.

  • **kwargs –

    Keyword arguments for capturing optional parameters for wslink server and/or desktop browser

async stop() → None

Coroutine for stopping the server

property port: int

Once started, you can retrieve the port used

property server_options

Once started, you can retrieve the server options used

trame.app.core.get_server(name: str | Server | None = None, create_if_missing: bool = True, client_type: Literal['vue2', 'vue3'] | None = None, **kwargs) → Server | None

Return a server for serving trame applications.

If a name is given and such server is not available yet, it will be created otherwise the previously created instance will be returned.

Parameters:

  • name (None | str | Server instance) – A server name identifier which can be useful when several servers are expected to be created. Most of the time, passing no arguments is what you are looking for. Also an actual Server instance can be provided so you can use it as a decorator function.

  • create_if_missing (bool) – By default if a server for a given name does not exist that method will create it.

  • client_type (None | "vue2" | "vue3") – If provided, it will set it on the server.

  • **kwargs –

    any extra keyword args are passed as option to the server instance.

Returns:

Return a unique Server instance per given name.

Return type:

trame_server.core.Server

trame.app.core.get_client(url: str | None = None, hot_reload: bool = False, **kwargs) → Client

Return a client to a remote trame applications.

If a url is given and such client is not available yet, it will be created otherwise the previously created instance will be returned.

Parameters:

  • url (str) – Websocket URL which to connect to.

  • hot_reload (bool) – Enable when state change function should be hot reloaded.

  • **kwargs –

    any extra keyword args use for authentication configuration.

Returns:

Return a unique Client instance per given url. Each instance needs to call connect().

Return type:

trame_server.client.Client