Chalk'it APIs¶

Chalk'it offers a set of APIs through chalkit that serve several primary purposes:

Scheduler APIs: Facilitate the scheduling process by enabling the modification of dataNode variables and launching the scheduler.
Dashboard APIs: Support the developpement of multi-dashboard applications and the display of widgets.
Datanode IOs

JavaScript¶

Scheduler features¶

The main feature allows the setting of dataNode variables in a script, replicating the behavior of a user interacting with a basic input/control widget.

The assessment of these functions is handled at the end of the current scheduling instance.

setVariable¶

chalkit.setVariable(dataNodeName, dataNodeValue);

This API sets the value dataNodeValue to the dataNode identified by dataNode["dataNodeName"].

dataNodeName: The name of the dataNode, must be a string.
dataNodeValue: The value to be assigned to the dataNode, which can be any JavaScript primitive type (number, string, boolean), array or JSON.

For example, if you have a dataNode info_person that contains:

{
  "name": "John Doe",
  "age": "30"
}

To modify it by another JSON value, you can use the following code:

chalkit.setVariable("info_person", {"name": "Jane Doe","age": "25"});

setVariableProperty¶

chalkit.setVariableProperty(dataNodeName, propertyPath, dataNodeValue);

This API allows to modify a specific property within a dataNode (not the entire dataNode). It assigns the value dataNodeValue to the specified property path: dataNode["dataNodeName"].propertyPath.

dataNodeName: The name of the dataNode, must be a string.
propertyPath: The path of the dataNode property to be modified, supporting JavaScript primitive types (number, string, boolean), array or JSON.
dataNodeValue: The value to be set to the dataNode property, can be of any JavaScript primitive type (number, string, boolean), array or JSON.

For example, if you have a dataNode info_address that contains:

{
  "name": "personal address",
  "address": {
    "city": "New York",
    "details":{
      "street": "123 Main St",
      "zipCode": "10001",
      "country": "USA"
    }
  }
}

To update the value of the street property in the nested structure within info_address, you can use the following code:

chalkit.setVariableProperty("info_person", ["address","details","street"], "West 23rd Street");

setVariables¶

chalkit.setVariables(dataNodeNames, dataNodeValues);

This API sets each value dataNodeValues[i] to dataNode["dataNodeNames[i]"], where i:0 .. length-1 of dataNodeNames.

dataNodeNames: An array containing the names of dataNodes, each as a string.
dataNodeValues: An array containing the corresponding values for the dataNodes, can be of any JavaScript primitive type (number, string, boolean), array or JSON. This array must match the size of dataNodeNames.

For example, to modify at the same time the previous dataNode info_person and another dataNode info_gender that contains:

{"gender": "male"}

you can use the following code:

chalkit.setVariables(["info_person","info_gender"], [{"name": "Jane Doe","age": "25"},{"gender": "female"}]);

executeDataNode¶

chalkit.executeDataNode(dataNodeName);

This API allows to launch the schedule with the source node identified as dataNodeName (the name of the dataNode that must be a string).

This functionality can be useful for a dataNode with explicit trigger flag set to true. Its execution can be explicitly triggered by this API, in addition to being triggered by an associated push button widget or by clicking on the dataNode update icon present in the dataNodes list.

executeDataNodes¶

chalkit.executeDataNodes(dataNodeNames);

This API is similar to executeDataNode, except it launches the schedule with multiple source nodes defined in the dataNodeNames array, where each name is represented as a string.

Dashboard features¶

The main feature allow navigation between Chalk'it pages with parameter transfer. When landing at the target page, specified dataNodes of type Variable can have their initial values modified, as described below.

goToPage¶

In constrained dashboard mode, the method:

chalkit.goToPage(pageNumber)

allows to show only the targed page. It is the main method for building multi-page app with custom navigation control.

viewPage¶

chalkit.viewPage(pageUrl, inputVals, bNewTab)

Navigates to pageUrl, setting the values of the specified dataNodes in inputVals.

pageUrl: target page URL
inputVals: an array of structures of type

{"dsName": "dataNodeName", "dsVal" : "dataNodeValue"}

dsName should be of type string. dsVal can be of any JavaScript primitive type (number, string, boolean), array or JSON.

bNewTab: open in new tab when true.

viewProject¶

Similar to view page, but applies for projects.

chalkit.viewProject(projectUrl, inputVals, bNewTab)

hideWidget¶

chalkit.hideWidget(widgetName)

Hides the display of the widget.

