CLI Library

The Python CLI library is mainly useful to implement custom CLI commands. The provided functionality is usually less flexible in comparison with the regular Python library, but it also provides some built-in error handling and console output.

In general, its functionality can be used similarly to the regular Python library:

from kadi_apy import CLIKadiManager

manager = CLIKadiManager()

record = manager.record(id=1)
record.upload_file("/path/to/file.txt")

CLIKadiManager

class kadi_apy.cli.core.CLIKadiManager(verbose=Verbose.INFO, **kwargs)[source]

Bases: KadiManager, RaiseRequestErrorMixin

Kadi Manager for the command line interface (CLI).

Parameters:

instance (str, optional) – The name of the instance to use in combination with a config file.
host (str, optional) – Name of the host.
token (str, optional) – Personal access token.
verify (bool, optional) – Whether to verify the SSL/TLS certificate of the host.
timeout (float, optional) – Timeout in seconds for the requests.
verbose (optional) – Global verbose level to define the amount of prints.

property misc: Central entry point for miscellaneous functionality.

property search: Central entry point for search functionality.

record(use_base_resource=False, **kwargs)[source]

Init a record to be used in a CLI.

Parameters:: use_base_resource (bool) – Flag indicating if the base resource should be used.
Returns:: The record of class Record or CLIRecord.
Return type:: Record, CLIRecord
Raises:: KadiAPYRequestError – If initializing the record was not successful.

collection(use_base_resource=False, **kwargs)[source]

Init a collection to be used in a CLI.

Parameters:: use_base_resource (bool) – Flag indicating if the base resource should be used.
Returns:: The collection of class Collection or CLICollection.
Return type:: Collection, CLICollection
Raises:: KadiAPYRequestError – If initializing the collection was not successful.

template(use_base_resource=False, **kwargs)[source]

Init a template to be used in a CLI.

Parameters:: use_base_resource (bool) – Flag indicating if the base resource should be used.
Returns:: The template of class Template or CLITemplate.
Return type:: Template, CLITemplate
Raises:: KadiAPYRequestError – If initializing the template was not successful.

group(use_base_resource=False, **kwargs)[source]

Init a group to be used in a CLI.

Parameters:: use_base_resource (bool) – Flag indicating if the base resource should be used.
Returns:: The group of class Group or CLIGroup.
Return type:: Group, CLIGroup
Raises:: KadiAPYRequestError – If initializing the group was not successful.

user(use_base_resource=False, **kwargs)[source]

Init a user to be used in a CLI.

Parameters:: use_base_resource (bool) – Flag indicating if the base resource should be used.
Returns:: The user of class User or CLIUser.
Return type:: User, CLIUser
Raises:: KadiAPYRequestError – If initializing the user was not successful.

debug(text, **kwargs)

Print text for debug level.

Parameters:

text – Text to be printed via click.echo().
**kwargs – Additional arguments to pass to click.echo().

Return type:

echo()

echo(text, verbose_level, **kwargs)

Print text via click.echo() if global verbose level is reached.

Parameters:

text (str) – Text to be printed via click.echo().
verbose_level – Verbose level.
**kwargs – Additional arguments to pass to click.echo().

error(text, **kwargs)

Print text for error level.

Parameters:

text – Text to be printed via click.echo().
**kwargs – Additional arguments to pass to click.echo().

Return type:

echo()

info(text, **kwargs)

Print text for info level.

Parameters:

text – Text to be printed via click.echo().
**kwargs – Additional arguments to pass to click.echo().

Return type:

echo()

is_verbose(verbose_level=Verbose.INFO)

Check the verbose level.

Parameters:: verbose_level – Local verbose level of the function.
Returns:: True if verbose level is reached, False otherwise.
Return type:: bool

make_request(endpoint, method='get', **kwargs)

Low level functionality to perform a request.

This function can be used to use endpoints for which no own functions exist yet.

Parameters:

endpoint (str) – Endpoint to use for the request.
method (str, optional) – Method to use for the request. One of "get", "post", "patch", "put" or "delete".
**kwargs – Additional arguments for the request.

Raises:

KadiAPYInputError – If the specified method is invalid.
KadiAPYRequestError – If the server answered with an invalid redirection.

property pat_user

Get the user related to the PAT.

Returns:: The user.
Return type:: User

raise_request_error(response)

Raise exception.

Parameters:: response – The response.
Raises:: KadiAPYRequestError – Error is raised since request was not successful.

warning(text, **kwargs)

Print text for warning level.

Parameters:

text – Text to be printed via click.echo().
**kwargs – Additional arguments to pass to click.echo().

Return type:

echo()

CLIRecord

class kadi_apy.cli.lib.records.CLIRecord(pipe=False, title=None, create=False, exit_not_created=False, **kwargs)[source]

Bases: BasicCLIMixin, UserCLIMixin, GroupRoleCLIMixin, TagCLIMixin, DeleteItemCLIMixin, ExportCLIMixin, Record, RaiseRequestErrorMixin

Records class to be used in a CLI.

Parameters:

manager (CLIKadiManager) – Manager to use for all API requests.
id (int, optional) – The ID of an existing resource.
identifier (str, optional) – The unique identifier of a new or existing resource, which is only relevant if no ID was given. If present, the identifier will be used to check for an existing resource instead. If no existing resource could be found or the resource to check does not use a unique identifier, it will be used to create a new resource instead, together with the additional metadata.
skip_request (bool, optional) – Flag to skip the initial request.
create (bool, optional) – Flag to determine if a resource should be created in case a identifier is given and the resource does not exist.
pipe (bool, optional) – Flag to indicate if only the id should be printed which can be used for piping.
title (str, optional) – Title of the new resource.
exit_not_created (bool, optional) – Flag to indicate if the function should exit with sys.exit(1) if the resource is not created.

