Skip to content

# Chalk'it APIs

Chalk'it offers a set of APIs through chalkit that address several primary functionalities:

- Scheduler APIs: Facilitate the scheduling process by enabling the modification of dataNode variables and triggering the scheduler.
- Dashboard APIs: Support the developpement of multi-dashboard applications and widget display.
- Notification APIs: Enable the creation, management, and delivery of real-time alerts and updates to users supporting both blocking (popup) and non-blocking notifications.
- 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.scheduler.setVariable(dataNodeName, dataNodeValue);

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

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

For example, to update the following dataNode named info_person:

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

Use this code:

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

#### setVariableProperty

    chalkit.scheduler.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 (string): The name of the dataNode.
- propertyPath (array|string): The path to the property to be modified, supporting nested structures.
- 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, given this dataNode named info_address:

    {
      "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.scheduler.setVariableProperty("info_person", ["address","details","street"], "West 23rd Street");

#### setVariables

    chalkit.scheduler.setVariables(dataNodeNames, dataNodeValues);

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

- dataNodeNames (array): An array of dataNode names.
- dataNodeValues (array): An array of values, matching the order and size of dataNodeNames.

For example, to update info_person and another dataNode info_gender:

    {"gender": "male"}

you can use the following code:

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

#### executeDataNode

    chalkit.scheduler.executeDataNode(dataNodeName);

This API triggers the scheduler 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.scheduler.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

The method:

    chalkit.dashboard.goToPage(pageNumber)

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

- pageNumber (number): The target page number.

#### viewPage

    chalkit.dashboard.viewPage(pageUrl, inputVals, bNewTab)

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

- pageUrl (string): The URL of the target page.
- inputVals (array): An array of objects with structure.

    {"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 (boolean): Opens the page in a new tab if true.

#### viewProject

Similar to view page, but applies for projects.

    chalkit.dashboard.viewProject(projectUrl, inputVals, bNewTab)

#### hideWidget

    chalkit.dashboard.hideWidget(widgetName)

Hides the display of the widget.

- widgetName (string): 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.dashboard.showWidget(widgetName)

Makes the display of the widget visible.

#### disableWidget

    chalkit.dashboard.disableWidget(widgetName)

Disables the interaction with a widget. The widget is enabled by default.

#### enableWidget

    chalkit.dashboard.enableWidget(widgetName)

Enables the interaction with a widget.

### Notification features

These features facilitate the creation and delivery of blocking and non-blocking notifications, supporting various types such as error, success, info, and warning.

### swalert

    chalkit.notification.swalert(title, message, type)

Creates and displays a blocking notification using the SweetAlert library:

- title (string): The title of the notification.
- message (string): The content of the notification message.
- type (string): The type of the notification. Accepted values are "error", "success", "warning", or "info".

### notify

    chalkit.notification.notify(dataNodeName, message, type)

Creates and displays a non-blocking notification, which will appear in the notification window under the bell icon :

- dataNodeName (string): The name of the associated dataNode. If dataNodeName is undefined or an empty string, the script source where the API is called will be used as the default.
- message (string): The content of the notification message.
- type (string): The type of the notification. Accepted values are "error", "success", "warning", or "info".

## 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))`.

Source code in `chalkit_python_api\public_api.py`

    class ChalkitApi:
        """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))`.

        """

        def __init__(self, state: ChalkitState):
            self._state = state
            self._scheduler = SchedulerActions(state)
            self._dashboard = DashboardActions(state)
            self._notification = NotificationActions(state)

        @property
        def scheduler(self) -> SchedulerActions:
            return self._scheduler

        @property
        def dashboard(self) -> DashboardActions:
            return self._dashboard

        @property
        def notification(self) -> NotificationActions:
            return self._notification

        @staticmethod
        def base64_to_bytes(b64: str) -> bytes:
            """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:
                b64: the base64 encoded string

            Returns:
                the decoded raw binary data
            """
            from base64 import standard_b64decode

            return standard_b64decode(b64)

        @staticmethod
        def as_json(value: Any) -> OutputAdapter:
            """
            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.

            Args:
                value: a return value for the script

            Returns:
                `value` either wrapped or converted. The returned object is not intended to be used by the user's script
                 but returned as it is.
            """
            return JsonAdapter(value)

        @staticmethod
        def as_python(value: Any) -> OutputAdapter:
            """
            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.

            Args:
                value: a return value for the script

            Returns:
                `value` either wrapped or converted. The returned object is not intended to be used by the user's script
                 but returned as it is.
            """
            return PythonAdapter(value)

        @staticmethod
        def as_image(value: Any) -> OutputAdapter:
            """
            This method instructs Chalk'it to convert the result (like a plot figure) into an image.

            Args:
                value: a return value for the script

            Returns:
                `value` either wrapped or converted. The returned object is not intended to be used by the user's script
                 but returned as it is.
            """
            return ImageAdapter(value)

        @staticmethod
        def as_data(value: Any, mime_type: Optional[str] = None, name: Optional[str] = None) -> OutputAdapter:
            """
            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.

            Args:
                value: a return value for the script
                mime_type: A MIME type to be added to the resulting JSON object.
                name: a name (usually a file name) to be added to the resulting JSON object.

            Returns:
                `value` either wrapped or converted. The returned object is not intended to be used by the user's script
                 but returned as it is.
            """
            return DataAdapter(value, mime_type, name)

        def output(self, value: Any, key: Optional[str] = None) -> 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.

            Args:
                value: a return value for the script
                key: if provided, attach `value` as the `key` attribute of a JSON object.
            """
            self._state.add_output(value, key)

        def output_json(self, value: Any, key: Optional[str] = None) -> None:
            """
            Same as `chalkit.output(chalkit.as_json(value), key)`.

            Args:
                value: a return value for the script
                key:
            """
            self._state.add_output(self.as_json(value), key)

        def output_python(self, value: Any, key: Optional[str] = None) -> None:
            """
                Same as `chalkit.output(chalkit.as_python(value), key)`.

            Args:
                value: a return value for the script
                key:
            """
            self._state.add_output(self.as_python(value), key)

        def output_image(self, value: Any, key: Optional[str] = None) -> None:
            """
            Same as `chalkit.output(chalkit.as_image(value), key)`.

            Args:
                value: a return value for the script
                key:
            """
            self._state.add_output(self.as_image(value), key)

        def output_data(self, value: Any, key: Optional[str] = None) -> None:
            """
            Same as `chalkit.output(chalkit.as_data(value), key)`.

            Args:
                value: a return value for the script
                key:
            """
            self._state.add_output(self.as_data(value), key)

        def debug(self, value: Any) -> None:
            """
            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.

            Args:
                value: the value to display
            """
            self._state.add_debug(value)

        def notify(self):
            pass
            # TODO

## `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.

Source code in `chalkit_python_api\public_api.py`

    @staticmethod
    def as_data(value: Any, mime_type: Optional[str] = None, name: Optional[str] = None) -> OutputAdapter:
        """
        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.

        Args:
            value: a return value for the script
            mime_type: A MIME type to be added to the resulting JSON object.
            name: a name (usually a file name) to be added to the resulting JSON object.

        Returns:
            `value` either wrapped or converted. The returned object is not intended to be used by the user's script
             but returned as it is.
        """
        return DataAdapter(value, mime_type, name)

## `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.

Source code in `chalkit_python_api\public_api.py`

    @staticmethod
    def as_image(value: Any) -> OutputAdapter:
        """
        This method instructs Chalk'it to convert the result (like a plot figure) into an image.

        Args:
            value: a return value for the script

        Returns:
            `value` either wrapped or converted. The returned object is not intended to be used by the user's script
             but returned as it is.
        """
        return ImageAdapter(value)

## `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.

Source code in `chalkit_python_api\public_api.py`

    @staticmethod
    def as_json(value: Any) -> OutputAdapter:
        """
        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.

        Args:
            value: a return value for the script

        Returns:
            `value` either wrapped or converted. The returned object is not intended to be used by the user's script
             but returned as it is.
        """
        return JsonAdapter(value)

## `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.

Source code in `chalkit_python_api\public_api.py`

    @staticmethod
    def as_python(value: Any) -> OutputAdapter:
        """
        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.

        Args:
            value: a return value for the script

        Returns:
            `value` either wrapped or converted. The returned object is not intended to be used by the user's script
             but returned as it is.
        """
        return PythonAdapter(value)

## `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

Source code in `chalkit_python_api\public_api.py`

    @staticmethod
    def base64_to_bytes(b64: str) -> bytes:
        """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:
            b64: the base64 encoded string

        Returns:
            the decoded raw binary data
        """
        from base64 import standard_b64decode

        return standard_b64decode(b64)

## `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

Source code in `chalkit_python_api\public_api.py`

    def debug(self, value: Any) -> None:
        """
        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.

        Args:
            value: the value to display
        """
        self._state.add_debug(value)

## `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`

Source code in `chalkit_python_api\public_api.py`

    def output(self, value: Any, key: Optional[str] = None) -> 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.

        Args:
            value: a return value for the script
            key: if provided, attach `value` as the `key` attribute of a JSON object.
        """
        self._state.add_output(value, key)

## `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`

Source code in `chalkit_python_api\public_api.py`

    def output_data(self, value: Any, key: Optional[str] = None) -> None:
        """
        Same as `chalkit.output(chalkit.as_data(value), key)`.

        Args:
            value: a return value for the script
            key:
        """
        self._state.add_output(self.as_data(value), key)

## `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`

Source code in `chalkit_python_api\public_api.py`

    def output_image(self, value: Any, key: Optional[str] = None) -> None:
        """
        Same as `chalkit.output(chalkit.as_image(value), key)`.

        Args:
            value: a return value for the script
            key:
        """
        self._state.add_output(self.as_image(value), key)

## `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`

Source code in `chalkit_python_api\public_api.py`

    def output_json(self, value: Any, key: Optional[str] = None) -> None:
        """
        Same as `chalkit.output(chalkit.as_json(value), key)`.

        Args:
            value: a return value for the script
            key:
        """
        self._state.add_output(self.as_json(value), key)

## `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`

Source code in `chalkit_python_api\public_api.py`

    def output_python(self, value: Any, key: Optional[str] = None) -> None:
        """
            Same as `chalkit.output(chalkit.as_python(value), key)`.

        Args:
            value: a return value for the script
            key:
        """
        self._state.add_output(self.as_python(value), key)

options: show_source: false heading_level: 4 show_signature_annotations: true show_object_full_path: false show_root_toc_entry: false separate_signature: true show_signature_annotations: false

### 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.

Source code in `chalkit_python_api\public_api.py`

    class SchedulerActions:
        """
        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.
        """

        def __init__(self, state: ChalkitState):
            self._state = state

        def set_variable(self, datanode_name: str, json_value: JSON) -> None:
            """
            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.

            Args:
                datanode_name: the name of the dataNode
                json_value: the new value, must convert to JSON
            """
            self.set_variables({datanode_name: json_value})

        def set_variables(self, datanodes_values: dict[str, JSON]) -> None:
            """
            Update the value of multiple dataNodes (see `set_variable`).

            Args:
                datanodes_values: dictionary mapping dataNode names to their new values. Values must convert to JSON.
            """
            self._state.add_side_effect("scheduler.setVariables", datanodes_values)

        def set_variable_property(self, datanode_name: str, property_path: PropertyPath, json_value: JSON) -> None:
            """
            Update part of the value of a dataNode (see `set_variable`).

            See the javascript version for more details.

            Args:
                datanode_name: the name of the dataNode
                property_path: Path in the old value where to set the new value. Sequence of strings (object keys) and
                               integers (array index).
                json_value: the new value to insert, must convert to JSON

            """
            self._state.add_side_effect("scheduler.setVariableProperty", datanode_name, property_path, json_value)

        def execute_datanode(self, datanode_name: str) -> None:
            """
            Schedules the evaluation of a dataNode.

            This is mostly meant for dataNodes with the explicit trigger flag. This will cascade to downstream dataNodes.
            Args:
                datanode_name: the name of the dataNode
            """
            self.execute_datanodes([datanode_name])

        def execute_datanodes(self, datanode_names: list[str]) -> None:
            """
            Schedules the evaluation of multiple dataNodes (see `execute_datanode).

            Args:
                datanode_names: the names of a group of dataNodes
            """
            self._state.add_side_effect("scheduler.executeDataNodes", datanode_names)

## `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

Source code in `chalkit_python_api\public_api.py`

    def execute_datanode(self, datanode_name: str) -> None:
        """
        Schedules the evaluation of a dataNode.

        This is mostly meant for dataNodes with the explicit trigger flag. This will cascade to downstream dataNodes.
        Args:
            datanode_name: the name of the dataNode
        """
        self.execute_datanodes([datanode_name])

## `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

Source code in `chalkit_python_api\public_api.py`

    def execute_datanodes(self, datanode_names: list[str]) -> None:
        """
        Schedules the evaluation of multiple dataNodes (see `execute_datanode).

        Args:
            datanode_names: the names of a group of dataNodes
        """
        self._state.add_side_effect("scheduler.executeDataNodes", datanode_names)

## `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

Source code in `chalkit_python_api\public_api.py`

    def set_variable(self, datanode_name: str, json_value: JSON) -> None:
        """
        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.

        Args:
            datanode_name: the name of the dataNode
            json_value: the new value, must convert to JSON
        """
        self.set_variables({datanode_name: json_value})

## `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

Source code in `chalkit_python_api\public_api.py`

    def set_variable_property(self, datanode_name: str, property_path: PropertyPath, json_value: JSON) -> None:
        """
        Update part of the value of a dataNode (see `set_variable`).

        See the javascript version for more details.

        Args:
            datanode_name: the name of the dataNode
            property_path: Path in the old value where to set the new value. Sequence of strings (object keys) and
                           integers (array index).
            json_value: the new value to insert, must convert to JSON

        """
        self._state.add_side_effect("scheduler.setVariableProperty", datanode_name, property_path, json_value)

## `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

Source code in `chalkit_python_api\public_api.py`

    def set_variables(self, datanodes_values: dict[str, JSON]) -> None:
        """
        Update the value of multiple dataNodes (see `set_variable`).

        Args:
            datanodes_values: dictionary mapping dataNode names to their new values. Values must convert to JSON.
        """
        self._state.add_side_effect("scheduler.setVariables", datanodes_values)

options: show_source: false heading_level: 4 show_signature_annotations: true show_object_full_path: false show_root_toc_entry: false separate_signature: true show_signature_annotations: false

### 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.

Source code in `chalkit_python_api\public_api.py`

    class DashboardActions:
        """
        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.
        """

        def __init__(self, state: ChalkitState):
            self._state = state

        def view_page(self, page_url: str, input_vals: Optional[ParamValues] = None, new_tab=False) -> None:
            """
            Navigates to pageUrl, setting the values of the specified dataNodes in inputVals.

            Args:
                page_url: target page URL
                input_vals: optional array of structures of type `{"dsName": "dataNodeName", "dsVal" : "dataNodeValue"}`.
                            `dsName` must be a string. `dsVal` must convert to JSON.
                new_tab: open in new tab when true
            """
            self._state.add_side_effect("dashboard.viewPage", page_url, input_vals, new_tab)

        def view_project(self, project_url: str, input_vals: Optional[ParamValues] = None, new_tab=False) -> None:
            """
            Similar to `view_page`, but for projects.

            Args:
                project_url: URL of an xprjson file
                input_vals:
                new_tab: open in new tab when true
            """
            self._state.add_side_effect("dashboard.viewProject", project_url, input_vals, new_tab)

        def go_to_page(self, num_page: int) -> None:
            """
            Changes the current page in constrained dashboard mode.

            Args:
                num_page: the page to display
            """
            self._state.add_side_effect("dashboard.goToPage", num_page)

        def enable_widget(self, widget_name: str) -> None:
            """
            (re)enables a widget, making it interactive.

            Args:
                widget_name: the name of a widget (can be obtained by hovering over a widget in the edit mode)
            """
            self._state.add_side_effect("dashboard.enableWidget", widget_name)

        def disable_widget(self, widget_name: str) -> None:
            """
            Disables a widget, making it non-interactive. All widgets are initially enabled.

            Args:
                widget_name: the name of a widget (can be obtained by hovering over a widget in the edit mode)
            """
            self._state.add_side_effect("dashboard.disableWidget", widget_name)

        def show_widget(self, widget_name: str) -> None:
            """
            Makes a widget visible. All widgets are initially visible.

            Args:
                widget_name: the name of a widget (can be obtained by hovering over a widget in the edit mode)
            """
            self._state.add_side_effect("dashboard.showWidget", widget_name)

        def hide_widget(self, widget_name: str) -> None:
            """
            Hides a widget. All widgets are initially visible.

            Args:
                widget_name: the name of a widget (can be obtained by hovering over a widget in the edit mode)
            """
            self._state.add_side_effect("dashboard.hideWidget", widget_name)

## `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

Source code in `chalkit_python_api\public_api.py`

    def disable_widget(self, widget_name: str) -> None:
        """
        Disables a widget, making it non-interactive. All widgets are initially enabled.

        Args:
            widget_name: the name of a widget (can be obtained by hovering over a widget in the edit mode)
        """
        self._state.add_side_effect("dashboard.disableWidget", widget_name)

## `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

Source code in `chalkit_python_api\public_api.py`

    def enable_widget(self, widget_name: str) -> None:
        """
        (re)enables a widget, making it interactive.

        Args:
            widget_name: the name of a widget (can be obtained by hovering over a widget in the edit mode)
        """
        self._state.add_side_effect("dashboard.enableWidget", widget_name)

## `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

Source code in `chalkit_python_api\public_api.py`

    def go_to_page(self, num_page: int) -> None:
        """
        Changes the current page in constrained dashboard mode.

        Args:
            num_page: the page to display
        """
        self._state.add_side_effect("dashboard.goToPage", num_page)

## `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

Source code in `chalkit_python_api\public_api.py`

    def hide_widget(self, widget_name: str) -> None:
        """
        Hides a widget. All widgets are initially visible.

        Args:
            widget_name: the name of a widget (can be obtained by hovering over a widget in the edit mode)
        """
        self._state.add_side_effect("dashboard.hideWidget", widget_name)

## `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

Source code in `chalkit_python_api\public_api.py`

    def show_widget(self, widget_name: str) -> None:
        """
        Makes a widget visible. All widgets are initially visible.

        Args:
            widget_name: the name of a widget (can be obtained by hovering over a widget in the edit mode)
        """
        self._state.add_side_effect("dashboard.showWidget", widget_name)

## `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`

Source code in `chalkit_python_api\public_api.py`

    def view_page(self, page_url: str, input_vals: Optional[ParamValues] = None, new_tab=False) -> None:
        """
        Navigates to pageUrl, setting the values of the specified dataNodes in inputVals.

        Args:
            page_url: target page URL
            input_vals: optional array of structures of type `{"dsName": "dataNodeName", "dsVal" : "dataNodeValue"}`.
                        `dsName` must be a string. `dsVal` must convert to JSON.
            new_tab: open in new tab when true
        """
        self._state.add_side_effect("dashboard.viewPage", page_url, input_vals, new_tab)

## `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`

Source code in `chalkit_python_api\public_api.py`

    def view_project(self, project_url: str, input_vals: Optional[ParamValues] = None, new_tab=False) -> None:
        """
        Similar to `view_page`, but for projects.

        Args:
            project_url: URL of an xprjson file
            input_vals:
            new_tab: open in new tab when true
        """
        self._state.add_side_effect("dashboard.viewProject", project_url, input_vals, new_tab)

options: show_source: false heading_level: 4 show_signature_annotations: true show_object_full_path: false show_root_toc_entry: false separate_signature: true show_signature_annotations: false

### Notification interactions

This class provides a port of the javascript API. An instance of it is provided to user scripts as `chalkit.notification`. It allows some interactions with the notifications.

Source code in `chalkit_python_api\public_api.py`

    class NotificationActions:
        """
        This class provides a port of the javascript API. An instance of it is provided to user scripts as
        `chalkit.notification`. It allows some interactions with the notifications.
        """

        def __init__(self, state: ChalkitState):
            self._state = state

        def notify(self, datanode_name: str, message: str, type: str) -> None:
            """
            Add a non-blocking notification.

            Args:
                datanode_name: the name of the dataNode
                message: the content of the message
                type: the type of the message (error, success, warning, info)
            """
            self._state.add_side_effect("notification.notify", datanode_name, message, type)

        def swalert(self, title: str,message: str,type: str) -> None:
            """
            Use sweetAlert blocking notification.

            Args:
                title: the title of the notification
                message: the content of the message
                type: the type of the message (error, success, warning, info)
            """
            self._state.add_side_effect("notification.swalert", title, message, type)

## `notify(self, datanode_name, message, type)`

Add a non-blocking notification.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`datanode_name` | `str` | the name of the dataNode | required
`message` | `str` | the content of the message | required
`type` | `str` | the type of the message (error, success, warning, info) | required

Source code in `chalkit_python_api\public_api.py`

    def notify(self, datanode_name: str, message: str, type: str) -> None:
        """
        Add a non-blocking notification.

        Args:
            datanode_name: the name of the dataNode
            message: the content of the message
            type: the type of the message (error, success, warning, info)
        """
        self._state.add_side_effect("notification.notify", datanode_name, message, type)

## `swalert(self, title, message, type)`

Use sweetAlert blocking notification.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`title` | `str` | the title of the notification | required
`message` | `str` | the content of the message | required
`type` | `str` | the type of the message (error, success, warning, info) | required

Source code in `chalkit_python_api\public_api.py`

    def swalert(self, title: str,message: str,type: str) -> None:
        """
        Use sweetAlert blocking notification.

        Args:
            title: the title of the notification
            message: the content of the message
            type: the type of the message (error, success, warning, info)
        """
        self._state.add_side_effect("notification.swalert", title, message, type)

options: show_source: false heading_level: 4 show_signature_annotations: true show_object_full_path: false show_root_toc_entry: false separate_signature: true show_signature_annotations: false