gwdetchar.io.html module

Utilties for HTML output

class gwdetchar.io.html.FancyPlot(img, caption=None)[source]

Bases: object

A helpful class of objects that coalesce image links and caption text for fancybox figures.

Parameters

img : str or FancyPlot

either a filename (including relative or absolute path) or another FancyPlot instance

caption : str

the text to be displayed in a fancybox as this figure’s caption

__dict__ = mappingproxy({'__module__': 'gwdetchar.io.html', '__doc__': "A helpful class of objects that coalesce image links and caption text\n    for fancybox figures.\n\n    Parameters\n    ----------\n    img : `str` or `FancyPlot`\n        either a filename (including relative or absolute path) or another\n        FancyPlot instance\n\n    caption : `str`\n        the text to be displayed in a fancybox as this figure's caption\n    ", '__init__': <function FancyPlot.__init__>, '__str__': <function FancyPlot.__str__>, '__dict__': <attribute '__dict__' of 'FancyPlot' objects>, '__weakref__': <attribute '__weakref__' of 'FancyPlot' objects>, '__annotations__': {}})
__doc__ = "A helpful class of objects that coalesce image links and caption text\n    for fancybox figures.\n\n    Parameters\n    ----------\n    img : `str` or `FancyPlot`\n        either a filename (including relative or absolute path) or another\n        FancyPlot instance\n\n    caption : `str`\n        the text to be displayed in a fancybox as this figure's caption\n    "
__init__(img, caption=None)[source]
__module__ = 'gwdetchar.io.html'
__str__()[source]

Return str(self).

__weakref__

list of weak references to the object (if defined)

gwdetchar.io.html._get_card_header(context)[source]

Return the correct bootstrap-4 card-header class for the given context

gwdetchar.io.html.about_this_page(config, packagelist=True, prog=None)[source]

Write a blurb documenting how a page was generated, including the command-line arguments and configuration files used

Parameters

config : str, list, optional

the absolute path(s) to one or a number of INI files used in this process

packagelist : bool, optional

boolean switch to include (True) or exclude (False) a comprehensive list of system packages

prog : str, optional

name of the program which produced this page, defaults to the script run on the command-line

Returns

page : page

the HTML page to be inserted into the #main <div>.

gwdetchar.io.html.alert(text, context='info', dismiss=True)[source]

Enclose text within a bootstrap dialog box

Parameters

text : str or list of str

text to enclose within the box, if a list then each item will be rendered in a separate <p> tag

context : str, optional

Bootstrap context type, default: info

dismiss : bool, optional

boolean switch to enable (True) or disable (False) a dismiss button, default: True

Returns

page : page

the rendered dialog box object

Write a channel name as a link to the Channel Information System

Parameters

channel : str

the name of the channel to link

**params

other HTML parmeters for the <a> tag

Returns
htmlstr
gwdetchar.io.html.close_page(page, target, **kwargs)[source]

Close an HTML document with markup then write to disk

This method writes the closing markup to complement the opening written by init_page, something like:

</div>
<footer>
    <!-- some stuff -->
</footer>
</body>
</html>
Parameters

page : markup.page

the markup object to close

target : str

the output filename for HTML

gwdetchar.io.html.download_btn(content, label='Download summary', btndiv='dropdown float-right d-none d-lg-block', btnclass='btn btn-outline-secondary dropdown-toggle')[source]

Toggle download options with a Bootstrap button

Parameters

content : list of tuple of str

collection of (title, link) pairs to list

label : str, optional

text appearing inside the button, default: Download summary

id_ : str, optional

unique HTML identifier for this button

btndiv : str, optional

class name of the enclosing <div>, default: dropdown float-right d-none d-lg-block

btnclass : str, optional

class name of the Bootstrap button object, default: btn btn-secondary dropdown-toggle

Returns

page : page

fully rendered download button

gwdetchar.io.html.dropdown(text, links, active=None, class_='nav-link dropdown-toggle')[source]

Construct a dropdown menu in bootstrap format

Parameters

text : str

dropdown menu header

