Module datapane.client.api.report.blocks

Datapane Blocks API

Describes the collection of Block objects that can be combined together to make a Report.

Classes

class Attachment (data: Optional[Any] = None, file: Union[pathlib.Path, os.PathLike, str, ForwardRef(None)] = None, filename: Optional[str] = None, caption: Optional[str] = None, name: str = None, label: str = None)

Attachment blocks are used to attach a file to the report that can be downloaded by report viewers

Any type of file may be attached, for instance, images (png / jpg), PDFs, JSON data, Excel files, etc.

Tip: To attach streamable / viewable video, audio or images, use the dp.Media block instead

Args

data
A python object to attach to the report (e.g. a dictionary)
file
Path to a file to attach to the report (e.g. a csv file)
filename
Name to be used when downloading the file (optional)
caption
A caption to display below the file (optional)
name
A unique name for the block to reference when adding text or embedding (optional)
label
A label used when displaying the block (optional)

Note: either data or file must be provided

Ancestors

Class variables

var file_attribs : Dict[str, str]
class BaseElement (name: str = None, **kwargs)

Base Block class - subclassed by all Block types

Note: The class is not used directly.

Args

name
A unique name to reference the block, used when referencing blocks via the report editor and when embedding

Ancestors

  • abc.ABC

Subclasses

Class variables

var name : Optional[str]
class Page (*arg_blocks: Union[ForwardRef('Group'), ForwardRef('Select'), ForwardRef('DataBlock'), ForwardRef('Empty'), Any], blocks: List[Union[ForwardRef('Group'), ForwardRef('Select'), ForwardRef('DataBlock'), ForwardRef('Empty'), Any]] = None, title: str = None, name: str = None)

All Reports consist of a list of Pages. A Page itself is a Block, but is only allowed at the top-level and cannot be nested.

Page objects take a list of blocks which make up the Page.

Note: You can pass ordinary Blocks to a page, e.g. Plots or DataTables.

Additionally, if a Python object is passed, e.g. a Dataframe, Datapane will attempt to convert it automatically.

Args

*arg_blocks
Blocks to add to Page
blocks
Allows providing the report blocks as a single list
title
The page title (optional)
name
A unique id for the Page to aid querying (optional)

Tip: Page can be passed using either arg parameters or the blocks kwarg, e.g.

dp.Page(group, select) or dp.Group(blocks=[group, select])

Ancestors

  • datapane.client.api.report.blocks.LayoutBlock
  • BaseElement
  • abc.ABC

Class variables

var blocks : List[Union[Group, Select, DataBlock, Empty]]
class Group (*arg_blocks: Union[ForwardRef('Group'), ForwardRef('Select'), ForwardRef('DataBlock'), ForwardRef('Empty'), Any], blocks: List[Union[ForwardRef('Group'), ForwardRef('Select'), ForwardRef('DataBlock'), ForwardRef('Empty'), Any]] = None, name: str = None, label: str = None, columns: int = 1)

Groups act as a container that holds a list of nested Blocks objects, such as Tables, Plots, etc.. - they may even hold Group themselves recursively.

Group are used to provide a grouping for blocks can have layout options applied to them

Note: Group expects a list of Blocks, e.g. a Plot or Table, but also including Select or Groups themselves,

but if a Python object is passed, e.g. a Dataframe, Datapane will attempt to convert it automatically.

Args

*arg_blocks
Group to add to report
blocks
Allows providing the report blocks as a single list
name
A unique id for the blocks to aid querying (optional)
label
A label used when displaying the block (optional)
columns
Display the contained blocks, e.g. Plots, using n columns (default = 1), setting to 0 auto-wraps the columns

Tip: Group can be passed using either arg parameters or the blocks kwarg, e.g.

dp.Group(plot, table, columns=2) or dp.Group(blocks=[plot, table], columns=2)

Ancestors

  • datapane.client.api.report.blocks.LayoutBlock
  • BaseElement
  • abc.ABC

Class variables

var blocks : List[Union[Group, Select, DataBlock, Empty]]
class Select (*arg_blocks: Union[ForwardRef('Group'), ForwardRef('Select'), ForwardRef('DataBlock'), ForwardRef('Empty'), Any], blocks: List[Union[ForwardRef('Group'), ForwardRef('Select'), ForwardRef('DataBlock'), ForwardRef('Empty'), Any]] = None, type: Optional[SelectType] = None, name: str = None, label: str = None)

Selects act as a container that holds a list of nested Blocks objects, such as Tables, Plots, etc.. - but only one may be visible, or "selected", at once.

The user can choose which nested object to view dynamically using either tabs or a dropdown.

Note: Select expects a list of Blocks, e.g. a Plot or Table, but also including Select or Groups themselves,

but if a Python object is passed, e.g. a Dataframe, Datapane will attempt to convert it automatically.

Args

