Modules 

Parameters:

identifier – See Collection.identifier.
title – See Collection.title.
creator – (optional) The creator of the collection. Defaults to the current user.
record_template – (optional) The ID of the record template of this collection.
tags – (optional) A list of tag names to tag the collection with. See also Tag.
description – (optional) See Collection.description.
visibility – (optional) See Collection.visibility.
state – (optional) See Collection.state.

Returns:

kadi.modules.collections.core.update_collection(collection, tags=None, user=None, **kwargs)[source]

Update an existing collection.

Parameters:

collection – The collection to update.
tags – (optional) A list of tag names to tag the collection with. See also Tag.
user – (optional) The user who triggered the update. Defaults to the current user.
**kwargs – Keyword arguments that will be passed to kadi.lib.resources.core.update_resource(). See also create_collection().

Returns:

kadi.modules.collections.core.delete_collection(collection, user=None)[source]

Delete an existing collection.

Parameters:

collection – The collection to delete.
user – (optional) The user who triggered the deletion. Defaults to the current user.

kadi.modules.collections.core.restore_collection(collection, user=None)[source]

Restore a deleted collection.

Parameters:

collection – The collection to restore.
user – (optional) The user who triggered the restoration. Defaults to the current user.

kadi.modules.collections.core.purge_collection(collection)[source]

Purge an existing collection.

Parameters:: collection – The collection to purge.

kadi.modules.collections.core.link_collections(parent_collection, child_collection, user=None)[source]

Link two collections together.

Note that this function may acquire a lock on the given collections.

Parameters:

parent_collection – The parent collection.
child_collection – The child collection.
user – (optional) The user performing the link operation. Defaults to the current user.

Returns:

True if the collections were linked successfully, False if both given collections refer to the same object, if the given child collection already has a parent or if the given child collection is already a parent of the parent collection.

Raises:

KadiPermissionError – If the user performing the operation does not have the necessary permissions.

class kadi.modules.collections.export.CollectionRDFGraph(collection, export_filter=None, user=None)[source]

Bases: RDFGraph

Collection RDF graph export class.

See get_export_data() for an explanation of the parameters.

kadi.modules.collections.export.get_dict_data(collection, export_filter, user)[source]

Export a collection as a dictionary.

See get_export_data() for an explanation of the parameters.

Returns:: The exported collection as a dictionary.

kadi.modules.collections.export.get_json_data(collection, export_filter, user)[source]

Export a collection as a JSON file.

See get_export_data() for an explanation of the parameters and return value.

kadi.modules.collections.export.get_qr_data(collection)[source]

Export a collection as a QR code in PNG format.

See get_export_data() for an explanation of the parameters and return value.

kadi.modules.collections.export.get_ro_crate_data(collection, export_filter, user)[source]

Export a collection as an RO-Crate.

See get_export_data() for an explanation of the parameters and return value.

kadi.modules.collections.export.get_rdf_data(collection, export_filter, user)[source]

Export a collection as an RDF graph in Turtle format.

See get_export_data() for an explanation of the parameters and return value.

kadi.modules.collections.export.get_export_data(collection, export_type, export_filter=None, user=None)[source]

Export a collection in a given format.

Parameters:

collection – The collection to export.
export_type – The export type, one of "json", "rdf", "qr" or "ro-crate".

export_filter –

(optional) A dictionary specifying various filters to adjust the returned export data, depending on the export type. Only usable in combination with the "json", "rdf" and "ro-crate" export types. Note that the values in the example below represent the respective default values.

Example:

{
    # Whether user information about the creator of the collection or any
    # linked resource should be excluded.
    "user": False,
    # Whether to exclude information about records that are part of the
    # collection.
    "records": False,
    # Whether to exclude all (True), outgoing ("out") or incoming ("in")
    # links of records with other records when record information is not
    # excluded.
    "links": False,
    # To specify which kind of export data of records should be included in
    # an exported RO-Crate when using the "ro-crate" export type and record
    # information is not excluded. All other filters also apply to this
    # export data, as far as applicable.
    "export_data": ["json", "rdf"],
    # Whether to return only the metadata file of an exported RO-Crate when
    # using the "ro-crate" export type.
    "metadata_only": False,
}

user – (optional) The user to check for various access permissions when generating the export data. Defaults to the current user.

Returns:

The exported collection data as an in-memory byte stream using io.BytesIO or None if an unknown export type was given. Note that for the ro-crate export type, the returned data is an iterable producing the actual binary data on the fly instead, unless only the metadata file is exported by specifying the corresponding export filter.

class kadi.modules.collections.forms.BaseCollectionForm(*args, **kwargs)[source]

Base form class for use in creating or updating collections.

Parameters:

collection – (optional) A collection used for prefilling the form.
user – (optional) A user that will be used for checking various access permissions when prefilling the form. Defaults to the current user.

class kadi.modules.collections.forms.NewCollectionForm(*args, **kwargs)[source]

Bases: BaseCollectionForm

A form for use in creating new collections.

Parameters:

collection – (optional) See BaseCollectionForm.
user – (optional) See BaseCollectionForm.

class kadi.modules.collections.forms.EditCollectionForm(*args, **kwargs)[source]

Bases: BaseCollectionForm

A form for use in editing existing collections.

Parameters:: collection – The collection to edit, used for prefilling the form.

class kadi.modules.collections.forms.LinkRecordsForm(*args, **kwargs)[source]

Bases: BaseForm

A form for use in linking collections with records.

class kadi.modules.collections.forms.LinkCollectionsForm(*args, **kwargs)[source]

Bases: BaseForm

A form for use in linking collections with other collections.

class kadi.modules.collections.forms.AddCollectionRolesForm(*args, **kwargs)[source]

Bases: BaseForm

A form for use in adding user or group roles to a collection.

class kadi.modules.collections.forms.UpdateRecordsRolesForm(*args, **kwargs)[source]

Bases: BaseForm

A form for use in updating user or group roles of linked records.

class kadi.modules.collections.mappings.CollectionMapping(meta: Dict[str, Any] | None = None, **kwargs: Any)[source]

Search mapping for collections.

See Collection.

class kadi.modules.collections.models.CollectionVisibility[source]

Bases: StringEnum

String enum containing all possible visibility values for collections.

class kadi.modules.collections.models.CollectionState[source]

Bases: StringEnum

String enum containing all possible state values for collections.

class kadi.modules.collections.models.Collection(**kwargs)[source]

Bases: SimpleReprMixin, SearchableMixin, StateTimestampMixin, FavoriteMixin, TaggingMixin, Model

Model to represent collections.

class Meta[source]

Bases: object

Container to store meta class attributes.

representation = ['id', 'user_id', 'parent_id', 'identifier', 'visibility', 'state']: See SimpleReprMixin.

search_mapping = 'kadi.modules.collections.mappings.CollectionMapping': See SearchableMixin.

revision = ['identifier', 'title', 'description', 'visibility', 'state', 'tags[name]', 'record_template[id]']: See kadi.lib.revisions.core.setup_revisions().

permissions = {'actions': {'create': 'Create new collections.', 'delete': l'Delete this collection.', 'link': l'Manage links of this collection with other resources.', 'permissions': l'Manage permissions of this collection.', 'read': l'View this collection.', 'update': l'Edit this collection.'}, 'default_permissions': {'read': {'visibility': 'public'}}, 'roles': {'admin': ['read', 'link', 'update', 'permissions', 'delete'], 'collaborator': ['read', 'link'], 'editor': ['read', 'link', 'update'], 'member': ['read']}}

Available actions, roles and default permissions for collections.

See kadi.lib.permissions.

check_constraints = {'description': {'length': {'max': 50000}}, 'identifier': {'length': {'max': 50}}, 'state': {'values': ['active', 'deleted']}, 'title': {'length': {'max': 150}}, 'visibility': {'values': ['private', 'public']}}: See kadi.lib.db.generate_check_constraints().

id: The ID of the collection, auto incremented.

user_id: The ID of the User who created the collection.

parent_id: The optional ID of the parent Collection.

identifier

The unique identifier of the collection.

Restricted to a maximum length of 50 characters.

title

The title of the collection.

Restricted to a maximum length of 150 characters.

created_at

The date and time an object has been created at.

Always uses the current UTC time.

description

The description of the collection.

Restricted to a maximum length of 50_000 characters.

last_modified

The date and time an object was last modified.

Always uses the current UTC time as initial value. After calling register_timestamp_listener() for an inheriting mixin class, this timestamp can automatically get updated by implementing _before_flush_timestamp() as a class method.

plain_description

The plain description of the collection.

Equal to the normal description with the difference that most markdown is stripped out and whitespaces are normalized.

visibility

The default visibility of the collection.

One of "private" or "public".

record_template_id

The optional ID of a record Template associated with the collection.

If specified, the template will be used as a default when adding new records to the collection.

state

The state of the collection.

One of "active" or "deleted".

classmethod create(*, creator, identifier, title, description='', plain_description='', visibility='private', record_template=None, state='active')[source]

Create a new collection and add it to the database session.

Parameters:

creator – The creator of the collection.
identifier – The unique identifier of the collection.
title – The title of the collection.
description – (optional) The description of the collection.
plain_description – (optional) The plain description of the collection.
visibility – (optional) The default visibility of the collection.
record_template – (optional) The record template of the collection.
state – (optional) The state of the collection.

Returns:

The new Collection object.

class kadi.modules.collections.schemas.CollectionSchema(previous_collection=None, linked_record=None, parent_collection=None, **kwargs)[source]

Schema to represent collections.

See Collection.

Parameters:

previous_collection – (optional) A collection whose identifier should be excluded when checking for duplicates while deserializing.
linked_record – (optional) A record that is linked to each collection that should be serialized. Will be used to build endpoints for corresponding actions.
parent_collection – (optional) A collection that is the parent of each collection that should be serialized. Will be used to build endpoints for corresponding actions.

class kadi.modules.collections.schemas.CollectionRevisionSchema(previous_collection=None, linked_record=None, parent_collection=None, **kwargs)[source]

Bases: CollectionSchema

Schema to represent collection revisions.

Additionally includes the serialization of the default record template with a limited subset of attributes.

kadi.modules.collections.utils.search_collections(search_query=None, page=1, per_page=10, sort='_score', visibility=None, explicit_permissions=False, user_ids=None, tags=None, tag_operator='or', user=None)[source]

Search and filter for collections.

Uses kadi.lib.resources.utils.get_filtered_resources() and kadi.lib.resources.utils.search_resources().

Parameters:

search_query – (optional) See kadi.lib.resources.utils.search_resources().
page – (optional) See kadi.lib.resources.utils.search_resources().
per_page – (optional) See kadi.lib.resources.utils.search_resources().
sort – (optional) See kadi.lib.resources.utils.search_resources().
visibility – (optional) See kadi.lib.resources.utils.get_filtered_resources().
explicit_permissions – (optional) See kadi.lib.resources.utils.get_filtered_resources().
user_ids – (optional) See kadi.lib.resources.utils.get_filtered_resources().
tags – (optional) A list of tag names to filter the collections with.
tag_operator – (optional) The operator to filter the tags with. One of "or" or "and".
user – (optional) The user to check for any permissions regarding the searched collections. Defaults to the current user.