upload_file(file_name, file_description=None, pattern=None, exclude_pattern=None, force=False)[source]

Upload files into a record using the CLI.

Parameters:

file_name (str) – The path to the file (incl. name of the file) or folder.
file_description (str, optional) – The description of a single file.
pattern (str, optional) – Pattern for selecting files matching certain pattern.
exclude_pattern (str, optional) – Pattern for excluding files matching certain pattern.
force (bool, optional) – Whether to replace an existing file with identical name.

Raises:

KadiAPYRequestError – If request was not successful.

upload_string_to_file(string, file_name, file_description=None, force=False)[source]

Upload a string to save as a file in a record using the CLI.

Parameters:

string (str) – The string to save as a file.
file_name (str) – The name under which the file should be stored.
file_description (str, optional) – The description of the file.
force (bool, optional) – Whether to replace an existing file with identical name.

Raises:

KadiAPYRequestError – If request was not successful.

add_metadatum(metadatum_new, force=False)[source]

Add a metadatum to a record using the CLI.

Parameters:

metadatum_new (dict) – The metadatum to add.
force (bool) – Whether to overwrite the metadatum with the new value in case the metadatum already exists.

Raises:

KadiAPYRequestError – If request was not successful.

add_metadata(metadata=None, file=None, force=False)[source]

Add metadata with dict or a list of dicts as input using the CLI.

Either specify the metadata via a file to be read from or via metadata.

Parameters:

metadata (dict, list) – One or more metadata entries to add, either as dictionary or a list of dictionaries.
file (dict, list) – File path to read the metadata from.
force (bool) – Whether to overwrite existing metadata with identical name.

Raises:

KadiAPYRequestError – If request was not successful.

get_file(filepath, force=False, file_id=None, pattern=None, exclude_pattern=None, use_folder=False, pipe=False)[source]

Download one file, all files or files matching a pattern from a record using the CLI.

If a file ID is given, the specified file is download. Otherwise all files or all files matching the pattern are downloaded.

Parameters:

filepath (str) – The path to folder to store the file.
force (bool, optional) – Whether to overwrite a file with identical name.
file_id (bool, optional) – The file ID (UUID) of a file to download.
pattern (str, optional) – Pattern for selecting files matching certain pattern.
exclude_pattern (str, optional) – Pattern for selecting files matching certain pattern.
use_folder (bool, optional) – Flag indicating if the a folder with the name of the records’s identifier should be created within given filepath. The downloaded file(s) are stored in this folder.

Returns:

A list of downloaded files with file path.

Type:

list

Raises:

KadiAPYRequestError – If request was not successful.

link_record(record_to, name, term_iri=None)[source]

Add a record link to a record using the CLI.

Parameters:

record_to (record) – The record to link.
name (str) – The name of the link.
term_iri (str) – An IRI specifying an existing term that the link should represent.

Raises:

KadiAPYRequestError – If request was not successful.

delete_record_link(record_link_id)[source]

Delete a record link using the CLI.

Parameters:: record_link_id (int) – The ID of the record link to delete. Attention: The record link ID is not the record ID.
Raises:: KadiAPYRequestError – If request was not successful.

get_record_links(page, per_page, direction)[source]

Print record links to another record using the CLI.

Parameters:

page (int) – Page of the search request.
per_page (int) – Number of results per page.
direction (str) – Specify whether to print incoming or outcoming links

Raises:

KadiAPYRequestError – If request was not successful.

get_metadatum(name, information='value', pipe=False)[source]

Print information of a specific metadatum using the CLI.

Parameters:

name (str or list) – See Record.get_metadatum().
information (str, optional) – The information of the metadatum to print.
pipe (bool) – Whether to only print the result for piping.

Raises:

KadiAPYRequestError – If request was not successful.

edit_file(file, name, mimetype)[source]

Edit the metadata of a file of a record using the CLI.

Parameters:

file (str) – The ID (UUID) of the file to edit.
name (str) – The new name of the file.
mimetype (str) – The new mimetype of the file.

Raises:

KadiAPYRequestError – If request was not successful.

delete_file(file_id)[source]

Delete a file of the record using the CLI.

Parameters:: file_id (str) – The ID (UUID) of the file to delete.
Raises:: KadiAPYRequestError – If request was not successful.

delete_files(i_am_sure=False)[source]

Delete all files of a record using the CLI.

Parameters:

i_am_sure (bool) – Flag which has to set to True to delete all files.

Raises:

KadiAPYInputError – If i_am_sure is not True.
KadiAPYRequestError – If request was not successful.

remove_metadatum(metadatum)[source]

Delete a metadatum of a record using the CLI.

Only first level metadata are supported (no nested types).

Parameters:: metadatum (str) – The metadatum to remove.
Raises:: KadiAPYRequestError – If request was not successful.

remove_all_metadata(i_am_sure=False)[source]

Remove all metadata from a record.

Parameters:: i_am_sure (bool) – Flag which has to set to True to remove all metadata.
Raises:: KadiAPYRequestError – If request was not successful.

add_collection_link(collection)[source]

Add a record to a collection using the CLI.

Parameters:: collection (Collection) – The collection to which the record should be added.
Raises:: KadiAPYRequestError – If request was not successful.

remove_collection_link(collection)[source]

Remove a record from a collection using the CLI.

Parameters:: collection (Collection) – The collection from which the record should be removed.
Raises:: KadiAPYRequestError – If request was not successful.

update_record_link(record_link_id, name)[source]

Update the name of a record link using the CLI.

Parameters:

record_link_id (int) – The ID of the record link to update. Attention: The record link ID is not the record ID.
name (str) – The name of the link.

Raises:

KadiAPYRequestError – If request was not successful.

