Common

Attributes:

Name	Type	Description
`EXCEL_LIKE_EXTENSIONS`	`tuple[str, ...]`	A tuple of file extensions that are considered Excel-like formats.

EXCEL_LIKE_EXTENSIONS ¶

EXCEL_LIKE_EXTENSIONS: tuple[str, ...] = ('.xls', '.xlsx', '.xlsm', '.xlsb', '.odf', '.ods', '.odt')

A tuple of file extensions that are considered Excel-like formats.

CommentBlock ¶

CommentBlock(item_id: str | None = None, collection_id: str | None = None, init_data: dict | None = None, unique_id: str | None = None)

Bases: DataBlock

Parameters:

Name	Type	Description	Default
`item_id`	`str \| None`	The item to which the block is attached, or	`None`
`collection_id`	`str \| None`	The collection to which the block is attached.	`None`
`init_data`	`dict \| None`	A dictionary of data to initialise the block with.	`None`
`unique_id`	`str \| None`	A unique id for the block, used in the DOM and database.	`None`

Attributes:

Name	Type	Description
`accepted_file_extensions`	`tuple[str, ...] \| None`	A list of file extensions that the block will attempt to read.
`block_db_model`
`block_id`
`blocktype`		A short (unique) string key specifying the type of block.
`data`
`defaults`	`dict[str, Any]`	Any default values that should be set if they are not
`description`		A longer description outlining the purpose and capability
`name`		The human-readable block name specifying which technique
`plot_functions`	`Sequence[Callable[[], None]] \| None`	A list of methods that will generate plots for this block.
`version`	`str`	The implementation version of this particular block.

accepted_file_extensions ¶

accepted_file_extensions: tuple[str, ...] | None

A list of file extensions that the block will attempt to read.

block_db_model ¶

block_db_model = DataBlockResponse

block_id ¶

block_id = unique_id or generate_random_id()

blocktype ¶

blocktype = 'comment'

A short (unique) string key specifying the type of block.

data ¶

data = {'item_id': item_id, 'collection_id': collection_id, 'blocktype': blocktype, 'block_id': block_id, None: defaults}

defaults ¶

defaults: dict[str, Any] = {}

Any default values that should be set if they are not supplied during block init.

description ¶

description = 'Add a rich text comment to the document.'

A longer description outlining the purpose and capability of the block.

name ¶

name = 'Comment'

The human-readable block name specifying which technique or file format it pertains to.

plot_functions ¶

plot_functions: Sequence[Callable[[], None]] | None = None

A list of methods that will generate plots for this block.

version ¶

version: str = __version__

The implementation version of this particular block.

event_names ¶

event_names() -> set[str]

Return a list of event names supported by this block.

events_by_name ¶

events_by_name() -> dict[str, Callable]

Returns a dict of registered events for this block.

from_web ¶

from_web(data: dict)

Initialise the block state from data passed via web request with a given item, collection and block ID.

Parameters:

Name	Type	Description	Default
`data`	`dict`	The block data to initialiaze the block with.	required

null_event ¶

null_event(**kwargs)

A null debug event that does nothing but logs its kwargs and overwrites the data dict with the args.

process_events ¶

process_events(events: list[dict] | dict)

Handle any supported events passed to the block.

to_db ¶

to_db() -> dict

returns a dictionary with the data for this block, ready to be input into mongodb

to_web ¶

to_web() -> dict[str, Any]

Returns a JSON serializable dictionary to render the data block on the web.

update_from_web ¶

update_from_web(data: dict)

Update the block with validated data received from a web request. Will strip any fields that are "computed" or otherwise not controllable by the user.

Parameters:

Name	Type	Description	Default
`data`	`dict`	A dictionary of data to update the block with.	required

MediaBlock ¶

MediaBlock(item_id: str | None = None, collection_id: str | None = None, init_data: dict | None = None, unique_id: str | None = None)

Bases: DataBlock

Parameters:

Name	Type	Description	Default
`item_id`	`str \| None`	The item to which the block is attached, or	`None`
`collection_id`	`str \| None`	The collection to which the block is attached.	`None`
`init_data`	`dict \| None`	A dictionary of data to initialise the block with.	`None`
`unique_id`	`str \| None`	A unique id for the block, used in the DOM and database.	`None`

Attributes:

Name	Type	Description
`accepted_file_extensions`		A list of file extensions that the block will attempt to read.
`block_db_model`
`block_id`
`blocktype`		A short (unique) string key specifying the type of block.
`data`
`defaults`	`dict[str, Any]`	Any default values that should be set if they are not
`description`		A longer description outlining the purpose and capability
`name`		The human-readable block name specifying which technique
`plot_functions`		A list of methods that will generate plots for this block.
`version`	`str`	The implementation version of this particular block.

