`auto_process_ngs.docwriter`

docwriter provides a set of classes that can be used to create HTML documents programmatically.

Example usage: create a new document:

>>> d = Document("Report")
>>> d.add_css_rule("h1 { color: blue; }")
>>> d.add_css_rule("h2 { color: green; }")
>>> d.add_css_rule("h3 { color: red; }")

Add a section:

>>> s = d.add_section("Introduction")
>>> s.add("This is the introduction")

Add a subsection:

>>> subs = s.add_section("Background")
>>> subs.add("This is the background")

Generate the HTML directly:

>>> d.html()

Write the HTML document to a file:

>>> d.write("report.html")

There are also classes to create lists, tables, images, links and anchors (aka “targets”) within documents.

The full list of available classes are:

Document: construct HTML documents
Section: generic document section
Table: construct HTML tables
List: create ordered and unordered HTML lists
Img: embed references to images
Link: embed references to other documents/items
Target: create anchor for referencing via a link
Para: wrap heterogeneous items into a single block
WarningIcon: create an inline warning icon image
DocumentIcon: create an inline ‘document’ icon image
LinkIcon: create an inline ‘link’ icon image

class auto_process_ngs.docwriter.Document(title=None)

Utility class for constructing documents

Basic usage:

>>> d = Document("Report")
>>> d.add_css_rule("h1 { color: red; }")
>>> s = d.add_section("Introduction")
>>> s.write("report.html")

The following properties are available:

title: returns the title string
css_rules: returns the CSS rules as a list

The ‘html’ method returns the document body rendered as HTML; the ‘write’ method writes the full HTML document to file, including the document header, CSS rules etc.

Parameters:: title (str) – title for the document

add_css_rule(css_rule)

Add a CSS rule block to the document

Parameters:: css_rule (str) – block of text to append to the CSS rules to write to the final document

add_javascript(script)

Add Javascript code to the document

Parameters:: script (str) – script block to include in the final document header

add_section(title=None, section=None, name=None, css_classes=None, style=None)

Add a section to the document

If an existing section is supplied then this is appended to the document; otherwise a new section is created with the title and name supplied.

Parameters:

title (str) – title for the new section
section (Section) – an existing Section instance which will be appended to the document
name (str) – internal name for the section; if not supplied then the name will be generated automatically from the title
css_classes (list) – list or iterable with names of CSS classes to associate with the new section
style (str) – style information to put into the ‘style’ attribute of the section

Returns:

the new or supplied section as: appropriate.

Return type:

Section

property css_rules: Get the CSS rules as a list

html()

Generate HTML version of the document contents

Note that this only generates the “body” HTML code; the header and footers will not be returned (so this will not be the full HTML that is written by the ‘write’ method).

Returns:

HTML representation of the document: content.

Return type:

String

property title: Get the document’s title

write(outfile)

Write document contents to a file

Arguments

outfile (str): path to file to write: HTML document to

class auto_process_ngs.docwriter.DocumentIcon(title=None, size=35)

Create image with an inline document icon

Parameters:

title (str) – optional, content to mark with the icon
size (int) – optional height/width specifier for the icon (defaults to 35)

class auto_process_ngs.docwriter.DownloadIcon(title=None, size=32)

Create image with an inline ‘download’ icon

Parameters:

title (str) – optional, content to mark with the icon
size (int) – optional height/width specifier for the icon (defaults to 32)

class auto_process_ngs.docwriter.Img(src, name=None, height=None, width=None, href=None, alt=None, title=None)

Utility class for embedding <img> tags

Example usage:

>>> img = Img('picture.png',width=150)
>>> img.html()
"<img src='picture.png' width='150' />"

Parameters:

src (str) – string to use as the ‘src’ attribute for the <img…/> tag
name (str) – string to use as the ‘id’ attribute for the <img…/> tag
height (int) – optional height (pixels)
width (int) – optional width (pixels)
href (str) – if specified then the <img…/> will be wrapped in <a href..>…</a> with this used as the link target
alt (str) – if specified then used as the ‘alternative text’ (‘alt’ attribute for <img…/> tag)
title (str) – if specified then assigned to the <img../> tag’s ‘title’ attribute

html()

Generate HTML version of the image tag

Returns:: HTML representation of the image.
Return type:: String

property name: Return the name (id) for the image

class auto_process_ngs.docwriter.Link(text, target=None)

Utility class for embedding <a href=…> tags

Example usage:

>>> ahref = Link('My report','report.html')
>>> ahref.html()
"<a href='report.html'>My report</a>"

The link target can be an object:

>>> sect = Section("New section",name='new_section')
>>> ahref = Link("New Section",sect)
>>> ahref.html()
"<a href='#new_section'>New Section</a>"

The target can be seen via the ‘href’ property:

>>> ahref.href
'#new_section'

Parameters:

text (str) – text to display for the link
target (Object) – target to link to; if not supplied then ‘text’ will be used as the link target

property href: Show the link target text

html()

Generate HTML version of the link

Returns:: HTML representation of the link.
Return type:: String

class auto_process_ngs.docwriter.LinkIcon(title=None, size=32)

Create image with an inline ‘link’ icon

Parameters:

title (str) – optional, content to mark with the icon
size (int) – optional height/width specifier for the icon (defaults to 32)

class auto_process_ngs.docwriter.List(name=None, ordered=False)

Utility class for creating ordered and unordered lists

Example usage:

>>> lst = List(ordered=True)
>>> lst.add_item("List item")
>>> lst.html()
"<ol><li>List item</li></ol>"

add_item(*content)

Append an item to the list

The item can consist of one or more objects (for example strings and other docwriter objects such as Lists, Links etc), which will be concatenated after rendering.

Parameters:: contents (sequence) – one or more objects to add to the list item

html()

Generate HTML version of the list

Returns:: HTML representation of the list.
Return type:: String

class auto_process_ngs.docwriter.Para(*items, **kws)

Utility to wrap heterogeneous items into a single block

The Para class provides a way to put several different items (e.g. plain text, links, images) into a single “block” (by default a ‘’-delimited paragraph).

Example usage:

>>> s = Section("QC reports")
>>> s.add(Para("%s" % project.name,
...            Link("qc_report.html")))

The Para wrapper prevents each plain text (i.e. string-like) content element being wrapped in its own … pair; instead only the completely assembled Para HTML is enclosed in ….

Parameters:

items (sequence) – optional, set of items to add to the block
css_classes (list) – list or iterable with names of CSS classes to associate with the section

add(*items)

Add (append) content to the block

Parameters:: items (sequence) – optional, set of items to append to the bloc

add_css_classes(*classes)

Associate CSS classes with the paragraph

Parameters:: classes (str) – the names of one or more CSS classes to associate with the section when it is rendered

html()

Generate HTML version of the block

Returns:: HTML representation of the block.
Return type:: String

class auto_process_ngs.docwriter.Section(title=None, name=None, level=2, css_classes=None, style=None)

Class representing a generic document section

A ‘section’ is a container for arbitrary content which can include text, images, links, tables, or other sections (which are considered to be subsections of the containing section).

A section typically has a title, however ‘anonymous’ (untitled) sections are also allowed.

Normally sections are created via the ‘add_section’ methods of a ‘Document’ or ‘Section’ instance, however they can also be created independently and then added (again via the ‘add_section’ method).

Content is added to the section using the ‘add’ method, which can invoked multiple times to append additional content.

When the content is rendered, each item is rendered to html via its ‘html’ method; or if the item doesn’t have a ‘html’ method then it will be rendered as a string and wrapped in ‘’ tags.

Example usage:

