{"id":6476,"library":"trame-common","title":"Trame Common Utilities","description":"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.","status":"active","version":"1.1.3","language":"en","source_language":"en","source_url":"https://github.com/Kitware/trame-common","tags":["trame","web framework","utilities","common","helpers","kitware"],"install":[{"cmd":"pip install trame-common","lang":"bash","label":"Install trame-common"}],"dependencies":[{"reason":"Required Python version","package":"python","optional":false},{"reason":"trame-common is designed to be a dependency for the broader trame ecosystem; its full utility is realized when used within trame applications.","package":"trame","optional":true}],"imports":[{"symbol":"throttle","correct":"from trame_common.exec import throttle"},{"symbol":"Singleton","correct":"from trame_common.obj import Singleton"},{"symbol":"get_mime_type","correct":"from trame_common.assets import get_mime_type"}],"quickstart":{"code":"import time\nfrom trame_common.exec import throttle\n\n@throttle(delay=1)\ndef log_message(value):\n    print(f\"Processing value: {value} at {time.time():.2f}\")\n\nprint(\"Calling log_message rapidly (throttled to 1 call/sec):\")\nfor i in range(5):\n    log_message(i)\n    time.sleep(0.2) # Call every 0.2 seconds\n\nprint(\"\\nWaiting for throttle to reset (1.5 seconds) and calling again:\")\ntime.sleep(1.5)\nlog_message(\"Final call\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"Trame 3.9.0 and later (affecting Trame applications using trame-common)"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z"}