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 (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

  • DataBlock
  • datapane.client.api.report.blocks.LayoutBlock

Class variables

var name : Optional[str]
class Page (*arg_blocks: Union[ForwardRef('Group'), ForwardRef('Select'), ForwardRef('DataBlock'), Any], blocks: List[Union[ForwardRef('Group'), ForwardRef('Select'), ForwardRef('DataBlock'), Any]] = None, title: 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
Blocks to add to Page
blocks
Allows providing the report blocks as a single list
title
The page title (optional)
label
A label used when displaying the page (optional, deprecated)

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]]
class Group (*arg_blocks: Union[ForwardRef('Group'), ForwardRef('Select'), ForwardRef('DataBlock'), Any], blocks: List[Union[ForwardRef('Group'), ForwardRef('Select'), ForwardRef('DataBlock'), Any]] = None, name: 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
name
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]]
class Select (*arg_blocks: Union[ForwardRef('Group'), ForwardRef('Select'), ForwardRef('DataBlock'), Any], blocks: List[Union[ForwardRef('Group'), ForwardRef('Select'), ForwardRef('DataBlock'), Any]] = None, type: Optional[SelectType] = None, name: 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
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]]
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: 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.

Note: Please use Table component when saving files locally over the DataTable component which has more features but requires publishing your report

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 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 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)
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 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 Plot (data: Any, caption: Optional[str] = None, responsive: bool = True, name: 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)
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 caption : Optional[str]
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: 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: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 name: A unique name for the block to reference when adding text or embedding (optional)

Ancestors

Subclasses

Class variables

var content : str

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', 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 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 File (data: Optional[Any] = None, file: Union[pathlib.Path, os.PathLike, str, NoneType] = None, is_json: bool = False, filename: Optional[str] = None, name: 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
filename
Name to be used when downloading the file
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 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