orangeqs.juice.dashboard.utils#

Utilities for dashboard.

Module Contents#

Classes#

DashboardEntry

Dashboard page entry. Appears on the homepage and the navigation bar.

DashboardCategory

Dashboard category. Appears on the home page and the navigation bar.

DashboardConfig

Configuration for the dashboard.

JuiceEnvironment

Manage the Jinja template environment for Juice.

Functions#

dashboard_base_url

Get the base URL for the dashboard without trailing slash.

filebrowser_base_url

Get the base URL for the filebrowser without trailing slash.

jupyterlab_base_url

Get the base URL for JupyterLab without trailing slash.

vscode_base_url

Get the base URL for VS Code without trailing slash.

influxdb2_base_url

Get the base URL for InfluxDB2 without trailing slash.

collect_dashboard_applications

Collect all dashboard applications defined by extensions.

subscribe_to_events_task

Create and manage an async task to listen for pub/sub events.

get_palette

Return OQS color palette for colors, repeating.

get_stylesheet

Retrieve CSS file hosted by the singleuser server.

to_local_time

Convert a datetime object to the local timezone.

Data#

TORNADO_APPLICATIONS

BOKEH_APPLICATIONS

HOME_PAGE_APPS

Predefined common applications for the dashboard homepage.

API#

orangeqs.juice.dashboard.utils.TORNADO_APPLICATIONS#

‘collect_entry_points(…)’

orangeqs.juice.dashboard.utils.BOKEH_APPLICATIONS#

‘collect_entry_points(…)’

orangeqs.juice.dashboard.utils.dashboard_base_url() → str#

Get the base URL for the dashboard without trailing slash.

The URL consists of:

  • The JupyterHub service prefix (e.g. /user/<username>)

  • The endpoint for the dashboard, which is /dashboard

An example full URL would be /user/<username>/dashboard.

orangeqs.juice.dashboard.utils.filebrowser_base_url() → str#

Get the base URL for the filebrowser without trailing slash.

A direct link to a specific path in the file browser can be constructed as {filebrowser_base_url()}/path/to/directory.

The URL returned by this function consists of:

  • The JupyterHub service prefix (e.g. /user/<username>)

  • The proxy path for the file browser, which is /filebrowser

  • The endpoint to serve files of the file browser, which is /files

An example returned URL is /user/<username>/filebrowser/files.

orangeqs.juice.dashboard.utils.jupyterlab_base_url() → str#

Get the base URL for JupyterLab without trailing slash.

The URL consists of:

  • The JupyterHub service prefix (e.g. /user/<username>)

  • The endpoint to serve JupyterLab, which is /lab

An example full URL would be /user/<username>/lab.

orangeqs.juice.dashboard.utils.vscode_base_url() → str#

Get the base URL for VS Code without trailing slash.

The URL consists of:

  • The JupyterHub service prefix (e.g. /user/<username>)

  • The endpoint to serve VS Code, which is /vscode

An example full URL would be /user/<username>/vscode. Specific folders can be opened by adding ?folder=path/to/folder to the URL.

orangeqs.juice.dashboard.utils.influxdb2_base_url() → str#

Get the base URL for InfluxDB2 without trailing slash.

The URL consists of:

  • The JupyterHub service prefix (e.g. /user/<username>)

  • The endpoint to serve InfluxDB2, which is /influxdb2

An example full URL would be /user/<username>/influxdb2.

orangeqs.juice.dashboard.utils.collect_dashboard_applications() → tuple[list[tuple[str, type[tornado.web.RequestHandler], dict[str, Any]]], dict[str, collections.abc.Callable[..., panel.template.Template] | bokeh.application.Application]]#

Collect all dashboard applications defined by extensions.

Returns#

  • (dict[str, type[web.RequestHandler], dict[str, Any]]): A dictionary mapping URL paths to Tornado request handlers and their initialization arguments.

  • (dict[str, Application]): A dictionary mapping URL paths to Bokeh applications.

class orangeqs.juice.dashboard.utils.DashboardEntry(/, **data: Any)#

Bases: orangeqs.juice.settings.BaseConfigurable

Dashboard page entry. Appears on the homepage and the navigation bar.

name: str#

None

Human-readable name of the entry.

url: str | None#

None

URL path of the entry, or None if not a link.

If entry_point is defined, this will be the URL the page will be served at. If not provided, will be determined automatically by using the key of the category and page, i.e. {category_key}/{page_key}.

Otherwise this can be any URL pointing to an internal or external resource. In that case it applies the following rules to determine how to handle the URL:

  • If the URL starts with http:// or https://, it’s considered an absolute URL.

  • If the URL starts with a /, it’s considered an absolute path on the current domain.

  • Otherwise the URL is considered relative to the dashboard base URL, which is useful for linking to specific dashboard pages.

