timApp.timdb package

Submodules

timApp.timdb.annotations module

The module contains the database functions related to annotations. This includes adding, modifiying and deleting annotations as well as adding comments to the annotations. The module also retrieves the annotations from the database.

authors:Joonas Lattu, Petteri Palojärvi copyright:2016 Timber project members version:1.0.0

class timApp.timdb.annotations.Annotations(db_path: sqlite3.Connection, files_root_path: str, type_name: str, current_user_name: str)

Bases: timdb.timdbbase.TimDbBase

Used as an interface to query the database about annotations.

class AnnotationVisibility

Bases: enum.Enum

Enum for storing the visibility

• myself = 1
• owner = 2
• teacher = 3
• everyone = 4

everyone = <AnnotationVisibility.everyone: 4>

myself = <AnnotationVisibility.myself: 1>

owner = <AnnotationVisibility.owner: 2>

teacher = <AnnotationVisibility.teacher: 3>

Annotations.add_comment(annotation_id: int, commenter_id: int, content: str) → int

Adds new comment to an annotation.

Parameters:

• annotation_id – ID of annotation
• commenter_id – ID of commenter
• content – Text of comment

Returns:

ID of the new comment.

Annotations.create_annotation(velp_version_id: int, visible_to: timApp.timdb.annotations.Annotations.AnnotationVisibility, points: typing.Union[float, NoneType], annotator_id: int, document_id: int, paragraph_id_start: typing.Union[str, NoneType], paragraph_id_end: typing.Union[str, NoneType], offset_start: int, node_start: int, depth_start: int, offset_end: int, node_end: int, depth_end: int, hash_start: typing.Union[str, NoneType], hash_end: typing.Union[str, NoneType], element_path_start: str, element_path_end: str, valid_until: typing.Union[str, NoneType] = None, icon_id: typing.Union[int, NoneType] = None, answer_id: typing.Union[int, NoneType] = None) → int

Create a new annotation.

Parameters:

• velp_version_id – Version of the velp that the annotation uses.
• visible_to – visibility of the annotation.
• points – Points given, overrides velp’s default and can be null.
• annotator_id – ID of user who left the annotation.
• document_id – ID of document in which annotation is located in.
• paragraph_id_start – ID of paragraph where annotation starts.
• paragraph_id_end – ID of paragraph where annotation ends.
• offset_start – Character location where annotation starts.
• node_start – Start node number
• depth_start – depth of the element path
• offset_end – Character location where annotation ends.
• node_end – End node number
• depth_end – depth of the element path
• hash_start – Hash code of paragraph where annotation starts.
• hash_end – Hash code of paragraph where annotation ends.
• element_path_start – List of elements as text (parsed in interface) connected to annotation start.
• element_path_end – List of elements as text (parsed in interface) connected to annotation end.
• valid_until – Datetime until which annotation is valid for, ‘none’ for forever.
• icon_id – ID of icon associated with annotation, can be ‘none’.
• answer_id – ID of answer if annotation is located within one.

Returns:

ID of the new, just added annotation.

Annotations.get_annotation(annotation_id: int) → typing.List[typing.Dict[KT, VT]]

Gets an annotation.

Parameters:annotation_id – ID of annotation Returns:A list of dictionaries with the fields of individual annotations. List is empty if nothing is found and has several rows if there are duplicate ids(not good).

Annotations.get_annotations_in_document(user_id: int, user_has_see_answers, user_has_teacher: bool, user_has_owner: bool, document_id: int) → typing.List[typing.Dict[KT, VT]]

Gets all annotations made in a document. Both in document and in answers.

Parameters:

• user_has_see_answers – whether user has ‘see answer’ rights or not.
• user_id – user that is viewing annotations. Affects which annotations are returned.
• user_has_teacher – whether user has ‘teacher’ rights or not.
• user_has_owner – whether user is document owner or not.
• document_id – The relevant document.

Returns:

List of dictionaries, each dictionary representing a single annotation.

Annotations.get_annotations_with_comments_in_document(user_id: int, user_has_see_answers: bool, user_has_teacher: bool, user_has_owner: bool, document_id: int) → typing.List[typing.Dict[KT, VT]]