widgetName: the name of the widget, which can be obtained by hovering over the widget target, in the edit mode. The widget is visible by default.

showWidget¶

chalkit.showWidget(widgetName)

Makes the display of the widget visible.

disableWidget¶

chalkit.disableWidget(widgetName)

Disables the access of the widget. The widget is enabled by default.

enableWidget¶

chalkit.enableWidget(widgetName)

Enables the access of the widget (interactive).

Python¶

The Python API deals with input and outputs for Python scripts and also offers a port of the JavaScript API to interact with the scheduler and the dashboard.

Input/ouputs helpers¶

An instance of ChalkitApi is provided to user scripts as chalkit. It can be used by scripts to interact with Chalk'it.

Aside from utility fonctions, it provides a set of methods to build the script's output. The output method can be used as an alternative to a return statement. If called multiple times the results will be combined as a JSON array or object.

As Chalk'it can only handle JSON data, any returned python object will be converted according to a set of heuristics. Lists, dicts, string and numbers will be directly mapped to their JSON equivalent; Plots from known libraries will be converted to images (preferably SVG); etc. As a last resort, the object will be pickled and sent as binary data. If this fails, an error is raised.

The as_* methods can be used to force the results to use a specific conversion:

dataframe = compute_my_data()
return [chalkit.as_json(dataframe), chalkit.as_python(dataframe)]

The output_* methods a juste conveniences to return a converted value. chalkit.output_json(dataframe) is the same as chalkit.output(chalkit.as_json(dataframe)).

`as_data(value, mime_type=None, name=None)` `staticmethod` ¶

This method instructs Chalk'it to output the result as binary data using its JSON convention.

Object of known types, like numpy arrays, will be saved as binary data. This behavior is very discretionary.

The most obvious use case is returning raw data from bytes or a BytesIO using Chalk'it conventions, with the possibility to attach a MIME type.

The resulting JSON looks like:

{
  "content": "ZHJncnNk",
  "isBinary": true,
  "type": "application/octet-stream",
  "name": "my_file.bin"
}

Only the first two fields are guarantied / necessary. The type is a MIME type and help datanodes and widgets handle the data. The name is often an original filename and may be used when downloading the content as a file.

Parameters:

Name	Type	Description	Default
`value`	`Any`	a return value for the script	required
`mime_type`	`Optional[str]`	A MIME type to be added to the resulting JSON object.	`None`
`name`	`Optional[str]`	a name (usually a file name) to be added to the resulting JSON object.	`None`

Returns:

Type	Description
`OutputAdapter`	`value` either wrapped or converted. The returned object is not intended to be used by the user's script but returned as it is.

`as_image(value)` `staticmethod` ¶

This method instructs Chalk'it to convert the result (like a plot figure) into an image.

Parameters:

Name	Type	Description	Default
`value`	`Any`	a return value for the script	required

Returns:

Type	Description
`OutputAdapter`	`value` either wrapped or converted. The returned object is not intended to be used by the user's script but returned as it is.

`as_json(value)` `staticmethod` ¶

This method instructs Chalk'it to convert a result to a JSON representation.

!!! note Technically, all data is ultimately converted to JSON. But using a plotly plot as an example, this method will output the plot's JSON configuration, whereas as_image would return an image of the plot encoded into JSON using base64.

Parameters:

Name	Type	Description	Default
`value`	`Any`	a return value for the script	required

Returns:

Type	Description
`OutputAdapter`	`value` either wrapped or converted. The returned object is not intended to be used by the user's script but returned as it is.

`as_python(value)` `staticmethod` ¶

This method instructs Chalk'it to pickle a result, the main use case being moving Python objects from a Python datanode to another.

The JSON encoding used will be recognized if the value is used in another Python datanode and the object will be automatically un-pickled, meaning dataNodes["previous-python-node"] will directly evaluate to the un-pickled object.

Parameters:

Name	Type	Description	Default
`value`	`Any`	a return value for the script	required

Returns:

Type	Description
`OutputAdapter`	`value` either wrapped or converted. The returned object is not intended to be used by the user's script but returned as it is.

`base64_to_bytes(b64)` `staticmethod` ¶

Reverts data encoded as a string using base 64 to raw bytes.

All binary data moved around as JSON in Chalk'it is encoded as base 64 strings. This method is provided as an easy way to get the data back into a binary form.

Parameters:

Name	Type	Description	Default
`b64`	`str`	the base64 encoded string	required

Returns:

Type	Description
`bytes`	the decoded raw binary data

`debug(self, value)` ¶

Output debug information.