print_info(pipe=False, **kwargs)[source]

Print infos of a record using the CLI.

Parameters:: **kwargs – Specify additional infos to print.
Raises:: KadiAPYRequestError: If request was not successful

add_group_role(group, permission_new)

Add a group role.

Parameters:

group (Group) – The group to add.
permission_new (str) – Role of the group.

Raises:

KadiAPYRequestError: If request was not successful.

add_tag(tag)

Add a tag using a CLI.

Parameters:: tag (str) – The tag to add.
Raises:: KadiAPYRequestError – If request was not successful.

add_user(user, permission_new)

Add a user.

Parameters:

user (User) – The user to add.
permission_new (str) – Role of the user.

Raises:

KadiAPYRequestError: If request was not successful.

change_group_role(group_id, role_name)

Change group role.

Parameters:

group_id (int) – The ID of the group whose role should be changed.
role_name (str) – Name of the new role.

Returns:

The response object.

change_user_role(user_id, role_name)

Change user role.

Parameters:

user_id (int) – The ID of the user whose role should be changed.
role_name (str) – Name of the new role.

Returns:

The response object.

check_metadatum(metadatum)

Check if a record has a certain metadatum.

Does currently not support metadata in nested types.

Parameters:: metadatum (str) – The metadatum to check.
Returns:: True if the metadatum exists, otherwise False.
Return type:: bool

check_tag(tag)

Check if a certain tag is already present.

Parameters:: tag (str) – The tag to check.
Returns:: True if tag already exists, otherwise False.
Return type:: bool

debug(text, **kwargs)

Print text for debug level.

Parameters:

text (str) – Text to be printed via click.echo().
**kwargs – Additional arguments to pass to click.echo().

delete(i_am_sure)

Delete the resource using a CLI.

Parameters:

i_am_sure (bool) – Flag which has to set to True to delete the resource.

Raises:

KadiAPYInputError – If i_am_sure is not True.
KadiAPYRequestError – If request was not successful.

download_all_files(file_path)

Download all files of a record as ZIP archive.

Parameters:: file_path (str) – The full path to store the archive.
Returns:: The response object.

download_file(file_id, file_path)

Download a file of a record.

Parameters:

file_id (str) – The file ID of the file to download.
file_path (str) – The full path to store the file.

Returns:

The response object.

edit(**kwargs)

Edit the metadata of the resource.

Parameters:: **kwargs – The updated metadata of the resource.
Returns:: The response object.

error(text, **kwargs)

Print text for error level.

Parameters:

text (str) – Text to be printed via click.echo().
**kwargs – Additional arguments to pass to click.echo().

export(export_type, path='.', name=None, force=False, pipe=False, use_folder=False, **params)

Export the resource using a specific export type using the CLI.

Parameters:

export_type (str) – The export format.
path (str, optional) – The path to store.
name (str, optional) – The name of the file. The identifier is uses as default.
force (bool, optional) – Whether to replace an existing file with identical name.
pipe (bool, optional) – Flag to indicate if json should be piped.
use_folder – Flag indicating if the a folder with the name of the resource’s identifier should be created within given path. The exported file is stored in this folder.
**params – Additional query parameters.

Raises:

KadiAPYInputError – If export type is invalid or if not json is used as input type togehter with pipe.
KadiAPYRequestError – If request was not successful.

flatten_extras(separator='.')

Create a list of flatted metadata.

Parameters:: separator (str, optional) – A string for separating the metadata.
Returns:: A list of flatted metadata.
Return type:: list

get_collection_links(**params)

Get collection links. Supports pagination.

Parameters:: **params – Additional query parameters.
Returns:: The response object.

get_file_id(file_name)

Get the file ID based on the file name.

Parameters:: file_name (str) – The name of the file.
Returns:: The file ID (UUID).
Return type:: str
Raises:: KadiAPYInputError – If no file with the given name exists.

get_file_info(file_id)

Get information of a file based on the file_id.

Parameters:: file_id (str) – The ID of the file.
Returns:: The response object.

get_file_name(file_id)

Get file name from a given file ID.

Parameters:: file_id – The ID of the file.
Returns:: The name of the file.
Return type:: str
Raises:: KadiAPYInputError – If no file with the given file ID exists.

get_file_revision(revision_id, **params)

Get a specific file revision of a file in this record.

Parameters:

revision_id (int) – The revision ID of the file.
**params – Additional query parameters.

Returns:

The response object.

get_file_revisions(**params)

Get the file revisions of a file in this record.

Parameters:: **params – Additional query parameters.
Returns:: The response object.

get_filelist(**params)

Get the filelist. Supports pagination.

Parameters:: **params – Additional query parameters.
Returns:: The response object.

get_groups(**params)

Get group roles from a record. Supports pagination.

Parameters:: **params – Additional query parameters.
Returns:: The response object.

get_number_files()

Get number of all files of a record.

Returns:: The number of files.
Return type:: int
Raises:: KadiAPYRequestError – If request was not successful.

get_record_revision(revision_id, **params)

Get a specific revision of this record.

Parameters:

revision_id (int) – The revision ID of the record.
**params – Additional query parameters.

Returns:

The response object.

get_record_revisions(**params)

Get the revisions of this record.

Parameters:: **params – Additional query parameters.
Returns:: The response object.

get_tags()

Get tags.

Returns:: A list of all tags.
Type:: list

get_users(**params)

Get users from a record. Supports pagination.

Parameters:: **params – Additional query parameters.
Returns:: The response object.

has_file(file_name)

Check if file with the given name already exists.

Parameters:: file_name (str) – The name of the file.
Returns:: True if file already exists, otherwise False.

info(text, **kwargs)

Print text for info level.

Parameters:

text (str) – Text to be printed via click.echo().
**kwargs – Additional arguments to pass to click.echo().

