API

API#

class pybloqs.BaseBlock(title: str | None = None, title_level: int = 3, title_wrap: bool = False, width=None, height=None, inherit_cfg: bool = True, styles=None, classes: str | Iterable[str] = (), anchor=None, id_: str | None = None, **kwargs)[source]#

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.

property data: bytes#

Function required to support interactive IPython plotting.

Should not be used directly.

Returns:

Data to be displayed

email(title: str = '', recipients: Tuple[str, ...] = ('docs',), header_block: BaseBlock | None = None, footer_block: BaseBlock | None = None, from_address: str | None = None, cc: str | None = None, bcc: str | None = None, attachments=None, convert_to_ascii: bool = True, **kwargs) → None[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.

  • 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

  • bcc – bcc recipient

  • convert_to_ascii – bool to control convertion of html email to ascii or to leave in current format

  • kwargs – Optional arguments to pass to Block.render_html()

publish(name: str, *args, **kwargs) → str[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: bool = True, static_output: bool = False, header_block: BaseBlock | None = None, footer_block: BaseBlock | None = None, permit_compression: bool = True) → str[source]#

Returns html output of the block

Parameters:

  • pretty – Toggles pretty printing of the resulting HTML. Not applicable for non-HTML output.

  • static_output – Passed down to _write_block. Will render static version of blocks which support this.

  • header_block – If not None, header_block is inlined into a HTML body as table.

  • footer_block – If not None, footer_block is inlined into a HTML body as table.

  • permit_compression – If set, resources will be embedded as base64 gzipped files

:return html-code of the block

save(filename: str | None = None, fmt: str | None = None, pdf_zoom: float = 1, pdf_page_size: str = 'A4', pdf_auto_shrink: bool = True, orientation: str = 'Portrait', header_block: BaseBlock | None = None, header_spacing: str | float = 5, footer_block: BaseBlock | None = None, footer_spacing: str | float = 5, **kwargs) → str[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.

  • pdf_zoom – The zooming to apply when rendering the page.

  • 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 (wkhtmltopdf only)

  • orientation – Either html_converter.PORTRAIT or html_converter.LANDSCAPE

  • header_block – Block to be used as header (and repeated on every page). Only used for PDF output.

  • header_spacing – Size of header block. Numbers are in mm. HTML sizes (e.g. ‘5cm’) in chrome_headless only.

  • footer_block – Block to be used as footer (and repeated on every page). Only used for PDF output.

  • footer_spacing – Size of header block. Numbers are in mm. HTML sizes (e.g. ‘5cm’) in chrome_headless only.

Returns:

html filename

show(fmt: str = 'html', header_block: BaseBlock | None = None, footer_block: BaseBlock | None = None) → str[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.

pybloqs.Block(contents: Any = None, title: str | None = None, title_level: int = 3, title_wrap: bool = False, inherit_cfg: bool = True, **kwargs) → BaseBlock[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.

  • 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.Box(contents, **kwargs)[source]#
class pybloqs.Cfg[source]#

A dict-like mapping for inheritable block parameters.

inherit(parent: dict | Cfg) → Cfg[source]#

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

inherit_many(*args: Cfg, **kwargs: Any) → Cfg[source]#

Inherit many settings at once.

override(parent: Dict | Cfg) → Cfg[source]#

Override all settings specified in the overrides.

override_many(*args: Cfg, **kwargs: Any) → Cfg[source]#

Override many settings at once.

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

A block that can be collapsed/expanded in HTML view.

Parameters#

contentslist, tuple or set

Elements to be included in the collapsible block.

cascade_cfgbool, default=True

If True, enables parameter cascading from this block. If False, child blocks do not inherit parameters.

**kwargsdict

Optional styling arguments. The style keyword has special meaning for grouping styling parameters.

Notes#

The style keyword argument is useful when styling parameter names clash with standard block parameters.

class pybloqs.Flow(contents, cascade_cfg: bool = True, **kwargs)[source]#
class pybloqs.Grid(contents, cols: int = 1, cascade_cfg: bool = True, **kwargs)[source]#
class pybloqs.HRule(title: str | None = None, title_level: int = 3, title_wrap: bool = False, width=None, height=None, inherit_cfg: bool = True, styles=None, classes: str | Iterable[str] = (), anchor=None, id_: str | None = None, **kwargs)[source]#

Draws a horizontal divider line.

class pybloqs.HStack(contents, cascade_cfg: bool = True, **kwargs)[source]#
class pybloqs.HTMLJinjaTableBlock(df: DataFrame, formatters: List[TableFormatter] | None = None, use_default_formatters: bool = True, merge_vertical: bool = False, **kwargs)[source]#
class FormatterData(cell, row_name, column_name, df)#
cell#

Alias for field number 0

column_name#

Alias for field number 2

df#

Alias for field number 3

row_name#

Alias for field number 1

class pybloqs.ImgBlock(data: BaseBlock | bytes, mime_type: str = 'png', width: str | None = None, height: str | None = None, img_style: Dict | None = None, **kwargs)[source]#
static from_file(img_file: str | BinaryIO, **kwargs) → ImgBlock[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.Markdown(contents: str, dedent: bool = True, **kwargs)[source]#

Renders Markdown into HTML content.

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

Wraps the content in a paragraph.

class pybloqs.PlotBlock(plot, close_plot: bool = True, bbox_inches='tight', width: str | None = None, height: str | None = None, **kwargs)[source]#
class pybloqs.Pre(contents: str, dedent: bool = True, **kwargs)[source]#

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

class pybloqs.Raw(contents: str, dedent: bool = True, **kwargs)[source]#
class pybloqs.Span(contents: str, dedent: bool = True, **kwargs)[source]#

Renders a piece of text with formatting.

class pybloqs.VStack(contents, cascade_cfg: bool = True, **kwargs)[source]#
pybloqs.set_plot_format(plot_format: str | None = None, plot_dpi: int | None = None) → None[source]#

Overwrite the current plot format settings

Parameters:

  • plot_format (str) – The plot format (e.g. ‘png’)

  • plot_dpi (int) – The DPI of the plots

Contents