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
Report
s 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)
ordp.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)
ordp.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)
ordp.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
- datapane.client.api.report.blocks.AssetBlock
- DataBlock
- BaseElement
- abc.ABC
Class variables
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
blockNote: 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
- datapane.client.api.report.blocks.AssetBlock
- DataBlock
- BaseElement
- abc.ABC
Class variables
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
- BaseElement
- abc.ABC
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
- datapane.client.api.report.blocks.AssetBlock
- DataBlock
- BaseElement
- abc.ABC
Class variables
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. Followsis_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
- DataBlock
- BaseElement
- abc.ABC
Class variables
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 blocksTip: 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
- datapane.client.api.report.blocks.EmbeddedTextBlock
- DataBlock
- BaseElement
- abc.ABC
Subclasses
Class variables
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
- datapane.client.api.report.blocks.EmbeddedTextBlock
- DataBlock
- BaseElement
- abc.ABC
Class variables
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
- datapane.client.api.report.blocks.EmbeddedTextBlock
- DataBlock
- BaseElement
- abc.ABC
Class variables
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 thedata
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
orfile
must be providedAncestors
- datapane.client.api.report.blocks.AssetBlock
- DataBlock
- BaseElement
- abc.ABC
Class variables