Note

Note that this library targets the stable version v1 of the HTTP API of Kadi4Mat. Detailed information about the API itself, including all endpoints and their parameters, can be found in the developer documentation of Kadi4Mat.

Library

The Python library is the most important and most flexible way to use the functionality that kadi-apy provides. The central entry point for most functionality is the KadiManager class. The following shows a basic example on how to use it:

from kadi_apy import KadiManager

manager = KadiManager()

# Retrieve an existing record by its ID.
record = manager.record(id=1)

# Upload a file to the record and retrieve its ID.
response = record.upload_file("/path/to/file.txt")

if response.ok:
    file_id = response.json()["id"]

Note

Most methods used to interact with resources return a response object as defined in the niquests Python library.

It is also possible to use the KadiManager class as a context manager. This ensures that the underlying session is always closed after exiting the with block:

with KadiManager() as manager:
    # Do something with the manager.

Next to records (Record), it is also possible to interact with other types of resources, namely collections (Collection), templates (Template), groups (Group) and users (User), for example:

# Retrieve an existing collection by its identifier.
collection = manager.collection(identifier="my_collection")

# Create a new template with the given metadata. If the template already exists, it
# will be retrieved by its identifier.
template = manager.template(
    identifier="my_template",
    title="My template",
    create=True,
)

Common methods, namely for searching (Search) as well as miscellaneous functionality (Miscellaneous), are offered directly by corresponding helper classes:

# Perform a search for records.
response = manager.search.search_resources("record")

# Get all deleted resources.
response = manager.misc.get_deleted_resources()

Tip

It is also possible to send individual requests directly using KadiManager.make_request(), while still ensuring a common handling of things like authorization and errors. This method is especially useful for endpoints for which no dedicated functionality exists yet, depending on the versions of kadi-apy and Kadi4Mat itself that are used.

Common conversion and utility functionality is offered via the conversion and utils module, respectively:

from kadi_apy import conversion
from kadi_apy import utils

# Convert parsed JSON data to a Kadi4Mat-compatible extra metadata structure.
extras = conversion.json_to_kadi({"string": "value", "number": 123})

# Generate a resource identifier from a string value.
identifier = utils.generate_identifier("My Value")

KadiManager

class kadi_apy.lib.core.KadiManager(instance=None, host=None, pat=None, verify=None, ca_bundle=None, timeout=None, whitelist=None, verbose=None)[source]

Bases: object

Base manager class for the API.

Manages the host, the personal access token (PAT) and other settings to use for all API requests. The KadiManager can instantiate new resources (e.g. records) via corresponding factory methods.

Parameters:

instance (str, optional) – The name of an instance to use in combination with the config file.
host (str, optional) – Name of the host. Will be required to be set in the config file if not given.
pat (str, optional) – Personal access token. Will be required to be set in the config file if not given.
verify (bool, optional) – Whether to verify the SSL/TLS certificate of the host.
ca_bundle (str, optional) – A path to a custom CA bundle to use for SSL/TLS verification if verify is True.
timeout (float, optional) – Timeout in seconds for the requests.
whitelist (list, optional) – A list of hosts that kadi-apy is allowed to redirect to.
verbose (optional) – Global verbose level to define the amount of prints.

property pat_user

Get the user related to the PAT.

Returns:: The user.
Return type:: User

property misc: Central entry point for miscellaneous functionality.

property search: Central entry point for search functionality.

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

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.

record(**kwargs)[source]

Init a record.

Parameters:: **kwargs – Arguments to initialize the record with.
Returns:: The record.
Return type:: Record
Raises:: KadiAPYRequestError – If initializing the record was not successful.

collection(**kwargs)[source]

Init a collection.

Parameters:: **kwargs – Arguments to initialize the collection with.
Returns:: The collection.
Return type:: Collection
Raises:: KadiAPYRequestError – If initializing the collection was not successful.

template(**kwargs)[source]

Init a template.

Parameters:: **kwargs – Arguments to initialize the template with.
Returns:: The template.
Return type:: Template
Raises:: KadiAPYRequestError – If initializing the template was not successful.

group(**kwargs)[source]

Init a group.

Parameters:: **kwargs – Arguments to initialize the group with.
Returns:: The group.
Return type:: Group
Raises:: KadiAPYRequestError – If initializing the group was not successful.

user(**kwargs)[source]

Init a user.

