Base

DataBlock

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

Base class for a data block.

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	str	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	str	A longer description outlining the purpose and capability
name	str	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: str = 'generic'

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: str = 'Generic Block'

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

name

name: str = 'base'

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

classproperty

classproperty(method=None)

Decorator that creates a class-level property.

Attributes:

Name	Type	Description
method

method

method = method

__get__

__get__(instance, cls=None)

event

event(func: Callable | None = None) -> Callable

Decorator to register an event with a block.

generate_js_callback_single_float_parameter

generate_js_callback_single_float_parameter(event_name: str, parameter: str, block_id: str, throttled: bool = False) -> str

Generates a Bokeh JS callback that can be attached to a widget and used to trigger datalab block events with a single named parameter.

Parameters:

Name	Type	Description	Default
event_name	str	The name of the block method to call.	required
parameter	str	The name of the parameter to update.	required
block_id	str	The ID of the block to target for the event.	required
throttled	bool	Whether to bind to the widget's value or value_throttled.	False

generate_random_id

generate_random_id()

This function generates a random 15-length string for use as an id for a datablock. It should be sufficiently random that there is a negligible risk of ever generating the same id twice, so this is a unique id that can be used as a unique database refrence and also can be used as id in the DOM. Note: uuid.uuid4() would do this too, but I think the generated ids are too long and ugly.

The ids here are HTML id friendly, using lowercase letters and numbers. The first character is always a letter.