Gets all annotations with comments the user can see / has access to.

Parameters:

• user_id – user ID
• user_has_see_answers – whether user has ‘see answer’ rights or not.
• user_has_teacher – whether user has ‘teacher’ rights or not.
• user_has_owner – whether user is document owner or not.
• document_id – The relevant document.

Returns:

List of dictionaries containing annotations with comments

Annotations.get_comments_for_annotations(annotation_ids: typing.List[int]) → typing.List[typing.Dict[KT, VT]]

Gets comments for annotations given as a list.

Also calculates for each comment how long ago it was made. (This can be negative if for some reason there are timestamps ahead of the server clock in the database. I didn’t find a way to calculate the difference without using strftime.

Parameters:annotation_ids – List of annotation IDs Returns:List of dictionaries containing annotation comment data

Annotations.invalidate_annotation(annotation_id: int, valid_until: typing.Union[str, NoneType] = None)

Invalidates and thus hides annotation.

Parameters:

• annotation_id – Id of annotation
• valid_until – Time when annotation will be invalidated

Annotations.update_annotation(annotation_id: int, version_id: typing.Union[int, NoneType], visible_to: timApp.timdb.annotations.Annotations.AnnotationVisibility, points: typing.Union[float, NoneType], icon_id: typing.Union[int, NoneType])

Changes an existing annotation.

Parameters:

• annotation_id – annotation to be changed.
• version_id – version of the velp that the annotation uses
• visible_to – visibility of the annotation
• points – Points given, overrides velp’s default and can be null
• icon_id – Icon id, can be null

timApp.timdb.icons module

The module contains the database functions related to icons that are used in velps and annotations. Icons are be retrieved from the database through this module. The module is not yet used in production.

authors:Joonas Lattu, Petteri Palojärvi copyright:2016 Timber project members version:1.0.0

class timApp.timdb.icons.Icons(db_path: sqlite3.Connection, files_root_path: str, type_name: str, current_user_name: str)

Bases: timdb.timdbbase.TimDbBase

get_file_name(icon_id: int) → str

Retrieves the filename for the icon.

Parameters:icon_id – The id of the icon. Returns:A filename for the icon.

timApp.timdb.velpgrouplabels module

The module contains the database functions related to labels that are used in velp groups. This includes adding, modifying and deleting velp group labels. The module also retrieves the velp group labels from the database. The module is not yet used in production.

authors:Joonas Lattu, Petteri Palojärvi copyright:2016 Timber project members version:1.0.0

class timApp.timdb.velpgrouplabels.VelpGroupLabels(db_path: sqlite3.Connection, files_root_path: str, type_name: str, current_user_name: str)

Bases: timdb.timdbbase.TimDbBase

add_translation(label_id: int, language_id: str, content: str)

Adds new translation to an existing label

Parameters:

• label_id – Label id
• language_id – Language chosen
• content – New translation

create_velp_group_label(language_id: str, content: str) → int

Creates a new label

Parameters:

• language_id – Language chosen
• content – Label content

Returns:

id of the new label.

delete_velp_group_label(label_id)

Deletes label (use with extreme caution)

Parameters:label_id – Label ID

get_velp_group_labels(velp_id: int, language_id: str)

Gets information of labels for one velp in specific language

Parameters:

• velp_id – ID of velp
• language_id – Language chosen

Returns:

List of labels associated with velp as a dictionary

update_velp_group_label(label_id: int, language_id: str, content: str)

Updates content of label in specific language

Parameters:

• label_id – Label id
• language_id – Language chosen
• content – Updated content

timApp.timdb.velpgroups module

The module contains the database functions related to velp groups and their default and show selections. This includes adding new velp groups and editing the information of their default and show selections in the document (and its paragraphs). The module also retrieves or creates the default and personal velp groups. Information about velp group selections are managed through this module. The module also retrieves the velp groups and their default and show selections from the database.

authors:Joonas Lattu, Petteri Palojärvi copyright:2016 Timber project members version:1.0.0

class timApp.timdb.velpgroups.VelpGroups(db_path: sqlite3.Connection, files_root_path: str, type_name: str, current_user_name: str)

Bases: timdb.documents.Documents

add_group_to_imported_table(user_group: int, doc_id: int, target_type: int, target_id: int, velp_group_id: int)

Adds velp group to ImportedVelpGroups table for specific document / user group combo

Parameters:

• user_group – ID of user group
• doc_id – Id of document
• target_type – Which kind of area group targets to (0 doc, 1 paragraph, 2 area)
• target_id – ID of target (0 for documents)
• velp_group_id – ID of velp group

Returns:

void

add_groups_to_default_table(velp_groups: dict, doc_id: int)

Adds velp groups to VelpGroupDefaults table

Parameters:

• velp_groups – Velp groups as dictionaries
• doc_id – ID of document

add_groups_to_document(velp_groups: dict, doc_id: int, user_id: int)

Adds velp groups to VelpGroupsInDocument table

Parameters:

• velp_groups – Velp groups as dictionaries
• doc_id – ID of document
• user_id – ID of user

add_groups_to_selection_table(velp_groups: dict, doc_id: int, user_id: int)

Adds velp groups to VelpGroupSelection table

Parameters:

• velp_groups – Velp groups as dictionaries
• doc_id – ID of document
• user_id – ID of user

add_velp_to_group(velp_id: int, velp_group_id: int)

Adds a velp to a specific group

Parameters:

• velp_id – Velp if
• velp_group_id – Velp group ID

add_velp_to_groups(velp_id: int, velp_group_ids: [<class 'int'>])

Adds a velp to specific groups

Parameters:

• velp_id – ID of velp
• velp_group_ids – List of velp group IDs

change_all_target_area_default_selections(doc_id: int, target_type: int, target_id: str, user_id: int, selected: bool)

Change all default selections to True or False for currently chose area (document or paragraph)

Parameters:

• doc_id – ID of document
• target_type – Currently 0 = document, 1 = paragraph
• target_id – ID of target (‘0’ for documents)
• user_id – ID of user (with manage access) to get all defaults from that user’s selection table
• selected – True or False

change_all_target_area_selections(doc_id: int, target_type: int, target_id: str, user_id: int, selected: bool)

Change all personal selections to True or False for currently chose area (document or paragraph)

Parameters:

• doc_id – ID of document
• target_type – Currently 0 = document, 1 = paragraph
• target_id – ID of target (‘0’ for documents)
• user_id – ID of user
• selected – True or False

change_default_selection(doc_id: int, velp_group_id: int, target_type: int, target_id: str, selected: bool)

Changes selection for velp group’s default selection in target area

Parameters:

• doc_id – ID of document
• target_type – 0 document, 1 paragraph
• target_id – ID of targeted area
• velp_group_id – ID of velp group
• selected – Boolean whether group is selected or not

change_selection(doc_id: int, velp_group_id: int, target_type: int, target_id: str, user_id: int, selected: bool)

Changes selection for velp group in VelpGroupSelection for specific user / document / target combo

Parameters:

• doc_id – ID of document
• velp_group_id – ID of velp group
• target_type – 0 document, 1 paragraph
• target_id – ID of targeted area
• user_id – ID of user
• selected – Boolean whether group is selected or not

check_velp_group_ids_for_default_group(velp_group_ids: typing.List[int])

Checks if list of velp group IDs contains a default velp group

Parameters:velp_group_ids – List of velp group IDs Returns:First found default velp group ID and name

create_default_velp_group(name: str, owner_group_id: int, default_group_path: str)

Creates default velp group for document.

Parameters:

• name – Name of the new default velp group.
• owner_group_id – The id of the owner group.
• default_group_path – Path of new document / velp group

Returns:

create_velp_group(name: str, owner_group_id: int, new_group_path: str, valid_until: typing.Union[str, NoneType] = None)

Create a velp group

Parameters:

• name – Name of the created group.
• owner_group_id – The id of the owner group.
• new_group_path – Path of new document / velp group
• valid_until – How long velp group is valid (None is forever).

Returns:

new velp group ID

delete_velp_group(velp_group_id: int)

Deletes velp group. Doesn’t delete velps belonging to group, only their links to deleted group

Parameters:velp_group_id – Velp group id

get_default_selections_for_velp_groups(doc_id: int, user_id: int)

Gets all velp group default selections for document

Parameters:

• doc_id – ID of document
• user_id – ID of user

Returns:

Dict with following info { target_id: [{velp_group_id, selected}, etc], etc }

get_groups_for_velp(velp_id)

Gets velp group’s of the velp

Parameters:velp_id – velp ID Returns:velp groups of the velp.

get_groups_from_document_table(doc_id: int, user_id: int)

Gets velp groups from VelpGroupsInDocument table of specific document / user combo

Parameters:

• doc_id – ID of document
• user_id – ID of user

Returns:

velp groups in document that user has access to.

get_groups_from_imported_table(user_groups: [<class 'int'>], doc_id: int)

Gets velp groups from ImportedVelpGroups table for specific document / user group IDs combo

Parameters:

• user_groups – List of user group IDs
• doc_id – ID of document

Returns:

velp groups in document that user has access to via group.

get_personal_selections_for_velp_groups(doc_id: int, user_id: int)

Gets all velp group personal selections for document

Parameters:

• doc_id – ID of document
• user_id – ID of user

Returns:

Dict with following info { target_id: [{velp_group_id, selected}, etc], etc }

get_velp_group_name(velp_group_id: int) → str

Gets velp group’s name

Parameters:velp_group_id – velp group ID Returns:velp group’s name as a string.

is_id_velp_group(doc_id: int) → bool

Checks whether given document id can also be found from VelpGroup table

Parameters:doc_id – ID of document Returns:True if part of VelpGroup table, else False

make_document_a_velp_group(name: str, velp_group_id: int, valid_until: typing.Union[str, NoneType] = None, default_group: typing.Union[bool, NoneType] = 0)

Adds document to VelpGroup table

Parameters:

• name – Name of the created group.
• velp_group_id – ID of new velp group (and existing document)
• valid_until – How long velp group is valid (None is forever)
• default_group – Boolean whether velp group should be default or not

Returns:

velp group ID

remove_velp_from_group(velp_id: int, velp_group_id: int)

Removes a velp from a specific group

Parameters:

• velp_id – Velp id
• velp_group_id – Velp group id

remove_velp_from_groups(velp_id: int, velp_group_ids: [<class 'int'>])

Removes a velp from specific groups

Parameters:

• velp_id – ID of velp
• velp_group_ids – List of velp group IDs

reset_all_selections_to_defaults(doc_id: int, user_id: int)

Changes user’s all personal velp group selections in document to defaults

Parameters:

• doc_id – ID of document
• user_id – ID of user

reset_target_area_selections_to_defaults(doc_id: int, target_id: str, user_id: int)

Changes user’s personal velp group selections in target area to defaults

Parameters:

• doc_id – ID of document
• target_id – ID of target area
• user_id – ID of user

update_velp_group(velp_group_id: int, name: str, valid_until: typing.Union[str, NoneType])

Updates name and/or valid until time of velp group

Parameters:

• velp_group_id – Velp group id
• name – Name of velp group
• valid_until – How long velp group is valid

update_velp_group_to_default_velp_group(velp_group_id: int)

Makes velp group a default velp group in velp group table

Parameters:velp_group_id – ID of velp group

timApp.timdb.velps module

The module contains the database functions related to velps and velp labels. This includes adding and modifying velps and their labels. The module also retrieves the data related to velps and their labels from the database.

authors:Joonas Lattu, Petteri Palojärvi copyright:2016 Timber project members version:1.0.0

class timApp.timdb.velps.Velps(db_path: sqlite3.Connection, files_root_path: str, type_name: str, current_user_name: str)

Bases: timdb.timdbbase.TimDbBase

Used as an interface to query the database about velps.

add_labels_to_velp(velp_id: int, labels: typing.List[int])

Associates a set of labels to a velp. (Appends to existing labels)

Do note that update_velp_labels depends on this method

Parameters:

• velp_id – id of the velp that
• labels – list of label ids

add_velp_label_translation(label_id: int, language_id: str, content: str)

Adds new translation to an existing label.

Parameters:

• label_id – Label id
• language_id – Language chosen
• content – New translation

create_new_velp(creator_id: int, content=<class 'str'>, default_points: typing.Union[float, NoneType] = None, icon_id: typing.Union[int, NoneType] = None, valid_until: typing.Union[str, NoneType] = None, language_id: str = 'FI', visible_to: typing.Union[int, NoneType] = None) → int

Creates a new velp with all information.

Creates a new velp with all necessary information in one function using three others.

Parameters:

• creator_id – User ID of creator.
• content – Text for velp.
• default_points – Default points for velp, None if not given.
• icon_id – Icon ID attached to velp. Can be null.
• valid_until – Time after velp becomes unusable.
• language_id – Language ID of velp.
• visible_to – Default visibility to annotation.

Returns:

ID of the new velp.

create_velp_content(version_id: int, language_id: str, content: str)

Method to create content (text) for velp.

Parameters:

• version_id – Version id where the content will be stored
• language_id – Language id
• content – Text of velp

create_velp_label(language_id: str, content: str) → int

Creates a new label.

Parameters:

• language_id – Language chosen
• content – Label content

Returns:

id of the new label

create_velp_version(velp_id: int)

Creates a new version for a velp to use.

Parameters:velp_id – ID of velp we’re adding version for Returns:ID of version that was just created

get_latest_velp_version(velp_id: int, language_id: str = 'FI')

Method to fetch the latest version for velp in specific language

Parameters:

• velp_id – ID of velp we’re checking
• language_id – ID of language

Returns:

Dictionary containing ID and content of velp version.

get_velp_content_for_document(doc_id: int, user_id: int, language_id: str = 'FI') → {}

Gets velp content including labels and velp groups for document.

Uses VelpGroupsInDocument table data to determine which velp groups are usable for specific user in specific document.

Parameters:

• doc_id – ID of document in question
• user_id – ID of current user
• language_id – ID of language used

Returns:

List of velps as dictionaries

get_velp_group_ids_for_document(doc_id: int, user_id: int) → {}

Gets velp group ids for document.

Uses VelpGroupsInDocument table data to determine which velp groups are usable for specific user in specific document.

Parameters:

• doc_id – ID of document in question
• user_id – ID of current user

Returns:

List of dicts containing velp ids and velp groups ids

get_velp_label_content_for_document(doc_id: int, user_id: int, language_id: str = 'FI') → {}

Gets velp label content for document.

Uses VelpGroupsInDocument table data to determine which velp groups and via those which velp labels are usable for specific user in specific document.

Parameters:

• doc_id – ID of document in question
• user_id – ID of current user
• language_id – ID of language used

Returns:

List of dicts containing velp label ids and content

get_velp_label_ids_for_document(doc_id: int, user_id: int) → {}

Gets velp labels ids for document.

Uses VelpGroupsInDocument table data to determine which velp groups and via those which velp labels are usable for specific user in specific document.

Parameters:

• doc_id – ID of document in question
• user_id – ID of current user

Returns:

List of dicts containing velp ids and label ids

get_velp_label_ids_for_velp(velp_id: int) → {}

Gets labels for one velp.

Parameters:velp_id – ID of velp Returns:List of labels represented by their ids associated with the velp.

get_velps_for_document(doc_id: int, user_id: int, language_id: str = 'FI') → {}

Gets velps for document.

Uses VelpGroupsInDocument table data to determine which velp groups and via those which velps are usable for specific user in specific document.

Parameters:

• doc_id – ID of document in question
• user_id – ID of current user
• language_id – ID of language used

Returns:

List of dicts containing velp ids, default points, content, icon ids and language ids

update_velp(velp_id: int, default_points: str, icon_id: str)

Changes the non-versioned properties of a velp. Does not update labels.

Parameters:

• velp_id – ID of velp that’s being updated
• default_points – New default points
• icon_id – ID of icon

update_velp_label(label_id: int, language_id: str, content: str)

Updates content of label in specific language.

Parameters:

• label_id – Label id
• language_id – Language chosen
• content – Updated content

update_velp_labels(velp_id: int, labels: typing.List[int])

Replaces the labels of a velp with new ones.

Parameters:

• velp_id – velp ID
• labels – list of label IDs.