Parameters:: **kwargs – Arguments to initialize the user with.
Returns:: The user.
Return type:: User
Raises:: KadiAPYRequestError – If initializing the user was not successful.

is_verbose(verbose_level=Verbose.INFO)[source]

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

error(text, **kwargs)[source]

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()

warning(text, **kwargs)[source]

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()

info(text, **kwargs)[source]

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()

debug(text, **kwargs)[source]

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)[source]

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().

Record

class kadi_apy.lib.resources.records.Record(manager, id=None, identifier=None, skip_request=False, create=False, **kwargs)[source]

Bases: Resource, ExportMixin, PermissionMixin, TagMixin

Model to represent records.

Parameters:

manager (KadiManager) – 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. The identifier is adjusted if it contains spaces, invalid characters or exceeds the length of 50 valid characters.
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.
**kwargs – Additional metadata of the new resource to create.

add_collection_link(collection_id)[source]

Add a record to a collection.

Parameters:: collection_id (int) – The ID of the collection to which the record should be added.
Returns:: The response object.

remove_collection_link(collection_id)[source]

Remove a record from a collection.

Parameters:: collection_id (int) – The ID of the collection from which the record should be removed.
Returns:: The response object.

check_metadatum(metadatum)[source]

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

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

Add metadatum to a record.

Validation supports currently no nested metadata.

Parameters:

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

Returns:

The response object.

add_metadata(metadata_new, force=False, callback=None)[source]

Add metadata to a record.

Validation supports currently no nested metadata.

Parameters:

metadata_new (dict, list) – One or more metadata entries to add, either as dictionary or a list of dictionaries.
force (bool) – Whether to overwrite the metadatum with the new value in case the metadatum already exists.
callback (optional) – Callback function.

Returns:

The response object.

remove_metadatum(metadatum)[source]

Remove a metadatum from a record.

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

Parameters:: metadatum (str) – The metadatum to remove.
Returns:: The response object.

remove_all_metadata()[source]

Remove all metadata from a record.

Returns:: The response object.

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

Upload a file to a record.

Parameters:

file_path (str) – The path to the file (incl. name of the file).
file_name (str, optional) – The name under which the file should be stored. If no name is given, the name is taken from the file path.
file_description (str, optional) – The description of the file.
force (bool, optional) – Whether to replace an existing file with identical name.

Returns:

The final response object of the upload process.

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

Upload a string to save as a file in a record.

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.

Returns:

The final response object of the upload process.

download_file(file_id, file_path=None)[source]

Download a file of a record.

Parameters:

file_id (str) – The file ID of the file to download.
file_path (str, optional) – (optional) The full path to store the file. If not given, the content of the returned response has to be consumed by the caller.

Returns:

The response object.

download_all_files(file_path)[source]

Download all files of a record as ZIP archive.

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

get_file_revisions(**params)[source]

Get the file revisions of a file in this record.

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

get_file_revision(revision_id, **params)[source]

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_record_revisions(**params)[source]

Get the revisions of this record.

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

get_record_revision(revision_id, **params)[source]

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_users(**params)[source]

Get users from a record. Supports pagination.

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

get_groups(**params)[source]

Get group roles from a record. Supports pagination.

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

get_filelist(**params)[source]

Get the filelist. Supports pagination.

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

get_number_files()[source]

Get number of all files of a record.

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

get_file_name(file_id)[source]

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_metadatum(name)[source]

Return a specific metadatum.

Parameters:: name (str or list) – Either a single key as a string or a list of strings for nested metadata. Note that for list values, the keys are replaced by corresponding indices, also as string, starting at 1.
Returns:: The metadatum or None if it could not be found.

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

Link record.

Parameters:

record_to (int) – The ID of 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.

Returns:

The response object.

delete_record_link(record_link_id)[source]

Delete a record link.

Parameters:: record_link_id (int) – The ID of the record link to delete. Attention: The record link ID is not the record ID.
Returns:: The response object.

update_record_link(record_link_id, **kwargs)[source]

Update the name of record link.

Parameters:

record_link_id (int) – The ID of the record link to update. Attention: The record link ID is not the record ID.
**kwargs – The metadata to update the record link with.

Returns:

The response object.

get_record_links(**params)[source]

Get record links. Supports pagination.

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

get_collection_links(**params)[source]

Get collection links. Supports pagination.

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