This method does nothing when not invoked while editing a script in the Python datanode editor. In the editor, the value with be displayed as conveniently as possible. This is intended to be similar to a print, or more accurately a logger.debug(value), with some additional rendering, like images being displayed, etc.

Parameters:

Name	Type	Description	Default
`value`	`Any`	the value to display	required

`output(self, value, key=None)` ¶

Provides an alternative way to return data, as opposed to the return statement.

Multiple calls build an array; using keys yield an object:

# Equivalent simple returns
chalkit.output(42)
# Or
return 42

# Equivalent array returns
chalkit.output(1)
chalkit.output(2)
chalkit.output(3)
# Or
return [1, 2, 3]

# Equivalent object returns
chalkit.output(1, key="a")
chalkit.output(2, key="b")
# Or
return {"a": 1, "b": 2}

Mixing output and return is an error, as is using output with and without keys.

Parameters:

Name	Type	Description	Default
`value`	`Any`	a return value for the script	required
`key`	`Optional[str]`	if provided, attach `value` as the `key` attribute of a JSON object.	`None`

`output_data(self, value, key=None)` ¶

Same as chalkit.output(chalkit.as_data(value), key).

Parameters:

Name	Type	Description	Default
`value`	`Any`	a return value for the script	required
`key`	`Optional[str]`		`None`

`output_image(self, value, key=None)` ¶

Same as chalkit.output(chalkit.as_image(value), key).

Parameters:

Name	Type	Description	Default
`value`	`Any`	a return value for the script	required
`key`	`Optional[str]`		`None`

`output_json(self, value, key=None)` ¶

Same as chalkit.output(chalkit.as_json(value), key).

Parameters:

Name	Type	Description	Default
`value`	`Any`	a return value for the script	required
`key`	`Optional[str]`		`None`

`output_python(self, value, key=None)` ¶

Same as `chalkit.output(chalkit.as_python(value), key)`.

Parameters:

Name	Type	Description	Default
`value`	`Any`	a return value for the script	required
`key`	`Optional[str]`		`None`

Scheduler interactions¶

This class provides a port of the javascript API. An instance of it is provided to user scripts as chalkit.scheduler. It allows some interactions with the dashboard's scheduler. Use with caution as these introduce side effects to data nodes executions. Be especially mindful of not creating update cycles.

`execute_datanode(self, datanode_name)` ¶

Schedules the evaluation of a dataNode.

This is mostly meant for dataNodes with the explicit trigger flag. This will cascade to downstream dataNodes.

Parameters:

Name	Type	Description	Default
`datanode_name`	`str`	the name of the dataNode	required

`execute_datanodes(self, datanode_names)` ¶