Returns:

The search results as returned by kadi.lib.resources.utils.search_resources().

kadi.modules.collections.utils.get_parent_collections(collection, user=None)[source]

Recursively get all parents of a collection that a user can access.

In this context having access to a collection means having read permission for it. Note that as soon as a parent collection is not accessible or inactive, no further potential parents are collected.

Parameters:

collection – The collection to get the parents of.
user – (optional) The user to check for access permissions when retrieving the collections. Defaults to the current user.

Returns:

A list of parent collections starting with the immediate parent of the given collection.

kadi.modules.collections.utils.get_child_collections(collection, user=None)[source]

Recursively get all children of a collection that a user can access.

In this context having access to a collection means having read permission for it. Note that if a collection is not accessible or inactive, no further potential children of this collection are collected.

Parameters:

collection – The collection to get the children of.
user – (optional) The user to check for access permissions when retrieving the collections. Defaults to the current user.

Returns:

A list of child collections in unspecified order.

kadi.modules.collections.utils.get_child_collection_records(collection, actions=None, user=None)[source]

Recursively get all records of a collection hierarchy that a user can access.

In this context, the collection hierarchy refers to the given collection and all its direct or indirect children. Having access to a child collection or record means having read permission for it.

Uses get_child_collections() to determine the children of the given collection.

Parameters:

collection – The collection to get the children and records of.
actions – (optional) A list of further actions to check as part of the access permissions of records.
user – (optional) The user to check for access permissions when retrieving the collections and records. Defaults to the current user.

Returns:

The records as query. Note that duplicate records are already filtered out.

kadi.modules.collections.utils.get_collection_links_graph(collection, records=False, children=False, user=None)[source]

Get the links of a collection for visualizing them in a graph.

Used in conjunction with D3.js to visualize the collection links in a graph.

Parameters:

collection – The collection to get the links of.
records – (optional) Whether to include the records (and their links) of the given collection.
children – (optional) Whether to include the children of the given collection.
user – (optional) The user to check for access permissions regarding the linked resources. Defaults to the current user.

Returns:

A dictionary containing the metadata of the given collection, optionally including its records ("records"), record links ("record_links") and its children ("children").

Groups

kadi.modules.groups.core.create_group(*, identifier, title, creator=None, description='', visibility='private', state='active')[source]

Create a new group.

Parameters:

identifier – See Group.identifier.
title – See Group.title.
creator – (optional) The creator of the group. Defaults to the current user.
description – (optional) See Group.description.
visibility – (optional) See Group.visibility.
state – (optional) See Group.state.

Returns:

kadi.modules.groups.core.update_group(group, user=None, **kwargs)[source]

Update an existing group.

Parameters:

group – The group to update.
user – (optional) The user who triggered the update. Defaults to the current user.
**kwargs – Keyword arguments that will be passed to kadi.lib.resources.update_resource(). See also create_group().

Returns:

kadi.modules.groups.core.delete_group(group, user=None)[source]

Delete an existing group.

Parameters:

group – The group to delete.
user – (optional) The user who triggered the deletion. Defaults to the current user.

kadi.modules.groups.core.restore_group(group, user=None)[source]

Restore a deleted group.

Parameters:

group – The group to restore.
user – (optional) The user who triggered the restoration. Defaults to the current user.

kadi.modules.groups.core.purge_group(group)[source]

Purge an existing group.

Parameters:: group – The group to purge.

class kadi.modules.groups.forms.BaseGroupForm(*args, **kwargs)[source]

Base form class for use in creating or updating groups.

class kadi.modules.groups.forms.NewGroupForm(*args, **kwargs)[source]

Bases: BaseGroupForm

A form for use in creating new groups.

class kadi.modules.groups.forms.EditGroupForm(*args, **kwargs)[source]

Bases: BaseGroupForm

A form for use in editing existing groups.

Parameters:: group – The group to edit, used for prefilling the form.

class kadi.modules.groups.forms.AddMembersForm(*args, **kwargs)[source]

Bases: BaseForm

A form for use in adding members (i.e. user roles) to a group.

class kadi.modules.groups.forms.AddRulesForm(*args, **kwargs)[source]

Bases: BaseForm

A form for use in adding new username role rules for groups.

class kadi.modules.groups.mappings.GroupMapping(meta: Dict[str, Any] | None = None, **kwargs: Any)[source]

Search mapping for groups.

See Group.

class kadi.modules.groups.models.GroupVisibility[source]

Bases: StringEnum

String enum containing all possible visibility values for groups.

class kadi.modules.groups.models.GroupState[source]

Bases: StringEnum

String enum containing all possible state values for groups.

class kadi.modules.groups.models.Group(**kwargs)[source]

Bases: SimpleReprMixin, SearchableMixin, StateTimestampMixin, FavoriteMixin, Model

Model to represent groups.

class Meta[source]

Bases: object

Container to store meta class attributes.

representation = ['id', 'user_id', 'identifier', 'visibility', 'state']: See SimpleReprMixin.

search_mapping = 'kadi.modules.groups.mappings.GroupMapping': See SearchableMixin.

timestamp_exclude = ['roles']: See BaseTimestampMixin.

revision = ['identifier', 'title', 'description', 'visibility', 'state']: See kadi.lib.revisions.core.setup_revisions().

permissions = {'actions': {'create': 'Create new groups.', 'delete': l'Delete this group.', 'members': l'Manage members of this group.', 'read': l'View this group.', 'update': l'Edit this group.'}, 'default_permissions': {'read': {'visibility': 'public'}}, 'roles': {'admin': ['read', 'update', 'members', 'delete'], 'editor': ['read', 'update'], 'member': ['read']}}

Available actions, roles and default permissions for groups.

See kadi.lib.permissions.

check_constraints = {'description': {'length': {'max': 50000}}, 'identifier': {'length': {'max': 50}}, 'state': {'values': ['active', 'deleted']}, 'title': {'length': {'max': 150}}, 'visibility': {'values': ['private', 'public']}}: See kadi.lib.db.generate_check_constraints().

id: The ID of the group, auto incremented.

user_id: The ID of the User who created the group.

identifier

The unique identifier of the group.

Restricted to a maximum length of 50 characters.

created_at

The date and time an object has been created at.

Always uses the current UTC time.

last_modified

The date and time an object was last modified.

Always uses the current UTC time as initial value. After calling register_timestamp_listener() for an inheriting mixin class, this timestamp can automatically get updated by implementing _before_flush_timestamp() as a class method.

title

The title of the group.

Restricted to a maximum length of 150 characters.

description

The description of the group.

Restricted to a maximum length of 50_000 characters.

plain_description

The plain description of the group.

Equal to the normal description with the difference that most markdown is stripped out and whitespaces are normalized.

image_name: The optional identifier of a group’s profile image.

visibility

The default visibility of the group.

One of "private" or "public".

state

The state of the group.

One of "active" or "deleted".

classmethod create(*, creator, identifier, title, description='', plain_description='', visibility='private', state='active')[source]

Create a new group and add it to the database session.

Parameters:

creator – The creator of the group.
identifier – The unique identifier of the group.
title – The title of the group.
description – (optional) The description of the group.
plain_description – (optional) The plain description of the group.
visibility – (optional) The default visibility of the group.
state – (optional) The state of the group.

Returns:

The new Group object.

class kadi.modules.groups.schemas.GroupSchema(previous_group=None, **kwargs)[source]

Schema to represent groups.

See Group.

Parameters:: previous_group – (optional) A group whose identifier should be excluded when checking for duplicates while deserializing.

kadi.modules.groups.utils.search_groups(search_query=None, page=1, per_page=10, sort='_score', visibility=None, member_only=False, user_ids=None, user=None)[source]

Search and filter for groups.

Uses kadi.lib.resources.utils.get_filtered_resources() and kadi.lib.resources.utils.search_resources().

Parameters:

search_query – (optional) See kadi.lib.resources.utils.search_resources().
page – (optional) See kadi.lib.resources.utils.search_resources().
per_page – (optional) See kadi.lib.resources.utils.search_resources().
sort – (optional) See kadi.lib.resources.utils.search_resources().
visibility – (optional) See kadi.lib.resources.utils.get_filtered_resources().
member_only – (optional) Flag indicating whether to exclude groups without membership.
user_ids – (optional) See kadi.lib.resources.utils.get_filtered_resources().
user – (optional) The user to check for any permissions regarding the searched groups. Defaults to the current user.

Returns:

The search results as returned by kadi.lib.resources.utils.search_resources().

kadi.modules.groups.utils.get_user_groups(user=None)[source]

Get all groups a user is a member of.

Group membership currently works through roles, specifically, as long as a user has any role inside a group, they are a member of it and should be able to at least read it. Note that inactive groups will be filtered out.

Parameters:: user – (optional) The user to get the groups for. Defaults to the current user.
Returns:: The groups of the given user as query.

kadi.modules.groups.utils.save_group_image(group, stream)[source]

Save image data as a group’s profile image.

Uses kadi.lib.storage.misc.save_as_thumbnail() to store the actual image data. Note that any previous profile image will be deleted beforehand using delete_group_image(), which will also be called if the image could not be saved.

Parameters:

group – The group to set the profile image for.
stream – The image data as a readable binary stream.

kadi.modules.groups.utils.delete_group_image(group)[source]

Delete a group’s profile image.

This is the inverse operation of save_group_image().

Parameters:: group – The group of which the profile image should be deleted.

Main

class kadi.modules.main.forms.AuthorizeApplicationForm(*args, **kwargs)[source]

Bases: BaseForm

A form for use in authorizing an OAuth2 application.

class kadi.modules.main.schemas.BasicResourceSchema(*args, _internal=None, **kwargs)[source]

Bases: BaseSchema

Schema to represent the basic attributes and different types of resources.

These resources may refer to instances of Record, Collection, Template or Group.

class kadi.modules.main.schemas.DeletedResourceSchema(*args, _internal=None, **kwargs)[source]

Bases: BasicResourceSchema

Schema to represent the basic attributes of deleted resources.

kadi.modules.main.utils.get_favorite_resources(max_items=6, user=None)[source]

Get a list of serialized resources favorited by the given user.

Parameters:

max_items – (optional) The maximum number of resource to return.
user – (optional) The user the favorite resources belong to. Defaults to the current user.

Returns:

The serialized resources as a list of dictionaries, each resource additionally containing its type in a human-readable manner as pretty_type.

kadi.modules.main.utils.get_resource_searches(user=None)[source]

Get a list of serialized saved resource searches of the given user.

Parameters:: user – (optional) The user the saved searches belong to. Defaults to the current user.
Returns:: The serialized searches as a list of dictionaries, each search additionally containing its corresponding resource type in a human-readable manner as pretty_type.