links : list

list of (Link text, linkurl) tuples or dict of such tuples for grouped dropdowns

active : int or list of ints, optional

collection of links to make active, default: None

class_ : str, optional

object class of the dropdown menu, default: 'dropdown-toggle'

Returns

page : page

HTML element with the following grammar:

<a>text</a>
<ul>
    <li>link</li>
    <li>link</li>
</ul>

Format links within a dropdown menu

Parameters

page : page

a page object to format in-place

link : page or list

the link(s) to format

active : bool, optional

boolean switch to enable (True) or disable (False) an active link, default: False

class_ : str, optional

object class of the link, default: ''

gwdetchar.io.html.fancybox_img(img, linkparams={}, lazy=False, **params)[source]

Return the markup to embed an <img> in HTML

Parameters

img : FancyPlot

a FancyPlot object containing the path of the image to embed and its caption to be displayed

linkparams : dict, optional

the HTML attributes for the <a> tag

lazy : bool, optional

whether to lazy-load the image, default: False

**params

the HTML attributes for the <img> tag

Returns

page : page

the markup object containing fancyplot HTML

gwdetchar.io.html.finalize_static_urls(static, base, cssfiles, jsfiles)[source]

Finalise the necessary CSS and javascript files as URLS.

The method parses the lists of files given, copying any local files into static as necessary to create resolvable URLs to include in the HTML <head>.

Parameters

static : str

the target directory for the static files, will be created if necessary

base : str

the base directory of the website

cssfiles : list of str

the list of CSS files to include

jsfiles : list of str

the (complete) list of javascript files to include

Returns

cssurls : list of str

the finalised list of CSS files

jsurls : list of str

the finalised list of javascript files

gwdetchar.io.html.get_brand(ifo, name, gps, about=None)[source]

Return a brand for navigation bar formatting

Parameters

ifo : str

interferometer prefix for color-coding, e.g. 'L1'

name : str

name of the analysis, e.g. 'Scattering'

gps : float

GPS second of the analysis

about : str, optional

relative path to the about page for this analysis, default: None

Returns

brand : page

the navbar brand page object

class_ : str

object class of the navbar

gwdetchar.io.html.get_command_line(language='bash', about=True, prog=None)[source]

Render the command-line invocation used to generate a page

Parameters

language : str, optional

type of environment the code is run in, default: 'bash'

about : bool, optional

whether this markup is for an ‘about’ page, default: True

prog : str, optional

name of the program which produced this page, defaults to the script run on the command-line

Returns

page : page

fully rendered command-line arguments

Write an HTML <a> tag

Parameters

href : str

the URL to point to

txt : str

the text for the link

target : str, optional

the target of this link

**params

other HTML parameters for the <a> tag

Returns
htmlstr
gwdetchar.io.html.navbar(links, class_='navbar navbar-expand-md fixed-top shadow-sm', brand=None, collapse=True)[source]

Construct a navigation bar in bootstrap format

Parameters

links : list

list of either (text, URL) tuples or page objects. Tuples will be written in <a> tags while pages will be copied directly. Both will be enclosed in a <li> element inside the navbar

class_ : str, optional

navbar object class, default: 'navbar navbar-expand-md fixed-top'

brand : str, page, or list, optional

branding for the navigation bar, default: None

collapse : bool, optional

whether to toggle all dropdown menus, default: True

Returns

page : page

navbar HTML page object

gwdetchar.io.html.new_bootstrap_page(base='.', path='.', lang='en', refresh=False, topbtn=True, navbar=None, **kwargs)[source]

Create a new page with custom twitter bootstrap CSS and JS headers

Parameters

base : str, optional

relative path to the base directory, default:

path : str, optional

path to directory where the page is located, default:

lang : str, optional

language of the page, default: en

refresh : bool, optional

boolean switch to enable periodic page refresh, default: False

topbtn : bool, optional

boolean switch to include or exclude a floating button that scrolls to the top of the page, default: True

navbar : str, optional

HTML enconding of a floating navbar, will be ignored if not given, default: None