Schedules the evaluation of multiple dataNodes (see `execute_datanode).

Parameters:

Name	Type	Description	Default
`datanode_names`	`list[str]`	the names of a group of dataNodes	required

`set_variable(self, datanode_name, json_value)` ¶

Update the value of a dataNode.

The change happens at the end of the evaluation of the current dataNode. This may trigger the re-evaluation of downstream dataNodes. Most dataNodes that are not Variable can't be updated.

Parameters:

Name	Type	Description	Default
`datanode_name`	`str`	the name of the dataNode	required
`json_value`	`Any`	the new value, must convert to JSON	required

`set_variable_property(self, datanode_name, property_path, json_value)` ¶

Update part of the value of a dataNode (see set_variable).

See the javascript version for more details.

Parameters:

Name	Type	Description	Default
`datanode_name`	`str`	the name of the dataNode	required
`property_path`	`list[Union[int, str]]`	Path in the old value where to set the new value. Sequence of strings (object keys) and integers (array index).	required
`json_value`	`Any`	the new value to insert, must convert to JSON	required

`set_variables(self, datanodes_values)` ¶

Update the value of multiple dataNodes (see set_variable).

Parameters:

Name	Type	Description	Default
`datanodes_values`	`dict[str, Any]`	dictionary mapping dataNode names to their new values. Values must convert to JSON.	required

Dashboard interactions¶

This class provides a port of the javascript API. An instance of it is provided to user scripts as chalkit.dashboard. It allows some interactions with the dashboard. Use with caution as these introduce side effects to data nodes executions.

`disable_widget(self, widget_name)` ¶

Disables a widget, making it non-interactive. All widgets are initially enabled.

Parameters:

Name	Type	Description	Default
`widget_name`	`str`	the name of a widget (can be obtained by hovering over a widget in the edit mode)	required

`enable_widget(self, widget_name)` ¶

(re)enables a widget, making it interactive.

Parameters:

Name	Type	Description	Default
`widget_name`	`str`	the name of a widget (can be obtained by hovering over a widget in the edit mode)	required

`go_to_page(self, num_page)` ¶

Changes the current page in constrained dashboard mode.

Parameters:

Name	Type	Description	Default
`num_page`	`int`	the page to display	required

`hide_widget(self, widget_name)` ¶

Hides a widget. All widgets are initially visible.

Parameters:

Name	Type	Description	Default
`widget_name`	`str`	the name of a widget (can be obtained by hovering over a widget in the edit mode)	required

`show_widget(self, widget_name)` ¶

Makes a widget visible. All widgets are initially visible.

Parameters:

Name	Type	Description	Default
`widget_name`	`str`	the name of a widget (can be obtained by hovering over a widget in the edit mode)	required

`view_page(self, page_url, input_vals=None, new_tab=False)` ¶

Navigates to pageUrl, setting the values of the specified dataNodes in inputVals.

Parameters:

Name	Type	Description	Default
`page_url`	`str`	target page URL	required
`input_vals`	`Optional[list[chalkit_python_api.public_api.ParamValue]]`	optional array of structures of type `{"dsName": "dataNodeName", "dsVal" : "dataNodeValue"}`. `dsName` must be a string. `dsVal` must convert to JSON.	`None`
`new_tab`		open in new tab when true	`False`

`view_project(self, project_url, input_vals=None, new_tab=False)` ¶

Similar to view_page, but for projects.

Parameters:

Name	Type	Description	Default
`project_url`	`str`	URL of an xprjson file	required
`input_vals`	`Optional[list[chalkit_python_api.public_api.ParamValue]]`		`None`
`new_tab`		open in new tab when true	`False`

Chalk'it APIs¶

JavaScript¶

Scheduler features¶

setVariable¶

setVariableProperty¶

setVariables¶

executeDataNode¶

executeDataNodes¶

Dashboard features¶

goToPage¶

viewPage¶

viewProject¶

hideWidget¶

showWidget¶

disableWidget¶

enableWidget¶

Python¶

Input/ouputs helpers¶

as_data(value, mime_type=None, name=None) staticmethod ¶

as_image(value) staticmethod ¶

as_json(value) staticmethod ¶

as_python(value) staticmethod ¶

base64_to_bytes(b64) staticmethod ¶

debug(self, value) ¶

output(self, value, key=None) ¶

output_data(self, value, key=None) ¶

output_image(self, value, key=None) ¶

output_json(self, value, key=None) ¶

output_python(self, value, key=None) ¶

Scheduler interactions¶

execute_datanode(self, datanode_name) ¶

execute_datanodes(self, datanode_names) ¶

set_variable(self, datanode_name, json_value) ¶

set_variable_property(self, datanode_name, property_path, json_value) ¶

set_variables(self, datanodes_values) ¶

Dashboard interactions¶

disable_widget(self, widget_name) ¶

enable_widget(self, widget_name) ¶

go_to_page(self, num_page) ¶

hide_widget(self, widget_name) ¶

show_widget(self, widget_name) ¶

view_page(self, page_url, input_vals=None, new_tab=False) ¶

view_project(self, project_url, input_vals=None, new_tab=False) ¶

`as_data(value, mime_type=None, name=None)` `staticmethod` ¶

`as_image(value)` `staticmethod` ¶

`as_json(value)` `staticmethod` ¶

`as_python(value)` `staticmethod` ¶

`base64_to_bytes(b64)` `staticmethod` ¶

`debug(self, value)` ¶

`output(self, value, key=None)` ¶

`output_data(self, value, key=None)` ¶

`output_image(self, value, key=None)` ¶

`output_json(self, value, key=None)` ¶

`output_python(self, value, key=None)` ¶

`execute_datanode(self, datanode_name)` ¶

`execute_datanodes(self, datanode_names)` ¶

`set_variable(self, datanode_name, json_value)` ¶

`set_variable_property(self, datanode_name, property_path, json_value)` ¶

`set_variables(self, datanodes_values)` ¶

`disable_widget(self, widget_name)` ¶

`enable_widget(self, widget_name)` ¶

`go_to_page(self, num_page)` ¶

`hide_widget(self, widget_name)` ¶

`show_widget(self, widget_name)` ¶

`view_page(self, page_url, input_vals=None, new_tab=False)` ¶

`view_project(self, project_url, input_vals=None, new_tab=False)` ¶