kadi.modules.main.utils.get_latest_resources(user=None)[source]

Get a list of serialized resources according to their modification date.

Uses the home page layout as configured via the user-specific "HOME_LAYOUT" config item to determine how many resources of each type to collect.

Parameters:: user – (optional) The user the layout belongs to. Defaults to the current user.
Returns:: The serialized resources as a list of dictionaries per resource type, each containing the localized resource title ("title"), the resource search url ("url") and the serialized resources themselves ("items").

Records

kadi.modules.records.core.create_record(*, identifier, title, creator=None, license=None, tags=None, type=None, description='', extras=None, visibility='private', state='active')[source]

Create a new record.

Parameters:

identifier – See Record.identifier.
title – See Record.title.
creator – (optional) The creator of the record. Defaults to the current user.
license – (optional) The name of the license of the record. See also License.
tags – (optional) A list of tag names to tag the record with. See also Tag.
type – (optional) See Record.type.
description – (optional) See Record.description.
extras – (optional) See Record.extras.
visibility – (optional) See Record.visibility.
state – (optional) See Record.state.

Returns:

kadi.modules.records.core.update_record(record, tags=None, user=None, **kwargs)[source]

Update an existing record.

Parameters:

record – The record to update.
tags – (optional) A list of tag names to tag the record with. See also Tag.
user – (optional) The user who triggered the update. Defaults to the current user.
**kwargs – Keyword arguments that will be passed to kadi.lib.resources.update_resource(). See also create_record().

Returns:

kadi.modules.records.core.delete_record(record, user=None)[source]

Delete an existing record.

Parameters:

record – The record to delete.
user – (optional) The user who triggered the deletion. Defaults to the current user.

kadi.modules.records.core.restore_record(record, user=None)[source]

Restore a deleted record.

Parameters:

record – The record to restore.
user – (optional) The user who triggered the restoration. Defaults to the current user.

kadi.modules.records.core.purge_record(record)[source]

Purge an existing record.

This will also remove all files and uploads of the record.

Parameters:: record – The record to purge.

kadi.modules.records.dashboards.get_custom_mimetype(file, base_mimetype)[source]

Get a custom MIME type of a dashboard based on its content.

Parameters:

file – The file to get the MIME type of.
base_mimetype – The base MIME type of the file on which to base the custom MIME type.

Returns:

The custom MIME type or None if no custom MIME type was found.

class kadi.modules.records.export.RecordPDF(record, export_filter=None, user=None)[source]

Bases: PDF

Record PDF export class.

See get_record_export_data() for an explanation of the parameters.

print_overview()[source]: Print the record overview, i.e. the basic metadata of the record.

print_extras()[source]: Print the extra metadata of the record.

print_files()[source]: Print the files of the record.

print_record_links()[source]: Print the links of the record with other records.

class kadi.modules.records.export.RecordRDFGraph(record, export_filter=None, user=None)[source]

Bases: RDFGraph

Record RDF graph export class.

See get_record_export_data() for an explanation of the parameters.

class kadi.modules.records.export.RecordROCrate(record_or_records, root_dir, export_filter=None, user=None)[source]

Bases: ROCrate

Record RO-Crate export class.

Parameters:

record_or_records – A single record or iterable of records to include in the RO-Crate.
root_dir – The name of the root directory of the RO-Crate.
export_filter – (optional) See get_record_export_data().
user – (optional) See get_record_export_data().

add_record_metadata(record, record_export_data)[source]: Add the metadata of a record to the RO-Crate.

add_record_data(record, record_export_data)[source]: Add the data of a record to the RO-Crate.

kadi.modules.records.export.get_record_dict_data(record, export_filter, user)[source]

Export a record as a dictionary.

See get_record_export_data() for an explanation of the parameters.

Returns:: The exported record as a dictionary.

kadi.modules.records.export.get_record_json_data(record, export_filter, user)[source]

Export a record as a JSON file.

See get_record_export_data() for an explanation of the parameters and return value.

kadi.modules.records.export.get_record_pdf_data(record, export_filter, user)[source]

Export a record as a PDF file.

See get_record_export_data() for an explanation of the parameters and return value.

kadi.modules.records.export.get_record_qr_data(record)[source]

Export a record as a QR code in PNG format.

See get_record_export_data() for an explanation of the parameters and return value.

kadi.modules.records.export.get_record_rdf_data(record, export_filter, user)[source]

Export a record as an RDF graph in Turtle format.

See get_record_export_data() for an explanation of the parameters and return value.

kadi.modules.records.export.get_record_ro_crate_data(record, export_filter, user)[source]

Export a record as an RO-Crate.

See get_record_export_data() for an explanation of the parameters and return value.

kadi.modules.records.export.get_record_export_data(record, export_type, export_filter=None, user=None)[source]

Export a record in a given format.

Parameters:

record – The record to export.
export_type – The export type, one of "json", "rdf", "pdf", "qr" or "ro-crate".

export_filter –

(optional) A dictionary specifying various filters to adjust the returned export data, depending on the export type. Currently only usable in combination with the "json", "rdf", "pdf" and "ro-crate" export types. Note that the values in the example below represent the respective default values.

Example:

{
    # Whether user information about the creator of the record or any linked
    # resource should be excluded.
    "user": False,
    # Whether to exclude all (True), outgoing ("out") or incoming ("in")
    # links of the record with other records.
    "links": False,
    # A dictionary specifying a filter mask of extra metadata keys to
    # exclude, e.g. {"sample_key": {}, "sample_list": {"0": {}}}. The value
    # of each key can either be an empty dictionary, to exclude the whole
    # extra, or another dictionary with the same possibilities as in the
    # parent dictionary. For list entries, indices need to be specified as
    # strings, starting at 0.
    "extras": {},
    # Whether to apply the extras filter mask to any linked records as well.
    "propagate_extras": False,
    # To specify which kind of export data of records should be included in
    # an exported RO-Crate when using the "ro-crate" export type. All other
    # filters also apply to this export data, as far as applicable.
    "export_data": ["json", "rdf"],
    # Whether to return only the metadata file of an exported RO-Crate when
    # using the "ro-crate" export type.
    "metadata_only": False,
}

user – (optional) The user to check for various access permissions when generating the export data. Defaults to the current user.

Returns:

The exported record data as an in-memory byte stream using io.BytesIO or None if an unknown export type was given. Note that for the ro-crate export type, the returned data is an iterable producing the actual binary data on the fly instead, unless only the metadata file is exported by specifying the corresponding export filter.

kadi.modules.records.export.get_extras_json_data(record, export_filter)[source]

Export the extras of a record as a JSON file.

See get_extras_export_data() for an explanation of the parameters and return value.

kadi.modules.records.export.get_extras_export_data(record, export_type, export_filter=None)[source]

Export the extras of a record in a given format.

Parameters:

record – The record whose extras should be exported.
export_type – The export type, currently only "json".

export_filter –

(optional) A dictionary specifying various filters to adjust the returned export data. Note that the values in the example below represent the respective default values.

Example:

{
    # A dictionary specifying a filter mask of extra metadata keys to
    # exclude, e.g. {"sample_key": {}, "sample_list": {"0": {}}}. The value
    # of each key can either be an empty dictionary, to exclude the whole
    # extra, or another dictionary with the same possibilities as in the
    # parent dictionary. For list entries, indices need to be specified as
    # strings, starting at 0.
    "extras": {},
    # The format of an exported JSON file when using the "json" export type.
    # This can either be the regular format used by Kadi4Mat ("standard") or
    # a simplified format, mapping keys directly to their respective values
    # ("plain").
    "format": "standard",
}

Returns:

The exported extras data as an in-memory byte stream using io.BytesIO or None if an unknown export type was given.

class kadi.modules.records.extras.ExtrasJSONB(*args, **kwargs)[source]

Bases: TypeDecorator

Custom JSON type for values (potentially) containing extra metadata.

Converts float values to float explicitly, as larger float values might otherwise be interpreted as integers. This also works with dictionaries that do not contain extras directly, but as any nested dictionary value instead. See also Record.extras.

impl: alias of JSONB

process_result_value(value, dialect)[source]: Convert float values of any extras recursively.

class kadi.modules.records.extras.ExtraSchema(is_template=False, **kwargs)[source]

Bases: BaseSchema

Schema to represent extra metadata.

Also does all necessary conversion and validation when deserializing. See also Record.extras.

Parameters:: is_template – (optional) Flag indicating whether the schema is used within a template, in which case slightly different validation rules apply.

class kadi.modules.records.extras.ExtrasField(*args, **kwargs)[source]

Bases: JSONField

Custom convenience field to process and validate extra metadata.

Uses ExtraSchema for its validation.

Parameters:: is_template – (optional) See ExtraSchema.

process_formdata(valuelist)[source]

Process data received over the wire from a form.

This will be called during form construction with data supplied through the formdata argument.

Parameters:: valuelist – A list of strings to process.

kadi.modules.records.extras.is_nested_type(value_type)[source]

Check if the type of an extra metadata entry is nested.

Parameters:: value_type – The type of the extra metadata entry.
Returns:: True if the given type is nested, False otherwise.

kadi.modules.records.extras.filter_extras(extras, excluded_extras)[source]

Filter the given extra metadata.

Parameters:

extras – The extras to filter
excluded_extras – A filter mask of extra metadata keys to exclude. See get_record_export_data().

Returns:

A copy of the filtered extras.

kadi.modules.records.extras.remove_extra_values(extras)[source]

Remove all values of the the given extra metadata.

Parameters:: extras – The extras for which the values are to be removed.
Returns:: A copy of the extras without values.

kadi.modules.records.extras.extras_to_plain_json(extras)[source]

Convert the given extra metadata to a plain JSON structure.

Parameters:: extras – The extras to convert.
Returns:: The converted extras as dictionary.

kadi.modules.records.files.update_file(file, user=None, **kwargs)[source]

Update an existing file.

Note that this function issues a database commit or rollback.

Parameters:

file – The file to update.
user – (optional) The user who triggered the update. Defaults to the current user.
**kwargs – Keyword arguments that will be passed to kadi.lib.db.update_object().

Returns:

True if the file was updated successfully, False otherwise.

kadi.modules.records.files.delete_file(file, create_revision=True, user=None)[source]

Delete an existing file.

This will mark the file for deletion, i.e. only the file’s state will be changed. Note that this function issues one or more database commits.

Parameters:

file – The file to delete.
create_revision – (optional) Flag indicating whether a revision should be created for the deletion.
user – (optional) The user who triggered the deletion. Defaults to the current user.

kadi.modules.records.files.remove_file(file, delete_from_db=True)[source]

Remove a file from storage and optionally from the database.

Note that this function issues one or more database commits.

Parameters:

file – The file to remove.
delete_from_db – (optional) A flag indicating whether the file should be deleted from the database as well, instead of just doing a soft deletion.

kadi.modules.records.files.stream_files(record)[source]

Stream all files of a record to a client as ZIP archive.

