Trame Common Utilities

1.1.3 · active · verified Wed Apr 15

trame-common is a core component within the Trame ecosystem, providing dependency-less classes and functions for various trame packages like trame-client and trame-server. It offers a centralized collection of utilities for assets handling, decorators, asynchronous/throttled execution, and common Trame object patterns (Component, App, Widget, Singleton). While it is installable, it's primarily designed to be consumed as a dependency by other `trame` libraries rather than used standalone, enabling robust and efficient development across the Trame framework. Trame itself is an active, Python-based framework for creating interactive web applications with visual analytics, with a rapid release cadence for its main packages.

Warnings

gotcha trame-common is intended as an internal dependency for the wider Trame ecosystem (e.g., trame-client, trame-server, trame itself) rather than a standalone end-user library. While you can install it, its full feature set and context are realized when used as part of a Trame application.
Fix: When building Trame applications, usually `pip install trame` will bring in `trame-common` and its necessary components. If you need specific functionalities, explicitly import from `trame_common.*` within your Trame project.
gotcha Some modules within trame-common (e.g., those related to specific backend operations) may have implicit 'extra dependencies' that are not declared in trame-common's `setup.py`. The consuming `trame` package or your user application is expected to manage and declare these additional dependencies if specific `trame-common` modules are utilized.
Fix: Always refer to the specific `trame` package documentation that uses `trame-common` for its full dependency list. If directly using a `trame-common` module, monitor for `ImportError` and install missing packages as needed.
breaking The broader Trame ecosystem (which `trame-common` supports) transitioned its default client from Vue 2 to Vue 3 starting with Trame v3.9.0 (released April 2025). Existing Trame applications built with Vue 2 might encounter breaking changes in UI widgets or behavior if not explicitly configured to use `client_type="vue2"` or updated to be Vue 3 compatible.
Fix: For existing Trame applications, explicitly set `server.client_type = "vue2"` during server initialization if you wish to retain Vue 2 compatibility. For new or updated applications, ensure your widgets and components are compatible with Vue 3.

Install

pip install trame-common Install trame-common

Imports

throttle
```
from trame_common.exec import throttle
```
Singleton
```
from trame_common.obj import Singleton
```

get_mime_type

from trame_common.assets import get_mime_type

Quickstart

This example demonstrates a direct use of a utility from `trame_common.exec`, specifically the `throttle` decorator. It showcases how `trame-common` provides useful functions that can be integrated into Python code, often within a larger Trame application, to control execution frequency. The function `log_message` will be called at most once every second, despite being invoked more frequently.

import time
from trame_common.exec import throttle

@throttle(delay=1)
def log_message(value):
    print(f"Processing value: {value} at {time.time():.2f}")

print("Calling log_message rapidly (throttled to 1 call/sec):")
for i in range(5):
    log_message(i)
    time.sleep(0.2) # Call every 0.2 seconds

print("\nWaiting for throttle to reset (1.5 seconds) and calling again:")
time.sleep(1.5)
log_message("Final call")

view raw JSON →