get_file_id(file_name)[source]

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)[source]

Get information of a file based on the file_id.

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

has_file(file_name)[source]

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.

edit_file(file_id, **kwargs)[source]

Edit the metadata of a file of the record.

Parameters:

file_id (str) – The ID (UUID) of the file to edit.
**kwargs – The metadata to update the file with.

Returns:

The response object.

delete_file(file_id)[source]

Delete a file of the record.

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

flatten_extras(separator='.')[source]

Create a list of flattened metadata.

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

export_metadata(path, export_type='json', pipe=False, **params)[source]

Export the extra metadata of a record.

Parameters:

path (str) – The path (including name of the file) to store the exported data.
export_type (str) – The export format.
pipe (bool) – If True, nothing is written here.
**params – Additional query parameters.

Returns:

The response object.

Raises:

KadiAPYInputError – If export type is invalid.

add_group_role(group_id, role_name)

Add a group role.

Parameters:

group_id (int) – The ID of the group to add.
role_name (str) – Role of the group.

Returns:

The response object.

add_tag(tag)

Add a tag.

Parameters:: tag (str) – The tag to add.
Returns:: The response object.

add_user(user_id, role_name)

Add a user role.

Parameters:

user_id (int) – The ID of the user to add.
role_name (str) – Role of the User.

Returns:

The Response object.

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()

Delete the resource.

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(path, export_type='json', pipe=False, **params)

Export a resource using a specific export type.

Parameters:

path (str) – The path (including name of the file) to store the exported data.
export_type (str) – The export format.
pipe (bool) – If True, nothing is written here.
**params – Additional query parameters.

Returns:

The response object.

get_tags()

Get tags.

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

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.

remove_group_role(group_id)

Remove a group role.

Parameters:: group_id (int) – The ID of the group to remove.
Returns:: The response object.

remove_tag(tag)

Remove a tag.

Parameters:: tag (str) – The tag to remove.
Returns:: The response object.

remove_user(user_id)

Remove a user role.

Parameters:: user_id (int) – The ID of the user to remove.
Returns:: The response object.

set_attribute(attribute, value)

Set attribute.

Parameters:

attribute (str) – The attribute to set.
value – The value of the attribute.

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().

Collection

class kadi_apy.lib.resources.collections.Collection(manager, id=None, identifier=None, skip_request=False, create=False, **kwargs)[source]

Bases: Resource, ExportMixin, PermissionMixin, TagMixin

Model to represent collections.

Parameters:

manager (KadiManager) – 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. The identifier is adjusted if it contains spaces, invalid characters or exceeds the length of 50 valid characters.
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.
**kwargs – Additional metadata of the new resource to create.

get_users(**params)[source]

Get user of a collection. Supports pagination.

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

get_groups(**params)[source]

Get group roles from a collection. Supports pagination.

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

add_record_link(record_id)[source]

Add a record to a collection.

Parameters:: record_id (int) – The ID of the record to add.
Returns:: The response object.

remove_record_link(record_id)[source]

Remove a record from a collection.

Parameters:: record_id (int) – The ID of the record to remove.
Returns:: The response object.

get_records(**params)[source]

Get records from a collection. Supports pagination.

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

get_collections(**params)[source]

Get collections linked with a collection id.

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

add_collection_link(collection_id)[source]

Add a child collection to a parent collection.

Parameters:: collection_id (int) – The ID of a child collection to which the parent collection should be added.
Returns:: The response object.

remove_collection_link(collection_id)[source]

Remove a child collection from a parent collection.

Parameters:: collection_id (int) – The ID of the child collection to be removed from the parent collection.
Returns:: The response object.

get_collection_revisions(**params)[source]

Get the revisions of this collection.

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

get_collection_revision(revision_id, **params)[source]

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.

add_group_role(group_id, role_name)

Add a group role.

Parameters:

group_id (int) – The ID of the group to add.
role_name (str) – Role of the group.

Returns:

The response object.

add_tag(tag)

Add a tag.

Parameters:: tag (str) – The tag to add.
Returns:: The response object.

add_user(user_id, role_name)

Add a user role.

Parameters:

user_id (int) – The ID of the user to add.
role_name (str) – Role of the User.

Returns:

The Response object.

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()

Delete the resource.

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(path, export_type='json', pipe=False, **params)

Export a resource using a specific export type.

Parameters:

path (str) – The path (including name of the file) to store the exported data.
export_type (str) – The export format.
pipe (bool) – If True, nothing is written here.
**params – Additional query parameters.

Returns:

The response object.

get_tags()

Get tags.

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

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.

remove_group_role(group_id)

Remove a group role.

Parameters:: group_id (int) – The ID of the group to remove.
Returns:: The response object.

remove_tag(tag)

Remove a tag.

Parameters:: tag (str) – The tag to remove.
Returns:: The response object.

remove_user(user_id)

Remove a user role.

Parameters:: user_id (int) – The ID of the user to remove.
Returns:: The response object.

set_attribute(attribute, value)

Set attribute.

Parameters:

attribute (str) – The attribute to set.
value – The value of the attribute.

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().

Template

class kadi_apy.lib.resources.templates.Template(manager, id=None, identifier=None, skip_request=False, create=False, **kwargs)[source]

Bases: Resource, ExportMixin, PermissionMixin

Model to represent templates.

Parameters:

manager (KadiManager) – 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. The identifier is adjusted if it contains spaces, invalid characters or exceeds the length of 50 valid characters.
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.
**kwargs – Additional metadata of the new resource to create.

get_users(**params)[source]

Get users from a template. Supports pagination.

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

get_template_revisions(**params)[source]

Get the revisions of this template.

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

get_template_revision(revision_id, **params)[source]

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_groups(**params)[source]

Get group roles from a template. Supports pagination.

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

add_group_role(group_id, role_name)

Add a group role.

Parameters:

group_id (int) – The ID of the group to add.
role_name (str) – Role of the group.

Returns:

The response object.

add_user(user_id, role_name)

Add a user role.

Parameters:

user_id (int) – The ID of the user to add.
role_name (str) – Role of the User.

Returns:

The Response object.

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()

Delete the resource.

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(path, export_type='json', pipe=False, **params)

Export a resource using a specific export type.

Parameters:

path (str) – The path (including name of the file) to store the exported data.
export_type (str) – The export format.
pipe (bool) – If True, nothing is written here.
**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.

remove_group_role(group_id)

Remove a group role.

Parameters:: group_id (int) – The ID of the group to remove.
Returns:: The response object.

remove_user(user_id)

Remove a user role.

Parameters:: user_id (int) – The ID of the user to remove.
Returns:: The response object.

set_attribute(attribute, value)

Set attribute.

Parameters:

attribute (str) – The attribute to set.
value – The value of the attribute.

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().

Group

class kadi_apy.lib.resources.groups.Group(manager, id=None, identifier=None, skip_request=False, create=False, **kwargs)[source]

Bases: Resource

Model to represent groups.

Parameters:

manager (KadiManager) – 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. The identifier is adjusted if it contains spaces, invalid characters or exceeds the length of 50 valid characters.
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.
**kwargs – Additional metadata of the new resource to create.

get_records(**params)[source]

Get records shared with a group. Supports pagination.

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

get_collections(**params)[source]

Get collections shared with a group. Supports pagination.

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

get_templates(**params)[source]

Get templates shared with a group. Supports pagination.

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

get_users(**params)[source]

Get users of a group. Supports pagination.

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

add_user(user_id, role_name)[source]

Add a user.

Parameters:

user_id (int) – The ID of the user to add.
role_name (str) – Role of the user.

Returns:

The response object.

remove_user(user_id)[source]

Remove a user.

Parameters:: user_id (int) – The ID of the user to remove.
Returns:: The response object.

get_group_revisions(**params)[source]

Get the revisions of this group.

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

get_group_revision(revision_id, **params)[source]

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.

change_user_role(user_id, role_name)[source]

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()

Delete the resource.

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().

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.

set_attribute(attribute, value)

Set attribute.

Parameters:

attribute (str) – The attribute to set.
value – The value of the attribute.

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().

User

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

Bases: ResourceMeta

Model to represent users.

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

Parameters:

manager (KadiManager) – 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 KadiManager should be used for instantiating the user.

Raises:

KadiAPYRequestError – If retrieving the user 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().

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.

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().

Miscellaneous

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

Bases: RequestMixin, VerboseMixin

Model to handle miscellaneous functionality.

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

get_deleted_resources(**params)[source]

Get a list of deleted resources in the trash. Supports pagination.

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

restore(item, item_id)[source]

Restore an item from the trash.