Parameters:: record – The record the files belong to.
Returns:: The response object.

kadi.modules.records.files.get_custom_mimetype(file, base_mimetype=None)[source]

Get a custom MIME type of a file based on its content.

Uses the kadi.plugins.spec.kadi_get_custom_mimetype() plugin hook for custom MIME types based on the file’s content.

Parameters:

file – The file to get the MIME type of.
base_mimetype – (optional) The base MIME type of the file on which to base the custom MIME type.

Returns:

The custom MIME type or None if no valid custom MIME type was found.

kadi.modules.records.files.get_direct_upload_type(file)[source]

Get the direct upload type of a file.

This type can be used to determine whether a file can be directly edited via a corresponding editor in the frontend. Such files must have a certain format and must not exceed a size of 10 MB.

Parameters:: file – The file to get the direct upload type of.
Returns:: The direct upload type or None if no suitable type can be determined.

kadi.modules.records.files.get_permitted_files(filter_term='', record_id=None, user=None)[source]

Convenience function to get all active record files that a user can access.

In this context having access to a file means having read permission for the record the file belongs to.

Parameters:

filter_term – (optional) A (case insensitive) term to filter the files by their name or record identifier.
record_id – (optional) A record ID by which to filter the files.
user – (optional) The user to check for access permissions. Defaults to the current user.

Returns:

The permitted file objects as query.

class kadi.modules.records.forms.RecordLinksField(*args, **kwargs)[source]

Bases: JSONField

Custom field to process and validate record links.

Uses RecordLinkDataSchema for its validation.

process_formdata(valuelist)[source]

Process data received over the wire from a form.

This will be called during form construction with data supplied through the formdata argument.

Parameters:: valuelist – A list of strings to process.

to_dict()[source]: Convert this field into a dictionary representation.

set_initial_data(data=None, record=None, user=None)[source]

Set the initial data of this field.

Parameters:

data – (optional) The form data to use for prefilling. Defaults to the submitted data of the current field instance.
record – (optional) An existing record, which can be used to set the initial data instead of the given form data.
user – (optional) A user that will be used for checking various access permissions when setting the data. Defaults to the current user.

class kadi.modules.records.forms.BaseRecordForm(*args, **kwargs)[source]

Base form class for use in creating or updating records.

Parameters:

import_data – (optional) A dictionary containing data imported from a file used for prefilling the form.
record – (optional) A record used for prefilling the form.
template – (optional) A record or extras template used for prefilling the form.

class kadi.modules.records.forms.NewRecordForm(*args, **kwargs)[source]

Bases: BaseRecordForm

A form for use in creating new records.

Parameters:

import_data – (optional) See BaseRecordForm.
record – (optional) See BaseRecordForm.
template – (optional) See BaseRecordForm.
collection – (optional) A collection used for prefilling the linked collections.
user – (optional) A user that will be used for checking various access permissions when prefilling the form. Defaults to the current user.

class kadi.modules.records.forms.EditRecordForm(*args, **kwargs)[source]

Bases: BaseRecordForm

A form for use in editing existing records.

Parameters:: record – The record to edit, used for prefilling the form.

class kadi.modules.records.forms.AddRecordLinksForm(*args, **kwargs)[source]

Bases: BaseForm

A form for use in creating new record links.

Parameters:: user – (optional) A user that will be used for checking various access permissions when prefilling the form. Defaults to the current user.

class kadi.modules.records.forms.EditRecordLinkForm(*args, **kwargs)[source]

Bases: BaseForm

A form for use in editing existing record links.

Parameters:

record_link – The record link to edit, used for prefilling the form.
record – The record in whose context the given record link is edited.
user – (optional) A user that will be used for checking various access permissions when prefilling the form. Defaults to the current user.

class kadi.modules.records.forms.LinkCollectionsForm(*args, **kwargs)[source]

Bases: BaseForm

A form for use in linking records with collections.

class kadi.modules.records.forms.AddRolesForm(*args, **kwargs)[source]

Bases: BaseForm

A form for use in adding user or group roles to a record.

class kadi.modules.records.forms.UploadDataForm(*args, **kwargs)[source]

Bases: BaseForm

A form for use in uploading data for direct uploads.

Currently only used within the API with data sent via custom headers.

class Meta[source]

Bases: object

Container to store meta class attributes.

class kadi.modules.records.forms.UploadChunkForm(*args, **kwargs)[source]

Bases: BaseForm

A form for use in uploading data for chunked uploads.

Currently only used within the API with data sent via custom headers.

Parameters:: chunk_count – The total amount of chunks that the upload this chunk is part of has. Will be used to validate the chunk’s index and size.

class Meta[source]

Bases: object

Container to store meta class attributes.

class kadi.modules.records.forms.EditFileForm(*args, **kwargs)[source]

Bases: BaseForm

A form for use in editing file metadata.

Parameters:: file – A file used for prefilling the form and checking for duplicate file names.

kadi.modules.records.links.create_record_link(*, name, record_from, record_to, creator=None, term=None)[source]

Create a new record link.

Note that this function may issue a database commit.

Parameters:

name – See RecordLink.name.
record_from – The record that is being linked from.
record_to – The record that is being linked to.
creator – (optional) The creator of the record link. Defaults to the current user.
term – (optional) See RecordLink.term.

Returns:

The created record link.

Raises:

KadiPermissionError – If the creator does not have the necessary permissions.
ValueError – When trying to link a record with itself or the link already exists.

kadi.modules.records.links.create_record_links(record, record_link_data, creator=None)[source]

Convenience function to create multiple new record links at once.

For ease of use in view functions, as errors are silently ignored. Furthermore, only a single revision is created for each updated record, even if multiple links from/to a single record are involved.

Note that this function may issue one or more database commits.

Parameters:

record – The record the new links should be linked with.
record_link_data – A list of dictionaries containing record link data corresponding to the structure of RecordLinkDataSchema.
creator – (optional) The creator of the record links. Defaults to the current user.

Returns:

The number of record links that were created successfully.

kadi.modules.records.links.update_record_link(record_link, user=None, **kwargs)[source]

Update an existing record link.

Note that this function may issue a database commit.

Parameters:

record_link – The record link to update.
user – (optional) The user performing the update operation. Defaults to the current user.
**kwargs – Keyword arguments that will be passed to kadi.lib.db.update_object().

Raises:

KadiPermissionError – If the user performing the operation does not have the necessary permissions.
ValueError – When the link already exists.

kadi.modules.records.links.remove_record_link(record_link, user=None)[source]

Remove an existing record link.

Note that this function may issue a database commit.

Parameters:

record_link – The record link to remove.
user – (optional) The user performing the remove operation. Defaults to the current user.

Raises:

KadiPermissionError – If the user performing the operation does not have the necessary permissions.

kadi.modules.records.links.get_linked_record(record_link, record)[source]

Get the record another record is linked to based on a given record link.

Record_link:: The record link.
Record:: One of the records linked via the given record link.
Returns:: A record linked to the given record via the given record link or None if the given record is not part of the given record link.

kadi.modules.records.links.get_permitted_record_links(record_or_id, direction=None, actions=None, user=None)[source]

Convenience function to get all links of a record that a user can access.

In this context having access to a record link means having read permission for each record the given record links to or is linked from. Note that record links containing inactive records will be filtered out.

Parameters:

record_or_id – The record or ID of a record whose links should be obtained.
direction – (optional) A direction to limit the returned record links to. One of "out" for outgoing links from the given record, or "in" for incoming links to the given record.
actions – (optional) A list of further actions to check as part of the access permissions of records.
user – (optional) The user to check for access permissions. Defaults to the current user.

Returns:

The permitted record link objects as query.

kadi.modules.records.links.get_record_link_changes(record_link)[source]

Get all changes of linked records since the given record link was updated.

The collected changes are based on the record and file revisions of the two linked records that were created since the record link was last updated.

Parameters:

record_link – The record link representing the two linked records whose changes should be collected.

Returns:

The changes of the linked records, consisting of the amount of new record and file revisions for each record. For the record revisions, the revision created immediately after updating the record link will also be included, if there has been at least one further change since then. The changes are returned as a dictionary in the following form:

{
    <record_from_id>: {
        "record": {
            "count": 1,
            "revision": <revision>,
        },
        "files": {
            "count": 2,
        },
    },
    <record_to_id>: {
        "record": {
            "count": 0,
            "revision": None,
        },
        "files": {
            "count": 1,
        },
    },
}

kadi.modules.records.links.get_record_links_graph(record, depth=1, direction=None, user=None)[source]

Get the links of a record for visualizing them in a graph.

Used in conjunction with D3.js to visualize the record links in a graph.

Parameters:

record – The record to start with.
depth – (optional) The link depth.
direction – (optional) A direction to limit the returned record links to. One of "out" for outgoing links from the start record, or "in" for incoming links to the start record.
user – (optional) The user to check for access permissions regarding the linked records. Defaults to the current user.

Returns:

A dictionary containing the record links ("record_links") as well as all records ("records") involved in the links.

class kadi.modules.records.mappings.BaseExtraMapping(meta: Dict[str, Any] | None = None, **kwargs: Any)[source]

Bases: InnerDoc

Base search mapping for extra metadata entries of records.

class kadi.modules.records.mappings.ExtraMappingString(meta: Dict[str, Any] | None = None, **kwargs: Any)[source]

Search mapping for extra string values.

class kadi.modules.records.mappings.ExtraMappingInteger(meta: Dict[str, Any] | None = None, **kwargs: Any)[source]

Search mapping for extra integer values.

Uses long values for the internal representation.

class kadi.modules.records.mappings.ExtraMappingFloat(meta: Dict[str, Any] | None = None, **kwargs: Any)[source]

Search mapping for extra float values.

Uses double values for the internal representation.

class kadi.modules.records.mappings.ExtraMappingBoolean(meta: Dict[str, Any] | None = None, **kwargs: Any)[source]

Search mapping for extra boolean values.

class kadi.modules.records.mappings.ExtraMappingDate(meta: Dict[str, Any] | None = None, **kwargs: Any)[source]

Search mapping for extra date values.

class kadi.modules.records.mappings.RecordMapping(meta: Dict[str, Any] | None = None, **kwargs: Any)[source]

Search mapping for records.

See Record.

classmethod create_document(obj)[source]

Create a new document to be indexed in ElasticSearch

Parameters:: obj – The object to be indexed.
Returns:: The created document.

class kadi.modules.records.models.RecordVisibility[source]

Bases: StringEnum

String enum containing all possible visibility values for records.

class kadi.modules.records.models.RecordState[source]

Bases: StringEnum

String enum containing all possible state values for records.

class kadi.modules.records.models.Record(**kwargs)[source]

Bases: SimpleReprMixin, SearchableMixin, StateTimestampMixin, FavoriteMixin, TaggingMixin, Model

Model to represent records.

class Meta[source]

Bases: object

Container to store meta class attributes.

representation = ['id', 'user_id', 'identifier', 'visibility', 'state']: See SimpleReprMixin.