accepted_file_extensions ¶

accepted_file_extensions = ('.png', '.jpeg', '.jpg', '.tif', '.tiff', '.mp4', '.mov', '.webm', '.pdf', '.svg')

A list of file extensions that the block will attempt to read.

block_db_model ¶

block_db_model = DataBlockResponse

block_id ¶

block_id = unique_id or generate_random_id()

blocktype ¶

blocktype = 'media'

A short (unique) string key specifying the type of block.

data ¶

data = {'item_id': item_id, 'collection_id': collection_id, 'blocktype': blocktype, 'block_id': block_id, None: defaults}

defaults ¶

defaults: dict[str, Any] = {}

Any default values that should be set if they are not supplied during block init.

description ¶

description = 'Display an image or a video of a supported format.'

A longer description outlining the purpose and capability of the block.

name ¶

name = 'Media'

The human-readable block name specifying which technique or file format it pertains to.

plot_functions ¶

plot_functions

A list of methods that will generate plots for this block.

version ¶

version: str = __version__

The implementation version of this particular block.

encode_tiff ¶

encode_tiff()

event_names ¶

event_names() -> set[str]

Return a list of event names supported by this block.

events_by_name ¶

events_by_name() -> dict[str, Callable]

Returns a dict of registered events for this block.

from_web ¶

from_web(data: dict)

Initialise the block state from data passed via web request with a given item, collection and block ID.

Parameters:

Name	Type	Description	Default
`data`	`dict`	The block data to initialiaze the block with.	required

null_event ¶

null_event(**kwargs)

A null debug event that does nothing but logs its kwargs and overwrites the data dict with the args.

process_events ¶

process_events(events: list[dict] | dict)

Handle any supported events passed to the block.

to_db ¶

to_db() -> dict

returns a dictionary with the data for this block, ready to be input into mongodb

to_web ¶

to_web() -> dict[str, Any]

Returns a JSON serializable dictionary to render the data block on the web.

update_from_web ¶

update_from_web(data: dict)

Update the block with validated data received from a web request. Will strip any fields that are "computed" or otherwise not controllable by the user.

Parameters:

Name	Type	Description	Default
`data`	`dict`	A dictionary of data to update the block with.	required

NotSupportedBlock ¶

NotSupportedBlock(item_id: str | None = None, collection_id: str | None = None, init_data: dict | None = None, unique_id: str | None = None)

Bases: DataBlock

Parameters:

Name	Type	Description	Default
`item_id`	`str \| None`	The item to which the block is attached, or	`None`
`collection_id`	`str \| None`	The collection to which the block is attached.	`None`
`init_data`	`dict \| None`	A dictionary of data to initialise the block with.	`None`
`unique_id`	`str \| None`	A unique id for the block, used in the DOM and database.	`None`

Attributes:

Name	Type	Description
`accepted_file_extensions`	`tuple[str, ...] \| None`	A list of file extensions that the block will attempt to read.
`block_db_model`
`block_id`
`blocktype`		A short (unique) string key specifying the type of block.
`data`
`defaults`	`dict[str, Any]`	Any default values that should be set if they are not
`description`		A longer description outlining the purpose and capability
`name`		The human-readable block name specifying which technique
`plot_functions`	`Sequence[Callable[[], None]] \| None`	A list of methods that will generate plots for this block.
`version`	`str`	The implementation version of this particular block.

accepted_file_extensions ¶

accepted_file_extensions: tuple[str, ...] | None

A list of file extensions that the block will attempt to read.

block_db_model ¶

block_db_model = DataBlockResponse

block_id ¶

block_id = unique_id or generate_random_id()

blocktype ¶

blocktype = 'notsupported'

A short (unique) string key specifying the type of block.

data ¶

data = {'item_id': item_id, 'collection_id': collection_id, 'blocktype': blocktype, 'block_id': block_id, None: defaults}

defaults ¶

defaults: dict[str, Any] = {}

Any default values that should be set if they are not supplied during block init.

description ¶

description = 'A placeholder block type when the requested block is not supported by the current version of the server.'

A longer description outlining the purpose and capability of the block.

name ¶

name = 'Not Supported'

The human-readable block name specifying which technique or file format it pertains to.

plot_functions ¶

plot_functions: Sequence[Callable[[], None]] | None = None

A list of methods that will generate plots for this block.

version ¶

version: str = __version__

The implementation version of this particular block.

event_names ¶

event_names() -> set[str]

Return a list of event names supported by this block.

events_by_name ¶

events_by_name() -> dict[str, Callable]

Returns a dict of registered events for this block.

from_web ¶