Returns

page : page

a populated HTML page object, which can be appended to as desired

gwdetchar.io.html.package_list()[source]

Get the list of packages installed alongside this one

Returns a list of dict

gwdetchar.io.html.package_table(h2='Environment', class_='table table-sm table-hover table-responsive', caption='Table of packages installed in the production environment', id_='package-table')[source]

Write a table listing packages installed in the current environment

Parameters

h2 : str, None, optional

the header for the HTML section

caption : str, None, optional

the <caption> for the package table

Returns

html : str

an HTML table

gwdetchar.io.html.parameter_table(content=[], start=None, end=None, flag=None, id_='parameters', tableclass='table table-sm table-hover')[source]

Render an informative section with run parameters in HTML

Parameters

content: `list` of `tuple` of `str`

collection of parameters to list

start : float

GPS start time of the analysis

end : float

GPS end time of the analysis

flag : str, optional

name of a data-quality state flag required for this analysis

section : str, optional

text to label the section header (<h2>), default: Parameters

id_ : str, optional

unique HTML identifier for this section, default: parameters

tableclass : str, optional

the class for the summary <table>, defaults to a responsive Bootstrap table

Returns

page : page

fully rendered table of parameters

gwdetchar.io.html.render_code(code, language)[source]

Render a block of code with syntax highlighting

Parameters

code : str

a raw block of source code

language : str

language the code is written in, e.g. 'python'

Returns

code : page

fully rendered command-line call

gwdetchar.io.html.scaffold_omega_scans(times, channel, plot_durations=[1, 4, 16], scandir='.')[source]

Preview a batch of omega scans in HTML

Parameters

times : list of float

a list of GPS times to scan

channel : str

name of the channel being scanned, e.g. H1:GDS-CALIB_STRAIN

plot_durations : list of int

list of plot durations in seconds, default: [1, 4, 16]

scandir : str

path to the directory containing omega scans, default:

Returns

page : page

rendered scaffold of omega scan plots

gwdetchar.io.html.scaffold_plots(plots, nperrow=3, lazy=True)[source]

Embed a list of images in a bootstrap scaffold

Parameters

plot : list of FancyPlot

the list of image paths to embed

nperrow : int

the number of images to place in a row (on a desktop screen)

lazy : bool, optional

whether to lazy-load images, default: True

Returns

page : page

the markup object containing the scaffolded HTML

gwdetchar.io.html.table(headers, data, caption=None, separator='', id=None, **class_)[source]

Write a <table> with one row of headers and many rows of data

Parameters

headers : list

list of column header names

data : list of lists

list of column data lists, for m rows and n columns, this should have dimensions m x n

caption : str, optional

content for this table’s <caption>

**class_

class attribute declarations for each tag used in the table, any of table, thead, tbody, tr, th, td, caption

Returns

table : page

a formatted HTML page object containing the <table>

gwdetchar.io.html.write_flag_html(flag, span=None, id=0, parent='accordion', context='warning', title=None, plotdir=None, plot_func=<function plot_segments>, **kwargs)[source]

Write HTML for data-quality flags

Parameters

flag : DataQualityFlag

the flag object to represent

span : Segment, optional

GPS start and stop time of flag duration

id : int, optional

unique identifier for the flag, default: 0

parent : str, optional

HTML identifier of the parent object, default: accordion

context : str, optional

Bootstrap context type, default: warning

title : str, optional

title of the flag, defaults to flag.name

plotdir : str, optional

path to directory containing plots, required if plotting segments

plot_func : func, optional

function used to plot segments, default: plot_segments

**kwargs : dict, optional

additional keyword arguments to plot_func

Returns

page : page

fully rendered HTML with a card object for the flag

Write a <footer> for a bootstrap page

Parameters

about : str, optional

path of about page to link

link : None or tuple, optional

tuple of package name, HTML link to source code, and host name (e.g. GitHub)

issues : str, optional

HTML link to issue report page

external : str, optional

additional footer link to an external page

Returns

page : page

the markup object containing the footer HTML