search_mapping = 'kadi.modules.records.mappings.RecordMapping': See SearchableMixin.

timestamp_exclude = ['uploads', 'temporary_files']: See BaseTimestampMixin.

revision = ['identifier', 'title', 'type', 'description', 'extras', 'visibility', 'state', 'license[name]', 'tags[name]', 'links_to[id, record_to_id, name, term]', 'linked_from[id, record_from_id, name, term]']: See kadi.lib.revisions.core.setup_revisions().

permissions = {'actions': {'create': 'Create new records.', 'delete': l'Delete this record.', 'link': l'Manage links of this record with other resources.', 'permissions': l'Manage permissions of this record.', 'read': l'View this record and its files.', 'update': l'Edit this record and its files.'}, 'default_permissions': {'read': {'visibility': 'public'}}, 'roles': {'admin': ['read', 'link', 'update', 'permissions', 'delete'], 'collaborator': ['read', 'link'], 'editor': ['read', 'link', 'update'], 'member': ['read']}}

Available actions, roles and default permissions for records.

See kadi.lib.permissions.

check_constraints = {'description': {'length': {'max': 50000}}, 'identifier': {'length': {'max': 50}}, 'state': {'values': ['active', 'deleted', 'purged']}, 'title': {'length': {'max': 150}}, 'type': {'length': {'max': 50}}, 'visibility': {'values': ['private', 'public']}}: See kadi.lib.db.generate_check_constraints().

id: The ID of the record, auto incremented.

user_id: The ID of the User who created the record.

identifier

The unique identifier of the record.

Restricted to a maximum length of 50 characters.

title

The title of the record.

Restricted to a maximum length of 150 characters.

type

The optional type of the record.

Restricted to a maximum length of 50 characters.

description

The description of the record.

Restricted to a maximum length of 50_000 characters.

plain_description

The plain description of the record.

Equal to the normal description with the difference that most markdown is stripped out and whitespaces are normalized.

license_id: The optional ID of the License of the record.

extras

The extra metadata of the record.

The extras are stored in JSON format as an array of objects, each object corresponding to an enhanced key/value-pair representing the metadatum. Each object contains some or all of the following properties:

type: The type of the extra, which is always present and must be one of "str", "int", "float", "bool", "date", "dict" or "list". Dictionaries ("dict") and lists ("list") contain nested values of the same structure as the top level extra metadata values (i.e. an array of objects), the only difference being that "list" values have no keys. All other types contain literal values of the corresponding type:
- "str": A (non-empty) string value.
- "int": An integer value. Limited to values between -(2^53 - 1) and 2^53 - 1.
- "float": A float value using double-precision (64 Bit) floating point format.
- "bool": A (binary) boolean value, either true or false.
- "date": A date and time string value according to ISO 8601 format.
key: The key of the extra as string, which needs to be unique within each array. Except for "list" values, it always needs to be present.
value: The value of the extra depending on its type. Defaults to null for literal values and an empty array for nested types.
unit: A unit the value corresponds to as string. Only usable in combination with the "int" or "float" type. Defaults to null.
description: An optional description of the extra as string.
term: An optional IRI (Internationalized Resource Identifier) as string, which can be used to specify an existing term that the extra should represent.
validation: An optional object containing additional, also optional, validation instructions for the values of non-nested types. The following instructions are currently supported:
- required: A boolean value indicating whether the value of the extra should be required, i.e. not null.
- options: An array containing an enumeration of (distinct) possible values that the extra can have, which all need to match the type of the extra. Only usable in combination with the "str", "int" or "float" type.
- range: An object containing a maximum ("max") and minimum ("min") value to restrict the range of the value an extra can have. Each range value may also be null, in which case the values are only limited in one direction. Note that the range is always inclusive. Only usable in combination with the "int" or "float" type.
- iri: A boolean value indicating whether the value of the extra represents an IRI. Only usable in combination with the "str" type.

visibility

The default visibility of the record.

One of "private" or "public".

state

The state of the record.

One of "active", "deleted" or "purged".

property active_files: Get all active files of a record as a query.

classmethod create(*, creator, identifier, title, type=None, description='', plain_description='', license=None, extras=None, visibility='private', state='active')[source]

Create a new record and add it to the database session.

Parameters:

creator – The creator of the record.
identifier – The unique identifier of the record.
title – The title of the record.
type – (optional) The type of the record.
description – (optional) The description of the record.
plain_description – (optional) The plain description of the record.
license – (optional) The license of the record.
extras – (optional) The extra metadata of the record.
visibility – (optional) The default visibility of the record.
state – (optional) The state of the record.

Returns:

The new Record object.

created_at

The date and time an object has been created at.

Always uses the current UTC time.

last_modified

The date and time an object was last modified.

Always uses the current UTC time as initial value. After calling register_timestamp_listener() for an inheriting mixin class, this timestamp can automatically get updated by implementing _before_flush_timestamp() as a class method.

class kadi.modules.records.models.RecordLink(**kwargs)[source]

Bases: SimpleReprMixin, SimpleTimestampMixin, Model

Model to represent directional links between records.

class Meta[source]

Bases: object

Container to store meta class attributes.

representation = ['id', 'name', 'record_from_id', 'record_to_id']: See SimpleReprMixin.

check_constraints = {'name': {'length': {'max': 150}}, 'term': {'length': {'max': 2048}}}: See kadi.lib.db.generate_check_constraints().

id: The ID of the link, auto incremented.

user_id: The ID of the User who created the record link.

name

The name of the link.

Restricted to a maximum length of 150 characters.

term

An optional IRI of an existing term that the link should represent.

Restricted to a maximum length of 2_048 characters.

record_from_id: The ID of the Record the link points from.

record_to_id: The ID of the Record the link points to.

classmethod create(*, creator, name, record_from, record_to, term=None)[source]

Create a new record link and add it to the database session.

Parameters:

creator – The creator of the record link.
name – The name of the link.
record_from – The record the link points from.
record_to – The record the link points to.
term – (optional) The term the record link should represent.

Returns:

The new RecordLink object.

created_at

The date and time an object has been created at.

Always uses the current UTC time.

last_modified

The date and time an object was last modified.

Always uses the current UTC time as initial value. After calling register_timestamp_listener() for an inheriting mixin class, this timestamp can automatically get updated by implementing _before_flush_timestamp() as a class method.

class kadi.modules.records.models.FileState[source]

Bases: StringEnum

String enum containing all possible state values for files.

class kadi.modules.records.models.File(**kwargs)[source]

Bases: SimpleReprMixin, StateTimestampMixin, Model

Model to represent files.

class Meta[source]

Bases: object

Container to store meta class attributes.

representation = ['id', 'user_id', 'record_id', 'name', 'size', 'mimetype', 'storage_type', 'state']: See SimpleReprMixin.

timestamp_exclude = ['storage_type', 'uploads']: See BaseTimestampMixin.

revision = ['name', 'description', 'size', 'mimetype', 'checksum', 'state']: See kadi.lib.revisions.core.setup_revisions().

check_constraints = {'checksum': {'length': {'max': 256}}, 'description': {'length': {'max': 50000}}, 'mimetype': {'length': {'max': 256}}, 'name': {'length': {'max': 256}}, 'size': {'range': {'min': 0}}, 'state': {'values': ['active', 'inactive', 'deleted']}}: See kadi.lib.db.generate_check_constraints().

id: The UUID of the file.

user_id: The ID of the User who created the file.

record_id: The ID of the Record the file belongs to.

name

The name of the file.

Restricted to a maximum length of 256 characters.

description

The description of the file.

Restricted to a maximum length of 50_000 characters.

size

The size of the file in bytes.

Must be a value greater than or equal to 0.

checksum

The checksum of the file.

The actual value depends on how a file was uploaded. For direct uploads, the value is an MD5 hash of the file’s content. For chunked uploads, the value is an MD5 hash created by first concatenating the MD5 hashes of all uploaded chunks (in chunk index order) and then calculating an MD5 hash of the result. The amount of chunks is then appended to the resulting value in the form of "<hash>-<chunk_count>".

Restricted to a maximum length of 256 characters.

mimetype

Regular MIME type of the file, possibly user-provided.

Restricted to a maximum length of 256 characters.

magic_mimetype: MIME type based on magic numbers in the file’s content.

storage_type: The storage provider type of the file.

state

The state of the file.

One of "active", "inactive" or "deleted".

property identifier

The identifier of the file.

Mainly used in correspondence with the file’s storage provider.

property storage: Get the storage provider of this file.

property has_md5_checksum: Check if the checksum of this file is an MD5 hash of it’s content.

classmethod create(*, creator, record, name, size, description='', checksum=None, mimetype='application/octet-stream', magic_mimetype=None, storage_type=None, state='inactive')[source]

Create a new file and add it to the database session.

Parameters:

creator – The creator of the file.
record – The record the file belongs to.
name – The name of the file.
size – The size of the file in bytes.
description – (optional) The description of the file.
checksum – (optional) The checksum of the file.
mimetype – (optional) The regular MIME type of the file.
magic_mimetype – (optional) The MIME type of the file based on its content.
storage_type – (optional) The storage provider type of the file. Defaults to the STORAGE_PROVIDER specified in the application’s configuration.
state – (optional) The state of the file.

Returns:

The new File object.

created_at

The date and time an object has been created at.

Always uses the current UTC time.

last_modified

The date and time an object was last modified.

Always uses the current UTC time as initial value. After calling register_timestamp_listener() for an inheriting mixin class, this timestamp can automatically get updated by implementing _before_flush_timestamp() as a class method.

class kadi.modules.records.models.UploadType[source]

Bases: StringEnum

String enum containing all currently used upload type values for uploads.

class kadi.modules.records.models.UploadState[source]

Bases: StringEnum

String enum containing all possible state values for uploads.

class kadi.modules.records.models.Upload(**kwargs)[source]

Bases: SimpleReprMixin, StateTimestampMixin, Model

Model to represent uploads.

class Meta[source]

Bases: object

Container to store meta class attributes.

representation = ['id', 'user_id', 'record_id', 'file_id', 'name', 'size', 'storage_type', 'upload_type', 'state']: See SimpleReprMixin.

timestamp_exclude = ['storage_type']: See BaseTimestampMixin.

check_constraints = {'checksum': {'length': {'max': 256}}, 'chunk_count': {'range': {'min': 1}}, 'description': {'length': {'max': 50000}}, 'mimetype': {'length': {'max': 256}}, 'name': {'length': {'max': 256}}, 'size': {'range': {'min': 0}}, 'state': {'values': ['active', 'inactive', 'processing']}, 'upload_type': {'values': ['direct', 'chunked']}}: See kadi.lib.db.generate_check_constraints().

id: The UUID of the upload.

user_id: The ID of the User who initiated the upload.

record_id: The ID of the Record the upload belongs to.

file_id: The optional ID of a File to be overwritten by the upload.

name

The name of the upload.

Restricted to a maximum length of 256 characters.

size

The size of the upload in bytes.

