pygsti.report.merge_helpers
Helper functions for creating HTML documents by “merging” with a template
Module Contents
Functions
|
Return the HTML used to insert a resource into a larger HTML file. |
|
Copy the pyGSTi 'offline' directory into output_dir. |
|
Load a HTML template from a file and perform an preprocessing. |
|
If path is a directory, remove all the files within it |
|
Ensure that dirname names an empty directory |
|
Render the workspace quantities (outputs and switchboards) in the qtys dictionary as HTML. |
|
Render the workspace quantities (outputs; not switchboards) in the qtys dictionary as LaTeX. |
|
Renders qtys and merges them into a single HTML file output_filename. |
|
Renders qtys and merges them into the HTML files under template_dir, saving the output under output_dir. |
|
Use subprocess to run call. |
|
Run call and raise CalledProcessError if exit code > 0 |
|
Renders qtys and merges them into the LaTeX file template_filename, saving the output under output_filename. |
|
Compile a PDF report from a TeX file. Will compile twice automatically. |
|
Convert a list of (key,value) pairs to a "pdfinfo" string. |
- pygsti.report.merge_helpers.insert_resource(connected, online_url, offline_filename, integrity=None, crossorigin=None)
Return the HTML used to insert a resource into a larger HTML file.
When connected==True, an internet connection is assumed and online_url is used if it’s non-None; otherwise offline_filename (assumed to be relative to the “templates/offline” folder within pyGSTi) is inserted inline. When connected==False an offline folder is assumed to be present in the same directory as the larger HTML file, and a reference to offline_filename is inserted.
Parameters
- connectedbool
Whether an internet connection should be assumed. If False, then an ‘offline’ folder is assumed to be present in the output HTML’s folder.
- online_urlstr
The url of the inserted resource as available from the internet. None if there is no such availability.
- offline_filenamestr
The filename of the resource relative to the templates/offline pyGSTi folder.
- integritystr, optional
The “integrity” attribute string of the <script> tag used to reference a *.js (javascript) file on the internet.
- crossoriginstr, optional
The “crossorigin” attribute string of the <script> tag used to reference a *.js (javascript) file on the internet.
Returns
str
- pygsti.report.merge_helpers.rsync_offline_dir(output_dir)
Copy the pyGSTi ‘offline’ directory into output_dir.
This creates or updates any non-existent or outdated files as needed.
Parameters
- output_dirstr
The output directory
Returns
None
- pygsti.report.merge_helpers.load_and_preprocess_template(template_filename, toggles)
Load a HTML template from a file and perform an preprocessing.
Preprocessing directives are “#iftoggle(name)”, “#elsetoggle”, and “#endtoggle”.
Parameters
- template_filenamestr
filename (no relative directory assumed).
- togglesdict
A dictionary of toggle_name:bool pairs specifying how to preprocess the template.
Returns
str
- pygsti.report.merge_helpers.clear_dir(path)
If path is a directory, remove all the files within it
Parameters
- pathstr
The path to clear.
Returns
None
- pygsti.report.merge_helpers.create_empty_dir(dirname)
Ensure that dirname names an empty directory
Parameters
- dirnamestr
The directory path.
Returns
- str
The directory name.
- pygsti.report.merge_helpers.render_as_html(qtys, render_options, link_to, verbosity)
Render the workspace quantities (outputs and switchboards) in the qtys dictionary as HTML.
Parameters
- qtysdict
A dictionary of workspace quantities to render.
- render_optionsdict
a dictionary of render options to set via the WorkspaceOutput.set_render_options method of workspace output objects.
- link_totuple
If not None, a list of one or more items from the set {“tex”, “pdf”, “pkl”} indicating whether or not to create and include links to Latex, PDF, and Python pickle files, respectively.
- verbosityint
How much detail to print to stdout.
Returns
- dict
With the same keys as qtys and values which contain the objects rendered as strings.
- pygsti.report.merge_helpers.render_as_latex(qtys, render_options, verbosity)
Render the workspace quantities (outputs; not switchboards) in the qtys dictionary as LaTeX.
Parameters
- qtysdict
A dictionary of workspace quantities to render.
- render_optionsdict
a dictionary of render options to set via the WorkspaceOutput.set_render_options method of workspace output objects.
- verbosityint
How much detail to print to stdout.
Returns
- dict
With the same keys as qtys and values which contain the objects rendered as strings.
- pygsti.report.merge_helpers.merge_jinja_template(qtys, output_filename, template_dir=None, template_name='main.html', auto_open=False, precision=None, link_to=None, connected=False, toggles=None, render_math=True, resizable=True, autosize='none', verbosity=0)
Renders qtys and merges them into a single HTML file output_filename.
This functions parameters are the same as those of
merge_jinja_template_dir().Parameters
- qtysdict
A dictionary of workspace quantities (switchboards and outputs).
- output_filenamestr or pathlib.Path
The output filename.
- template_dirstr, optional
The template filename, relative to pyGSTi’s templates directory.
- template_namestr, optional
The name of the template file within template_dir.
- auto_openbool, optional
Whether the output file should be automatically opened in a web browser.
- precisionint or dict, optional
The amount of precision to display. A dictionary with keys “polar”, “sci”, and “normal” can separately specify the precision for complex angles, numbers in scientific notation, and everything else, respectively. If an integer is given, it this same value is taken for all precision types. If None, then a default is used.
- link_tolist, optional
If not None, a list of one or more items from the set {“tex”, “pdf”, “pkl”} indicating whether or not to create and include links to Latex, PDF, and Python pickle files, respectively.
- connectedbool, optional
Whether an internet connection should be assumed. If False, then an ‘offline’ folder is assumed to be present in the output HTML’s folder.
- togglesdict, optional
A dictionary of toggle_name:bool pairs specifying how to preprocess the template.
- render_mathbool, optional
Whether math should be rendered.
- resizablebool, optional
Whether figures should be resizable.
- autosize{‘none’, ‘initial’, ‘continual’}
Whether tables and plots should be resized, either initially – i.e. just upon first rendering (“initial”) – or whenever the browser window is resized (“continual”).
- verbosityint, optional
Amount of detail to print to stdout.
Returns
None
- pygsti.report.merge_helpers.merge_jinja_template_dir(qtys, output_dir, template_dir=None, template_name='main.html', auto_open=False, precision=None, link_to=None, connected=False, toggles=None, render_math=True, resizable=True, autosize='none', embed_figures=True, verbosity=0)
Renders qtys and merges them into the HTML files under template_dir, saving the output under output_dir.
Parameters
- qtysdict
A dictionary of workspace quantities (switchboards and outputs).
- output_dirstr
The merged-output directory..
- template_dirstr, optional
The template filename, relative to pyGSTi’s templates directory.
- template_namestr, optional
The name of the template file within template_dir.
- auto_openbool, optional
Whether the output file should be automatically opened in a web browser.
- precisionint or dict, optional
The amount of precision to display. A dictionary with keys “polar”, “sci”, and “normal” can separately specify the precision for complex angles, numbers in scientific notation, and everything else, respectively. If an integer is given, it this same value is taken for all precision types. If None, then a default is used.
- link_tolist, optional
If not None, a list of one or more items from the set {“tex”, “pdf”, “pkl”} indicating whether or not to create and include links to Latex, PDF, and Python pickle files, respectively.
- connectedbool, optional
Whether an internet connection should be assumed. If False, then an ‘offline’ folder is assumed to be present in the output HTML’s folder.
- togglesdict, optional
A dictionary of toggle_name:bool pairs specifying how to preprocess the template.
- render_mathbool, optional
Whether math should be rendered.
- resizablebool, optional
Whether figures should be resizable.
- autosize{‘none’, ‘initial’, ‘continual’}
Whether tables and plots should be resized, either initially – i.e. just upon first rendering (“initial”) – or whenever the browser window is resized (“continual”).
- embed_figuresbool, optional
Whether figures should be embedded in the generated report. If False, figures will be written to a ‘figures’ directory in the output directory, and will be loaded dynamically via AJAX. This may be useful for reducing the size of the generated report if the report includes relatively many figures. Note that all major web browsers will block AJAX requests from an HTML document loaded from the filesystem. If this option is set to False, the generated report will fail to load from the filesystem, and must be served up by a webserver. Python’s http.server module works fine.
- verbosityint, optional
Amount of detail to print to stdout.
Returns
None
- pygsti.report.merge_helpers.process_call(call)
Use subprocess to run call.
Parameters
- calllist
A list of exec name and args, e.g. [‘ls’,’-l’,’myDir’]
Returns
stdout : str stderr : str return_code : int
- pygsti.report.merge_helpers.evaluate_call(call, stdout, stderr, returncode, printer)
Run call and raise CalledProcessError if exit code > 0
Parameters
- calllist
List containing the command and flags in the form that
subprocess.check_call()uses.- stdoutfile pointer
As in
subprocess.check_call().- stderrfile pointer
As in
subprocess.check_call().- returncodeint
Return/exit code.
- printerVerbosityPrinter
Printer object to write errors to.
Returns
None
- pygsti.report.merge_helpers.merge_latex_template(qtys, template_filename, output_filename, toggles=None, precision=None, verbosity=0)
Renders qtys and merges them into the LaTeX file template_filename, saving the output under output_filename.
Parameters
- qtysdict
A dictionary of workspace quantities (outputs).
- template_filenamestr
The template filename, relative to pyGSTi’s templates directory.
- output_filenamestr
The merged-output filename.
- togglesdict, optional
A dictionary of toggle_name:bool pairs specifying how to preprocess the template.
- precisionint or dict, optional
The amount of precision to display. A dictionary with keys “polar”, “sci”, and “normal” can separately specify the precision for complex angles, numbers in scientific notation, and everything else, respectively. If an integer is given, it this same value is taken for all precision types. If None, then a default is used.
- verbosityint, optional
Amount of detail to print to stdout.
Returns
None
- pygsti.report.merge_helpers.compile_latex_report(report_filename, latex_call, printer, auto_open)
Compile a PDF report from a TeX file. Will compile twice automatically.
Parameters
- report_filenamestring
The full file name, which may (but need not) include a “.tex” or “.pdf” extension, of the report input tex and output pdf files.
- latex_calllist of string
List containing the command and flags in the form that
subprocess.check_call()uses.- printerVerbosityPrinter
Printer to handle logging.
- auto_openbool, optional
Whether the generated report file should be opened by the OS right before this function exists.
Returns
None
Raises
- subprocess.CalledProcessException
If the call to the process comiling the PDF returns non-zero exit status.
- pygsti.report.merge_helpers.to_pdfinfo(list_of_keyval_tuples)
Convert a list of (key,value) pairs to a “pdfinfo” string.
The returned string is in the format expected for a latex document’s “pdfinfo” directive (for setting PDF file meta information).
Parameters
- list_of_keyval_tupleslist
A list of (key,value) tuples.
Returns
str