Plugins Client Methods#

This page lists all relevant methods for Dioptra Plugins that are available via the Python Client.

Contents

Requirements
Plugins - CRUD methods
Plugin Files - Methods
Tags Attached to Plugin - Methods
Snapshots of Plugin - Methods
- Methods - Plugin Specific Snapshots
- Download Files Bundle
See Also

Requirements #

Install Dioptra - an installation and deployment of Dioptra must be available
Set Up the Python Client - the Python client must be configured and initialized

Plugins - CRUD methods #

After importing and initializing the client, these methods for creating, reading, updating, and deleting (CRUD) Plugins can be executed via client.plugins.METHOD_NAME().

Create Plugin #

PluginsCollectionClient.create(group_id: int, name: str, description: str | None = None) → dioptra.client.plugins.T[source]#
Creates a plugin.

Parameters

group_id – The id of the group that will own the plugin.

name – The name of the new plugin.

description – The description of the new plugin. Optional, defaults to None.
Example

Create a plugin called “hello” with a description.
plugin = client.plugins.create(
    group_id, "hello", "This is a Hello World Plugin"
)
Returns

The response from the Dioptra API.

Get Plugins #

PluginsCollectionClient.get(group_id: int | None = None, index: int = 0, page_length: int = 10, sort_by: str | None = None, descending: bool | None = None, search: str | None = None) → dioptra.client.plugins.T[source]#

Get a list of plugins.

Parameters

group_id – The group id the plugins belong to. If None, return plugins from all groups that the user has access to. Optional, defaults to None.

index – The paging index. Optional, defaults to 0.

page_length – The maximum number of plugins to return in the paged response. Optional, defaults to 10.

sort_by – The field to use to sort the returned list. Optional, defaults to None.

descending – Sort the returned list in descending order. Optional, defaults to None.

search – Search for plugins using the Dioptra API’s query language. Optional, defaults to None.

Returns

The response from the Dioptra API.

Get Plugin by ID #

PluginsCollectionClient.get_by_id(plugin_id: str | int) → dioptra.client.plugins.T[source]#

Get the plugin matching the provided id.

Parameters

plugin_id – The plugin id, an integer.

Returns

The response from the Dioptra API.

Modify Plugin #

PluginsCollectionClient.modify_by_id(plugin_id: str | int, name: str, description: str | None) → dioptra.client.plugins.T[source]#

Modify the plugin matching the provided id.

Parameters

plugin_id – The plugin id, an integer.

name – The new name of the plugin.

description – The new description of the plugin. To remove the description, pass None.

Returns

The response from the Dioptra API.

Delete Plugin #

PluginsCollectionClient.delete_by_id(plugin_id: str | int) → dioptra.client.plugins.T[source]#

Delete the plugin matching the provided id.

Parameters

plugin_id – The plugin id, an integer.

Returns

The response from the Dioptra API.

Plugin Files - Methods #

These methods exist within the class PluginFilesSubCollectionClient, and are accessed via the files property of the Plugins Client (which points to PluginFilesSubCollectionClient).

Example - Create a file within a Plugin

Create a file within a Plugin

client.plugins.files.create(plugin_id=1, filename="script.py", contents="print('hello')")

Create Plugin File #

PluginFilesSubCollectionClient.create(plugin_id: str | int, filename: str, contents: str, function_tasks: list[dict[str, Any]] | None = None, artifact_tasks: list[dict[str, Any]] | None = None, description: str | None = None) → dioptra.client.plugins.T[source]#
Creates a plugin file.

Either function_tasks or artifact_tasks should be provided. Mixing the two types of tasks is not recommended.

Parameters

plugin_id – The id for the plugin that will own the new plugin file.

filename – The filename for the new plugin file.

contents – The contents of the new Python file.

function_tasks – The information needed to register plugin function tasks contained in the plugin file, a list. Can be empty.

artifact_tasks – The information needed to register plugin artifact tasks contained in the plugin file, a list. Can be empty.

description – The description of the new plugin file. Optional, defaults to None.
Example

Attach Python code embedded in a string to a Plugin, and register a task with two input parameters and one output parameter.
file = client.plugins.files.create(
    plugin_id=plugin["id"],
    filename="hello.py",
    content=PYTHON_CONTENTS,
    tasks=[
        {
            "name": "hello_world",
            "inputParams": [
                {
                    "name": "greeting",
                    "parameterType": string_param_type_id,
                    "required": True,
                },
                {
                    "name": "name",
                    "parameterType": string_param_type_id,
                    "required": True,
                },
            ],
            "outputParams": [
                {
                    "name": "message",
                    "parameterType": string_param_type_id,
                }
            ],
        }
    ],
)
Returns