*arg_blocks
Page to add to report
blocks
Allows providing the report blocks as a single list
type
An instance of SelectType that indicates if the select should use tabs or a dropdown
name
A unique id for the blocks to aid querying (optional)
label
A label used when displaying the block (optional)

Tip: Select can be passed using either arg parameters or the blocks kwarg, e.g.

dp.Select(table, plot, type=dp.SelectType.TABS) or dp.Group(blocks=[table, plot])

Ancestors

  • datapane.client.api.report.blocks.LayoutBlock
  • BaseElement
  • abc.ABC

Class variables

var blocks : List[Union[Group, Select, DataBlock, Empty]]
class Toggle (*arg_blocks: Union[ForwardRef('Group'), ForwardRef('Select'), ForwardRef('DataBlock'), ForwardRef('Empty'), Any], blocks: List[Union[ForwardRef('Group'), ForwardRef('Select'), ForwardRef('DataBlock'), ForwardRef('Empty'), Any]] = None, name: str = None, label: str = None)

Toggles act as a container that holds a list of nested Block objects, whose visbility can be toggled on or off by the report viewer

Args

*arg_blocks
Group to add to report
blocks
Allows providing the report blocks as a single list
name
A unique id for the blocks to aid querying (optional)
label
A label used when displaying the block (optional)

Ancestors

  • datapane.client.api.report.blocks.LayoutBlock
  • BaseElement
  • abc.ABC

Class variables

var blocks : List[Union[Group, Select, DataBlock, Empty]]
class SelectType (value, names=None, *, module=None, qualname=None, type=None, start=1)

An enumeration.

Ancestors

  • enum.Enum

Class variables

var DROPDOWN
var TABS
class Empty (name: str)

An empty block that can be patched later

Args

name
A unique name for the block to reference when updating the report

Args

name
A unique name to reference the block, used when referencing blocks via the report editor and when embedding

Ancestors

Class variables

var name : Optional[str]
class Table (data: Union[pandas.core.frame.DataFrame, pandas.io.formats.style.Styler], caption: Optional[str] = None, name: str = None, label: str = None)

Table blocks store the contents of a dataframe as a HTML table whose style can be customised using pandas' Styler API.

Args

data
The pandas Styler instance or dataframe to generate the table from
caption
A caption to display below the table (optional)
name
A unique name for the block to reference when adding text or embedding (optional)
label
A label used when displaying the block (optional)

Ancestors

Class variables

var file : pathlib.Path
var file_attribs : Dict[str, str]
var caption : Optional[str]
class DataTable (df: pandas.core.frame.DataFrame, caption: Optional[str] = None, name: str = None, label: str = None)

DataTable blocks store a dataframe that can be viewed, sorted, filtered by users viewing your report, similar to a spreadsheet, and can be downloaded by them as a CSV or Excel file.

Tip: For smaller dataframes where you don't require sorting and filtering, also consider using the Table block

Note: The DataTable component has advanced analysis features that requires a server and is not supported when saving locally, please upload such reports to a Datapane Server or use dp.Table

Args

df
The pandas dataframe to attach to the report
caption
A caption to display below the plot (optional)
name
A unique name for the block to reference when adding text or embedding (optional)
label
A label used when displaying the block (optional)

Ancestors

Class variables

var file_attribs : Dict[str, str]
var caption : Optional[str]
class DataBlock (name: str = None, **kwargs)

Abstract block that represents a leaf-node in the tree, e.g. a Plot or Table

Note: This class is not used directly.

Args

name
A unique name to reference the block, used when referencing blocks via the report editor and when embedding

Ancestors

Subclasses

  • datapane.client.api.report.blocks.AssetBlock
  • BigNumber
  • datapane.client.api.report.blocks.EmbeddedTextBlock

Class variables

var name : Optional[str]
class Divider

Divider blocks add a horizontal line to your report, normally used to break up report contents

Args

name
A unique name to reference the block, used when referencing blocks via the report editor and when embedding

Ancestors

Class variables

var content : str
class Plot (data: Any, caption: Optional[str] = None, responsive: bool = True, scale: float = 1.0, name: str = None, label: str = None)

Plot blocks store a Python-based plot object, including ones created by Altair, Plotly, Matplotlib, Bokeh, Folium, and PlotAPI, for interactive display in your report when viewed in the browser.

Args

data
The plot object to attach
caption
A caption to display below the plot (optional)
responsive
Whether the plot should automatically be resized to fit, set to False if your plot looks odd (optional, default: True)
scale
Set the scaling factor for the plt (optional, default = 1.0)
name
A unique name for the block to reference when adding text or embedding (optional)
label
A label used when displaying the block (optional)

Ancestors

Class variables

var file_attribs : Dict[str, str]
var caption : Optional[str]
class BigNumber (heading: str, value: Union[str, int, float], change: Union[str, int, float, ForwardRef(None)] = None, prev_value: Union[str, int, float, ForwardRef(None)] = None, is_positive_intent: Optional[bool] = None, is_upward_change: Optional[bool] = None, name: str = None, label: str = None)

