trame a framework to write ubiquitous applications in Python

Version 2.0 is a rewrite of trame 1.x.
It keeps the idea behind trame while normalizing its API and enabling a wider extensability.
This new version open another set of doors while renforcing the strength of the trame core.

BREAKING CHANGE: The API between v1 and v2 are not compatible but the migration should remain straight forward

Co-authored-by: Patrick Avery <[email protected]>

.gitignore

@@ -0,0 +1,124 @@
+# local env files
+.env.local
+.env.*.local
+
+# OS files
+.DS_Store
+
+# Editor directories and files
+.idea
+.vscode
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+dist/
+downloads/
+eggs/
+.eggs/
+sdist/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/

LICENSE

@@ -0,0 +1,13 @@
+Copyright 2022 Kitware Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

MANIFEST.in

@@ -0,0 +1 @@
+include trame/LICENSE

README.rst

@@ -0,0 +1,140 @@
+trame: simple, powerful, innovative
+===========================================================
+
+**trame** - a web framework that weaves together open source components into customized visual analytics easily.
+
+**trame** is French for
+
+* the core that ties things together
+* a guide providing the essence of a task
+
+.. image:: https://kitware.github.io/trame/examples/MultiFilter.jpg
+  :alt: Welcome to trame and 3D visualization
+
+With **trame**, create stunning, interactive web applications compactly and intuitively.
+
+|image_1| |image_2| |image_3|
+
+.. |image_1| image:: https://kitware.github.io/trame/examples/CarotidFlow.jpg
+  :width: 30%
+.. |image_2| image:: https://kitware.github.io/trame/examples/UberPickupsNYC.jpg
+  :width: 30%
+.. |image_3| image:: https://kitware.github.io/trame/examples/FiniteElementAnalysis.jpg
+  :width: 30%
+
+3D Visualization
+-----------------------------------------------------------
+
+With best-in-class VTK and ParaView platforms at its core, **trame** provides complete control of 3D visualizations and data movements.
+Developers benefit from a write-once environment while **trame** simply exposes both local and remote rendering through a single method.
+
+Rich Features
+-----------------------------------------------------------
+
+**trame** leverages existing libraries and tools such as Vuetify, Altair, Vega, deck.gl, VTK, ParaView, and more, to create vivid content for visual analytics applications.
+
+Problem Focused
+-----------------------------------------------------------
+
+By relying simply on Python, **trame** focuses on one's data and associated analysis and visualizations while hiding the complications of web app development.
+
+Desktop to cloud
+-----------------------------------------------------------
+
+The resulting **trame** applications can act as local desktop applications or remote cloud applications both accessed through a browser.
+
+
+Installing
+-----------------------------------------------------------
+
+trame can be installed with `pip <https://pypi.org/project/trame/>`_:
+
+.. code-block:: bash
+
+    pip install --upgrade trame --pre
+
+Usage
+-----------------------------------------------------------
+
+The `Trame Tutorial <https://kitware.github.io/trame/docs/tutorial.html>`_ is the place to go to learn how to use the library and start building your own application.
+
+The `API Reference <https://trame.readthedocs.io/en/latest/index.html>`_ documentation provides API-level documentation.
+
+
+License
+-----------------------------------------------------------
+
+trame is made available under the Apache License, Version 2.0. For more details, see `LICENSE <https://github.com/Kitware/trame/blob/master/LICENSE>`_
+
+
+Community
+-----------------------------------------------------------
+
+`Trame <https://kitware.github.io/trame/>`_ | `Discussions <https://github.com/Kitware/trame/discussions>`_ | `Issues <https://github.com/Kitware/trame/issues>`_ | `RoadMap <https://github.com/Kitware/trame/projects/1>`_ | `Contact Us <https://www.kitware.com/contact-us/>`_
+
+.. image:: https://zenodo.org/badge/410108340.svg
+    :target: https://zenodo.org/badge/latestdoi/410108340
+
+
+Enjoying trame?
+-----------------------------------------------------------
+
+Share your experience `with a testimonial <https://github.com/Kitware/trame/issues/18>`_ or `with a brand approval <https://github.com/Kitware/trame/issues/19>`_.
+
+
+Optional dependencies
+-----------------------------------------------------------
+
+When installing trame using pip (`pip install trame`) you will get the core infrastructure for any trame application to work but more advanced usage may require additional dependencies.
+The list below capture which may need to add depending on your usage:
+
+* **pywebview**  : Needed for desktop usage (--app)
+* **jupyterlab** : Needed to run inside jupyter-lab
+* **notebook**   : Needed to run inside jupyter-notebook
+* **requests**   : Needed when using remote assets such as GDrive files
+
+
+Environments variables
+-----------------------------------------------------------
+
+* **TRAME_LOG_NETWORK**     : Path to log file for capturing network exchange. (default: None)
+* **TRAME_WS_MAX_MSG_SIZE** : Maximum size in bytes of any ws message. (default: 10MB)
+* **TRAME_WS_HEART_BEAT**   : Time in second before assuming the server is non-responsive. (default: 30s)
+
+
+Life cycle callbacks
+--------------------------------------------------------------------------
+
+Life cycle events are directly managed on the application controller
+and are prefixed with `on_*`.
+
+* **on_server_ready**     : All protocols initialized and available for client to connect
+* **on_client_connected** : Connection established to server
+* **on_client_exited**    : Linked to browser "beforeunload" event
+* **on_server_exited**    : Trame is exiting its event loop
+
+* **on_server_reload**    : If callback registered it is use for reloading server side modules
+
+
+Reserved state entries
+--------------------------------------------------------------------------
+
+The shared state allow us to synchronize the server with the client.
+Rather than creating another mechanism to handle similar needs throughout
+the application we purposely reuse that state for internal purpose.
+To prevent any conflict with any user we are prefixing our internal
+variable with `trame__*`. In general those state values should not be use
+or changed by the user except for the one listed below:
+
+Read/Write:
+  - **trame__favicon**: Update it to replace the displayed favicon in your
+    browser. The content needs to be a image encoded url.
+  - **trame__title**: Update it to replace your page title
+    (tab name / window name).
+
+Read-only:
+  - **trame__busy**: Provide information if we have pending request waiting
+    for the server to respond.
+  - **tts**: Template Time Stamp to regenerate sub elements when a template
+    get's updated. Usually used as `:key="tts"` to force some component
+    rebuild.