The response from the Dioptra API.

Get Files for Plugin #

PluginFilesSubCollectionClient.get(plugin_id: int | str, index: int = 0, page_length: int = 10, sort_by: str | None = None, descending: bool | None = None, search: str | None = None) → dioptra.client.plugins.T[source]#

Get a list of plugin files for a specific plugin.

Parameters

plugin_id – The id for the plugin that owns the plugin files.

index – The paging index. Optional, defaults to 0.

page_length – The maximum number of plugins to return in the paged response. Optional, defaults to 10.

sort_by – The field to use to sort the returned list. Optional, defaults to None.

descending – Sort the returned list in descending order. Optional, defaults to None.

search – Search for plugins using the Dioptra API’s query language. Optional, defaults to None.

Returns

The response from the Dioptra API.

Get Plugin File by ID #

PluginFilesSubCollectionClient.get_by_id(plugin_id: str | int, plugin_file_id: str | int) → dioptra.client.plugins.T[source]#

Get the plugin file matching the provided ids.

Parameters

plugin_id – The id for the plugin that owns the plugin file.

plugin_file_id – The plugin file id, an integer.

Returns

The response from the Dioptra API.

Modify Plugin File #

PluginFilesSubCollectionClient.modify_by_id(plugin_id: str | int, plugin_file_id: str | int, filename: str, contents: str, function_tasks: list[dict[str, Any]] | None = None, artifact_tasks: list[dict[str, Any]] | None = None, description: str | None = None) → dioptra.client.plugins.T[source]#

Modify a plugin file matching the provided ids.

Either function_tasks or artifact_tasks should be provided. Mixing the two types of tasks is not recommended.

Parameters

plugin_id – The id for the plugin that owns the plugin file.

plugin_file_id – The plugin file id, an integer.

filename – The filename for the new plugin file.

contents – The contents of the new Python file.

function_tasks – The information needed to register plugin function tasks contained in the plugin file, a list. Can be empty.

artifact_tasks – The information needed to register plugin artifact tasks contained in the plugin file, a list. Can be empty.

description – The description of the new plugin file. Optional, defaults to None.

Returns

The response from the Dioptra API.

Delete Plugin File #

PluginFilesSubCollectionClient.delete_by_id(plugin_id: str | int, plugin_file_id: str | int) → dioptra.client.plugins.T[source]#

Delete a plugin file.

Parameters

plugin_id – The id for the plugin that owns the plugin file to be deleted.

plugin_file_id – The plugin file id, an integer.

Returns

The response from the Dioptra API.

Delete All Files in Plugin #

PluginFilesSubCollectionClient.delete_all(plugin_id: str | int) → dioptra.client.plugins.T[source]#

Delete all plugin files owned by the plugin matching the provided id.

Parameters

plugin_id – The id for the plugin that owns the plugin files to be deleted.

Returns

The response from the Dioptra API.

Tags Attached to Plugin - Methods #

Methods belonging to the TagsSubCollectionClient are accessed via the tags property of the Plugins Client (which points to TagsSubCollectionClient).

Example - Get tags for a Plugin

Get tags for a Plugin

client.plugins.tags.get(1)

See available methods for the TagsSubCollectionClient:

Tags Client Methods

Snapshots of Plugin - Methods #

Methods belonging to the PluginsSnapshotCollectionClient are accessed via the snapshots property of the Plugins Client (which points to PluginsSnapshotCollectionClient).

Example - Get snapshots for a Plugin

Get snapshots for a Plugin

client.plugins.snapshots.get(1)

See available methods for the SnapshotsSubCollectionClient:

Snapshots Client Methods

Methods - Plugin Specific Snapshots #

The following methods are specific to Plugin snapshots and are not available on other resources.

Download Files Bundle #

PluginsSnapshotCollectionClient.get_files_bundle(plugin_id: str | int, plugin_snapshot_id: str | int, file_type: dioptra.client.utils.FileTypes = FileTypes.TAR_GZ, output_dir: pathlib.Path | None = None, file_stem: str = 'task-plugins') → pathlib.Path[source]#

Get the task plugins bundle for the entrypoint matching the provided
snapshot id.

Parameters

entrypoint_id – The entrypoint id, an integer.

entrypoint_snapshot_id – The entrypoint snapshot id, an integer.

file_type – The file type of the bundle that is returned, defaults to None. If None is provided, then a default of FileTypes.TAR_GZ is used.

output_dir – the directory to save the downloaded artifact, defaults to None. If None, then the current working directory will be used.

file_stem – the file prefix or stem to use for the name of the downloaded file. Defaults to the value of “task-plugins”.

Returns

The response from the Dioptra API.