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 BaseElement (id: str = None, **kwargs)

Base Block class - subclassed by all Block types

Note: The class is not used directly.

Args

id
A unique id to reference the block, used when querying blocks via XPath to aid embedding

Ancestors

  • abc.ABC

Subclasses

  • DataBlock
  • datapane.client.api.report.blocks.LayoutBlock
class Page (*arg_blocks: Union[ForwardRef('Group'), ForwardRef('Select'), ForwardRef('DataBlock'), Any], blocks: List[Union[ForwardRef('Group'), ForwardRef('Select'), ForwardRef('DataBlock'), Any]] = None, id: str = None, label: 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 Group and Select blocks which make up the Page.

Note: You can pass ordinary Blocks to a page, e.g. Plots, and Datapane will automatically wrap them in a Group.

Additionally, 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
id
A unique id for the blocks to aid querying (optional)
label
A label used when displaying the block (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]]
var id : Union[str, NoneType]

Inherited from: BaseElement.id

dummy

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

Groups act as a container that hold a list of nested Blocks object, 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
id
A unique id for the blocks to aid querying (optional)
label
A label used when displaying the block (optional)
rows
Display the contained blocks, e.g. Plots, using n rows (set to 0 to autofill)
columns
Display the contained blocks, e.g. Plots, using n columns (set to 0 to autofill)

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

Subclasses

Class variables

var blocks : List[Union[Group, Select, DataBlock]]
var id : Union[str, NoneType]

Inherited from: BaseElement.id

dummy

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

Select act as a container that hold a list of nested Blocks object, 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
id
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]]
var id : Union[str, NoneType]

Inherited from: BaseElement.id

dummy

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 Table (data: Union[pandas.core.frame.DataFrame, pandas.io.formats.style.Styler], caption: Union[str, NoneType] = None, id: 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)
id
A unique id for the block to aid querying (optional)
label
A label used when displaying the block (optional)

Ancestors

Class variables

var file : pathlib.Path
var caption : Union[str, NoneType]
var id : Union[str, NoneType]

Inherited from: DataBlock.id

dummy

class DataTable (df: pandas.core.frame.DataFrame, caption: Union[str, NoneType] = None, id: 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 requires a server and is not supported when saving locally, please publish 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)
id
A unique id for the block to aid querying (optional)
label
A label used when displaying the block (optional)

Ancestors

Class variables

var caption : Union[str, NoneType]
var id : Union[str, NoneType]

Inherited from: DataBlock.id

dummy

class DataBlock (id: 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

id
A unique id to reference the block, used when querying blocks via XPath to aid embedding

Ancestors

Subclasses

  • datapane.client.api.report.blocks.AssetBlock
  • BigNumber
  • datapane.client.api.report.blocks.EmbeddedTextBlock
class Plot (data: Any, caption: Union[str, NoneType] = None, responsive: bool = True, id: str = None, label: str = None)

Plot blocks store a Python-based plot object, including ones created by Altair, Plotly, Matplotlib, Bokeh, and Folium, 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)
id
A unique id for the block to aid querying (optional)
label
A label used when displaying the block (optional)

Ancestors

Class variables

var caption : Union[str, NoneType]
var id : Union[str, NoneType]

Inherited from: DataBlock.id

dummy

class BigNumber (heading: str, value: Union[str, int, float], change: Union[str, int, float, NoneType] = None, prev_value: Union[str, int, float, NoneType] = None, is_positive_intent: Union[bool, NoneType] = None, is_upward_change: Union[bool, NoneType] = None, id: 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)
id
A unique id for the block to aid querying (optional)
label
A label used when displaying the block (optional)

Ancestors

Class variables

var id : Union[str, NoneType]

Inherited from: DataBlock.id

dummy

class Text (text: str = None, file: Union[pathlib.Path, os.PathLike, str] = None, id: 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:te text: The markdown formatted text, use triple-quotes, ("""# My Title""") to create multi-line markdown text file: Path to a file containing markdown text id: A unique id for the block to aid querying (optional)

Ancestors

Subclasses

Class variables

var content : str
var id : Union[str, NoneType]

Inherited from: DataBlock.id

dummy

Methods

def format(self, *args: Union[ForwardRef('Group'), ForwardRef('Select'), ForwardRef('DataBlock'), Any], **kwargs: Union[ForwardRef('Group'), ForwardRef('Select'), ForwardRef('DataBlock'), 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', id: 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)
id
A unique id for the block to aid querying (optional)
label
A label used when displaying the block (optional)

Ancestors

Class variables

var content : str
var id : Union[str, NoneType]

Inherited from: DataBlock.id

dummy

class HTML (html: Union[str, dominate.dom_tag.dom_tag], id: 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
id
A unique id for the block to aid querying (optional)
label
A label used when displaying the block (optional)

Ancestors

Class variables

var content : str
var id : Union[str, NoneType]

Inherited from: DataBlock.id

dummy

class File (data: Union[Any, NoneType] = None, file: Union[pathlib.Path, os.PathLike, str, NoneType] = None, is_json: bool = False, can_download: bool = True, name: Union[str, NoneType] = None, id: str = None, label: str = None)

File blocks are used to attach a file to the report that can be displayed (if possible) and downloaded by report viewers

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

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 JPEG image)
is_json
If True, treat the data as JSON data already
can_download
Allow users to download the file when viewing the report
name
Name to be used when downloading the file
id
A unique id for the block to aid querying (optional)
label
A label used when displaying the block (optional)

Note: either data or file must be provided

Ancestors

Class variables

var id : Union[str, NoneType]

Inherited from: DataBlock.id

dummy