is_verbose(**kwargs)

Check the verbose level.

Returns:: See KadiManager.is_verbose().

property meta

Get all metadata of the resource.

In case the previous metadata was invalidated, either manually, after a timeout or due to another request, a request will be sent to retrieve the possibly updated metadata again.

Returns:: The metadata of the resource.
Raises:: KadiAPYRequestError – If requesting the metadata was not successful.

raise_request_error(response)

Raise exception.

Parameters:: response – The response.
Raises:: KadiAPYRequestError – Error is raised since request was not successful.

remove_group_role(group)

Remove a group role.

Parameters:: group (Group) – The group to remove.
Raises:: KadiAPYRequestError: If request was not successful.

remove_tag(tag)

Remove a tag using a CLI.

Parameters:: tag (str) – The tag to remove.
Raises:: KadiAPYRequestError – If request was not successful.

remove_user(user)

Remove a user.

Parameters:: user (User) – The user to remove.
Raises:: KadiAPYRequestError: If request was not successful.

set_attribute(**kwargs)

Set attribute using a CLI.

Parameters:: **kwargs – The attributes and values to set.
Raises:: KadiAPYRequestError – If request was not successful.

warning(text, **kwargs)

Print text for warning level.

Parameters:

text (str) – Text to be printed via click.echo().
**kwargs – Additional arguments to pass to click.echo().

CLICollection

class kadi_apy.cli.lib.collections.CLICollection(pipe=False, title=None, create=False, exit_not_created=False, **kwargs)[source]

Bases: BasicCLIMixin, UserCLIMixin, GroupRoleCLIMixin, TagCLIMixin, DeleteItemCLIMixin, ExportCLIMixin, Collection, RaiseRequestErrorMixin

Collection class to be used in a CLI.

Parameters:

manager (CLIKadiManager) – Manager to use for all API requests.
id (int, optional) – The ID of an existing resource.
identifier (str, optional) – The unique identifier of a new or existing resource, which is only relevant if no ID was given. If present, the identifier will be used to check for an existing resource instead. If no existing resource could be found or the resource to check does not use a unique identifier, it will be used to create a new resource instead, together with the additional metadata.
skip_request (bool, optional) – Flag to skip the initial request.
create (bool, optional) – Flag to determine if a resource should be created in case a identifier is given and the resource does not exist.
pipe (bool, optional) – Flag to indicate if only the id should be printed which can be used for piping.
title (str, optional) – Title of the new resource.
exit_not_created (bool, optional) – Flag to indicate if the function should exit with sys.exit(1) if the resource is not created.

add_record_link(record_to)[source]

Add a record to a collection using a CLI.

Parameters:: record_to (Record) – The the record to add.
Raises:: KadiAPYRequestError – If request was not successful.

remove_record_link(record)[source]

Remove a record from a collection using a CLI.

Parameters:: record (Record) – The record to remove.
Raises:: KadiAPYRequestError – If request was not successful.

add_collection_link(child_collection)[source]

Add a child collection to a parent collection using CLI.

Parameters:: child_collection (Collection) – The child collection to which the parent collection should be added.
Raises:: KadiAPYRequestError – If request was not successful.

remove_collection_link(child_collection)[source]

Remove a child collection from a parent collection using CLI.

Parameters:: child_collection (Collection) – The child collection to remove from the parent collection.
Raises:: KadiAPYRequestError – If request was not successful.

print_info(pipe=False, **kwargs)[source]

Print infos of a collection using the CLI.

Parameters:: **kwargs – Specify additional infos to print.
Raises:: KadiAPYRequestError: If request was not successful

add_group_role(group, permission_new)

Add a group role.

Parameters:

group (Group) – The group to add.
permission_new (str) – Role of the group.

Raises:

KadiAPYRequestError: If request was not successful.

add_tag(tag)

Add a tag using a CLI.

Parameters:: tag (str) – The tag to add.
Raises:: KadiAPYRequestError – If request was not successful.

add_user(user, permission_new)

Add a user.

Parameters:

user (User) – The user to add.
permission_new (str) – Role of the user.

Raises:

KadiAPYRequestError: If request was not successful.

change_group_role(group_id, role_name)

Change group role.

Parameters:

group_id (int) – The ID of the group whose role should be changed.
role_name (str) – Name of the new role.

Returns:

The response object.

change_user_role(user_id, role_name)

Change user role.

Parameters:

user_id (int) – The ID of the user whose role should be changed.
role_name (str) – Name of the new role.

Returns:

The response object.

check_tag(tag)

Check if a certain tag is already present.

Parameters:: tag (str) – The tag to check.
Returns:: True if tag already exists, otherwise False.
Return type:: bool

debug(text, **kwargs)

Print text for debug level.

Parameters:

text (str) – Text to be printed via click.echo().
**kwargs – Additional arguments to pass to click.echo().

delete(i_am_sure)

Delete the resource using a CLI.

Parameters:

i_am_sure (bool) – Flag which has to set to True to delete the resource.

Raises:

KadiAPYInputError – If i_am_sure is not True.
KadiAPYRequestError – If request was not successful.

edit(**kwargs)

Edit the metadata of the resource.

Parameters:: **kwargs – The updated metadata of the resource.
Returns:: The response object.

error(text, **kwargs)

Print text for error level.

Parameters:

text (str) – Text to be printed via click.echo().
**kwargs – Additional arguments to pass to click.echo().

export(export_type, path='.', name=None, force=False, pipe=False, use_folder=False, **params)

Export the resource using a specific export type using the CLI.

Parameters:

export_type (str) – The export format.
path (str, optional) – The path to store.
name (str, optional) – The name of the file. The identifier is uses as default.
force (bool, optional) – Whether to replace an existing file with identical name.
pipe (bool, optional) – Flag to indicate if json should be piped.
use_folder – Flag indicating if the a folder with the name of the resource’s identifier should be created within given path. The exported file is stored in this folder.
**params – Additional query parameters.

Raises:

KadiAPYInputError – If export type is invalid or if not json is used as input type togehter with pipe.
KadiAPYRequestError – If request was not successful.

get_collection_revision(revision_id, **params)

Get a specific revision of this collection.

Parameters:

revision_id (int) – The revision ID of the collection.
**params – Additional query parameters.

Returns:

The response object.

get_collection_revisions(**params)

Get the revisions of this collection.

Parameters:: **params – Additional query parameters.
Returns:: The response object.

get_collections(**params)

Get collections linked with a collection id.

Parameters:: **params – Additional query parameters.
Returns:: The response object.

get_groups(**params)

Get group roles from a collection. Supports pagination.

Parameters:: **params – Additional query parameters.
Returns:: The response object.

get_records(**params)

Get records from a collection. Supports pagination.

Parameters:: **params – Additional query parameters.
Returns:: The response object.

get_tags()

Get tags.

Returns:: A list of all tags.
Type:: list

get_users(**params)

Get user of a collection. Supports pagination.

Parameters:: **params – Additional query parameters.
Returns:: The response object.

info(text, **kwargs)

Print text for info level.

Parameters:

text (str) – Text to be printed via click.echo().
**kwargs – Additional arguments to pass to click.echo().

is_verbose(**kwargs)

Check the verbose level.

Returns:: See KadiManager.is_verbose().

property meta

Get all metadata of the resource.

In case the previous metadata was invalidated, either manually, after a timeout or due to another request, a request will be sent to retrieve the possibly updated metadata again.

Returns:: The metadata of the resource.
Raises:: KadiAPYRequestError – If requesting the metadata was not successful.

raise_request_error(response)

Raise exception.

Parameters:: response – The response.
Raises:: KadiAPYRequestError – Error is raised since request was not successful.

remove_group_role(group)

Remove a group role.

Parameters:: group (Group) – The group to remove.
Raises:: KadiAPYRequestError: If request was not successful.

remove_tag(tag)

Remove a tag using a CLI.

Parameters:: tag (str) – The tag to remove.
Raises:: KadiAPYRequestError – If request was not successful.

remove_user(user)

Remove a user.

Parameters:: user (User) – The user to remove.
Raises:: KadiAPYRequestError: If request was not successful.

set_attribute(**kwargs)

Set attribute using a CLI.

Parameters:: **kwargs – The attributes and values to set.
Raises:: KadiAPYRequestError – If request was not successful.

warning(text, **kwargs)

Print text for warning level.

Parameters:

text (str) – Text to be printed via click.echo().
**kwargs – Additional arguments to pass to click.echo().

CLITemplate

class kadi_apy.cli.lib.templates.CLITemplate(pipe=False, title=None, create=False, exit_not_created=False, **kwargs)[source]

Bases: BasicCLIMixin, DeleteItemCLIMixin, ExportCLIMixin, UserCLIMixin, GroupRoleCLIMixin, Template, RaiseRequestErrorMixin

Template class to be used in a CLI.

Parameters:

manager (CLIKadiManager) – Manager to use for all API requests.
type (str) – Type of the template. Can either be record or extras.
data – Dict in case of a record template or a list in case of a extras template containing the content for the template.
id (int, optional) – The ID of an existing resource.
identifier (str, optional) – The unique identifier of a new or existing resource, which is only relevant if no ID was given. If present, the identifier will be used to check for an existing resource instead. If no existing resource could be found or the resource to check does not use a unique identifier, it will be used to create a new resource instead, together with the additional metadata.
skip_request (bool, optional) – Flag to skip the initial request.
create (bool, optional) – Flag to determine if a resource should be created in case a identifier is given and the resource does not exist.
pipe (bool, optional) – Flag to indicate if only the id should be printed which can be used for piping.
title (str, optional) – Title of the new resource.
exit_not_created (bool, optional) – Flag to indicate if the function should exit with sys.exit(1) if the resource is not created.

add_group_role(group, permission_new)

Add a group role.

Parameters:

group (Group) – The group to add.
permission_new (str) – Role of the group.

Raises:

KadiAPYRequestError: If request was not successful.

add_user(user, permission_new)

Add a user.

Parameters:

user (User) – The user to add.
permission_new (str) – Role of the user.

Raises:

KadiAPYRequestError: If request was not successful.

change_group_role(group_id, role_name)

Change group role.

Parameters:

group_id (int) – The ID of the group whose role should be changed.
role_name (str) – Name of the new role.

Returns:

The response object.

change_user_role(user_id, role_name)

Change user role.

Parameters:

user_id (int) – The ID of the user whose role should be changed.
role_name (str) – Name of the new role.

Returns:

The response object.

debug(text, **kwargs)

Print text for debug level.

Parameters:

text (str) – Text to be printed via click.echo().
**kwargs – Additional arguments to pass to click.echo().

delete(i_am_sure)

Delete the resource using a CLI.

Parameters:

i_am_sure (bool) – Flag which has to set to True to delete the resource.

Raises:

KadiAPYInputError – If i_am_sure is not True.
KadiAPYRequestError – If request was not successful.

edit(**kwargs)

Edit the metadata of the resource.

Parameters:: **kwargs – The updated metadata of the resource.
Returns:: The response object.

error(text, **kwargs)

Print text for error level.

Parameters:

text (str) – Text to be printed via click.echo().
**kwargs – Additional arguments to pass to click.echo().

export(export_type, path='.', name=None, force=False, pipe=False, use_folder=False, **params)

Export the resource using a specific export type using the CLI.