Must be a value greater than or equal to 0.

checksum

The checksum of the upload.

Calculated automatically during the upload process. The actual value depends on the upload type and is copied to the resulting file, see File.checksum.

Restricted to a maximum length of 256 characters.

created_at

The date and time an object has been created at.

Always uses the current UTC time.

description

The optional description of the upload.

Restricted to a maximum length of 50_000 characters.

last_modified

The date and time an object was last modified.

Always uses the current UTC time as initial value. After calling register_timestamp_listener() for an inheriting mixin class, this timestamp can automatically get updated by implementing _before_flush_timestamp() as a class method.

mimetype

The optional MIME type of the upload.

Restricted to a maximum length of 256 characters.

chunk_count

Number of chunks an upload is split into.

For direct uploads, the chunk count is always 1.

Must be a value greater than or equal to 1.

storage_type: The storage provider type of the upload.

upload_type

The type of the upload.

One of "direct" or "chunked".

state

The state of the upload.

One of "active", "inactive" or "processing".

property identifier

The identifier of the upload.

Mainly used in correspondence with the upload’s storage provider.

property storage: Get the storage provider of this upload.

property active_chunks: Get all active chunks of this upload as query.

classmethod create(*, creator, record, name, size, description=None, mimetype=None, chunk_count=None, storage_type=None, upload_type=None, file=None, state='active')[source]

Create a new upload and add it to the database session.

Parameters:

creator – The user who is initiating the upload.
record – The record the upload belongs to.
name – The name of the upload.
size – The size of the upload in bytes.
description – (optional) The description of the upload.
mimetype – (optional) The MIME type of the upload.
chunk_count – (optional) The chunk count of the upload. Defaults to an automatically calculated value based on kadi.lib.constants.UPLOAD_CHUNK_SIZE for chunked uploads, and to 1 for direct uploads.
storage_type – (optional) The storage provider type of the upload. Defaults to the STORAGE_PROVIDER specified in the application’s configuration.
upload_type – (optional) The upload type. Defaults to a type based on the provided size and kadi.lib.constants.UPLOAD_CHUNKED_BOUNDARY.
file – (optional) A file the upload should replace.
state – The state of the upload.

Returns:

The new Upload object.

class kadi.modules.records.models.ChunkState[source]

Bases: StringEnum

String enum containing all possible state values for chunks.

class kadi.modules.records.models.Chunk(**kwargs)[source]

Bases: SimpleReprMixin, Model

Model to represent file chunks.

class Meta[source]

Bases: object

Container to store meta class attributes.

representation = ['id', 'upload_id', 'index', 'size', 'state']: See SimpleReprMixin.

check_constraints = {'checksum': {'length': {'max': 256}}, 'index': {'range': {'min': 0}}, 'size': {'range': {'min': 0}}, 'state': {'values': ['active', 'inactive']}}: See kadi.lib.db.generate_check_constraints().

id: The ID of the chunk, auto incremented.

upload_id: The ID of the Upload the chunk belongs to.

index

The index of the chunk inside its upload.

Must be a value greater than or equal to 0.

size

The size of the chunk in bytes.

Must be a value greater than or equal to 0.

checksum

The checksum of the chunk.

Always corresponds to an MD5 hash of the chunk’s content, which is calculated automatically during the chunk upload process.

Restricted to a maximum length of 256 characters.

state

The state of the chunk.

One of "active" or "inactive".

property identifier

The identifier of the chunk.

Mainly used in correspondence with the storage provider of the chunk’s upload.

classmethod create(*, upload, index, size, state='inactive')[source]

Create a new chunk and add it to the database session.

Parameters:

upload – The upload the chunk belongs to.
index – The index of the chunk.
size – The size of the chunk in bytes.
state – (optional) The state of the chunk.

Returns:

The new Chunk object.

classmethod update_or_create(*, upload, index, size, state='inactive')[source]

Update an existing chunk or create one if it does not exist yet.

See create() for an explanation of the parameters.

Returns:: The new or updated Chunk object.

class kadi.modules.records.models.TemporaryFileState[source]

Bases: StringEnum

String enum containing all possible state values for temporary files.

class kadi.modules.records.models.TemporaryFile(**kwargs)[source]

Bases: SimpleReprMixin, StateTimestampMixin, Model

Model to represent temporary files.

Currently not used anymore, but may still be repurposed in the future.

created_at

The date and time an object has been created at.

Always uses the current UTC time.

last_modified

The date and time an object was last modified.

Always uses the current UTC time as initial value. After calling register_timestamp_listener() for an inheriting mixin class, this timestamp can automatically get updated by implementing _before_flush_timestamp() as a class method.

class Meta[source]

Bases: object

Container to store meta class attributes.

representation = ['id', 'user_id', 'record_id', 'type', 'name', 'size', 'mimetype', 'state']: See SimpleReprMixin.

check_constraints = {'mimetype': {'length': {'max': 256}}, 'name': {'length': {'max': 256}}, 'size': {'range': {'min': 0}}, 'state': {'values': ['active', 'inactive']}}: See kadi.lib.db.generate_check_constraints().

id: The UUID of the temporary file.

user_id: The ID of the User who created the temporary file.

record_id: The ID of the Record the temporary file belongs to.

type

The optional type of the temporary file.

Can be used to distinguish different types of temporary files for different use cases.

name

The name of the temporary file.

Restricted to a maximum length of 256 characters.

size

The size of the temporary file in bytes.

Must be a value greater than or equal to 0.

mimetype

MIME type of the temporary file.

Restricted to a maximum length of 256 characters.

state

The state of the temporary file.

One of "active" or "inactive".

classmethod create(*, creator, record, name, size, type=None, mimetype=None, state='inactive')[source]

Create a new temporary file and add it to the database session.

Parameters:

creator – The creator of the temporary file.
record – The record the temporary file belongs to.
name – The name of the temporary file.
size – The size of the temporary file in bytes.
type – (optional) The type of the temporary file.
mimetype – (optional) The MIME type of the temporary file. Defaults to a MIME type based on the filename or the default MIME type as defined in kadi.lib.constants.MIMETYPE_BINARY if it cannot be guessed.
state – (optional) The state of the temporary file.

Returns:

The new TemporaryFile object.

kadi.modules.records.previews.get_builtin_preview_data(file)[source]

Get the preview data of a file based on all built-in preview types.

