Skip to content

AnnotationResource

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/dsp_base_resources.py 
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
@dataclass
class AnnotationResource:
    res_id: str
    label: str
    annotation_of: str
    comments: list[str]
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS
    migration_metadata: MigrationMetadata | None = None

    def __post_init__(self) -> None:
        _check_strings(string_to_check=self.res_id, res_id=self.res_id, field_name="Resource ID")
        _check_strings(string_to_check=self.label, res_id=self.res_id, field_name="Label")

    @staticmethod
    def create_new(
        res_id: str,
        label: str,
        annotation_of: str,
        comments: Collection[str],
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    ) -> AnnotationResource:
        """
        Creates a new annotation resource.
        An annotation is a comment to another resource.

        [See XML documentation for details](https://docs.dasch.swiss/latest/DSP-TOOLS/file-formats/xml-data-file/#annotation)

        Args:
            res_id: ID of this annotation resource
            label: label of this annotation resource
            annotation_of: ID of the resource that this annotation refers to (cardinality 1)
            comments: the comment(s) that this annotation consists of, i.e. the annotation itself (cardinality 1-n)
            permissions: permissions of this annotation resource

        Returns:
            An annotation resource
        """
        return AnnotationResource(
            res_id=res_id,
            label=label,
            annotation_of=annotation_of,
            comments=list(comments),
            permissions=permissions,
        )

    def add_comment(self, comment: str) -> AnnotationResource:
        """
        Add a comment to the resource

        Args:
            comment: text

        Returns:
            The original resource, with the added comment
        """
        self.comments.append(comment)
        return self

    def add_comment_multiple(self, comments: Collection[str]) -> AnnotationResource:
        """
        Add several comments to the resource

        Args:
            comments: List of texts

        Returns:
            The original resource, with the added comments
        """
        self.comments.extend(comments)
        return self

    def add_comment_optional(self, comment: Any) -> AnnotationResource:
        """
        If the value is not empty, add it as comment, otherwise return the resource unchanged.

        Args:
            comment: text or empty value

        Returns:
            The original resource, with the added comment
        """
        if is_nonempty_value(comment):
            self.comments.append(comment)
        return self

    def add_migration_metadata(
        self, creation_date: str | None, iri: str | None = None, ark: str | None = None
    ) -> AnnotationResource:
        """
        Add metadata from a SALSAH migration.

        Args:
            creation_date: creation date of the resource in SALSAH
            iri: Original IRI in SALSAH
            ark: Original ARK in SALSAH

        Raises:
            InputError: if metadata already exists

        Returns:
            The original resource, with the added metadata
        """
        if self.migration_metadata:
            raise InputError(
                f"The resource with the ID '{self.res_id}' already contains migration metadata, "
                f"no new data can be added."
            )
        self.migration_metadata = MigrationMetadata(creation_date=creation_date, iri=iri, ark=ark, res_id=self.res_id)
        return self

    def serialise(self) -> etree._Element:
        self.comments = _transform_unexpected_input(self.comments, "comments", self.res_id)
        res_ele = self._serialise_resource_element()
        res_ele.append(self._serialise_annotation_of())
        res_ele.append(_serialise_has_comment(self.comments, self.res_id))
        return res_ele

    def _serialise_resource_element(self) -> etree._Element:
        attribs = {"label": self.label, "id": self.res_id}
        if self.permissions != Permissions.PROJECT_SPECIFIC_PERMISSIONS:
            attribs["permissions"] = self.permissions.value
        return etree.Element(f"{DASCH_SCHEMA}annotation", attrib=attribs, nsmap=XML_NAMESPACE_MAP)

    def _serialise_annotation_of(self) -> etree._Element:
        return LinkValue(value=self.annotation_of, prop_name="isAnnotationOf", resource_id=self.res_id).serialise()

create_new

Creates a new annotation resource. An annotation is a comment to another resource.

See XML documentation for details

Parameters:

Name Type Description Default
res_id str

ID of this annotation resource

 required
label str

label of this annotation resource

 required
annotation_of str