Parameters:

export_type (str) – The export format.
path (str, optional) – The path to store.
name (str, optional) – The name of the file. The identifier is uses as default.
force (bool, optional) – Whether to replace an existing file with identical name.
pipe (bool, optional) – Flag to indicate if json should be piped.
use_folder – Flag indicating if the a folder with the name of the resource’s identifier should be created within given path. The exported file is stored in this folder.
**params – Additional query parameters.

Raises:

KadiAPYInputError – If export type is invalid or if not json is used as input type togehter with pipe.
KadiAPYRequestError – If request was not successful.

get_groups(**params)

Get group roles from a template. Supports pagination.

Parameters:: **params – Additional query parameters.
Returns:: The response object.

get_template_revision(revision_id, **params)

Get a specific revision of this template.

Parameters:

revision_id (int) – The revision ID of the template.
**params – Additional query parameters.

Returns:

The response object.

get_template_revisions(**params)

Get the revisions of this template.

Parameters:: **params – Additional query parameters.
Returns:: The response object.

get_users(**params)

Get users from a template. Supports pagination.

Parameters:: **params – Additional query parameters.
Returns:: The response object.

info(text, **kwargs)

Print text for info level.

Parameters:

text (str) – Text to be printed via click.echo().
**kwargs – Additional arguments to pass to click.echo().

is_verbose(**kwargs)

Check the verbose level.

Returns:: See KadiManager.is_verbose().

property meta

Get all metadata of the resource.

In case the previous metadata was invalidated, either manually, after a timeout or due to another request, a request will be sent to retrieve the possibly updated metadata again.

Returns:: The metadata of the resource.
Raises:: KadiAPYRequestError – If requesting the metadata was not successful.

print_info(pipe=False, **kwargs)

Print infos using a CLI.

Parameters:: **kwargs – Specify additional infos to print.
Raises:: KadiAPYRequestError – If request was not successful.

raise_request_error(response)

Raise exception.

Parameters:: response – The response.
Raises:: KadiAPYRequestError – Error is raised since request was not successful.

remove_group_role(group)

Remove a group role.

Parameters:: group (Group) – The group to remove.
Raises:: KadiAPYRequestError: If request was not successful.

remove_user(user)

Remove a user.

Parameters:: user (User) – The user to remove.
Raises:: KadiAPYRequestError: If request was not successful.

set_attribute(**kwargs)

Set attribute using a CLI.

Parameters:: **kwargs – The attributes and values to set.
Raises:: KadiAPYRequestError – If request was not successful.

warning(text, **kwargs)

Print text for warning level.

Parameters:

text (str) – Text to be printed via click.echo().
**kwargs – Additional arguments to pass to click.echo().

CLIGroup

class kadi_apy.cli.lib.groups.CLIGroup(pipe=False, title=None, create=False, exit_not_created=False, **kwargs)[source]

Bases: BasicCLIMixin, UserCLIMixin, DeleteItemCLIMixin, Group, RaiseRequestErrorMixin

Group class to be used in a CLI.

Parameters:

manager (CLIKadiManager) – Manager to use for all API requests.
id (int, optional) – The ID of an existing resource.
identifier (str, optional) – The unique identifier of a new or existing resource, which is only relevant if no ID was given. If present, the identifier will be used to check for an existing resource instead. If no existing resource could be found or the resource to check does not use a unique identifier, it will be used to create a new resource instead, together with the additional metadata.
skip_request (bool, optional) – Flag to skip the initial request.
create (bool, optional) – Flag to determine if a resource should be created in case a identifier is given and the resource does not exist.
pipe (bool, optional) – Flag to indicate if only the id should be printed which can be used for piping.
title (str, optional) – Title of the new resource.
exit_not_created (bool, optional) – Flag to indicate if the function should exit with sys.exit(1) if the resource is not created.

add_user(user, permission_new)

Add a user.

Parameters:

user (User) – The user to add.
permission_new (str) – Role of the user.

Raises:

KadiAPYRequestError: If request was not successful.

change_user_role(user_id, role_name)

Change role of a user.

Parameters:

user_id (int) – The ID of the user whose role should be changed.
role_name (str) – Name of the new role.

Returns:

The response object.

debug(text, **kwargs)

Print text for debug level.

Parameters:

text (str) – Text to be printed via click.echo().
**kwargs – Additional arguments to pass to click.echo().

delete(i_am_sure)

Delete the resource using a CLI.

Parameters:

i_am_sure (bool) – Flag which has to set to True to delete the resource.

Raises:

KadiAPYInputError – If i_am_sure is not True.
KadiAPYRequestError – If request was not successful.

edit(**kwargs)

Edit the metadata of the resource.

Parameters:: **kwargs – The updated metadata of the resource.
Returns:: The response object.

error(text, **kwargs)

Print text for error level.

Parameters:

text (str) – Text to be printed via click.echo().
**kwargs – Additional arguments to pass to click.echo().

get_collections(**params)

Get collections shared with a group. Supports pagination.

Parameters:: **params – Additional query parameters.
Returns:: The response object.

get_group_revision(revision_id, **params)

Get a specific revision from this group.

Parameters:

revision_id (int) – The revision ID of the group.
**params – Additional query parameters.

Returns:

The response object.

get_group_revisions(**params)

Get the revisions of this group.

Parameters:: **params – Additional query parameters.
Returns:: The response object.

get_records(**params)

Get records shared with a group. Supports pagination.

Parameters:: **params – Additional query parameters.
Returns:: The response object.

get_templates(**params)

Get templates shared with a group. Supports pagination.

Parameters:: **params – Additional query parameters.
Returns:: The response object.

get_users(**params)

Get users of a group. Supports pagination.

Parameters:: **params – Additional query parameters.
Returns:: The response object.