setup.cfg

@@ -0,0 +1,39 @@
+[metadata]
+name = trame
+version = 2.0.0rc3
+description = Trame, a framework to build applications in plain Python
+long_description = file: README.rst
+long_description_content_type = text/x-rst
+author = Kitware Inc.
+license = Apache License 2.0
+classifiers =
+    Development Status :: 5 - Production/Stable
+    Environment :: Web Environment
+    License :: OSI Approved :: Apache Software License
+    Natural Language :: English
+    Operating System :: OS Independent
+    Programming Language :: Python :: 3 :: Only
+    Topic :: Software Development :: Libraries :: Application Frameworks
+    Topic :: Software Development :: Libraries :: Python Modules
+keywords =
+    Python
+    Interactive
+    Web
+    Application
+    Framework
+
+[options]
+packages = find:
+include_package_data = True
+install_requires =
+    trame-client
+    trame-components
+    trame-deckgl
+    trame-markdown
+    trame-matplotlib
+    trame-plotly
+    trame-router
+    trame-server
+    trame-vega
+    trame-vtk
+    trame-vuetify

setup.py

@@ -0,0 +1,3 @@
+from setuptools import setup
+
+setup()

trame/LICENSE

@@ -0,0 +1 @@
+../LICENSE

trame/__init__.py

@@ -0,0 +1,3 @@
+__path__ = __import__("pkgutil").extend_path(__path__, __name__)
+
+__license__ = "Apache License 2.0"

trame/app/__init__.py

@@ -0,0 +1,27 @@
+from trame_server import Server
+from trame_client import module
+
+DEFAULT_NAME = "trame"
+AVAILABLE_SERVERS = {}
+
+
+def get_server(name=None, create_if_missing=True, **kwargs):
+    """
+    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 previsouly created instance will be returned.
+    """
+    if name is None:
+        name = DEFAULT_NAME
+
+    if name in AVAILABLE_SERVERS:
+        return AVAILABLE_SERVERS[name]
+
+    if create_if_missing:
+        server = Server(name, **kwargs)
+        server.enable_module(module)  # Always load html module first
+        AVAILABLE_SERVERS[name] = server
+        return server
+
+    # No server available for given name
+    return None

trame/app/asynchronous.py

@@ -0,0 +1,15 @@
+from trame_server.utils.asynchronous import (
+    create_task,
+    decorate_task,
+    create_state_queue_monitor_task,
+    StateQueue,
+    task,
+)
+
+__all__ = [
+    "create_task",
+    "decorate_task",
+    "create_state_queue_monitor_task",
+    "StateQueue",
+    "task",
+]