>>> d = Document("Report")
>>> abstract = d.section("Abstract")
>>> abstract.add("This is the abstract","It's quite short")
>>> paper = d.section()
>>> methods = paper.add_subsection("Methods")
>>> methods.add("This describes the methods used")
>>> results = paper.add_subsection("Results)
>>> result.add("Some nice figures")
>>> result.add(Img("graph.png"))

Parameters:

title (str) – title text
name (str) – name used for the ‘id’ of the section
level (int) – section heading level (defaults to 2)
css_classes (list) – list or iterable with names of CSS classes to associate with the section
style (str) – style information to put into the ‘style’ attribute of the section

add(*args)

Add content to the section

Parameters:: args (object) – one or more arbitrary items of content to append to the section; items must implement either a ‘html’ or ‘__str__’ method

add_css_classes(*classes)

Associate CSS classes with the section

Parameters:: classes (str) – the names of one or more CSS classes to associate with the section when it is rendered

add_subsection(title=None, section=None, name=None, css_classes=None, style=None)

Add subsection within the section

If an existing section is supplied then this is appended to the content; otherwise a new Section instance is created and appended.

Parameters:

title (str) – title text
section (Section) – if supplied then must be a Section instance which is inserted into the current Section as-is
name (str) – name used for the ‘id’ of the section
css_classes (list) – list or iterable with names of CSS classes to associate with the new section.
style (str) – style information to put into the ‘style’ attribute of the section

Returns:

the appended section.

Return type:

Section

property css_classes: Return the CSS classes as a list

html()

Generate HTML version of the section

Returns:

HTML representation of the section: content.

Return type:

String

property level: Return the level of the section

property name: Return the name (id) for the section

property title: Return the title for the section

class auto_process_ngs.docwriter.Table(columns, **aliases)

Utility class for constructing HTML tables

Usage examples:

Table with two columns with titles “Key” and “Value”, and with one row of data:

>>> t = Table(('Key','Value'))
>>> t.add_row(Key="Employee name",
...           Value="John Doe")
>>> print(t.html())
<table>
<tr><th>Key</th><th>Value</th></tr>
<tr><td>Employee name</td><td>John Doe</td></tr>
</table>

Table with three columns, with aliases for column names:

>>> t = Table(('name','date','result'),
...           name="Experiment",
...           date="Date run",
...           result="Final result")
>>> t.add_row(name="Test setup",
...           date="10/10/2017",
...           result="Ok")
>>> print(t.html())
<table>
<tr><th>Experiment</th><th>Date run</th><th>Final result</th></tr>
<tr><td>Test setup</td><td>10/10/2017</td><td>Ok</td></tr>
</table>

Add a column to the previous table, and set values:

>>> t.append_columns('verified',verified="Is verified?")
>>> t.set_value(0,"verified","no")
>>> print(t.html())
<table>
<tr><th>Experiment</th><th>Date run</th><th>Final result</th><th>Is verified?</th></tr>
<tr><td>Test setup</td><td>10/10/2017</td><td>Ok</td><td>no</td></tr>
</table>

The Table class provides the following properties:

nrows: number of rows in the table

It provides the following methods:

add_css_classes: associate CSS classes with the table
no_header: turn off writing table header in output HTML
append_columns: add additional columns to the table
add_row: append a row to the table
set_value: set the value in a table cell

Parameters:

columns (list) – list of column ids
aliases (mapping) – optional, mapping of column ids to aliases (i.e. actual names)

add_css_classes(*classes, **kws)

Associate CSS classes with the table

By default the supplied CSS classes associated with the whole table. If the ‘column’ keyword is supplied then the classes will be associated only with the table cells in that column.

Parameters:

classes (list) – one or more classes to associate with the table
column (str) – optional, if supplied then should specify a column name with which the classes will be associated

add_row(**kws)

Add (append) a row to the table

Appends a new empty row to the end of the table, and returns its row index.

Optionally values can also be assigned to columns in the new row, e.g.

t.add_row(col1=”value1”,col2=”value2”,…)

Parameters:

kws (mapping) – set of key=value assignments, defining the values to assign to columns in the new row

Returns:

the row index of the appended: row (for use e.g. in ‘set_value’)

Return type:

Integer

append_columns(*columns, **aliases)

Add a new columns to the table

Parameters:

columns (list) – list of column ids
aliases (mapping) – optional, mapping of column ids to aliases (i.e. actual names)

html(css_id=None)

Generate HTML version of the table contents

Parameters:: css_id (str) – optional, string to write into the CSS id attribute
Returns:: HTML representation of the table.
Return type:: String

no_header(): Don’t write the table header on output

property nrows: Return the number of rows in the table

set_value(row, key, value)

Set the value of a cell in the table

Parameters:

row (int) – index of the row to update
key (str) – id of the column to set the value for in this row
value (str) – value to assign to the table cell indicated by row/column

class auto_process_ngs.docwriter.Target(name)

Utility class for embedding <a id=… /> tags

Example usage:

>>> tgt = Target('my_target')
>>> tgt.html()
"<a id='my_target' />"

The target name/id can be retrieved using the ‘name’ property. It can also be supplied directly to a Link object:

>>> ahref = Link("My target",tgt)
>>> ahref.html()
"<a href='#my_target'>My target</a>"

Parameters:: name (str) – name (i.e. ‘id’) for the target

html()

Generate HTML version of the target

Returns:

HTML representation of the: target.

Return type:

String

property name: Return the name (id) for the target

class auto_process_ngs.docwriter.WarningIcon(title=None, size=25)

Create image with an inline warning icon

Parameters:

title (str) – optional, content to mark with the warning
size (int) – optional height/width specifier for the icon (defaults to 25)

auto_process_ngs.docwriter.sanitize_css_string(s)

Remove or replace invalid (non-CSS) characters in a string

Parameters:

s (str) – string to be sanitized

Returns:

version of the original string with whitespace: converted to underscores, and all other invalid characters removed.

Return type:

String

auto_process_ngs.docwriter

`auto_process_ngs.docwriter`