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:
- 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 ‘<p>’-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 <p>…</p> pair; instead only the completely assembled Para HTML is enclosed in <p>…</p>.
- 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 ‘<p>’ 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:
- 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