BigNumber blocks display a numerical value with a heading, alongside optional contextual information about the previous value.

Args

heading
A title that gives context to the displayed number
value
The value of the number
prev_value
The previous value to display as comparison (optional)
change
The amount changed between the value and previous value (optional)
is_positive_intent
Displays the change on a green background if True, and red otherwise. Follows is_upward_change if not set (optional)
is_upward_change
Whether the change is upward or downward (required when change is set)
name
A unique name for the block to reference when adding text or embedding (optional)
label
A label used when displaying the block (optional)

Ancestors

Class variables

var name : Optional[str]
class Text (text: str = None, file: Union[pathlib.Path, os.PathLike, str] = None, name: str = None, label: str = None)

Markdown objects store Markdown text that can be displayed as formatted text when viewing your report.

Note: This object is also available as dp.Text, and any strings provided directly to the Report/Group object are converted automatically to Markdown blocks

Tip: You can also insert a dataframe in a Markdown block as a table by using df.to_markdown(), or use dp.Table or dp.DataTable for dedicated dataframe tables.

Args

text
The markdown formatted text, use triple-quotes, ("""# My Title""") to create multi-line markdown text
file
Path to a file containing markdown text
name
A unique name for the block to reference when adding text or embedding (optional)
label
A label used when displaying the block (optional)

Note: File encodings are auto-detected, if this fails please read the file manually with an explicit encoding and use the text parameter on dp.Attachment

Ancestors

Class variables

var content : str

Methods

def format(self, *args: Union[ForwardRef('Group'), ForwardRef('Select'), ForwardRef('DataBlock'), ForwardRef('Empty'), Any], **kwargs: Union[ForwardRef('Group'), ForwardRef('Select'), ForwardRef('DataBlock'), ForwardRef('Empty'), Any]) ‑> Group

Format the markdown text template, using the supplied context to insert blocks into {{}} markers in the template.

{} markers can be empty, hence positional, or have a name, e.g. {{plot}}, which is used to lookup the value from the keyword context.

Args

*args
positional template context arguments
**kwargs
keyword template context arguments

Tip: Either Python objects, e.g. dataframes, and plots, or Datapane blocks as context

Returns

A datapane Group object containing the list of text and embedded objects

class Code (code: str, language: str = 'python', caption: str = None, name: str = None, label: str = None)

Code objects store source code that can be displayed as formatted text when viewing your report.

Args

code
The source code
language
The language of the code, most common languages are supported (optional - defaults to Python)
caption
A caption to display below the Code (optional)
name
A unique name for the block to reference when adding text or embedding (optional)
label
A label used when displaying the block (optional)

Ancestors

Class variables

var content : str
class Embed (url: str, width: int = 960, height: int = 540, name: str = None, label: str = None)

Embed blocks allow HTML from OEmbed providers (e.g. Youtube, Twitter, Vimeo) to be embedded in a report.

Args

url
The URL of the resource to be embedded
width
The width of the embedded object (optional)
height
The height of the embedded object (optional)
name
A unique name for the block to reference when adding text or embedding (optional)
label
A label used when displaying the block (optional)

Ancestors

Class variables

var content : str
class HTML (html: Union[str, dominate.dom_tag.dom_tag], name: str = None, label: str = None)

HTML blocks can be used to embed an arbitrary HTML fragment in a report.

Args

html
The HTML fragment to embed - can be a string or a dominate tag
name
A unique name for the block to reference when adding text or embedding (optional)
label
A label used when displaying the block (optional)

Ancestors

Class variables

var content : str
class Media (file: Union[pathlib.Path, os.PathLike, str], name: str = None, label: str = None, caption: Optional[str] = None)

Media blocks are used to attach a file to the report that can be viewed or streamed by report viewers

Note: Supported video, audio and image formats depends on the browser used to view the report. MP3, MP4, and all common image formats are generally supported by modern browsers

Args

file
Path to a file to attach to the report (e.g. a JPEG image)
name
A unique name for the block to reference when adding text or embedding (optional)
caption
A caption to display below the file (optional)
label
A label used when displaying the block (optional)

Ancestors

Class variables

var file_attribs : Dict[str, str]
class Formula (formula: str, caption: str = None, name: str = None, label: str = None)

Formula blocks can be used to embed LaTeX in a report.

Args

formula
The formula to embed, using LaTeX format (use raw strings)
caption
A caption to display below the Formula (optional)
name
A unique name for the block to reference when adding text or embedding (optional)
label
A label used when displaying the block (optional)

Note: LaTeX commonly uses special characters, hence prefix your formulas with r to make them

raw strings, e.g. r"\frac{1}{\sqrt{x^2 + 1}}"

Ancestors

Class variables

var content : str