API Reference
This is the API for the signac-dashboard application.
The Dashboard
Attributes
|
Add a route to the dashboard. |
|
Override this method for custom job sorting. |
Override this method for custom job subtitles. |
|
|
Override this method for custom job titles. |
Runs the command line interface. |
|
Register an asset required by a dashboard module. |
|
|
Runs the dashboard webserver. |
Clear project and dashboard server caches. |
- class signac_dashboard.Dashboard(config={}, project=None, modules=[])[source]
A dashboard application to display a
signac.Project
.The Dashboard class is designed to be used as a base class for a child class such as
MyDashboard
which can be customized and launched via its command line interface (CLI). The CLI is invoked by callingmain()
on an instance of this class.Configuration options: The
config
dictionary recognizes the following options:HOST: Sets binding address (default: localhost).
PORT: Sets port to listen on (default: 8888).
DEBUG: Enables debug mode if
True
(default:False
).PROFILE: Enables the profiler
werkzeug.middleware.profiler.ProfilerMiddleware
ifTrue
(default:False
).PER_PAGE: Maximum number of jobs to show per page (default: 25).
SECRET_KEY: This must be specified to run via WSGI with multiple workers, so that sessions remain intact. See the Flask docs for more information.
ALLOW_WHERE: If True, search queries can include
$where
statements, which potentially allows arbitrary code execution from user input. Caution: This should only be enabled in trusted environments, never on a publicly-accessible server (default: False).
- Parameters
config (dict) – Configuration dictionary (default:
{}
).project (
signac.Project
) – signac project (default:None
, autodetected).
- add_url(import_name, url_rules=[], import_file='signac_dashboard', **options)[source]
Add a route to the dashboard.
This method allows custom view functions to be triggered for specified routes. These view functions are imported lazily, when their route is triggered. For example, write a file
my_views.py
:def my_custom_view(dashboard): return 'This is a custom message.'
Then, in
dashboard.py
:Finally, launching the dashboard with
python dashboard.py run
and navigating to/custom-url
will show the custom message. This can be used in conjunction with user-provided jinja templates and the methodflask.render_template()
for extending dashboard functionality.- Parameters
import_name (str) – The view function name to be imported.
url_rules (list) – A list of URL rules, see
flask.Flask.add_url_rule()
.import_file (str) – The module from which to import (default:
'signac_dashboard'
).**options – Additional options to pass to
flask.Flask.add_url_rule()
.
- job_sorter(job)[source]
Override this method for custom job sorting.
This method returns a key that can be compared to sort jobs. By default, the sorting key is based on
Dashboard.job_title()
, with natural sorting of numbers. Good examples of such keys are strings or tuples of properties that should be used to sort.- Parameters
job (
signac.contrib.job.Job
) – The job being sorted.- Returns
Key for sorting.
- Return type
any comparable type
- job_subtitle(job)[source]
Override this method for custom job subtitles.
This method generates job subtitles. By default, the subtitle is a minimal unique substring of the job id.
- Parameters
job (
signac.contrib.job.Job
) – The job being subtitled.- Returns
Subtitle to be displayed.
- Return type
- job_title(job)[source]
Override this method for custom job titles.
This method generates job titles. By default, the title is a pretty (but verbose) form of the job state point, based on the project schema.
- Parameters
job (
signac.contrib.job.Job
) – The job being titled.- Returns
Title to be displayed.
- Return type
- main()[source]
Runs the command line interface.
Call this function to use signac-dashboard from its command line interface. For example, save this script as
dashboard.py
:Then the dashboard can be launched with:
python dashboard.py run
- register_module_asset(asset)[source]
Register an asset required by a dashboard module.
Some modules require special scripts or stylesheets, like the
signac_dashboard.modules.Notes
module. It is recommended to use a namespace for each module that matches the example below:dashboard.register_module_asset({ 'file': 'templates/my-module/js/my-script.js', 'url': '/module/my-module/js/my-script.js' })
- Parameters
asset (dict) – A dictionary with keys
'file'
and'url'
.
- run(*args, **kwargs)[source]
Runs the dashboard webserver.
Use
main()
instead of this method for the command-line interface. Arguments to this function are passed directly toflask.Flask.run()
.
Dashboard Modules
|
Base class for dashboard modules. |
|
Provides an interface to edit the job document. |
|
Displays the job document. |
|
Lists files in the job workspace with download links. |
|
Show job labels from a |
|
Displays images in the job workspace that match a glob. |
|
Displays a text box that is synced to the job document. |
|
Displays the job state point. |
|
Render custom text or Markdown in a card. |
|
Displays videos in the job workspace that match a glob. |
- class signac_dashboard.Module(name, context, template, enabled=True)[source]
Base class for dashboard modules.
Modules provide cards of content, for a specific context. Each module must have a name which appears in its cards’ titles, a context (such as
'JobContext'
) in which its contents will be displayed, and a template file (written in HTML/Jinja-compatible syntax) for rendering card content. Modules can be disabled by default, by settingenabled=False
in the constructor.Custom modules: User-defined module classes should be a subclass of
Module
and define the functionget_cards()
. See this example.Module assets: If a module requires scripts or stylesheets to be included for its content to be rendered, they must be handled by the callback
register()
. For example, a module inheriting from the basesignac_dashboard.Module
class may implement this by overriding the default method as follows:def register(self, dashboard): assets = ['js/my-script.js', 'css/my-style.css'] for asset in assets: dashboard.register_module_asset({ 'file': 'templates/my-module/{}'.format(asset), 'url': '/module/my-module/{}'.format(asset) })
Then, when the module is active, its assets will be included and a route will be created that returns the asset file.
Module routes: The callback
register()
allows modules to implement custom routes, such as methods that should be triggered byPOST
requests or custom APIs. For example, a module inheriting from the basesignac_dashboard.Module
class may implement this by overriding the default method as follows:def register(self, dashboard): @dashboard.app.route('/module/my-module/update', methods=['POST']) def my_module_update(): # Perform update return "Saved."
- Parameters
- get_cards()[source]
Returns this module’s cards for rendering.
The cards are returned as a list of dictionaries with keys
'name'
and'content'
.- Returns
List of module cards.
- Return type
- register(dashboard)[source]
Callback to register this module with the dashboard.
This callback should register assets and routes, as well as any other initialization that accesses or modifies the dashboard.
- Parameters
dashboard (
signac_dashboard.Dashboard
) – The dashboard invoking this callback method.
- class signac_dashboard.modules.DocumentEditor(name='Document Editor', context='JobContext', template='cards/document_editor.html', **kwargs)[source]
Provides an interface to edit the job document.
This module shows keys in the job document with a form that allows users to edit their contents. When saving, the edited strings are parsed into JSON-compatible Python data structures (e.g.,
list
anddict
). Job document keys beginning with an underscore_
are treated as private and are not displayed.
- class signac_dashboard.modules.DocumentList(name='Job Document', context='JobContext', template='cards/document_list.html', max_chars=None, **kwargs)[source]
Displays the job document.
Long values can be optionally truncated.
- Parameters
max_chars (int) – Truncation length for document values (default:
None
).
- class signac_dashboard.modules.FileList(name='File List', context='JobContext', template='cards/file_list.html', prefix_jobid=True, **kwargs)[source]
Lists files in the job workspace with download links.
- Parameters
prefix_jobid (bool) – Whether filenames should be prefixed with the job id when being downloaded (default:
True
).
- class signac_dashboard.modules.FlowStatus(name='Flow Status', context='JobContext', template='cards/flow_status.html', project_module='project', project_class='Project', **kwargs)[source]
Show job labels from a
flow.FlowProject
.This module displays a card with labels from
flow.FlowProject.labels()
. The user must provide an instance offlow.FlowProject
to the dashboard constructor. Example:
- class signac_dashboard.modules.ImageViewer(name='Image Viewer', context='JobContext', template='cards/image_viewer.html', img_globs=('*.png', '*.jpg', '*.gif'), **kwargs)[source]
Displays images in the job workspace that match a glob.
This module can display images in any format that works with a standard
<img>
tag. The module defaults to showing all images of PNG, JPG, or GIF types. A filename or glob can be defined to select specific filenames. Multiple ImageViewer modules can be defined with different filenames or globs to enable/disable cards for each image or image group. Examples:from signac_dashboard.modules import ImageViewer img_mod = ImageViewer() # Shows all PNG/JPG/GIF images img_mod = ImageViewer(name='Bond Order Diagram', img_globs=['bod.png'])
- Parameters
img_globs (list) – A list of glob expressions or exact filenames to be displayed, one per card (default:
['*.png', '*.jpg', '*.gif']
).
- class signac_dashboard.modules.Notes(name='Notes', context='JobContext', template='cards/notes.html', key='notes', **kwargs)[source]
Displays a text box that is synced to the job document.
The contents of the text box are saved to
job.document['notes']
. The Notes module can be used to annotate a large data space with tags or human-readable descriptions for post-processing, parsing, or searching.- Parameters
key (str) – Document key to display and update (default:
'notes'
).
- class signac_dashboard.modules.StatepointList(name='Statepoint Parameters', context='JobContext', template='cards/statepoint_list.html', **kwargs)[source]
Displays the job state point.
- class signac_dashboard.modules.TextDisplay(name='Text Display', message=<function TextDisplay.<lambda>>, markdown=False, **kwargs)[source]
Render custom text or Markdown in a card.
This module calls a user-provided function to display text or Markdown content in a card. Rendering Markdown requires the
markdown
library to be installed. Example:from signac_dashboard.modules import TextDisplay def my_text(job): return f"This job id is {job}." modules = [TextDisplay(message=my_text)]
- Parameters
message (callable) – A callable accepting one argument of type
signac.contrib.job.Job
and returning text or Markdown content.markdown (bool) – Enables Markdown rendering if True (default: False).
- class signac_dashboard.modules.VideoViewer(name='Video Viewer', context='JobContext', template='cards/video_viewer.html', video_globs=('*.mp4', '*.m4v'), preload='none', poster=None, **kwargs)[source]
Displays videos in the job workspace that match a glob.
The
VideoViewer
module displays videos using an HTML<video>
tag. The module defaults to showing all videos of MP4 or M4V types. A filename or glob can be defined to select specific filenames, which may be of any format supported by your browser with the<video>
tag. A “poster” can be defined, which shows a thumbnail with that filename before the video is started. Videos do not preload by default, since file sizes can be large and there may be many videos on a page. To enable preloading, use the argumentpreload='auto'
orpreload='metadata'
. Multiple VideoViewer modules can be defined with different filenames or globs to enable/disable cards individually. Examples:from signac_dashboard.modules import VideoViewer video_mod = VideoViewer() # Shows all MP4/M4V videos video_mod = VideoViewer(name='Cool Science Video', video_globs=['cool_science.mp4'], poster='cool_science_thumbnail.jpg', preload='none')
- Parameters
video_globs (list) – A list of glob expressions or exact filenames to be displayed, one per card (default:
['*.mp4', '*.m4v']
).preload (str) – Option for preloading videos, one of
'auto'
,'metadata'
, or'none'
(default:'none'
).poster (str) – A path in the job workspace for a poster image to be shown before a video begins playback (default:
None
).