The URL supports the following placeholders. All placeholders have a leading /, but no trailing /.

image: str | None#

None

Optional image for the entry.

Must be of the form importable.module:filepath, where filepath is the path to the image file relative to the module. For example, my_module.static:images/my_image.png.

Don’t forget to include the image file in the package data of your package, see for example https://setuptools.pypa.io/en/latest/userguide/datafiles.html for how to do this using setuptools.

entry_point: str | None#

None

Object reference to the function that instantiates the page this entry links to.

Also referred to as the “entry point”. This function will be called to instantiate the page that this entry refers to. Must be of the form importable.module:callable.

description: str | None#

None

Optional description of the entry, shown on the homepage.

order: int#

‘Field(…)’

Order of the entry in the navigation bar and home page.

Lower numbers appear first.

new_tab: bool#

False

Whether to open the link in a new tab.

class orangeqs.juice.dashboard.utils.DashboardCategory(/, **data: Any)#

Bases: orangeqs.juice.dashboard.utils.DashboardEntry

Dashboard category. Appears on the home page and the navigation bar.

Note that a category entry also supports linking to a page. However, this link will only show up in the navigation bar, not on the homepage.

pages: dict[str, orangeqs.juice.dashboard.utils.DashboardEntry]#

‘Field(…)’

Sub-pages under this category, keyed by unique keys.

class orangeqs.juice.dashboard.utils.DashboardConfig(/, **data: Any)#

Bases: orangeqs.juice.settings.Configurable

Configuration for the dashboard.

Defines the pages and categories that appears on the home page and navigation bar.

filename: ClassVar[str]#

‘dashboard’

categories: dict[str, orangeqs.juice.dashboard.utils.DashboardCategory]#

‘Field(…)’

Categories for the dashboard pages, keyed by unique keys.

add_page_from_entrypoint(url: str, entry_point: str) → None#

Add a page to the dashboard by URL.

If the page URL is found in the common apps, it will be added as that entry.

Otherwise, this assumes the URL is of the form “category/page” or just “page”. Automatically creates categories as needed.

orangeqs.juice.dashboard.utils.HOME_PAGE_APPS#

‘_common_apps(…)’

Predefined common applications for the dashboard homepage.

These are also used to populate the navigation bar.

orangeqs.juice.dashboard.utils.subscribe_to_events_task(doc: bokeh.document.Document, subscriptions: list[tuple[type, str]], handler: collections.abc.Callable[[Any], None]) → asyncio.Task[Any]#

Create and manage an async task to listen for pub/sub events.

WARNING: The returned task must be kept referenced to avoid being garbage collected.

Parameters#

  • doc: Document: The Bokeh document to schedule callbacks on.

  • subscriptions: list[tuple[type, str]]: A list of (event class, topic) tuples to subscribe to.

  • handler: Callable[[Any], None]: A callable to handle each incoming event.

Returns#

  • (An asyncio.Task managing the subscription.)

  • (Example:): class SomeDashboardComponent: def init(self, client, doc): self.client = client self.doc = doc self.listener_task = subscribe_to_events_task( self.doc, [(QuantityUpdate, “he3_flow”)], self._handle_event ) def _handle_event(self, event): # Process event (e.g. update a ColumnDataSource) self.source.patch({…})

orangeqs.juice.dashboard.utils.get_palette(count: int) → list[str]#

Return OQS color palette for colors, repeating.

orangeqs.juice.dashboard.utils.get_stylesheet(path: str) → bokeh.models.ImportedStyleSheet#

Retrieve CSS file hosted by the singleuser server.

orangeqs.juice.dashboard.utils.to_local_time(dt: datetime.datetime) → datetime.datetime#

Convert a datetime object to the local timezone.

Parameters#

  • dt (datetime): The datetime object to convert. It should be timezone-aware.: If the input datetime is naive (lacking timezone information), it will be assumed to be in UTC, and a warning will be raised.

Returns#

  • (datetime: The datetime object converted to the local timezone.)

Notes#

  • If the input is a pandas.Timestamp, it will be handled similarly, with naive timestamps being assumed to be in UTC.

  • A warning will be logged if the input datetime or pandas.Timestamp is naive.

class orangeqs.juice.dashboard.utils.JuiceEnvironment(extra_loaders: jinja2.BaseLoader | list[jinja2.BaseLoader] | None = None, extra_template_paths: str | list[str] | None = None)#

Bases: jinja2.Environment

Manage the Jinja template environment for Juice.

get_jinja_template(file_name: str) → jinja2.Template#

Retrieve a Jinja template by name.

get_panel_template(file_name: str) → panel.template.Template#

Retrieve a template by file name as a Panel template.

For Juice Extensions: Note that if the directory the template file is in has not been added with extra_loaders or extra_template_paths in the init function beforehand, it will not be found.