Parameters:

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

Returns:

The response object.

purge(item, item_id)[source]

Purge an item from the trash.

Parameters:

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

Returns:

The response object.

get_licenses(**params)[source]

Get a list of available licenses. Supports pagination.

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

get_kadi_info()[source]

Get information about the Kadi instance.

Returns:: The response object.

get_roles()[source]

Get all possible roles and corresponding permissions of all resources.

Returns:: The response object.

get_tags(**params)[source]

Get a list of all tags. Supports pagination.

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

import_eln(file_path)[source]

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')[source]

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.

import_shacl(file_path, template_type='extras')[source]

Import SHACL Shapes file and create a template.

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 Shapes is not valid.
KadiAPYRequestError – If any request was not successful while importing the metadata.

reuse_collection(collection_id, suffix)[source]

Reuse the collection with the given ID.

This method creates a new collection by duplicating all records from an existing collection and appending the given suffix to their identifiers. It ensures that record links are preserved within the modified collection. Note that currently only the metadata of records is copied.

Parameters:

collection_id – The ID of the collection to be reused.
suffix – A string to append to each record and collection identifier.

Raises:

KadiAPYRequestError – If any request was not successful during the duplication process.

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().

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().

Search

class kadi_apy.lib.search.Search(manager)[source]

Bases: RequestMixin, VerboseMixin

Search class for resources and users.

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

search_resources(item, **params)[source]

Search for resources.

Parameters:

item – The resource type defined either as string or class.
**params – Additional query parameters.

Returns:

The response object.

search_user_resources(item, user, **params)[source]

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.

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().

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().

Conversion

kadi_apy.lib.conversion.json_to_kadi(data, convert_invalid_ints=False, fallback_value=None)[source]

Convert plain JSON to a Kadi4Mat-compatible extra metadata structure.

Parameters:

data – The JSON data to convert as dictionary, list or singular, primitive value.
convert_invalid_ints – (optional) Flag indicating whether to automatically convert integer values which are not in the value range supported by Kadi to strings instead.
fallback_value – (optional) A fallback value to use for all null values instead of ignoring them.

Returns:

The converted data as a list of extra metadata.

kadi_apy.lib.conversion.kadi_to_json(extras)[source]

Convert Kadi4Mat-compatible extra metadata to a plain JSON structure.

Parameters:: extras – A list of extra metadata to convert.
Returns:: The converted metadata as dictionary.

Utils

kadi_apy.lib.utils.chunked_response(path, response)[source]

Stream the data of a given response to a file.

Parameters:

path – The file path to store the data in.
response – The response object, which needs to support streaming.

kadi_apy.lib.utils.generate_identifier(value)[source]

Generate a valid resource identifier from a given string.

Parameters:: value – The string to create the identifier from.
Returns:: The generated identifier.

kadi_apy.lib.utils.append_identifier_suffix(identifier, suffix)[source]

Append a suffix to an existing identifier.

Parameters:

identifier – The identifier to append the suffix to. If the combined identifier is longer than the maximum identifier length, the original identifier will be truncated accordingly.
suffix – The suffix to append to the identifier, which will be formatted according to the usual identifier rules. If the suffix is longer than the maximum identifier length, it will be truncated accordingly.

Returns:

The combined identifier.

kadi_apy.lib.utils.get_resource_type(resource_type)[source]

Get a resource class from a corresponding string.

Parameters:: resource_type – The resource type as a string.
Returns:: The resource class.
Raises:: KadiAPYInputError – If the given resource type does not exist.

kadi_apy.lib.utils.paginate(callback)[source]

Helper to handle paginated requests.

Parameters:: callback – A callback function that takes a single argument, which is the current result page, starting at 1. The callback function has to perform the actual request using the given page and has to return the parsed response data (containing the pagination data) after processing it.

Exceptions

exception kadi_apy.lib.exceptions.KadiAPYException[source]

Bases: Exception

Base exception class.

exception kadi_apy.lib.exceptions.KadiAPYConfigurationError[source]

Bases: KadiAPYException

For errors relating to invalid configurations.

exception kadi_apy.lib.exceptions.KadiAPYRequestError[source]

Bases: KadiAPYException

For errors relating to invalid requests.

exception kadi_apy.lib.exceptions.KadiAPYInputError[source]

Bases: KadiAPYException

For errors relating to invalid inputs.