ID of the resource that this annotation refers to (cardinality 1)

 required
comments Collection[str]

the comment(s) that this annotation consists of, i.e. the annotation itself (cardinality 1-n)

 required
permissions Permissions

permissions of this annotation resource

 PROJECT_SPECIFIC_PERMISSIONS

Returns:

Type Description
AnnotationResource

An annotation resource
Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/dsp_base_resources.py 
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
@staticmethod
def create_new(
    res_id: str,
    label: str,
    annotation_of: str,
    comments: Collection[str],
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
) -> AnnotationResource:
    """
    Creates a new annotation resource.
    An annotation is a comment to another resource.

    [See XML documentation for details](https://docs.dasch.swiss/latest/DSP-TOOLS/file-formats/xml-data-file/#annotation)

    Args:
        res_id: ID of this annotation resource
        label: label of this annotation resource
        annotation_of: ID of the resource that this annotation refers to (cardinality 1)
        comments: the comment(s) that this annotation consists of, i.e. the annotation itself (cardinality 1-n)
        permissions: permissions of this annotation resource

    Returns:
        An annotation resource
    """
    return AnnotationResource(
        res_id=res_id,
        label=label,
        annotation_of=annotation_of,
        comments=list(comments),
        permissions=permissions,
    )

add_comment

Add a comment to the resource

Parameters:

Name Type Description Default
comment str

text

 required

Returns:

Type Description
AnnotationResource

The original resource, with the added comment
Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/dsp_base_resources.py 
77
78
79
80
81
82
83
84
85
86
87
88
def add_comment(self, comment: str) -> AnnotationResource:
    """
    Add a comment to the resource

    Args:
        comment: text

    Returns:
        The original resource, with the added comment
    """
    self.comments.append(comment)
    return self

add_comment_multiple

Add several comments to the resource

Parameters:

Name Type Description Default
comments Collection[str]

List of texts

 required

Returns:

Type Description
AnnotationResource

The original resource, with the added comments
Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/dsp_base_resources.py 
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
def add_comment_multiple(self, comments: Collection[str]) -> AnnotationResource:
    """
    Add several comments to the resource

    Args:
        comments: List of texts

    Returns:
        The original resource, with the added comments
    """
    self.comments.extend(comments)
    return self

add_comment_optional

If the value is not empty, add it as comment, otherwise return the resource unchanged.

Parameters:

Name Type Description Default
comment Any

text or empty value

 required

Returns:

Type Description
AnnotationResource

The original resource, with the added comment
Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/dsp_base_resources.py 
103
104
105
106
107
108
109
110
111
112
113
114
115
def add_comment_optional(self, comment: Any) -> AnnotationResource:
    """
    If the value is not empty, add it as comment, otherwise return the resource unchanged.

    Args:
        comment: text or empty value

    Returns:
        The original resource, with the added comment
    """
    if is_nonempty_value(comment):
        self.comments.append(comment)
    return self

add_migration_metadata

Add metadata from a SALSAH migration.

Parameters:

Name Type Description Default
creation_date str | None

creation date of the resource in SALSAH

 required
iri str | None

Original IRI in SALSAH

 None
ark str | None

Original ARK in SALSAH

 None

Returns:

Type Description
AnnotationResource

The original resource, with the added metadata
Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/dsp_base_resources.py 
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
def add_migration_metadata(
    self, creation_date: str | None, iri: str | None = None, ark: str | None = None
) -> AnnotationResource:
    """
    Add metadata from a SALSAH migration.

    Args:
        creation_date: creation date of the resource in SALSAH
        iri: Original IRI in SALSAH
        ark: Original ARK in SALSAH

    Raises:
        InputError: if metadata already exists

    Returns:
        The original resource, with the added metadata
    """
    if self.migration_metadata:
        raise InputError(
            f"The resource with the ID '{self.res_id}' already contains migration metadata, "
            f"no new data can be added."
        )
    self.migration_metadata = MigrationMetadata(creation_date=creation_date, iri=iri, ark=ark, res_id=self.res_id)
    return self