API Reference¶
This is the API for the signac-dashboard application.
The Dashboard¶
Attributes
Dashboard.add_url (import_name[, url_rules, …]) |
Add a route to the dashboard. |
Dashboard.job_sorter (job) |
Override this method for custom job sorting. |
Dashboard.job_subtitle (job) |
Override this method for custom job subtitles. |
Dashboard.job_title (job) |
Override this method for custom job titles. |
Dashboard.main () |
Runs the command line interface. |
Dashboard.register_module_asset (asset) |
Register an asset required by a dashboard module. |
Dashboard.run (*args, **kwargs) |
Runs the dashboard webserver. |
Dashboard.update_cache () |
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). - modules (list) – List of
Module
instances to display.
-
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
:from signac_dashboard import Dashboard class MyDashboard(Dashboard): pass if __name__ == '__main__': dashboard = MyDashboard() dashboard.add_url('my_custom_view', url_rules=['/custom-url'], import_file='my_views') dashboard.main()
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: str
-
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: str
-
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
:from signac_dashboard import Dashboard class MyDashboard(Dashboard): pass if __name__ == '__main__': MyDashboard().main()
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¶
Module (name, context, template[, enabled]) |
Base class for dashboard modules. |
modules.DocumentEditor ([name, context, template]) |
Provides an interface to edit the job document. |
modules.DocumentList ([name, context, …]) |
Displays the job document. |
modules.FileList ([name, context, template, …]) |
Lists files in the job workspace with download links. |
modules.FlowStatus ([name, context, …]) |
Show job labels from a flow.FlowProject . |
modules.ImageViewer ([name, context, …]) |
Displays images in the job workspace that match a glob. |
modules.Notes ([name, context, template, key]) |
Displays a text box that is synced to the job document. |
modules.StatepointList ([name, context, template]) |
Displays the job state point. |
modules.TextDisplay ([name, message, markdown]) |
Render custom text or Markdown in a card. |
modules.VideoViewer ([name, context, …]) |
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: list
-
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:from project import Project # FlowProject subclass with labels from signac_dashboard import Dashboard if __name__ == '__main__': Dashboard(project=Project()).main()
-
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:def my_text(job): return 'This job id is {}.'.format(str(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).
- message (callable) – A callable accepting one argument of type
-
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
).
- video_globs (list) – A list of glob expressions or exact filenames to be
displayed, one per card (default: