pybloqs package

Submodules

pybloqs.config module

pybloqs.email module

Common email related functions used by various reports.

pybloqs.email.send(message, recipients)[source]

Send an email to a list of recipients.

  • If the message is missing the From address it’s set to the current user [1].
  • If the message is missing the To field it’s set to recipients [1].
  • If add_footer is True and message is a subclass of MIMEBase the standard report email footer will be added before the email’s sent.
Parameters:
  • message – email.message.Message or subclass, eg email.mime.MIMEMultpart
  • recipients – list of email addresses
[1](1, 2) the original message is modified in these cases.
pybloqs.email.send_html_report(html_str, to, subject=None, attachments=None, From=None, Cc=None)[source]

Email html report and embed any images. Extract html title to email subject.

Returns:

MIMEMultipart object
Parameters:
  • html_str – html string to send in the email body
  • to – list of recipients
  • subject – email subject
  • attachments – a list of tuple(extension, filename)
  • footer_text – string to be used in place of the default footer text
  • From – from, sender of the message
  • Cc – cc recipient

pybloqs.html module

pybloqs.html.append_to(parent, tag, **kwargs)[source]

Append an element to the supplied parent.

Parameters:
  • parent – Parent to append to.
  • tag – Tag to create.
  • args – Tag args.
  • kwargs – Tag kwargs.
Returns:

New element.
pybloqs.html.id_generator()[source]
pybloqs.html.id_generator_sequential()[source]

Generatres unique identifiers sequentially from a known constant seed.

pybloqs.html.id_generator_uuid()[source]

Generates unique identifiers using the uuid package.

pybloqs.html.js_elem(container=None, script=None)[source]

Constructs a Javascript element and appends it to the container.

Parameters:
  • container – Container to add the element to.
  • script – Javascript code.
Returns:

New element.
pybloqs.html.parse(string)[source]

Parses the string into a beautiful soup tree.

Parameters:string – String to parse.
Returns:Soup.
pybloqs.html.render(item, pretty=True, encoding='utf8')[source]

Renders the given element into a string.

Parameters:
  • item – Item to render. Must be an element or soup instance.
  • pretty – Toggles pretty formatting of the resulting string.
Returns:

Rendered content.
pybloqs.html.root(tag_name='html', doctype=None)[source]

Creates a new soup with the given root element.

Parameters:
  • tag_name – Root element tag name.
  • doctype – Optional doctype tag to add.
Returns:

Soup.
pybloqs.html.set_id_generator(generator)[source]

Sets the global id generator function (must be a python generator function)

Parameters:generator – Generator function to use.

pybloqs.util module

class pybloqs.util.Cfg[source]

Bases: dict

Provides plumbing for inheritable block parameters.

inherit(parent)[source]

Inherit all parent settings that the current config does not define.

inherit_many(*args, **kwargs)[source]

Inherit many settings at once.

override(parent)[source]

Override all settings specified in the overrides.

override_many(*args, **kwargs)[source]

Override many settings at once.

pybloqs.util.camelcase(value)[source]

Converts ‘under_score_string’ -> ‘underScoreString’

Parameters:value – Underscore separated string
Returns:CamelCased string
pybloqs.util.cfg_to_css_string(cfg)[source]
pybloqs.util.cfg_to_prop_string(cfg, key_transform=<function <lambda>>, value_transform=<function <lambda>>, separator=';')[source]

Convert the config object to a property string. Useful for constructing CSS and javascript object init strings.

Underscores are replaced with dashes and values are converted to lower case.

pybloqs.util.dt_epoch_msecs(value)[source]

Calculate miliseconds since epoch start for python datetimes.

pybloqs.util.encode_string(string, level=9)[source]

Compresses and base64 encodes the supplied string :param string: String to encode and compress :param level: Compression level :return: Compressed and encoded string

pybloqs.util.np_dt_epoch_msec(value)[source]

Calculate miliseconds since epoch start for numpy datetimes.

pybloqs.util.str_base(num, base=36, numerals='0123456789abcdefghijklmnopqrstuvwxyz')[source]

Converts a decimal to the specified base using the provided numerals.

Parameters:
  • num – Decimal number.
  • base – Desired base.
  • numerals – Numerals to use in the rebased number.
Returns:

Number in base.
pybloqs.util.underscorecase(camelcased)[source]

Converts ‘underScoreString’ -> ‘under_score_string’

Parameters:value – CamelCased string
Returns:Underscore separated string

Module contents

pybloqs.set_plot_format(plot_format=None, plot_dpi=None)[source]
pybloqs.Block(contents=None, title=None, title_level=3, title_wrap=False, inherit_cfg=True, **kwargs)[source]

Constructs a composable layout element that will be rendered automatically by IPython Notebooks. It can also be saved in HTML, PDF, PNG or JPEG formats.

Content is handled as follows:

  • Lists, tuples and sets are written out into a grid layout, with a single column by default. Individual elements of the grid are parsed recursively.
  • DataFrames are written out as an interactive HTML table.
  • WidePanels are written out as a series of DataFrames along the Items axis. Each item in the panel will have the item name as a title, with the title level one below the current block title level.
  • Strings are written out in a raw format, preserving any HTML content in them.
  • Nested blocks are simply wrapped, unless there is more than one in which case the same logic applies as for lists, tuples and sets.
Parameters:
  • contents – Contents to put in a block.
  • title – Optional title of the block.
  • title_level – Optional title level (adjusts the size and TOC level), 1 being the biggest and 9 being the smallest.
  • title_wrap – Toggles whitespace wrapping of the title. (Default: False).
  • inherit_cfg – Optional. Set to False to ensure that the block does not inherit any parameters from parents.
  • cascade_cfg – Set to True to enable parmater cascading from this block. A value of False means that child blocks do not inherit parameters from this block.
  • kwargs – Optional styling arguments. The style keyword argument has special meaning in that it allows styling to be grouped as one argument. It is also useful in case a styling parameter name clashes with a standard block parameter.
Returns:

A block instance.
class pybloqs.BaseBlock(title=None, title_level=3, title_wrap=False, width=None, height=None, inherit_cfg=True, styles=None, classes=(), anchor=None, **kwargs)[source]

Bases: object

Base class for all blocks. Provides infrastructure for rendering the block in an IPython Notebook or saving it to disk in HTML, PDF, PNG or JPG format.

container_tag = 'div'
data

Function required to support interactive IPython plotting.

Should not be used directly.

Returns:Data to be displayed
email(title='', recipients=('docs', ), footer_text=None, header_block=None, footer_block=None, from_address=None, cc=None, attachments=None, **kwargs)[source]

Send the rendered blocks as email. Each output format chosen will be added as an attachment.

Parameters:
  • title – title of the email
  • recipients – recipient of the email
  • fmt – One or more output formats that should be included as attachments. The following formats are supported: - HTML - PDF - PNG - JPG
  • body_block – The block to use as the email body. The default behavior is to use the current block.
  • footer_text – string to be used in place of the default footer text
  • from_address – sender of the message. Defaults to user name. Can be overwritten in .pybloqs.cfg with yaml format: ‘user_email_address: a@b.com‘
  • cc – cc recipient
  • kwargs – Optional arguments to pass to Block.save()
publish(name, *args, **kwargs)[source]

Publish the block so that others can access it.

Parameters:
  • name – Name to publish under. Can be a filename or a relative path.
  • args – Arguments to pass to Block.save.
  • kwargs – Keyword arguments to pass to Block.save.
Returns:

Path to the published block file.
render_html(pretty=True, static_output=False, header_block=None, footer_block=None, pdf_page_size='A4')[source]

Returns html output of the block :param pretty: Toggles pretty printing of the resulting HTML. Not applicable for non-HTML output. :return html-code of the block

resource_deps = []
save(filename=None, fmt=None, toc=False, pdf_zoom=1, pdf_page_size='A4', pdf_auto_shrink=True, pretty=True, orientation='Portrait', header_block=None, header_spacing=5, footer_block=None, footer_spacing=5, java_script_delay=200, **kwargs)[source]

Render and save the block. Depending on whether the filename or the format is provided, the content will either be written out to a file or returned as a string.

Parameters:
  • filename – Format will be based on the file extension. The following formats are supported: - HTML - PDF - PNG - JPG
  • fmt – Specifies the format of a temporary output file. When supplied, the filename parameter must be omitted.
  • toc – Toggles the generation of Table of Contents. Note: currently supported for PDF output only.
  • pdf_zoom – The zooming to apply when rendering the page to PDF.
  • pdf_page_size – The page size to use when rendering the page to PDF.
  • pdf_auto_shrink – Toggles auto-shrinking content to fit the desired page size.
  • pretty – Toggles pretty printing of the resulting HTML. Not applicable for non-HTML output.
Returns:

html filename
show(fmt='html', header_block=None, footer_block=None)[source]

Show the block in a browser.

Parameters:fmt – The format of the saved block. Supports the same output as Block.save
Returns:Path to the block file.
to_static()[source]
class pybloqs.HRule(title=None, title_level=3, title_wrap=False, width=None, height=None, inherit_cfg=True, styles=None, classes=(), anchor=None, **kwargs)[source]

Bases: pybloqs.block.base.BaseBlock

Draws a horizontal divider line.

class pybloqs.Raw(contents, dedent=True, **kwargs)[source]

Bases: pybloqs.block.base.BaseBlock

class pybloqs.Grid(contents, cols=1, cascade_cfg=True, **kwargs)[source]

Bases: pybloqs.block.layout.CompositeBlockMixin, pybloqs.block.base.BaseBlock

class pybloqs.Flow(contents, cascade_cfg=True, **kwargs)[source]

Bases: pybloqs.block.layout.CompositeBlockMixin, pybloqs.block.base.BaseBlock

class pybloqs.HStack(contents, cascade_cfg=True, **kwargs)[source]

Bases: pybloqs.block.layout.Grid

class pybloqs.VStack(contents, cascade_cfg=True, **kwargs)[source]

Bases: pybloqs.block.layout.CompositeBlockMixin, pybloqs.block.base.BaseBlock

class pybloqs.ImgBlock(data, mime_type='png', width=None, height=None, img_style=None, **kwargs)[source]

Bases: pybloqs.block.base.BaseBlock

static from_file(img_file, **kwargs)[source]

Load an image block from a file.

Parameters:
  • img_file – File path or file-like object.
  • kwargs – Arguments to pass to the ImgBlock constructor.
Returns:

ImgBlock instance.
class pybloqs.PlotBlock(plot, close_plot=True, bbox_inches='tight', width=None, height=None, **kwargs)[source]

Bases: pybloqs.block.image.ImgBlock

class pybloqs.Box(contents, **kwargs)[source]

Bases: pybloqs.block.base.BaseBlock

class pybloqs.Paragraph(contents, **kwargs)[source]

Bases: pybloqs.block.wrap.Box

Wraps the content in a paragraph.

container_tag = 'p'
class pybloqs.Pre(contents, dedent=True, **kwargs)[source]

Bases: pybloqs.block.text.Raw

Renders the content with a fixed-width font, preserving whitespace.

container_tag = 'pre'
class pybloqs.Span(contents, dedent=True, **kwargs)[source]

Bases: pybloqs.block.text.Raw

Renders a piece of text with formatting.

container_tag = 'span'
class pybloqs.Markdown(contents, dedent=True, **kwargs)[source]

Bases: pybloqs.block.text.Raw

Renders Markdown into HTML content.

encoding = 'UTF-8'
class pybloqs.Cfg[source]

Bases: dict

Provides plumbing for inheritable block parameters.

inherit(parent)[source]

Inherit all parent settings that the current config does not define.

inherit_many(*args, **kwargs)[source]

Inherit many settings at once.

override(parent)[source]

Override all settings specified in the overrides.

override_many(*args, **kwargs)[source]

Override many settings at once.

pybloqs.interactive(verbose=True)[source]

Enables interactive usage of block layout content.