from_web(data: dict)

Initialise the block state from data passed via web request with a given item, collection and block ID.

Parameters:

Name	Type	Description	Default
`data`	`dict`	The block data to initialiaze the block with.	required

null_event ¶

null_event(**kwargs)

A null debug event that does nothing but logs its kwargs and overwrites the data dict with the args.

process_events ¶

process_events(events: list[dict] | dict)

Handle any supported events passed to the block.

to_db ¶

to_db() -> dict

returns a dictionary with the data for this block, ready to be input into mongodb

to_web ¶

to_web() -> dict[str, Any]

Returns a JSON serializable dictionary to render the data block on the web.

update_from_web ¶

update_from_web(data: dict)

Update the block with validated data received from a web request. Will strip any fields that are "computed" or otherwise not controllable by the user.

Parameters:

Name	Type	Description	Default
`data`	`dict`	A dictionary of data to update the block with.	required

TabularDataBlock ¶

TabularDataBlock(item_id: str | None = None, collection_id: str | None = None, init_data: dict | None = None, unique_id: str | None = None)

Bases: DataBlock

This block simply tries to read the given file with pandas, and expose an interface to plot its columns as scatter points.

Parameters:

Name	Type	Description	Default
`item_id`	`str \| None`	The item to which the block is attached, or	`None`
`collection_id`	`str \| None`	The collection to which the block is attached.	`None`
`init_data`	`dict \| None`	A dictionary of data to initialise the block with.	`None`
`unique_id`	`str \| None`	A unique id for the block, used in the DOM and database.	`None`

Attributes:

Name	Type	Description
`accepted_file_extensions`		A list of file extensions that the block will attempt to read.
`block_db_model`
`block_id`
`blocktype`		A short (unique) string key specifying the type of block.
`data`
`defaults`	`dict[str, Any]`	Any default values that should be set if they are not
`description`		A longer description outlining the purpose and capability
`name`		The human-readable block name specifying which technique
`plot_functions`		A list of methods that will generate plots for this block.
`version`	`str`	The implementation version of this particular block.

accepted_file_extensions ¶

accepted_file_extensions = ('.csv', '.txt', '.tsv', '.dat', *EXCEL_LIKE_EXTENSIONS)

A list of file extensions that the block will attempt to read.

block_db_model ¶

block_db_model = DataBlockResponse

block_id ¶

block_id = unique_id or generate_random_id()

blocktype ¶

blocktype = 'tabular'

A short (unique) string key specifying the type of block.

data ¶

data = {'item_id': item_id, 'collection_id': collection_id, 'blocktype': blocktype, 'block_id': block_id, None: defaults}

defaults ¶

defaults: dict[str, Any] = {}

Any default values that should be set if they are not supplied during block init.

description ¶

description = 'This block will load tabular data from common plain text files and Excel-like spreadsheets and allow you to create simple scatter plots of the columns within.'

A longer description outlining the purpose and capability of the block.

name ¶

name = 'Tabular Data Block'

The human-readable block name specifying which technique or file format it pertains to.

plot_functions ¶

plot_functions

A list of methods that will generate plots for this block.

version ¶

version: str = __version__

The implementation version of this particular block.

event_names ¶

event_names() -> set[str]

Return a list of event names supported by this block.

events_by_name ¶

events_by_name() -> dict[str, Callable]

Returns a dict of registered events for this block.

from_web ¶

from_web(data: dict)

Initialise the block state from data passed via web request with a given item, collection and block ID.

Parameters:

Name	Type	Description	Default
`data`	`dict`	The block data to initialiaze the block with.	required

load ¶

load(location: Path | str) -> DataFrame

Throw several pandas readers at the target file.

If an excel-like format, try to read it with pandas.read_excel(). Then, try well-described formats such as JSON, Parquet and Feather. Otherwise, use decreasingly strict csv parsers until successful.

Returns:

Type	Description
`DataFrame`	pd.DataFrame: The loaded dataframe.

null_event ¶

null_event(**kwargs)

A null debug event that does nothing but logs its kwargs and overwrites the data dict with the args.

plot_df ¶

plot_df()

process_events ¶

process_events(events: list[dict] | dict)

Handle any supported events passed to the block.

to_db ¶

to_db() -> dict

returns a dictionary with the data for this block, ready to be input into mongodb

to_web ¶

to_web() -> dict[str, Any]

Returns a JSON serializable dictionary to render the data block on the web.

update_from_web ¶

update_from_web(data: dict)

Update the block with validated data received from a web request. Will strip any fields that are "computed" or otherwise not controllable by the user.

Parameters:

Name	Type	Description	Default
`data`	`dict`	A dictionary of data to update the block with.	required