Parameters:: file – The File to get the preview data of.
Returns:: The preview type and preview data as tuple or None` if none of the built-in preview types are suitable.

kadi.modules.records.previews.get_preview_data(file, use_fallback=True)[source]

Get the preview data of a file.

Uses the kadi.plugins.spec.kadi_get_preview_data() plugin hook for custom preview data.

Parameters:

file – The File to get the preview data of.
use_fallback – (optional) Flag indicating whether the file should be checked for textual data as fallback.

Returns:

The preview type and preview data as tuple, which are always guaranteed to be JSON serializable. If either the preview type or data could not be determined, None is returned.

class kadi.modules.records.schemas.RecordSchema(previous_record=None, linked_collection=None, is_template=False, **kwargs)[source]

Schema to represent records.

See Record.

Parameters:

previous_record – (optional) A record whose identifier should be excluded when checking for duplicates while deserializing.
linked_collection – (optional) A collection that is linked to each record that should be serialized. Will be used to build endpoints for corresponding actions.
is_template – (optional) Flag indicating whether the schema is used inside a template. Currently, this is only relevant for the extra metadata.

class kadi.modules.records.schemas.RecordRevisionSchema(previous_record=None, linked_collection=None, is_template=False, **kwargs)[source]

Bases: RecordSchema

Schema to represent record revisions.

Additionally includes the direct serialization of record links with a limited subset of attributes.

class kadi.modules.records.schemas.RecordImportSchema(previous_record=None, linked_collection=None, is_template=False, **kwargs)[source]

Bases: RecordSchema

Schema to represent imported record data.

class kadi.modules.records.schemas.BaseRecordLinkSchema(*args, _internal=None, **kwargs)[source]

Bases: BaseSchema

Base schema class to represent record links.

class kadi.modules.records.schemas.RecordLinkSchema(current_record=None, **kwargs)[source]

Bases: BaseRecordLinkSchema

Schema to represent record links.

See RecordLink.

Parameters:: current_record – (optional) The current record in whose context the record links are being serialized, in order to generate corresponding URLs to view or edit each record link. Only relevant for internal use.

class kadi.modules.records.schemas.RecordLinkDataSchema(*args, _internal=None, **kwargs)[source]

Bases: BaseRecordLinkSchema

Schema to represent the data of a generic record link in a certain direction.

Mainly useful in combination with kadi.modules.records.links.create_record_links() and within templates.

class kadi.modules.records.schemas.RecordLinkRevisionSchema(current_record=None, **kwargs)[source]

Bases: RecordLinkSchema

Schema to represent record link revisions.

Additionally includes the direct serialization of the IDs of the linked records.

class kadi.modules.records.schemas.FileSchema(record=None, previous_file=None, **kwargs)[source]

Bases: BaseSchema

Schema to represent files.

See File.

Parameters:

record – (optional) A record the file to be deserialized belongs to. Will be used to check for duplicate filenames while deserializing.
previous_file – (optional) A file that will be excluded when checking for duplicate filenames while deserializing.

class kadi.modules.records.schemas.UploadSchema(*args, _internal=None, **kwargs)[source]

Bases: BaseSchema

Schema to represent uploads.

See Upload.

class kadi.modules.records.schemas.ChunkSchema(*args, _internal=None, **kwargs)[source]

Bases: BaseSchema

Schema to represent chunks.

See Chunk.

kadi.modules.records.tasks.start_merge_chunks_task(upload, user=None)[source]

Merge the chunks of a local file upload in a background task.

Uses kadi.modules.records.uploads.merge_chunk_data(). The created task will be kept in the database.

Note that this function issues one or more database commits.

Parameters:

upload – The upload that the chunks belong to.
user – (optional) The user who started the task. Defaults to the current user.

Returns:

The new task object if the task was started successfully, None otherwise.

kadi.modules.records.tasks.start_purge_record_task(record)[source]

Purge an existing record in a background task.

Uses kadi.modules.records.core.purge_record().

Parameters:: record – The record to purge.

kadi.modules.records.uploads.delete_upload(upload)[source]

Delete an existing upload.

This will mark the upload for deletion, i.e. only the upload’s state will be changed.

Parameters:: upload – The upload to delete.

kadi.modules.records.uploads.remove_upload(upload)[source]

Remove an upload from storage and from the database.

Note that this function issues one or more database commits.

Parameters:: upload – The upload to remove.

kadi.modules.records.uploads.save_chunk_data(upload, stream, *, index, size, checksum=None)[source]

Save the uploaded chunk data of a chunked upload.

Note that this function issues one or more database commits.

Parameters:

upload – The upload.
stream – The chunk data as a readable binary stream.
index – The index of the chunk.
size – The size of the chunk in bytes.
checksum – (optional) The checksum of the chunk. If provided, it will be used to verify the calculated checksum after saving the chunk.

Returns:

The created or updated Chunk object.

Raises:

KadiFilesizeExceededError – If the chunk data exceeds the size of its upload or the maximum chunk size.
KadiFilesizeMismatchError – If the actual size of the chunk data does not match the provided size.
KadiChecksumMismatchError – If the actual checksum of the chunk data does not match the provided checksum.

kadi.modules.records.uploads.merge_chunk_data(upload)[source]

Merge the chunk data of a chunked upload.

Note that this function issues one or more database commits or rollbacks.

Parameters:: upload – The upload.
Returns:: The newly created or updated file or None if a conflict occured while completing the upload.
Raises:: KadiFilesizeMismatchError – If the actual final size of the upload data does not match the size provided when the upload was created.

kadi.modules.records.uploads.save_upload_data(upload, stream, checksum=None)[source]

Save the uploaded data of a direct upload.

Note that this function issues one or more database commits or rollbacks.

Parameters:

upload – The upload.
stream – The upload data as a readable binary stream.
checksum – (optional) The checksum of the upload. If provided, it will be used to verify the calculated checksum after saving the upload.

Returns:

The newly created or updated file or None if a conflict occured while completing the upload.

Raises:

KadiFilesizeExceededError – If the upload data exceeds the size of its upload or the maximum direct upload size.
KadiFilesizeMismatchError – If the actual size of the upload data does not match match the size provided when the upload was created.
KadiChecksumMismatchError – If the actual checksum of the upload data does not match the provided checksum.

kadi.modules.records.utils.search_records(search_query=None, page=1, per_page=10, sort='_score', visibility=None, explicit_permissions=False, user_ids=None, collection_ids=None, child_collections=False, record_types=None, tags=None, tag_operator='or', mimetypes=None, extras=None, user=None)[source]

Search for and filter records.

Uses kadi.lib.resources.utils.get_filtered_resources() and kadi.lib.resources.utils.search_resources().

Parameters:

search_query – (optional) See kadi.lib.resources.utils.search_resources().
page – (optional) See kadi.lib.resources.utils.search_resources().
per_page – (optional) See kadi.lib.resources.utils.search_resources().
sort – (optional) See kadi.lib.resources.utils.search_resources().
visibility – (optional) See kadi.lib.resources.utils.get_filtered_resources().
explicit_permissions – (optional) See kadi.lib.resources.utils.get_filtered_resources().
user_ids – (optional) See kadi.lib.resources.utils.get_filtered_resources().
collection_ids – (optional) A list of collection IDs the searched records need to belong to.
child_collections – (optional) Flag indicating whether the records of the children of the given collection IDs should be included.
record_types – (optional) A list of record types to filter the records with.
tags – (optional) A list of tag names to filter the records with.
tag_operator – (optional) The operator to filter the tags with. One of "or" or "and".
mimetypes – (optional) A list of MIME types to filter the records with based on their files

extras –

(optional) A list of dictionaries to specifiy search queries within the extra metadata of records. Each query can contain a link type, a key, a type and one or multiple value restrictions depending on the type. See also Record.extras.

Example:

[
    {
        # The link type, one of "and" or "or". Note that the link type of
        # the first query can also be left out.
        "link": "and",
        # The key of the metadatum. Supports exact matches when surrounded
        # by double quotes.
        "key": "sample key",
        # The type of the metadatum, one of "str", "numeric" (for integer
        # and float values), "bool" or "date".
        "type": "str",
        # The string value of the metadatum if the type is "str". Supports
        # exact matches when surrounded by double quotes.
        "str": "string",
        # Restrictions about the numeric value of the metadatum if the type
        # is "numeric". Either a minimum value ("min"), a maximum value
        # ("max") or both can be specified. Note that the range is always
        # inclusive. Units ("unit") can optionally be specified as well and
        # are always matched exactly.
        "numeric": {"min": 0, "max": 1, "unit": "cm"},
        # The boolean value of the metadatum if the type is "bool", one of
        # True, "true", False or "false".
        "bool": True,
        # Restrictions about the date value of the metadatum if the type is
        # "date". Either a minimum value ("min"), a maximum value ("max") or
        # both can be specified as a formatted date string. Note that the
        # range is always inclusive.
        "date": {
            "min": "2020-07-01T00:00:00.000Z",
            "max": "2020-07-02T00:00:00.000Z",
        },
    },
]

user – (optional) The user to check for any permissions regarding the searched records. Defaults to the current user.

Returns:

The search results as returned by kadi.lib.resources.utils.search_resources().

kadi.modules.records.utils.get_user_quota(user=None)[source]

Get the total size (quota) of a user’s files and uploads.

All active files as well as active and processing uploads are taken into account. Uploads that replace files are only considered if their size is larger than the file they are replacing, in which case the size difference between the upload and the replaced file is added to the total. Note that if multiple uploads replace the same file, their combined size is taken instead.

Parameters:: user – (optional) The user to calculate the quota for. Defaults to the current user.
Returns:: The user’s quota.

kadi.modules.records.utils.parse_import_data(stream, import_type)[source]

Parse imported record data of a given format.

Parameters:

stream – The import data as a readable binary stream.
import_type – The import type, currently only "json".

Returns:

The imported record data as a dictionary. Note that none of the record attributes are guaranteed to be present.

kadi.modules.records.utils.clean_files(inside_task=False)[source]

Clean all expired/inactive files and uploads.

Note that this function may issue one or more database commits.

Parameters:: inside_task – (optional) A flag indicating whether the function is executed in a task. In that case, additional information will be logged.

Settings

class kadi.modules.settings.forms.OrcidField(*args, **kwargs)[source]

Bases: StringField

Custom field to process and validate ORCID iDs.

process_formdata(valuelist)[source]

Process data received over the wire from a form.

This will be called during form construction with data supplied through the formdata argument.

Parameters:: valuelist – A list of strings to process.

class kadi.modules.settings.forms.HomeLayoutField(*args, **kwargs)[source]

Bases: JSONField

Custom field to process and validate preferences for the home page layout.

process_formdata(valuelist)[source]

Process data received over the wire from a form.

This will be called during form construction with data supplied through the formdata argument.

Parameters:: valuelist – A list of strings to process.

class kadi.modules.settings.forms.ScopesField(*args, **kwargs)[source]

Bases: StringField

Custom field to process and validate access token scopes.

process_formdata(valuelist)[source]

Process data received over the wire from a form.

This will be called during form construction with data supplied through the formdata argument.

Parameters:: valuelist – A list of strings to process.

class kadi.modules.settings.forms.RedirectURIsField(*args, **kwargs)[source]

Bases: LFTextAreaField

Custom field to process and validate OAuth2 redirect URIs.

Parameters:: max_len – (optional) The maximum length of each invidiual URI.

process_formdata(valuelist)[source]

Process data received over the wire from a form.

This will be called during form construction with data supplied through the formdata argument.

Parameters:: valuelist – A list of strings to process.

to_dict()[source]: Convert this field into a dictionary representation.

class kadi.modules.settings.forms.EditProfileForm(*args, **kwargs)[source]

Bases: BaseForm

A form for use in editing a user’s profile information.

Parameters:: user – The user to prepopulate the fields with.

class kadi.modules.settings.forms.ChangePasswordForm(*args, **kwargs)[source]

Bases: BaseForm

A form for use in changing a local user’s password.

class kadi.modules.settings.forms.CustomizationPreferencesForm(*args, **kwargs)[source]

Bases: BaseConfigForm

A form for use in setting user-specific config items related to customization.

Parameters:: user – (optional) The user to pass to BaseConfigForm. Defaults to the current user.

class kadi.modules.settings.forms.NewPersonalTokenForm(*args, **kwargs)[source]

Bases: BaseForm

A form for use in creating new personal tokens.

clear()[source]: Reset all relevant field data of this form to their default values.

class kadi.modules.settings.forms.BaseApplicationForm(*args, **kwargs)[source]

Bases: BaseForm

Base form class for use in creating or updating OAuth2 applications.

class kadi.modules.settings.forms.NewApplicationForm(*args, **kwargs)[source]

Bases: BaseApplicationForm

A form for use in creating new OAuth2 applications.

clear()[source]: Reset all relevant field data of this form to their default values.

class kadi.modules.settings.forms.EditApplicationForm(*args, **kwargs)[source]

Bases: BaseApplicationForm

A form for use in editing existing OAuth2 application.

Parameters:: application – The application to edit, used for prefilling the form.

kadi.modules.settings.utils.get_plugin_preferences_configs()[source]

Get all plugin preferences configurations.

Uses the kadi.plugins.spec.kadi_get_preferences_config() plugin hook to collect all potential configurations.

Returns:: A dictionary of plugin preferences configurations, mapping the name of each plugin (as specificed in the plugin forms) to a dictionary in the form expected by kadi.plugins.spec.kadi_get_preferences_config().

Sysadmin

class kadi.modules.sysadmin.forms.NavFooterField(*args, **kwargs)[source]

Bases: JSONField

Custom field to process and validate navigation footer items.

Only performs some basic validation to make sure the overall structure of the items is valid.

process_formdata(valuelist)[source]

Process data received over the wire from a form.

This will be called during form construction with data supplied through the formdata argument.

Parameters:: valuelist – A list of strings to process.

class kadi.modules.sysadmin.forms.CustomizationConfigForm(*args, **kwargs)[source]

Bases: BaseConfigForm

A form for use in setting global config items related to customization.

class kadi.modules.sysadmin.forms.LegalsConfigForm(*args, **kwargs)[source]

Bases: BaseConfigForm

A form for use in setting global config items related to legal notices.

class kadi.modules.sysadmin.forms.MiscConfigForm(*args, **kwargs)[source]

Bases: BaseConfigForm

A form for use in setting miscellaneous global config items.

class kadi.modules.sysadmin.forms.MergeUsersForm(*args, **kwargs)[source]

Bases: BaseForm

A form for use in merging users.

kadi.modules.sysadmin.utils.sysadmin_required(func)[source]

Decorator to add access restrictions based on sysadmin status to an endpoint.

If the current user is not authenticated, the decorator will behave the same as Flask-Login’s login_required decorator.

kadi.modules.sysadmin.utils.save_index_image(stream)[source]

Save image data as the global index image config item.

Uses kadi.lib.storage.misc.save_as_thumbnail() to store the actual image data and kadi.lib.constants.SYS_CONFIG_INDEX_IMAGE as the key for the config item. Note that any previous index image will be deleted beforehand using delete_index_image(), which will also be called if the image could not be saved.

Parameters:: stream – The image data as a readable binary stream.

kadi.modules.sysadmin.utils.delete_index_image()[source]

Delete the global index image config item.

This is the inverse operation of save_index_image().

kadi.modules.sysadmin.utils.legals_acceptance_required()[source]

Check whether users need to accept the configured legal notices.

Returns:: True if any of the relevant legal notices are configured and accepting them is enforced, False otherwise.

kadi.modules.sysadmin.utils.get_legals_modification_date()[source]

Get the latest modification date of the configured legal notices.

Note that only config items in the database are considered, as only these track their modification date.

Returns:: The latest modification date as a datetime object as specified in Python’s datetime module or None if none of the relevant legal notices is configured in the database.

Templates

kadi.modules.templates.core.create_template(*, identifier, title, type, data, creator=None, description='', visibility='private', state='active')[source]

Create a new template.

Parameters:

identifier – See Template.identifier.
title – See Template.title.
type – See Template.type.
data – See Template.data.
creator – (optional) The creator of the template. Defaults to the current user.
description – (optional) See Template.description.
visibility – (optional) See Template.visibility.
state – (optional) See Template.state.

Returns:

kadi.modules.templates.core.update_template(template, data=None, user=None, **kwargs)[source]

Update an existing template.

Parameters:

template – The template to update.
data – (optional) See Template.data.
user – (optional) The user who triggered the update. Defaults to the current user.
**kwargs – Keyword arguments that will be passed to kadi.lib.resources.update_resource(). See also create_template().

Returns:

kadi.modules.templates.core.delete_template(template, user=None)[source]

Delete an existing template.

Parameters:

template – The template to delete.
user – (optional) The user who triggered the deletion. Defaults to the current user.

kadi.modules.templates.core.restore_template(template, user=None)[source]

Restore a deleted template.

Parameters:

template – The template to restore.
user – (optional) The user who triggered the restoration. Defaults to the current user.

kadi.modules.templates.core.purge_template(template)[source]

Purge an existing template.

Parameters:: template – The template to purge.

class kadi.modules.templates.export.TemplateShaclGraph(template, export_filter=None, user=None)[source]

Bases: RDFGraph

Template SHACL shapes graph export class.

See get_export_data() for an explanation of the parameters.

kadi.modules.templates.export.get_dict_data(template, export_filter, user)[source]

Export a template as a dictionary.

See get_export_data() for an explanation of the parameters.

Returns:: The exported template as a dictionary.

kadi.modules.templates.export.get_json_data(template, export_filter, user)[source]

Export a template as a JSON file.

See get_export_data() for an explanation of the parameters and return value.

kadi.modules.templates.export.get_json_schema_data(template, export_filter, user)[source]

Export a template as a JSON Schema file in JSON format.

See get_export_data() for an explanation of the parameters and return value.

kadi.modules.templates.export.get_shacl_data(template, export_filter, user)[source]

Export a template as a SHACL shapes graph.

See get_export_data() for an explanation of the parameters and return value.

kadi.modules.templates.export.get_export_data(template, export_type, export_filter=None, user=None)[source]

Export a template in a given format.

Parameters:

template – The template to export.
export_type – The export type, one of "json", "json-schema" or "shacl".

export_filter –

(optional) A dictionary specifying various filters to adjust the returned export data, depending on the export and template type. Note that the values in the example below represent the respective default values.

Example:

{
    # Whether user information about the creator of the template should be
    # excluded.
    "user": False,
    # A dictionary specifying a filter mask of extra metadata keys to
    # exclude, e.g. {"sample_key": {}, "sample_list": {"0": {}}}. The value
    # of each key can either be an empty dictionary, to exclude the whole
    # extra, or another dictionary with the same possibilities as in the
    # parent dictionary. For list entries, indices need to be specified as
    # strings, starting at 0.
    "extras": {},
}

user – (optional) The user to check for various access permissions when generating the export data. Defaults to the current user.

Returns:

The exported template data as an in-memory byte stream using io.BytesIO or None if an unknown export type was given.

class kadi.modules.templates.forms.BaseTemplateForm(*args, **kwargs)[source]

Base form class for use in creating or updating templates.

Parameters:

import_data – (optional) A dictionary containing data imported from a file used for prefilling the form.
template – (optional) A template used for prefilling the form, which must be of the correct type corresponding to each form class.

property template_data

Get the collected template data.

The data may optionally be validated again. If it is invalid, None should be returned instead.

class kadi.modules.templates.forms.BaseRecordTemplateForm(*args, **kwargs)[source]

Bases: BaseTemplateForm

Base form class for use in creating or updating record templates.

Parameters:

import_data – (optional) See BaseTemplateForm.
template – (optional) See BaseTemplateForm.
record – (optional) A record used for prefilling the template data.
user – (optional) A user that will be used for checking various access permissions when prefilling the form. Defaults to the current user.

property template_data

Get the collected template data.

The data may optionally be validated again. If it is invalid, None should be returned instead.

class kadi.modules.templates.forms.BaseExtrasTemplateForm(*args, **kwargs)[source]

Bases: BaseTemplateForm

Base form class for use in creating or updating extras templates.

Parameters:

import_data – (optional) See BaseTemplateForm.
template – (optional) See BaseTemplateForm.
record – (optional) A record used for prefilling the template data.

property template_data

Get the collected template data.

The data may optionally be validated again. If it is invalid, None should be returned instead.

class kadi.modules.templates.forms.NewTemplateFormMixin(*args, template=None, user=None, **kwargs)[source]

Bases: object

Mixin class for forms used in creating new templates.

Parameters:

template – (optional) See BaseTemplateForm.
user – (optional) A user that will be used for checking various access permissions when prefilling the form. Defaults to the current user.

class kadi.modules.templates.forms.NewRecordTemplateForm(*args, **kwargs)[source]

Bases: NewTemplateFormMixin, BaseRecordTemplateForm

A form for use in creating new record templates.

class kadi.modules.templates.forms.NewExtrasTemplateForm(*args, **kwargs)[source]

Bases: NewTemplateFormMixin, BaseExtrasTemplateForm

A form for use in creating new extras templates.

class kadi.modules.templates.forms.EditTemplateFormMixin(template, *args, **kwargs)[source]

Bases: object

Mixin class for forms used in editing existing templates.

Parameters:: template – The template to edit, used for prefilling the form.

class kadi.modules.templates.forms.EditRecordTemplateForm(*args, **kwargs)[source]

Bases: EditTemplateFormMixin, BaseRecordTemplateForm

A form for use in updating record templates.

class kadi.modules.templates.forms.EditExtrasTemplateForm(*args, **kwargs)[source]

Bases: EditTemplateFormMixin, BaseExtrasTemplateForm

A form for use in updating extras templates.

class kadi.modules.templates.forms.AddRolesForm(*args, **kwargs)[source]

Bases: BaseForm

A form for use in adding user or group roles to a template.

class kadi.modules.templates.mappings.TemplateMapping(meta: Dict[str, Any] | None = None, **kwargs: Any)[source]

Search mapping for templates.

See Template.

class kadi.modules.templates.models.TemplateVisibility[source]

Bases: StringEnum

String enum containing all possible visibility values for templates.

class kadi.modules.templates.models.TemplateType[source]

Bases: StringEnum

String enum containing all possible type values for templates.

class kadi.modules.templates.models.TemplateState[source]

Bases: StringEnum

String enum containing all possible state values for templates.

class kadi.modules.templates.models.Template(**kwargs)[source]

Bases: SimpleReprMixin, SearchableMixin, StateTimestampMixin, FavoriteMixin, Model

Model to represent templates.

class Meta[source]

Bases: object

Container to store meta class attributes.

representation = ['id', 'user_id', 'identifier', 'visibility', 'type', 'state']: See SimpleReprMixin.

search_mapping = 'kadi.modules.templates.mappings.TemplateMapping': See SearchableMixin.

timestamp_exclude = ['collections']: See BaseTimestampMixin.

revision = ['identifier', 'title', 'description', 'visibility', 'data', 'state']: See kadi.lib.revisions.core.setup_revisions().

permissions = {'actions': {'create': 'Create new templates.', 'delete': l'Delete this template.', 'permissions': l'Manage permissions of this template.', 'read': l'View this template.', 'update': l'Edit this template.'}, 'default_permissions': {'read': {'visibility': 'public'}}, 'roles': {'admin': ['read', 'update', 'permissions', 'delete'], 'editor': ['read', 'update'], 'member': ['read']}}

Available actions, roles and default permissions for templates.

See kadi.lib.permissions.

check_constraints = {'description': {'length': {'max': 50000}}, 'identifier': {'length': {'max': 50}}, 'state': {'values': ['active', 'deleted']}, 'title': {'length': {'max': 150}}, 'type': {'values': ['record', 'extras']}, 'visibility': {'values': ['private', 'public']}}: See kadi.lib.db.generate_check_constraints().

id: The ID of the template, auto incremented.

user_id: The ID of the User who created the template.

identifier

The unique identifier of the template.

Restricted to a maximum length of 50 characters.

created_at

The date and time an object has been created at.

Always uses the current UTC time.

last_modified

The date and time an object was last modified.

Always uses the current UTC time as initial value. After calling register_timestamp_listener() for an inheriting mixin class, this timestamp can automatically get updated by implementing _before_flush_timestamp() as a class method.

title

The title of the template.

Restricted to a maximum length of 150 characters.

description

The description of the template.

Restricted to a maximum length of 50_000 characters.

plain_description

The plain description of the template.

Equal to the normal description with the difference that most markdown is stripped out and whitespaces are normalized.

visibility

The default visibility of the template.

One of "private" or "public".

type

The type of the template.

One of "record" or "extras".

data

The data of the template depending on its type.

The data is stored in JSON format. For each of the template types, it consists of:

"record": An object containing all relevant record properties as keys with corresponding values. See also Record. Furthermore, some additional settings can be specified:
- "collections": An array of collection IDs that a record may directly be linked with, assuming the required permissions are met.
- "record_links": An array of objects specifying predefined record links that a record may directly be linked with, assuming the required permissions are met. Each object must contain the link direction ("direction"), one of "out" or "in", the record ID to link with ("record"), the name of the link ("name") and optionally its term IRI ("term").
- "roles": An array of objects specifying predefined roles that may directly be granted to users and/or groups (also referred to as subjects), assuming the required permissions are met. Each object must contain the type of subject ("subject_type"), one of "user" or "group", the ID of the subject ("subject_id") and the corresponding role name ("role").
"extras": An array of objects containing the extra metadata of a record. See also Record.extras.

state

The state of the template.

One of "active" or "deleted".

classmethod create(*, creator, identifier, title, type, data, description='', plain_description='', visibility='private', state='active')[source]

Create a new template and add it to the database session.

Parameters:

creator – The creator of the template.
identifier – The identifier of the template.
title – The title of the template.
type – The type of the template.
data – The data of the template.
description – (optional) The description of the template.
plain_description – (optional) The plain description of the template.
visibility – (optional) The default visibility of the template.
state – (optional) The state of the template.

Returns:

The new Template object.

class kadi.modules.templates.schemas.RecordTemplateDataSchema(*args, _internal=None, **kwargs)[source]

Bases: BaseSchema

Schema to represent the data of record templates.

See Template.data.

class kadi.modules.templates.schemas.TemplateSchema(previous_template=None, template_type=None, **kwargs)[source]