CRUD

The CRUD methods are used to create, read, update and delete extensions. There are two ways to use them. The first is through the SDK and the second is through the Project object. The syntax is the same for all CRUD methods. If you want to manage extensions from the project, you can use the Project object and avoid to specify the project parameter. In this last case, you need to specify every parameter as keyword argument.

Example:

import digitalhub as dh

project = dh.get_or_create_project("my-project")

# Use CRUD method on project

extension = project.new_extension(name="my-extension",
                                  kind="extension",
                                  schema='{"name": "string", "kind": "custom", "spec": {}}')

# Use CRUD method from SDK

extension = dh.new_extension(project="my-project",
                             name="my-extension",
                             kind="extension",
                             schema='{"name": "string", "kind": "custom", "spec": {}}')

An extension entity can be managed with the following methods.

Create:

new_extension

Read:

get_extension
get_extension_versions
import_extension
list_extensions

Update:

update_extension

Delete:

delete_extension

Create

You can create an extension with the new_extension() method. The kwargs parameters are determined by the kind of the object, and are described in the kinds section.

New

This function create a new entity and saves it into the backend.

`new_extension`

Parameters:

Name	Type	Description	Default
`project`	`str`	Project name.	required
`name`	`str`	Object name.	required
`kind`	`str`	Kind the object.	required
`uuid`	`str`	ID of the object.	`None`
`description`	`str`	Description of the object (human readable).	`None`
`labels`	`list[str]`	List of labels.	`None`
`embedded`	`bool`	Flag to determine if object spec must be embedded in project spec.	`False`
`schema`	`str`	Schema mapped to the extension.	`None`
`**kwargs`	`dict`	Spec keyword arguments.	`{}`

Returns:

Type	Description
`Extension`	Object instance.

Examples:

>>> obj = new_extension(project="my-project",
>>>                     name="my-extension",
>>>                     kind="extension",
>>>                     schema="my-schema")

Read

To read extensions you can use the get_extension(), get_extension_versions(), list_extensions() or import_extension() functions.

Get

This function searches for a single extension into the backend. If you want to collect an extension from the backend using get_extension(), you have two options:

The first one is to use the key parameter which has the pattern store://<project-name>/<entity-type>/<entity-kind>/<entity-name>:<entity-id>.
The second one is to use the entity name as identifier, the project name as project and the entity id as entity_id parameters. If you do not specify the entity id, you will get the latest version.

`get_extension`

Parameters:

Name	Type	Description	Default
`identifier`	`str`	Entity key (store://...) or entity name.	required
`project`	`str`	Project name.	`None`
`entity_id`	`str`	Entity ID.	`None`

Returns:

Type	Description
`Extension`	Object instance.

Examples:

Using entity key:

>>> obj = get_extension("store://my-extension-key")

Using entity name:

>>> obj = get_extension("my-extension-name",
>>>                     project="my-project",
>>>                     entity_id="my-extension-id")

Get versions

This function returns all the versions of an extension from the backend.

`get_extension_versions`

Parameters:

Name	Type	Description	Default
`identifier`	`str`	Entity key (store://...) or entity name.	required
`project`	`str`	Project name.	`None`

Returns:

Type	Description
`list[Extension]`	List of object instances.

Examples:

Using entity key:

>>> obj = get_extension_versions("store://my-extension-key")

Using entity name:

>>> obj = get_extension_versions("my-extension-name",
>>>                              project="my-project")

List

This function returns all the latest extensions from the backend related to a project.

`list_extensions`

Parameters:

Name	Type	Description	Default
`project`	`str`	Project name.	required
`q`	`str`	Query string to filter objects.	`None`
`name`	`str`	Object name.	`None`
`kind`	`str`	Kind of the object.	`None`
`user`	`str`	User that created the object.	`None`
`state`	`str`	Object state.	`None`
`created`	`str`	Creation date filter.	`None`
`updated`	`str`	Update date filter.	`None`
`versions`	`str`	Object version, default is latest.	`None`

Returns:

Type	Description
`list[Extension]`	List of object instances.

Examples:

>>> objs = list_extensions(project="my-project")

Import

This function load the extension from a local yaml file descriptor.

`import_extension`

Parameters:

Name	Type	Description	Default
`file`	`str`	Path to the YAML file.	`None`
`key`	`str`	Entity key (store://...).	`None`
`reset_id`	`bool`	Flag to determine if the ID of executable entities should be reset.	`False`
`context`	`str`	Project name to use for context resolution.	`None`

Returns:

Type	Description
`Extension`	Object instance.

Examples:

>>> obj = import_extension("my-extension.yaml")

Update

To update an extension you can use the update_extension() method.

`update_extension`

Parameters:

Name	Type	Description	Default
`entity`	`Extension`	Object to update.	required

Returns:

Type	Description
`Extension`	Entity updated.

Examples:

>>> obj = update_extension(obj)

Delete

To delete an extension you can use the delete_extension() method.

`delete_extension`

Parameters:

Name	Type	Description	Default
`identifier`	`str`	Entity key (store://...) or entity name.	required
`project`	`str`	Project name.	`None`
`entity_id`	`str`	Entity ID.	`None`
`delete_all_versions`	`bool`	Delete all versions of the named entity. If True, use entity name instead of entity key as identifier.	`False`
`cascade`	`bool`	Cascade delete.	`True`

Returns:

Type	Description
`dict`	Response from backend.

Examples:

If delete_all_versions is False:

>>> delete_extension("store://my-extension-key")

Otherwise:

>>> delete_extension("my-extension-name",
>>>                  project="my-project",
>>>                  delete_all_versions=True)