info(text, **kwargs)

Print text for info level.

Parameters:

text (str) – Text to be printed via click.echo().
**kwargs – Additional arguments to pass to click.echo().

is_verbose(**kwargs)

Check the verbose level.

Returns:: See KadiManager.is_verbose().

property meta

Get all metadata of the resource.

In case the previous metadata was invalidated, either manually, after a timeout or due to another request, a request will be sent to retrieve the possibly updated metadata again.

Returns:: The metadata of the resource.
Raises:: KadiAPYRequestError – If requesting the metadata was not successful.

print_info(pipe=False, **kwargs)

Print infos using a CLI.

Parameters:: **kwargs – Specify additional infos to print.
Raises:: KadiAPYRequestError – If request was not successful.

raise_request_error(response)

Raise exception.

Parameters:: response – The response.
Raises:: KadiAPYRequestError – Error is raised since request was not successful.

remove_user(user)

Remove a user.

Parameters:: user (User) – The user to remove.
Raises:: KadiAPYRequestError: If request was not successful.

set_attribute(**kwargs)

Set attribute using a CLI.

Parameters:: **kwargs – The attributes and values to set.
Raises:: KadiAPYRequestError – If request was not successful.

warning(text, **kwargs)

Print text for warning level.

Parameters:

text (str) – Text to be printed via click.echo().
**kwargs – Additional arguments to pass to click.echo().

CLIUser

class kadi_apy.cli.lib.users.CLIUser(manager, id=None, username=None, identity_type=None, use_pat=False)[source]

Bases: User, RaiseRequestErrorMixin

User class to be used in a CLI.

A user can either be clearly identified via its id or the combination of username and identity type.

Parameters:

manager (CLIManager) – Manager to use for all API requests.
id (int, optional) – The ID of an existing user.
username (str, optional) – The username.
identity_type (str, optional) – The identity type of the user.
use_pat (bool, optional) – Flag to indicate that the pat stored in the CLIKadiManager should be used for instantiating the user.

Raises:

KadiAPYRequestError – If retrieving the user was not successful.

print_info()[source]: Print user infos using a CLI.

debug(text, **kwargs)

Print text for debug level.

Parameters:

text (str) – Text to be printed via click.echo().
**kwargs – Additional arguments to pass to click.echo().

error(text, **kwargs)

Print text for error level.

Parameters:

text (str) – Text to be printed via click.echo().
**kwargs – Additional arguments to pass to click.echo().

info(text, **kwargs)

Print text for info level.

Parameters:

text (str) – Text to be printed via click.echo().
**kwargs – Additional arguments to pass to click.echo().

is_verbose(**kwargs)

Check the verbose level.

Returns:: See KadiManager.is_verbose().

property meta

Get all metadata of the resource.

In case the previous metadata was invalidated, either manually, after a timeout or due to another request, a request will be sent to retrieve the possibly updated metadata again.

Returns:: The metadata of the resource.
Raises:: KadiAPYRequestError – If requesting the metadata was not successful.

raise_request_error(response)

Raise exception.

Parameters:: response – The response.
Raises:: KadiAPYRequestError – Error is raised since request was not successful.

warning(text, **kwargs)

Print text for warning level.

Parameters:

text (str) – Text to be printed via click.echo().
**kwargs – Additional arguments to pass to click.echo().

CLIMiscellaneous

class kadi_apy.cli.lib.misc.CLIMiscellaneous(manager)[source]

Bases: Miscellaneous, RaiseRequestErrorMixin

Model to handle miscellaneous functionality.

Parameters:: manager (CLIKadiManager) – Manager to use for all API requests.

get_deleted_resources(**params)[source]

Get a list of deleted resources in the trash using the CLI.

Supports pagination.

Parameters:: **params – Additional query parameters.
Raises:: KadiAPYRequestError – If request was not successful.

restore(item, item_id)[source]

Restore an item from the trash using the CLI.

Parameters:

item – The resource type defined as class.
item_id (int) – The ID of the item to restore.

Raises:

KadiAPYRequestError – If request was not successful.

purge(item, item_id)[source]

Purge an item from the trash using the CLI.

Parameters:

item – The resource type defined as class or string.
item_id (int) – The ID of the item to restore.

Raises:

KadiAPYRequestError – If request was not successful.

get_licenses(**params)[source]

Get a list of available licenses using the CLI.

Parameters:: **params – Additional query parameters.
Raises:: KadiAPYRequestError – If request was not successful.

get_kadi_info(manager)[source]

Print information about the Kadi instance and the config file.

Parameters:: manager (KadiManager, CLIKadiManager) – Used Manager.
Raises:: KadiAPYRequestError – If request was not successful.

get_roles(item_type=None)[source]

Get a list of all possible roles.

Print all possible roles and corresponding permissions of all resources or of one resource.

Parameters:: item_type (str, optional) – Type of resource for printing roles and permissions.
Raises:: KadiAPYRequestError – If request was not successful.

get_tags(**params)[source]

Get a list of all available tags using the CLI.

Parameters:: **params – Additional query parameters.
Raises:: KadiAPYRequestError – If request was not successful.

debug(text, **kwargs)

Print text for debug level.

Parameters:

text (str) – Text to be printed via click.echo().
**kwargs – Additional arguments to pass to click.echo().

error(text, **kwargs)

Print text for error level.

Parameters:

text (str) – Text to be printed via click.echo().
**kwargs – Additional arguments to pass to click.echo().

import_eln(file_path)

Import an RO-Crate file following the “ELN” file specification.

Parameters:

file_path (str) – The path of the file.

Raises:

KadiAPYInputError – If the structure of the RO-Crate is not valid.
KadiAPYRequestError – If any request was not successful while importing the data and metadata.

import_json_schema(file_path, template_type='extras')

Import JSON Schema file and create a template.

Note that only JSON Schema draft 2020-12 is fully supported, but older schemas might still work.

Parameters:

file_path (str) – The path of the file.
template_type (str) – Type of the template. Can either be "record" or "extras".

Raises:

KadiAPYInputError – If the structure of the Schema is not valid.
KadiAPYRequestError – If any request was not successful while importing the metadata.

info(text, **kwargs)

Print text for info level.

Parameters:

text (str) – Text to be printed via click.echo().
**kwargs – Additional arguments to pass to click.echo().

is_verbose(**kwargs)

Check the verbose level.

Returns:: See KadiManager.is_verbose().

raise_request_error(response)

Raise exception.

Parameters:: response – The response.
Raises:: KadiAPYRequestError – Error is raised since request was not successful.

warning(text, **kwargs)

Print text for warning level.

Parameters:

text (str) – Text to be printed via click.echo().
**kwargs – Additional arguments to pass to click.echo().

CLISearch

class kadi_apy.cli.search.CLISearch(manager)[source]

Bases: Search, RaiseRequestErrorMixin

Search class to be used in a CLI.

Parameters:: manager (CLIKadiManager) – Manager to use for all API requests.

search_resources(item, user=None, use_my_user_id=False, **params)[source]

Search for resources.

Parameters:

item – The resource type defined either as string or class.
user (int) – ID of the user whose items are to be searched for.
use_my_user_id (bool) – Flag indicating if only the records corresponding to the used PAT are to be searched for.
**params – Additional query parameters.

Raises:

KadiAPYInputError – If both a user ID is given and the flag use_my_user_id is True.

search_resource_ids(item, pipe=False, i_am_sure=False, **params)[source]

Search for resource ids.

Parameters:

item – The resource type defined either as string or class.
pipe (bool) – If the results should be printed in form of a tokenlist for piping.
i_am_sure (bool) – If the search results in more than 1000 results, this flag has to be activated to search for all results.
**params – Additional query parameters.

Returns:

A list of ids found.

Return type:

list

Raises:

KadiAPYConfigurationError – If more than 1000 results are found and the flag ‘i_am_sure’ is not set to true.

search_users(**params)[source]

Search for users.

Parameters:: **params – Additional query parameters.
Returns:: The response object.

debug(text, **kwargs)

Print text for debug level.

Parameters:

text (str) – Text to be printed via click.echo().
**kwargs – Additional arguments to pass to click.echo().

error(text, **kwargs)

Print text for error level.

Parameters:

text (str) – Text to be printed via click.echo().
**kwargs – Additional arguments to pass to click.echo().

info(text, **kwargs)

Print text for info level.

Parameters:

text (str) – Text to be printed via click.echo().
**kwargs – Additional arguments to pass to click.echo().

is_verbose(**kwargs)

Check the verbose level.

Returns:: See KadiManager.is_verbose().

raise_request_error(response)

Raise exception.

Parameters:: response – The response.
Raises:: KadiAPYRequestError – Error is raised since request was not successful.

search_user_resources(item, user, **params)

Search for resources of users.

Parameters:

item – The resource type defined either as string or class.
user – ID of the user whose items are to be searched for.
**params – Additional query parameters.

Returns:

The response object.

warning(text, **kwargs)

Print text for warning level.

Parameters:

text (str) – Text to be printed via click.echo().
**kwargs – Additional arguments to pass to click.echo().

Decorators

kadi_apy.cli.decorators.apy_command(use_kadi_manager=False)[source]

Decorator to handle the default arguments and exceptions of an APY command.

This function inits the KadiManager or CLIKadiManager and includes it as manager to **kwargs. It adds the options instance and verbose to the CLI tool.

Parameters:: use_kadi_manager (bool, optional) – Flag to use the KadiManager instead of the CLIKadiManager.

kadi_apy.cli.decorators.id_identifier_options(class_type, keep_manager=False, helptext=None, name=None, required=True, char=None, allow_tokenlist=False, tokenlist_name=None, tokenlist_char='T')[source]

Decorator to handle the common ID and identifier options of commands.

This function inits a resource and includes it to **kwargs. It adds the options to read the ID or the identifier of the resource to the CLI tool.

Parameters:

class_type – The resource type defined either as string or class.
keep_manager (bool, optional) – Whether to keep the manager for further use.
helptext (str, optional) – Text to describe the input.
name (str, optional) – Name to better describe the input.
required (bool, optional) – Whether the parameter is required.
char (str, optional) – Char for the options.
allow_tokenlist (bool, optional) – Flag indicating if a tokenlist should be an option for input. If True the manager is passed to the function even if keep_manager is False.
tokenlist_name (str, optional) – Name of the tokenlist.
tokenlist_char (str, optional) – Char for the tokenlist.

kadi_apy.cli.decorators.user_id_options(helptext=None, required=True, keep_manager=False)[source]

Decorator to handle options to identify a user.

This function inits a CLIUser and includes it to **kwargs. Is adds the options to read the user ID, username and identity-type to the CLI tool.

Parameters:

helptext (str, optional) – Text to describe the input.
keep_manager (bool, optional) – Whether to keep the manager for further use.
required (bool, optional) – Whether to init the user is required.

kadi_apy.cli.decorators.file_id_options(helptext=None, required=True, name=None, char=None)[source]

Decorator to handle options to identify a file of a record.

Parameters:

helptext (str, optional) – Text to describe the input.
required (bool, optional) – Whether to init the file is required.
name (str, optional) – Name to better describe the input.
char (str, optional) – Char for the options.

kadi_apy.cli.decorators.search_pagination_options(description_page=None)[source]

Decorator to add two parameters for the search.

Parameters:: description_page (str, optional) – Description of the page option.