Resource

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/resource.py

@dataclass
class Resource:
    res_id: str
    restype: str
    label: str
    values: list[Value] = field(default_factory=list)
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS
    file_value: AbstractFileValue | None = None
    migration_metadata: MigrationMetadata | None = None

    def __post_init__(self) -> None:
        msg = []
        if not is_string_like(str(self.label)):
            msg.append(f"Label '{self.label}'")
        if not is_string_like(str(self.res_id)):
            msg.append(f"Resource ID '{self.res_id}'")
        if not is_string_like(str(self.restype)):
            msg.append(f"Resource Type '{self.restype}'")
        if msg:
            out_msg = (
                f"The Resource with the ID '{self.res_id}' should have strings in the following field(s), "
                f"the input is not a valid string.:{LIST_SEPARATOR}{LIST_SEPARATOR.join(msg)}"
            )
            warnings.warn(DspToolsUserWarning(out_msg))

    @staticmethod
    def create_new(
        res_id: str,
        restype: str,
        label: str,
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    ) -> Resource:
        """
        Create a new resource.

        Args:
            res_id: resource ID
            restype: resource type
            label: resource label
            permissions: optional permissions of this resource

        Returns:
            Resource
        """
        return Resource(
            res_id=res_id,
            restype=restype,
            label=label,
            permissions=permissions,
        )

    def serialise(self) -> etree._Element:
        res_ele = self._serialise_resource_element()
        if self.file_value:
            res_ele.append(self.file_value.serialise())
        res_ele.extend(self._serialise_values())
        return res_ele

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

    def _serialise_values(self) -> list[etree._Element]:
        grouped = defaultdict(list)
        for val in self.values:
            grouped[val.prop_name].append(val)
        return [self._combine_values(prop_values) for prop_values in grouped.values()]

    def _combine_values(self, prop_values: list[Value]) -> etree._Element:
        prop_ = prop_values[0].make_prop()
        prop_eles = [x.make_element() for x in prop_values]
        prop_.extend(prop_eles)
        return prop_

    #######################
    # BooleanValue
    #######################

    def add_bool(
        self,
        prop_name: str,
        value: bool | str | int | float,
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
    ) -> Resource:
        """
        Add a boolean value to the resource.

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

        Conversions:
         - The conversion is case-insensitive, meaning that the words can also be capitalised.
         - "false", "0", "0.0", "no", "non", "nein" -> "false"
         - "true", "1", "1.0", "yes", "oui", "ja" -> "true"

        Args:
            prop_name: name of the property
            value: value to add
            permissions: optional permissions of this value
            comment: optional comment

        Returns:
            The original resource, with the added value
        """
        self.values.append(BooleanValue(value, prop_name, permissions, comment, self.res_id))
        return self

    def add_bool_optional(
        self,
        prop_name: str,
        value: Any,
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
    ) -> Resource:
        """
        If the value is not empty, add it to the resource, otherwise return the resource unchanged.

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

        Conversions:
         - The conversion is case-insensitive, meaning that the words can also be capitalised.
         - "false", "0", "0.0", "no", "non", "nein" -> "false"
         - "true", "1", "1.0", "yes", "oui", "ja" -> "true"

        Args:
            prop_name: name of the property
            value: value to add or empty value
            permissions: optional permissions of this value
            comment: optional comment

        Returns:
            The original resource, with the added value if it was not empty, else the unchanged original resource.
        """
        if is_nonempty_value(value):
            self.values.append(BooleanValue(value, prop_name, permissions, comment, self.res_id))
        return self

    #######################
    # ColorValue
    #######################

    def add_color(
        self,
        prop_name: str,
        value: str,
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
    ) -> Resource:
        """
        Add a color value to the resource.

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

        Args:
            prop_name: name of the property
            value: value to add
            permissions: optional permissions of this value
            comment: optional comment

        Returns:
            The original resource, with the added value
        """
        self.values.append(ColorValue(value, prop_name, permissions, comment, self.res_id))
        return self

    def add_color_multiple(
        self,
        prop_name: str,
        values: Collection[str],
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
    ) -> Resource:
        """
        Add several color values to the resource.

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

        Args:
            prop_name: name of the property
            values: values to add
            permissions: optional permissions of this value
            comment: optional comment

        Returns:
            The original resource, with the added values
        """
        self.values.extend([ColorValue(v, prop_name, permissions, comment, self.res_id) for v in values])
        return self

    def add_color_optional(
        self,
        prop_name: str,
        value: Any,
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
    ) -> Resource:
        """
        If the value is not empty, add it to the resource, otherwise return the resource unchanged.

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

        Args:
            prop_name: name of the property
            value: value to add or empty value
            permissions: optional permissions of this value
            comment: optional comment

        Returns:
            The original resource, with the added value if it was not empty, else the unchanged original resource.
        """
        if is_nonempty_value(value):
            self.values.append(ColorValue(value, prop_name, permissions, comment, self.res_id))
        return self

    #######################
    # DateValue
    #######################

    def add_date(
        self,
        prop_name: str,
        value: str,
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
    ) -> Resource:
        """
        Add a date value to the resource.
        [See XML documentation for details](https://docs.dasch.swiss/latest/DSP-TOOLS/file-formats/xml-data-file/#date)

        Args:
            prop_name: name of the property
            value: value to add
            permissions: optional permissions of this value
            comment: optional comment

        Returns:
            The original resource, with the added value
        """
        self.values.append(DateValue(value, prop_name, permissions, comment, self.res_id))
        return self

    def add_date_multiple(
        self,
        prop_name: str,
        values: Collection[str],
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
    ) -> Resource:
        """
        Add several date values to the resource.

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

        Args:
            prop_name: name of the property
            values: values to add
            permissions: optional permissions of this value
            comment: optional comment

        Returns:
            The original resource, with the added values
        """
        self.values.extend([DateValue(v, prop_name, permissions, comment, self.res_id) for v in values])
        return self

    def add_date_optional(
        self,
        prop_name: str,
        value: Any,
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
    ) -> Resource:
        """
        If the value is not empty, add it to the resource, otherwise return the resource unchanged.

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

        Args:
            prop_name: name of the property
            value: value to add or empty value
            permissions: optional permissions of this value
            comment: optional comment

        Returns:
            The original resource, with the added value if it was not empty, else the unchanged original resource.
        """
        if is_nonempty_value(value):
            self.values.append(DateValue(value, prop_name, permissions, comment, self.res_id))
        return self

    #######################
    # DecimalValue
    #######################

    def add_decimal(
        self,
        prop_name: str,
        value: float | int | str,
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
    ) -> Resource:
        """
        Add a decimal value to the resource.
        If the value is provided as string, it must be convertible to integer or float.

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

        Args:
            prop_name: name of the property
            value: value to add
            permissions: optional permissions of this value
            comment: optional comment

        Returns:
            The original resource, with the added value
        """
        self.values.append(DecimalValue(value, prop_name, permissions, comment, self.res_id))
        return self

    def add_decimal_multiple(
        self,
        prop_name: str,
        values: Collection[float | int | str],
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
    ) -> Resource:
        """
        Add several decimal values to the resource.
        If the values are provided as string, they must be convertible to integer or float.

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

        Args:
            prop_name: name of the property
            values: values to add
            permissions: optional permissions of this value
            comment: optional comment

        Returns:
            The original resource, with the added values
        """
        self.values.extend([DecimalValue(v, prop_name, permissions, comment, self.res_id) for v in values])
        return self

    def add_decimal_optional(
        self,
        prop_name: str,
        value: Any,
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
    ) -> Resource:
        """
        If the value is not empty, add it to the resource, otherwise return the resource unchanged.
        If the value is provided as string, it must be convertible to integer or float.

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

        Args:
            prop_name: name of the property
            value: value to add or empty value
            permissions: optional permissions of this value
            comment: optional comment

        Returns:
            The original resource, with the added value if it was not empty, else the unchanged original resource.
        """
        if is_nonempty_value(value):
            self.values.append(DecimalValue(value, prop_name, permissions, comment, self.res_id))
        return self

    #######################
    # GeonameValue
    #######################

    def add_geoname(
        self,
        prop_name: str,
        value: int | str,
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
    ) -> Resource:
        """
        Add a [geonames.org](https://www.geonames.org/) value to the resource.
        The [geonames.org](https://www.geonames.org/) identifier must be provided as integer
        or string that is convertible to integer.

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


        Args:
            prop_name: name of the property
            value: value to add
            permissions: optional permissions of this value
            comment: optional comment

        Returns:
            The original resource, with the added value
        """
        self.values.append(GeonameValue(value, prop_name, permissions, comment, self.res_id))
        return self

    def add_geoname_multiple(
        self,
        prop_name: str,
        values: Collection[int | str],
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
    ) -> Resource:
        """
        Add several [geonames.org](https://www.geonames.org/) values to the resource.
        The [geonames.org](https://www.geonames.org/) identifiers must be provided as integers
        or strings that are convertible to integers.

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

        Args:
            prop_name: name of the property
            values: values to add
            permissions: optional permissions of this value
            comment: optional comment

        Returns:
            The original resource, with the added values
        """
        self.values.extend([GeonameValue(v, prop_name, permissions, comment, self.res_id) for v in values])
        return self

    def add_geoname_optional(
        self,
        prop_name: str,
        value: Any,
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
    ) -> Resource:
        """
        If the value is not empty, add it to the resource, otherwise return the resource unchanged.
        The [geonames.org](https://www.geonames.org/) identifier must be provided as integer
        or string that is convertible to integer.

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

        Args:
            prop_name: name of the property
            value: value to add or empty value
            permissions: optional permissions of this value
            comment: optional comment

        Returns:
            The original resource, with the added value if it was not empty, else the unchanged original resource.
        """
        if is_nonempty_value(value):
            self.values.append(GeonameValue(value, prop_name, permissions, comment, self.res_id))
        return self

    #######################
    # IntValue
    #######################

    def add_integer(
        self,
        prop_name: str,
        value: int | str,
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
    ) -> Resource:
        """
        Add an integer value to the resource.
        If the value is provided as string, it must be convertible to integer.

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

        Args:
            prop_name: name of the property
            value: value to add
            permissions: optional permissions of this value
            comment: optional comment

        Returns:
            The original resource, with the added value
        """
        self.values.append(IntValue(value, prop_name, permissions, comment, self.res_id))
        return self

    def add_integer_multiple(
        self,
        prop_name: str,
        values: Collection[int | str],
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
    ) -> Resource:
        """
        Add several integer values to the resource.
        If the values are provided as string, they must be convertible to integer.

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

        Args:
            prop_name: name of the property
            values: values to add
            permissions: optional permissions of this value
            comment: optional comment

        Returns:
            The original resource, with the added values
        """
        self.values.extend([IntValue(v, prop_name, permissions, comment, self.res_id) for v in values])
        return self

    def add_integer_optional(
        self,
        prop_name: str,
        value: Any,
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
    ) -> Resource:
        """
        If the value is not empty, add it to the resource, otherwise return the resource unchanged.
        If the value is provided as string, it must be convertible to integer.

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

        Args:
            prop_name: name of the property
            value: value to add or empty value
            permissions: optional permissions of this value
            comment: optional comment

        Returns:
            The original resource, with the added value if it was not empty, else the unchanged original resource.
        """
        if is_nonempty_value(value):
            self.values.append(IntValue(value, prop_name, permissions, comment, self.res_id))
        return self

    #######################
    # LinkValue
    #######################

    def add_link(
        self,
        prop_name: str,
        value: str,
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
    ) -> Resource:
        """
        Add a link value to the resource, in the form of an ID of another resource.

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

        Args:
            prop_name: name of the property
            value: target resource ID
            permissions: optional permissions of this value
            comment: optional comment

        Returns:
            The original resource, with the added value
        """
        self.values.append(LinkValue(value, prop_name, permissions, comment, self.res_id))
        return self

    def add_link_multiple(
        self,
        prop_name: str,
        values: Collection[str],
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
    ) -> Resource:
        """
        Add several link values to the resource, in the form of IDs of other resources.

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

        Args:
            prop_name: name of the property
            values: list of target resources IDs
            permissions: optional permissions of this value
            comment: optional comment

        Returns:
            The original resource, with the added values
        """
        self.values.extend([LinkValue(v, prop_name, permissions, comment, self.res_id) for v in values])
        return self

    def add_link_optional(
        self,
        prop_name: str,
        value: Any,
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
    ) -> Resource:
        """
        If the value is not empty, add it to the resource, otherwise return the resource unchanged.
        If non-empty, the value must be an ID of another resource.

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

        Args:
            prop_name: name of the property
            value: target resource ID or empty value
            permissions: optional permissions of this value
            comment: optional comment

        Returns:
            The original resource, with the added value if it was not empty, else the unchanged original resource.
        """
        if is_nonempty_value(value):
            self.values.append(LinkValue(value, prop_name, permissions, comment, self.res_id))
        return self

    #######################
    # ListValue
    #######################

    def add_list(
        self,
        prop_name: str,
        list_name: str | int | float,
        value: str | int | float,
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
    ) -> Resource:
        """
        Add a list value to the resource, i.e. a name of a list node.

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

        Args:
            prop_name: name of the property
            list_name: name of the list (N.B. not the label, but the name of the list)
            value: name of a list node (N.B. not the label, but the name of the list node)
            permissions: optional permissions of this value
            comment: optional comment

        Returns:
            The original resource, with the added value
        """
        self.values.append(ListValue(value, list_name, prop_name, permissions, comment, self.res_id))
        return self

    def add_list_multiple(
        self,
        prop_name: str,
        list_name: str | int | float,
        values: Collection[str | int | float],
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
    ) -> Resource:
        """
        Add several list values to the resource, i.e. names of list nodes.

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

        Args:
            prop_name: name of the property
            list_name: name of the list (N.B. not the label, but the name of the list)
            values: names of list nodes (N.B. not the labels, but the names of the list nodes)
            permissions: optional permissions of this value
            comment: optional comment

        Returns:
            The original resource, with the added values
        """
        self.values.extend([ListValue(v, list_name, prop_name, permissions, comment, self.res_id) for v in values])
        return self

    def add_list_optional(
        self,
        prop_name: str,
        list_name: str | int | float,
        value: Any,
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
    ) -> Resource:
        """
        If the value is not empty, add it to the resource, otherwise return the resource unchanged.

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

        Args:
            prop_name: name of the property
            list_name: name of the list (N.B. not the label, but the name of the list)
            value: name of a list node (N.B. not the label, but the name of the list node) or empty value
            permissions: optional permissions of this value
            comment: optional comment

        Returns:
            The original resource, with the added value if it was not empty, else the unchanged original resource.
        """
        if is_nonempty_value(value):
            self.values.append(ListValue(value, list_name, prop_name, permissions, comment, self.res_id))
        return self

    #######################
    # TextValue: SimpleText
    #######################

    def add_simpletext(
        self,
        prop_name: str,
        value: str,
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
    ) -> Resource:
        """
        Add a simple text value to the resource.

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

        Args:
            prop_name: name of the property
            value: value to add
            permissions: optional permissions of this value
            comment: optional comment

        Returns:
            The original resource, with the added value
        """
        self.values.append(SimpleText(value, prop_name, permissions, comment, self.res_id))
        return self

    def add_simpletext_multiple(
        self,
        prop_name: str,
        values: Collection[str],
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
    ) -> Resource:
        """
        Add several simple text values to the resource.

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

        Args:
            prop_name: name of the property
            values: values to add
            permissions: optional permissions of this value
            comment: optional comment

        Returns:
            The original resource, with the added values
        """
        self.values.extend([SimpleText(v, prop_name, permissions, comment, self.res_id) for v in values])
        return self

    def add_simpletext_optional(
        self,
        prop_name: str,
        value: Any,
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
    ) -> Resource:
        """
        If the value is not empty, add it to the resource, otherwise return the resource unchanged.

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

        Args:
            prop_name: name of the property
            value: value to add or empty value
            permissions: optional permissions of this value
            comment: optional comment

        Returns:
            The original resource, with the added value if it was not empty, else the unchanged original resource.
        """
        if is_nonempty_value(value):
            self.values.append(SimpleText(value, prop_name, permissions, comment, self.res_id))
        return self

    #######################
    # TextValue: Richtext
    #######################

    def add_richtext(
        self,
        prop_name: str,
        value: str,
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
        newline_replacement: NewlineReplacement = NewlineReplacement.LINEBREAK,
    ) -> Resource:
        """
        Add a rich text value to the resource.
        Rich text values must be provided as strings, potentially containing DSP Standard Standoff Markup XML tags
        as [documented here.](https://docs.dasch.swiss/latest/DSP-API/03-endpoints/api-v2/text/standard-standoff/)
        Only the documented tags are allowed.

        Conversions:
            By default, replace newline characters inside the text value with `<br/>`, which preserves the linebreak.
            Without this replacement, the newline would disappear, because `\\n` is meaningless in an XML file.

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

        Args:
            prop_name: name of the property
            value: value to add
            permissions: optional permissions of this value
            comment: optional comment
            newline_replacement: options how to deal with `\\n` inside the text value. Default: replace with `<br/>`

        Returns:
            The original resource, with the added value
        """
        value = replace_newlines_with_tags(str(value), newline_replacement)
        self.values.append(Richtext(value, prop_name, permissions, comment, self.res_id))
        return self

    def add_richtext_multiple(
        self,
        prop_name: str,
        values: Collection[str],
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
        newline_replacement: NewlineReplacement = NewlineReplacement.LINEBREAK,
    ) -> Resource:
        """
        Add several rich text values to the resource.
        Rich text values must be provided as strings, potentially containing DSP Standard Standoff Markup XML tags
        as [documented here.](https://docs.dasch.swiss/latest/DSP-API/03-endpoints/api-v2/text/standard-standoff/)
        Only the documented tags are allowed.

        Conversions:
            By default, replace newline characters inside the text value with `<br/>`, which preserves the linebreak.
            Without this replacement, the newline would disappear, because `\\n` is meaningless in an XML file.

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

        Args:
            prop_name: name of the property
            values: values to add
            permissions: optional permissions of this value
            comment: optional comment
            newline_replacement: options how to deal with `\\n` inside the text value. Default: replace with `<br/>`

        Returns:
            The original resource, with the added values
        """
        values = [replace_newlines_with_tags(str(v), newline_replacement) for v in values]
        self.values.extend([Richtext(v, prop_name, permissions, comment, self.res_id) for v in values])
        return self

    def add_richtext_optional(
        self,
        prop_name: str,
        value: Any,
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
        newline_replacement: NewlineReplacement = NewlineReplacement.LINEBREAK,
    ) -> Resource:
        """
        If the value is not empty, add it to the resource, otherwise return the resource unchanged.
        Rich text values must be provided as strings, potentially containing DSP Standard Standoff Markup XML tags
        as [documented here.](https://docs.dasch.swiss/latest/DSP-API/03-endpoints/api-v2/text/standard-standoff/)
        Only the documented tags are allowed.

        Conversions:
            By default, replace newline characters inside the text value with `<br/>`, which preserves the linebreak.
            Without this replacement, the newline would disappear, because `\\n` is meaningless in an XML file.

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

        Args:
            prop_name: name of the property
            value: value to add or empty value
            permissions: optional permissions of this value
            comment: optional comment
            newline_replacement: options how to deal with `\\n` inside the text value. Default: replace with `<br/>`

        Returns:
            The original resource, with the added value if it was not empty, else the unchanged original resource.
        """
        if is_nonempty_value(value):
            value = replace_newlines_with_tags(str(value), newline_replacement)
            self.values.append(Richtext(value, prop_name, permissions, comment, self.res_id))
        return self

    #######################
    # TimeValue
    #######################

    def add_time(
        self,
        prop_name: str,
        value: str,
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
    ) -> Resource:
        """
        Add a time value to the resource.

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

        Args:
            prop_name: name of the property
            value: value to add
            permissions: optional permissions of this value
            comment: optional comment

        Returns:
            The original resource, with the added value
        """
        self.values.append(TimeValue(value, prop_name, permissions, comment, self.res_id))
        return self

    def add_time_multiple(
        self,
        prop_name: str,
        values: Collection[str],
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
    ) -> Resource:
        """
        Add several time values to the resource.

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

        Args:
            prop_name: name of the property
            values: values to add
            permissions: optional permissions of this value
            comment: optional comment

        Returns:
            The original resource, with the added values
        """
        self.values.extend([TimeValue(v, prop_name, permissions, comment, self.res_id) for v in values])
        return self

    def add_time_optional(
        self,
        prop_name: str,
        value: Any,
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
    ) -> Resource:
        """
        If the value is not empty, add it to the resource, otherwise return the resource unchanged.

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

        Args:
            prop_name: name of the property
            value: value to add or empty value
            permissions: optional permissions of this value
            comment: optional comment

        Returns:
            The original resource, with the added value if it was not empty, else the unchanged original resource.
        """
        if is_nonempty_value(value):
            self.values.append(TimeValue(value, prop_name, permissions, comment, self.res_id))
        return self

    #######################
    # UriValue
    #######################

    def add_uri(
        self,
        prop_name: str,
        value: str,
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
    ) -> Resource:
        """
        Add a URI value to the resource.

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

        Args:
            prop_name: name of the property
            value: value to add
            permissions: optional permissions of this value
            comment: optional comment

        Returns:
            The original resource, with the added value
        """
        self.values.append(UriValue(value, prop_name, permissions, comment, self.res_id))
        return self

    def add_uri_multiple(
        self,
        prop_name: str,
        values: Collection[str],
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
    ) -> Resource:
        """
        Add several URI values to the resource.

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

        Args:
            prop_name: name of the property
            values: values to add
            permissions: optional permissions of this value
            comment: optional comment

        Returns:
            The original resource, with the added values
        """
        self.values.extend([UriValue(v, prop_name, permissions, comment, self.res_id) for v in values])
        return self

    def add_uri_optional(
        self,
        prop_name: str,
        value: Any,
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
    ) -> Resource:
        """
        If the value is not empty, add it to the resource, otherwise return the resource unchanged.

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

        Args:
            prop_name: name of the property
            value: value to add or empty value
            permissions: optional permissions of this value
            comment: optional comment

        Returns:
            The original resource, with the added value if it was not empty, else the unchanged original resource.
        """
        if is_nonempty_value(value):
            self.values.append(UriValue(value, prop_name, permissions, comment, self.res_id))
        return self

    #######################
    # AbstractFileValue
    #######################

    def add_file(
        self,
        filename: str,
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
    ) -> Resource:
        """
        Add a file (bitstream) to the resource.

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

        Args:
            filename: path to the file
            permissions: optional permissions of this file
            comment: optional comment

        Raises:
            InputError: If the resource already has a file or IIIF URI value

        Returns:
            The original resource, with the added value
        """
        if self.file_value:
            raise InputError(
                f"The resource with the ID '{self.res_id}' already contains a file with the name: "
                f"'{self.file_value.value}'.\n"
                f"The new file with the name '{filename}' cannot be added."
            )
        self.file_value = FileValue(filename, permissions, comment, self.res_id)
        return self

    def add_iiif_uri(
        self,
        iiif_uri: str,
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
    ) -> Resource:
        """
        Add a IIIF URI to the resource.

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

        Args:
            iiif_uri: valid IIIF URI
            permissions: optional permissions of this value
            comment: optional comment

        Raises:
            InputError: If the resource already has a file or IIIF URI value

        Returns:
            The original resource, with the added value
        """
        if self.file_value:
            raise InputError(
                f"The resource with the ID '{self.res_id}' already contains a file with the name: "
                f"'{self.file_value.value}'.\n"
                f"The new file with the name '{iiif_uri}' cannot be added."
            )
        self.file_value = IIIFUri(iiif_uri, permissions, comment, self.res_id)
        return self

    #######################
    # Migration Metadata
    #######################

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

        [See XML documentation for details](https://docs.dasch.swiss/latest/DSP-TOOLS/file-formats/xml-data-file/#describing-resources-with-the-resource-element)

        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 migration 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

create_new

Create a new resource.

Parameters:

Name	Type	Description	Default
res_id	str	resource ID	required
restype	str	resource type	required
label	str	resource label	required
permissions	Permissions	optional permissions of this resource	PROJECT_SPECIFIC_PERMISSIONS

Returns:

Type	Description
Resource	Resource

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/resource.py

@staticmethod
def create_new(
    res_id: str,
    restype: str,
    label: str,
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
) -> Resource:
    """
    Create a new resource.

    Args:
        res_id: resource ID
        restype: resource type
        label: resource label
        permissions: optional permissions of this resource

    Returns:
        Resource
    """
    return Resource(
        res_id=res_id,
        restype=restype,
        label=label,
        permissions=permissions,
    )

add_bool

Add a boolean value to the resource.

See XML documentation for details

Conversions

• The conversion is case-insensitive, meaning that the words can also be capitalised.
• "false", "0", "0.0", "no", "non", "nein" -> "false"
• "true", "1", "1.0", "yes", "oui", "ja" -> "true"

Parameters:

Name	Type	Description	Default
prop_name	str	name of the property	required
value	bool | str | int | float	value to add	required
permissions	Permissions	optional permissions of this value	PROJECT_SPECIFIC_PERMISSIONS
comment	str | None	optional comment	None

Returns:

Type	Description
Resource	The original resource, with the added value

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/resource.py

def add_bool(
    self,
    prop_name: str,
    value: bool | str | int | float,
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
) -> Resource:
    """
    Add a boolean value to the resource.

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

    Conversions:
     - The conversion is case-insensitive, meaning that the words can also be capitalised.
     - "false", "0", "0.0", "no", "non", "nein" -> "false"
     - "true", "1", "1.0", "yes", "oui", "ja" -> "true"

    Args:
        prop_name: name of the property
        value: value to add
        permissions: optional permissions of this value
        comment: optional comment

    Returns:
        The original resource, with the added value
    """
    self.values.append(BooleanValue(value, prop_name, permissions, comment, self.res_id))
    return self

add_bool_optional

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

See XML documentation for details

Conversions

• The conversion is case-insensitive, meaning that the words can also be capitalised.
• "false", "0", "0.0", "no", "non", "nein" -> "false"
• "true", "1", "1.0", "yes", "oui", "ja" -> "true"

Parameters:

Name	Type	Description	Default
prop_name	str	name of the property	required
value	Any	value to add or empty value	required
permissions	Permissions	optional permissions of this value	PROJECT_SPECIFIC_PERMISSIONS
comment	str | None	optional comment	None

Returns:

Type	Description
Resource	The original resource, with the added value if it was not empty, else the unchanged original resource.

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/resource.py

def add_bool_optional(
    self,
    prop_name: str,
    value: Any,
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
) -> Resource:
    """
    If the value is not empty, add it to the resource, otherwise return the resource unchanged.

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

    Conversions:
     - The conversion is case-insensitive, meaning that the words can also be capitalised.
     - "false", "0", "0.0", "no", "non", "nein" -> "false"
     - "true", "1", "1.0", "yes", "oui", "ja" -> "true"

    Args:
        prop_name: name of the property
        value: value to add or empty value
        permissions: optional permissions of this value
        comment: optional comment

    Returns:
        The original resource, with the added value if it was not empty, else the unchanged original resource.
    """
    if is_nonempty_value(value):
        self.values.append(BooleanValue(value, prop_name, permissions, comment, self.res_id))
    return self

add_color

Add a color value to the resource.

See XML documentation for details

Parameters:

Name	Type	Description	Default
prop_name	str	name of the property	required
value	str	value to add	required
permissions	Permissions	optional permissions of this value	PROJECT_SPECIFIC_PERMISSIONS
comment	str | None	optional comment	None

Returns:

Type	Description
Resource	The original resource, with the added value

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/resource.py

def add_color(
    self,
    prop_name: str,
    value: str,
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
) -> Resource:
    """
    Add a color value to the resource.

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

    Args:
        prop_name: name of the property
        value: value to add
        permissions: optional permissions of this value
        comment: optional comment

    Returns:
        The original resource, with the added value
    """
    self.values.append(ColorValue(value, prop_name, permissions, comment, self.res_id))
    return self

add_color_multiple

Add several color values to the resource.

See XML documentation for details

Parameters:

Name	Type	Description	Default
prop_name	str	name of the property	required
values	Collection[str]	values to add	required
permissions	Permissions	optional permissions of this value	PROJECT_SPECIFIC_PERMISSIONS
comment	str | None	optional comment	None

Returns:

Type	Description
Resource	The original resource, with the added values

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/resource.py

def add_color_multiple(
    self,
    prop_name: str,
    values: Collection[str],
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
) -> Resource:
    """
    Add several color values to the resource.

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

    Args:
        prop_name: name of the property
        values: values to add
        permissions: optional permissions of this value
        comment: optional comment

    Returns:
        The original resource, with the added values
    """
    self.values.extend([ColorValue(v, prop_name, permissions, comment, self.res_id) for v in values])
    return self

add_color_optional

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

See XML documentation for details

Parameters:

Name	Type	Description	Default
prop_name	str	name of the property	required
value	Any	value to add or empty value	required
permissions	Permissions	optional permissions of this value	PROJECT_SPECIFIC_PERMISSIONS
comment	str | None	optional comment	None

Returns:

Type	Description
Resource	The original resource, with the added value if it was not empty, else the unchanged original resource.

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/resource.py

def add_color_optional(
    self,
    prop_name: str,
    value: Any,
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
) -> Resource:
    """
    If the value is not empty, add it to the resource, otherwise return the resource unchanged.

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

    Args:
        prop_name: name of the property
        value: value to add or empty value
        permissions: optional permissions of this value
        comment: optional comment

    Returns:
        The original resource, with the added value if it was not empty, else the unchanged original resource.
    """
    if is_nonempty_value(value):
        self.values.append(ColorValue(value, prop_name, permissions, comment, self.res_id))
    return self

add_date

Add a date value to the resource. See XML documentation for details

Parameters:

Name	Type	Description	Default
prop_name	str	name of the property	required
value	str	value to add	required
permissions	Permissions	optional permissions of this value	PROJECT_SPECIFIC_PERMISSIONS
comment	str | None	optional comment	None

Returns:

Type	Description
Resource	The original resource, with the added value

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/resource.py

def add_date(
    self,
    prop_name: str,
    value: str,
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
) -> Resource:
    """
    Add a date value to the resource.
    [See XML documentation for details](https://docs.dasch.swiss/latest/DSP-TOOLS/file-formats/xml-data-file/#date)

    Args:
        prop_name: name of the property
        value: value to add
        permissions: optional permissions of this value
        comment: optional comment

    Returns:
        The original resource, with the added value
    """
    self.values.append(DateValue(value, prop_name, permissions, comment, self.res_id))
    return self

add_date_multiple

Add several date values to the resource.

See XML documentation for details

Parameters:

Name	Type	Description	Default
prop_name	str	name of the property	required
values	Collection[str]	values to add	required
permissions	Permissions	optional permissions of this value	PROJECT_SPECIFIC_PERMISSIONS
comment	str | None	optional comment	None

Returns:

Type	Description
Resource	The original resource, with the added values

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/resource.py

def add_date_multiple(
    self,
    prop_name: str,
    values: Collection[str],
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
) -> Resource:
    """
    Add several date values to the resource.

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

    Args:
        prop_name: name of the property
        values: values to add
        permissions: optional permissions of this value
        comment: optional comment

    Returns:
        The original resource, with the added values
    """
    self.values.extend([DateValue(v, prop_name, permissions, comment, self.res_id) for v in values])
    return self

add_date_optional

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

See XML documentation for details

Parameters:

Name	Type	Description	Default
prop_name	str	name of the property	required
value	Any	value to add or empty value	required
permissions	Permissions	optional permissions of this value	PROJECT_SPECIFIC_PERMISSIONS
comment	str | None	optional comment	None

Returns:

Type	Description
Resource	The original resource, with the added value if it was not empty, else the unchanged original resource.

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/resource.py

def add_date_optional(
    self,
    prop_name: str,
    value: Any,
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
) -> Resource:
    """
    If the value is not empty, add it to the resource, otherwise return the resource unchanged.

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

    Args:
        prop_name: name of the property
        value: value to add or empty value
        permissions: optional permissions of this value
        comment: optional comment

    Returns:
        The original resource, with the added value if it was not empty, else the unchanged original resource.
    """
    if is_nonempty_value(value):
        self.values.append(DateValue(value, prop_name, permissions, comment, self.res_id))
    return self

add_decimal

Add a decimal value to the resource. If the value is provided as string, it must be convertible to integer or float.

See XML documentation for details

Parameters:

Name	Type	Description	Default
prop_name	str	name of the property	required
value	float | int | str	value to add	required
permissions	Permissions	optional permissions of this value	PROJECT_SPECIFIC_PERMISSIONS
comment	str | None	optional comment	None

Returns:

Type	Description
Resource	The original resource, with the added value

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/resource.py

def add_decimal(
    self,
    prop_name: str,
    value: float | int | str,
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
) -> Resource:
    """
    Add a decimal value to the resource.
    If the value is provided as string, it must be convertible to integer or float.

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

    Args:
        prop_name: name of the property
        value: value to add
        permissions: optional permissions of this value
        comment: optional comment

    Returns:
        The original resource, with the added value
    """
    self.values.append(DecimalValue(value, prop_name, permissions, comment, self.res_id))
    return self

add_decimal_multiple

Add several decimal values to the resource. If the values are provided as string, they must be convertible to integer or float.

See XML documentation for details

Parameters:

Name	Type	Description	Default
prop_name	str	name of the property	required
values	Collection[float | int | str]	values to add	required
permissions	Permissions	optional permissions of this value	PROJECT_SPECIFIC_PERMISSIONS
comment	str | None	optional comment	None

Returns:

Type	Description
Resource	The original resource, with the added values

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/resource.py

def add_decimal_multiple(
    self,
    prop_name: str,
    values: Collection[float | int | str],
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
) -> Resource:
    """
    Add several decimal values to the resource.
    If the values are provided as string, they must be convertible to integer or float.

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

    Args:
        prop_name: name of the property
        values: values to add
        permissions: optional permissions of this value
        comment: optional comment

    Returns:
        The original resource, with the added values
    """
    self.values.extend([DecimalValue(v, prop_name, permissions, comment, self.res_id) for v in values])
    return self

add_decimal_optional

If the value is not empty, add it to the resource, otherwise return the resource unchanged. If the value is provided as string, it must be convertible to integer or float.

See XML documentation for details

Parameters:

Name	Type	Description	Default
prop_name	str	name of the property	required
value	Any	value to add or empty value	required
permissions	Permissions	optional permissions of this value	PROJECT_SPECIFIC_PERMISSIONS
comment	str | None	optional comment	None

Returns:

Type	Description
Resource	The original resource, with the added value if it was not empty, else the unchanged original resource.

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/resource.py

def add_decimal_optional(
    self,
    prop_name: str,
    value: Any,
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
) -> Resource:
    """
    If the value is not empty, add it to the resource, otherwise return the resource unchanged.
    If the value is provided as string, it must be convertible to integer or float.

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

    Args:
        prop_name: name of the property
        value: value to add or empty value
        permissions: optional permissions of this value
        comment: optional comment

    Returns:
        The original resource, with the added value if it was not empty, else the unchanged original resource.
    """
    if is_nonempty_value(value):
        self.values.append(DecimalValue(value, prop_name, permissions, comment, self.res_id))
    return self

add_geoname

Add a geonames.org value to the resource. The geonames.org identifier must be provided as integer or string that is convertible to integer.

See XML documentation for details

Parameters:

Name	Type	Description	Default
prop_name	str	name of the property	required
value	int | str	value to add	required
permissions	Permissions	optional permissions of this value	PROJECT_SPECIFIC_PERMISSIONS
comment	str | None	optional comment	None

Returns:

Type	Description
Resource	The original resource, with the added value

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/resource.py

def add_geoname(
    self,
    prop_name: str,
    value: int | str,
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
) -> Resource:
    """
    Add a [geonames.org](https://www.geonames.org/) value to the resource.
    The [geonames.org](https://www.geonames.org/) identifier must be provided as integer
    or string that is convertible to integer.

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


    Args:
        prop_name: name of the property
        value: value to add
        permissions: optional permissions of this value
        comment: optional comment

    Returns:
        The original resource, with the added value
    """
    self.values.append(GeonameValue(value, prop_name, permissions, comment, self.res_id))
    return self

add_geoname_multiple

Add several geonames.org values to the resource. The geonames.org identifiers must be provided as integers or strings that are convertible to integers.

See XML documentation for details

Parameters:

Name	Type	Description	Default
prop_name	str	name of the property	required
values	Collection[int | str]	values to add	required
permissions	Permissions	optional permissions of this value	PROJECT_SPECIFIC_PERMISSIONS
comment	str | None	optional comment	None

Returns:

Type	Description
Resource	The original resource, with the added values

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/resource.py

def add_geoname_multiple(
    self,
    prop_name: str,
    values: Collection[int | str],
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
) -> Resource:
    """
    Add several [geonames.org](https://www.geonames.org/) values to the resource.
    The [geonames.org](https://www.geonames.org/) identifiers must be provided as integers
    or strings that are convertible to integers.

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

    Args:
        prop_name: name of the property
        values: values to add
        permissions: optional permissions of this value
        comment: optional comment

    Returns:
        The original resource, with the added values
    """
    self.values.extend([GeonameValue(v, prop_name, permissions, comment, self.res_id) for v in values])
    return self

add_geoname_optional

If the value is not empty, add it to the resource, otherwise return the resource unchanged. The geonames.org identifier must be provided as integer or string that is convertible to integer.

See XML documentation for details

Parameters:

Name	Type	Description	Default
prop_name	str	name of the property	required
value	Any	value to add or empty value	required
permissions	Permissions	optional permissions of this value	PROJECT_SPECIFIC_PERMISSIONS
comment	str | None	optional comment	None

Returns:

Type	Description
Resource	The original resource, with the added value if it was not empty, else the unchanged original resource.

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/resource.py

def add_geoname_optional(
    self,
    prop_name: str,
    value: Any,
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
) -> Resource:
    """
    If the value is not empty, add it to the resource, otherwise return the resource unchanged.
    The [geonames.org](https://www.geonames.org/) identifier must be provided as integer
    or string that is convertible to integer.

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

    Args:
        prop_name: name of the property
        value: value to add or empty value
        permissions: optional permissions of this value
        comment: optional comment

    Returns:
        The original resource, with the added value if it was not empty, else the unchanged original resource.
    """
    if is_nonempty_value(value):
        self.values.append(GeonameValue(value, prop_name, permissions, comment, self.res_id))
    return self

add_integer

Add an integer value to the resource. If the value is provided as string, it must be convertible to integer.

See XML documentation for details

Parameters:

Name	Type	Description	Default
prop_name	str	name of the property	required
value	int | str	value to add	required
permissions	Permissions	optional permissions of this value	PROJECT_SPECIFIC_PERMISSIONS
comment	str | None	optional comment	None

Returns:

Type	Description
Resource	The original resource, with the added value

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/resource.py

def add_integer(
    self,
    prop_name: str,
    value: int | str,
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
) -> Resource:
    """
    Add an integer value to the resource.
    If the value is provided as string, it must be convertible to integer.

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

    Args:
        prop_name: name of the property
        value: value to add
        permissions: optional permissions of this value
        comment: optional comment

    Returns:
        The original resource, with the added value
    """
    self.values.append(IntValue(value, prop_name, permissions, comment, self.res_id))
    return self

add_integer_multiple

Add several integer values to the resource. If the values are provided as string, they must be convertible to integer.

See XML documentation for details

Parameters:

Name	Type	Description	Default
prop_name	str	name of the property	required
values	Collection[int | str]	values to add	required
permissions	Permissions	optional permissions of this value	PROJECT_SPECIFIC_PERMISSIONS
comment	str | None	optional comment	None

Returns:

Type	Description
Resource	The original resource, with the added values

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/resource.py

def add_integer_multiple(
    self,
    prop_name: str,
    values: Collection[int | str],
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
) -> Resource:
    """
    Add several integer values to the resource.
    If the values are provided as string, they must be convertible to integer.

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

    Args:
        prop_name: name of the property
        values: values to add
        permissions: optional permissions of this value
        comment: optional comment

    Returns:
        The original resource, with the added values
    """
    self.values.extend([IntValue(v, prop_name, permissions, comment, self.res_id) for v in values])
    return self

add_integer_optional

If the value is not empty, add it to the resource, otherwise return the resource unchanged. If the value is provided as string, it must be convertible to integer.

See XML documentation for details

Parameters:

Name	Type	Description	Default
prop_name	str	name of the property	required
value	Any	value to add or empty value	required
permissions	Permissions	optional permissions of this value	PROJECT_SPECIFIC_PERMISSIONS
comment	str | None	optional comment	None

Returns:

Type	Description
Resource	The original resource, with the added value if it was not empty, else the unchanged original resource.

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/resource.py

def add_integer_optional(
    self,
    prop_name: str,
    value: Any,
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
) -> Resource:
    """
    If the value is not empty, add it to the resource, otherwise return the resource unchanged.
    If the value is provided as string, it must be convertible to integer.

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

    Args:
        prop_name: name of the property
        value: value to add or empty value
        permissions: optional permissions of this value
        comment: optional comment

    Returns:
        The original resource, with the added value if it was not empty, else the unchanged original resource.
    """
    if is_nonempty_value(value):
        self.values.append(IntValue(value, prop_name, permissions, comment, self.res_id))
    return self

add_link

Add a link value to the resource, in the form of an ID of another resource.

See XML documentation for details

Parameters:

Name	Type	Description	Default
prop_name	str	name of the property	required
value	str	target resource ID	required
permissions	Permissions	optional permissions of this value	PROJECT_SPECIFIC_PERMISSIONS
comment	str | None	optional comment	None

Returns:

Type	Description
Resource	The original resource, with the added value

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/resource.py

def add_link(
    self,
    prop_name: str,
    value: str,
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
) -> Resource:
    """
    Add a link value to the resource, in the form of an ID of another resource.

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

    Args:
        prop_name: name of the property
        value: target resource ID
        permissions: optional permissions of this value
        comment: optional comment

    Returns:
        The original resource, with the added value
    """
    self.values.append(LinkValue(value, prop_name, permissions, comment, self.res_id))
    return self

add_link_multiple

Add several link values to the resource, in the form of IDs of other resources.

See XML documentation for details

Parameters:

Name	Type	Description	Default
prop_name	str	name of the property	required
values	Collection[str]	list of target resources IDs	required
permissions	Permissions	optional permissions of this value	PROJECT_SPECIFIC_PERMISSIONS
comment	str | None	optional comment	None

Returns:

Type	Description
Resource	The original resource, with the added values

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/resource.py

def add_link_multiple(
    self,
    prop_name: str,
    values: Collection[str],
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
) -> Resource:
    """
    Add several link values to the resource, in the form of IDs of other resources.

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

    Args:
        prop_name: name of the property
        values: list of target resources IDs
        permissions: optional permissions of this value
        comment: optional comment

    Returns:
        The original resource, with the added values
    """
    self.values.extend([LinkValue(v, prop_name, permissions, comment, self.res_id) for v in values])
    return self

add_link_optional

If the value is not empty, add it to the resource, otherwise return the resource unchanged. If non-empty, the value must be an ID of another resource.

See XML documentation for details

Parameters:

Name	Type	Description	Default
prop_name	str	name of the property	required
value	Any	target resource ID or empty value	required
permissions	Permissions	optional permissions of this value	PROJECT_SPECIFIC_PERMISSIONS
comment	str | None	optional comment	None

Returns:

Type	Description
Resource	The original resource, with the added value if it was not empty, else the unchanged original resource.

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/resource.py

def add_link_optional(
    self,
    prop_name: str,
    value: Any,
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
) -> Resource:
    """
    If the value is not empty, add it to the resource, otherwise return the resource unchanged.
    If non-empty, the value must be an ID of another resource.

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

    Args:
        prop_name: name of the property
        value: target resource ID or empty value
        permissions: optional permissions of this value
        comment: optional comment

    Returns:
        The original resource, with the added value if it was not empty, else the unchanged original resource.
    """
    if is_nonempty_value(value):
        self.values.append(LinkValue(value, prop_name, permissions, comment, self.res_id))
    return self

add_list

Add a list value to the resource, i.e. a name of a list node.

See XML documentation for details

Parameters:

Name	Type	Description	Default
prop_name	str	name of the property	required
list_name	str | int | float	name of the list (N.B. not the label, but the name of the list)	required
value	str | int | float	name of a list node (N.B. not the label, but the name of the list node)	required
permissions	Permissions	optional permissions of this value	PROJECT_SPECIFIC_PERMISSIONS
comment	str | None	optional comment	None

Returns:

Type	Description
Resource	The original resource, with the added value

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/resource.py

def add_list(
    self,
    prop_name: str,
    list_name: str | int | float,
    value: str | int | float,
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
) -> Resource:
    """
    Add a list value to the resource, i.e. a name of a list node.

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

    Args:
        prop_name: name of the property
        list_name: name of the list (N.B. not the label, but the name of the list)
        value: name of a list node (N.B. not the label, but the name of the list node)
        permissions: optional permissions of this value
        comment: optional comment

    Returns:
        The original resource, with the added value
    """
    self.values.append(ListValue(value, list_name, prop_name, permissions, comment, self.res_id))
    return self

add_list_multiple

Add several list values to the resource, i.e. names of list nodes.

See XML documentation for details

Parameters:

Name	Type	Description	Default
prop_name	str	name of the property	required
list_name	str | int | float	name of the list (N.B. not the label, but the name of the list)	required
values	Collection[str | int | float]	names of list nodes (N.B. not the labels, but the names of the list nodes)	required
permissions	Permissions	optional permissions of this value	PROJECT_SPECIFIC_PERMISSIONS
comment	str | None	optional comment	None

Returns:

Type	Description
Resource	The original resource, with the added values

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/resource.py

def add_list_multiple(
    self,
    prop_name: str,
    list_name: str | int | float,
    values: Collection[str | int | float],
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
) -> Resource:
    """
    Add several list values to the resource, i.e. names of list nodes.

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

    Args:
        prop_name: name of the property
        list_name: name of the list (N.B. not the label, but the name of the list)
        values: names of list nodes (N.B. not the labels, but the names of the list nodes)
        permissions: optional permissions of this value
        comment: optional comment

    Returns:
        The original resource, with the added values
    """
    self.values.extend([ListValue(v, list_name, prop_name, permissions, comment, self.res_id) for v in values])
    return self

add_list_optional

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

See XML documentation for details

Parameters:

Name	Type	Description	Default
prop_name	str	name of the property	required
list_name	str | int | float	name of the list (N.B. not the label, but the name of the list)	required
value	Any	name of a list node (N.B. not the label, but the name of the list node) or empty value	required
permissions	Permissions	optional permissions of this value	PROJECT_SPECIFIC_PERMISSIONS
comment	str | None	optional comment	None

Returns:

Type	Description
Resource	The original resource, with the added value if it was not empty, else the unchanged original resource.

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/resource.py

def add_list_optional(
    self,
    prop_name: str,
    list_name: str | int | float,
    value: Any,
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
) -> Resource:
    """
    If the value is not empty, add it to the resource, otherwise return the resource unchanged.

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

    Args:
        prop_name: name of the property
        list_name: name of the list (N.B. not the label, but the name of the list)
        value: name of a list node (N.B. not the label, but the name of the list node) or empty value
        permissions: optional permissions of this value
        comment: optional comment

    Returns:
        The original resource, with the added value if it was not empty, else the unchanged original resource.
    """
    if is_nonempty_value(value):
        self.values.append(ListValue(value, list_name, prop_name, permissions, comment, self.res_id))
    return self

add_simpletext

Add a simple text value to the resource.

See XML documentation for details

Parameters:

Name	Type	Description	Default
prop_name	str	name of the property	required
value	str	value to add	required
permissions	Permissions	optional permissions of this value	PROJECT_SPECIFIC_PERMISSIONS
comment	str | None	optional comment	None

Returns:

Type	Description
Resource	The original resource, with the added value

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/resource.py

def add_simpletext(
    self,
    prop_name: str,
    value: str,
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
) -> Resource:
    """
    Add a simple text value to the resource.

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

    Args:
        prop_name: name of the property
        value: value to add
        permissions: optional permissions of this value
        comment: optional comment

    Returns:
        The original resource, with the added value
    """
    self.values.append(SimpleText(value, prop_name, permissions, comment, self.res_id))
    return self

add_simpletext_multiple

Add several simple text values to the resource.

See XML documentation for details

Parameters:

Name	Type	Description	Default
prop_name	str	name of the property	required
values	Collection[str]	values to add	required
permissions	Permissions	optional permissions of this value	PROJECT_SPECIFIC_PERMISSIONS
comment	str | None	optional comment	None

Returns:

Type	Description
Resource	The original resource, with the added values

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/resource.py

def add_simpletext_multiple(
    self,
    prop_name: str,
    values: Collection[str],
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
) -> Resource:
    """
    Add several simple text values to the resource.

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

    Args:
        prop_name: name of the property
        values: values to add
        permissions: optional permissions of this value
        comment: optional comment

    Returns:
        The original resource, with the added values
    """
    self.values.extend([SimpleText(v, prop_name, permissions, comment, self.res_id) for v in values])
    return self

add_simpletext_optional

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

See XML documentation for details

Parameters:

Name	Type	Description	Default
prop_name	str	name of the property	required
value	Any	value to add or empty value	required
permissions	Permissions	optional permissions of this value	PROJECT_SPECIFIC_PERMISSIONS
comment	str | None	optional comment	None

Returns:

Type	Description
Resource	The original resource, with the added value if it was not empty, else the unchanged original resource.

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/resource.py

def add_simpletext_optional(
    self,
    prop_name: str,
    value: Any,
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
) -> Resource:
    """
    If the value is not empty, add it to the resource, otherwise return the resource unchanged.

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

    Args:
        prop_name: name of the property
        value: value to add or empty value
        permissions: optional permissions of this value
        comment: optional comment

    Returns:
        The original resource, with the added value if it was not empty, else the unchanged original resource.
    """
    if is_nonempty_value(value):
        self.values.append(SimpleText(value, prop_name, permissions, comment, self.res_id))
    return self

add_richtext

Add a rich text value to the resource. Rich text values must be provided as strings, potentially containing DSP Standard Standoff Markup XML tags as documented here. Only the documented tags are allowed.

Conversions

By default, replace newline characters inside the text value with <br/>, which preserves the linebreak. Without this replacement, the newline would disappear, because \n is meaningless in an XML file.

See XML documentation for details

Parameters:

Name	Type	Description	Default
prop_name	str	name of the property	required
value	str	value to add	required
permissions	Permissions	optional permissions of this value	PROJECT_SPECIFIC_PERMISSIONS
comment	str | None	optional comment	None
newline_replacement	NewlineReplacement	options how to deal with \n inside the text value. Default: replace with <br/>	LINEBREAK

Returns:

Type	Description
Resource	The original resource, with the added value

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/resource.py

def add_richtext(
    self,
    prop_name: str,
    value: str,
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
    newline_replacement: NewlineReplacement = NewlineReplacement.LINEBREAK,
) -> Resource:
    """
    Add a rich text value to the resource.
    Rich text values must be provided as strings, potentially containing DSP Standard Standoff Markup XML tags
    as [documented here.](https://docs.dasch.swiss/latest/DSP-API/03-endpoints/api-v2/text/standard-standoff/)
    Only the documented tags are allowed.

    Conversions:
        By default, replace newline characters inside the text value with `<br/>`, which preserves the linebreak.
        Without this replacement, the newline would disappear, because `\\n` is meaningless in an XML file.

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

    Args:
        prop_name: name of the property
        value: value to add
        permissions: optional permissions of this value
        comment: optional comment
        newline_replacement: options how to deal with `\\n` inside the text value. Default: replace with `<br/>`

    Returns:
        The original resource, with the added value
    """
    value = replace_newlines_with_tags(str(value), newline_replacement)
    self.values.append(Richtext(value, prop_name, permissions, comment, self.res_id))
    return self

add_richtext_multiple

Add several rich text values to the resource. Rich text values must be provided as strings, potentially containing DSP Standard Standoff Markup XML tags as documented here. Only the documented tags are allowed.

Conversions

By default, replace newline characters inside the text value with <br/>, which preserves the linebreak. Without this replacement, the newline would disappear, because \n is meaningless in an XML file.

See XML documentation for details

Parameters:

Name	Type	Description	Default
prop_name	str	name of the property	required
values	Collection[str]	values to add	required
permissions	Permissions	optional permissions of this value	PROJECT_SPECIFIC_PERMISSIONS
comment	str | None	optional comment	None
newline_replacement	NewlineReplacement	options how to deal with \n inside the text value. Default: replace with <br/>	LINEBREAK

Returns:

Type	Description
Resource	The original resource, with the added values

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/resource.py

def add_richtext_multiple(
    self,
    prop_name: str,
    values: Collection[str],
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
    newline_replacement: NewlineReplacement = NewlineReplacement.LINEBREAK,
) -> Resource:
    """
    Add several rich text values to the resource.
    Rich text values must be provided as strings, potentially containing DSP Standard Standoff Markup XML tags
    as [documented here.](https://docs.dasch.swiss/latest/DSP-API/03-endpoints/api-v2/text/standard-standoff/)
    Only the documented tags are allowed.

    Conversions:
        By default, replace newline characters inside the text value with `<br/>`, which preserves the linebreak.
        Without this replacement, the newline would disappear, because `\\n` is meaningless in an XML file.

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

    Args:
        prop_name: name of the property
        values: values to add
        permissions: optional permissions of this value
        comment: optional comment
        newline_replacement: options how to deal with `\\n` inside the text value. Default: replace with `<br/>`

    Returns:
        The original resource, with the added values
    """
    values = [replace_newlines_with_tags(str(v), newline_replacement) for v in values]
    self.values.extend([Richtext(v, prop_name, permissions, comment, self.res_id) for v in values])
    return self

add_richtext_optional

If the value is not empty, add it to the resource, otherwise return the resource unchanged. Rich text values must be provided as strings, potentially containing DSP Standard Standoff Markup XML tags as documented here. Only the documented tags are allowed.

Conversions

By default, replace newline characters inside the text value with <br/>, which preserves the linebreak. Without this replacement, the newline would disappear, because \n is meaningless in an XML file.

See XML documentation for details

Parameters:

Name	Type	Description	Default
prop_name	str	name of the property	required
value	Any	value to add or empty value	required
permissions	Permissions	optional permissions of this value	PROJECT_SPECIFIC_PERMISSIONS
comment	str | None	optional comment	None
newline_replacement	NewlineReplacement	options how to deal with \n inside the text value. Default: replace with <br/>	LINEBREAK

Returns:

Type	Description
Resource	The original resource, with the added value if it was not empty, else the unchanged original resource.

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/resource.py

def add_richtext_optional(
    self,
    prop_name: str,
    value: Any,
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
    newline_replacement: NewlineReplacement = NewlineReplacement.LINEBREAK,
) -> Resource:
    """
    If the value is not empty, add it to the resource, otherwise return the resource unchanged.
    Rich text values must be provided as strings, potentially containing DSP Standard Standoff Markup XML tags
    as [documented here.](https://docs.dasch.swiss/latest/DSP-API/03-endpoints/api-v2/text/standard-standoff/)
    Only the documented tags are allowed.

    Conversions:
        By default, replace newline characters inside the text value with `<br/>`, which preserves the linebreak.
        Without this replacement, the newline would disappear, because `\\n` is meaningless in an XML file.

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

    Args:
        prop_name: name of the property
        value: value to add or empty value
        permissions: optional permissions of this value
        comment: optional comment
        newline_replacement: options how to deal with `\\n` inside the text value. Default: replace with `<br/>`

    Returns:
        The original resource, with the added value if it was not empty, else the unchanged original resource.
    """
    if is_nonempty_value(value):
        value = replace_newlines_with_tags(str(value), newline_replacement)
        self.values.append(Richtext(value, prop_name, permissions, comment, self.res_id))
    return self

add_time

Add a time value to the resource.

See XML documentation for details

Parameters:

Name	Type	Description	Default
prop_name	str	name of the property	required
value	str	value to add	required
permissions	Permissions	optional permissions of this value	PROJECT_SPECIFIC_PERMISSIONS
comment	str | None	optional comment	None

Returns:

Type	Description
Resource	The original resource, with the added value

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/resource.py

def add_time(
    self,
    prop_name: str,
    value: str,
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
) -> Resource:
    """
    Add a time value to the resource.

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

    Args:
        prop_name: name of the property
        value: value to add
        permissions: optional permissions of this value
        comment: optional comment

    Returns:
        The original resource, with the added value
    """
    self.values.append(TimeValue(value, prop_name, permissions, comment, self.res_id))
    return self

add_time_multiple

Add several time values to the resource.

See XML documentation for details

Parameters:

Name	Type	Description	Default
prop_name	str	name of the property	required
values	Collection[str]	values to add	required
permissions	Permissions	optional permissions of this value	PROJECT_SPECIFIC_PERMISSIONS
comment	str | None	optional comment	None

Returns:

Type	Description
Resource	The original resource, with the added values

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/resource.py

def add_time_multiple(
    self,
    prop_name: str,
    values: Collection[str],
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
) -> Resource:
    """
    Add several time values to the resource.

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

    Args:
        prop_name: name of the property
        values: values to add
        permissions: optional permissions of this value
        comment: optional comment

    Returns:
        The original resource, with the added values
    """
    self.values.extend([TimeValue(v, prop_name, permissions, comment, self.res_id) for v in values])
    return self

add_time_optional

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

See XML documentation for details

Parameters:

Name	Type	Description	Default
prop_name	str	name of the property	required
value	Any	value to add or empty value	required
permissions	Permissions	optional permissions of this value	PROJECT_SPECIFIC_PERMISSIONS
comment	str | None	optional comment	None

Returns:

Type	Description
Resource	The original resource, with the added value if it was not empty, else the unchanged original resource.

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/resource.py

def add_time_optional(
    self,
    prop_name: str,
    value: Any,
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
) -> Resource:
    """
    If the value is not empty, add it to the resource, otherwise return the resource unchanged.

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

    Args:
        prop_name: name of the property
        value: value to add or empty value
        permissions: optional permissions of this value
        comment: optional comment

    Returns:
        The original resource, with the added value if it was not empty, else the unchanged original resource.
    """
    if is_nonempty_value(value):
        self.values.append(TimeValue(value, prop_name, permissions, comment, self.res_id))
    return self

add_uri

Add a URI value to the resource.

See XML documentation for details

Parameters:

Name	Type	Description	Default
prop_name	str	name of the property	required
value	str	value to add	required
permissions	Permissions	optional permissions of this value	PROJECT_SPECIFIC_PERMISSIONS
comment	str | None	optional comment	None

Returns:

Type	Description
Resource	The original resource, with the added value

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/resource.py

def add_uri(
    self,
    prop_name: str,
    value: str,
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
) -> Resource:
    """
    Add a URI value to the resource.

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

    Args:
        prop_name: name of the property
        value: value to add
        permissions: optional permissions of this value
        comment: optional comment

    Returns:
        The original resource, with the added value
    """
    self.values.append(UriValue(value, prop_name, permissions, comment, self.res_id))
    return self

add_uri_multiple

Add several URI values to the resource.

See XML documentation for details

Parameters:

Name	Type	Description	Default
prop_name	str	name of the property	required
values	Collection[str]	values to add	required
permissions	Permissions	optional permissions of this value	PROJECT_SPECIFIC_PERMISSIONS
comment	str | None	optional comment	None

Returns:

Type	Description
Resource	The original resource, with the added values

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/resource.py

def add_uri_multiple(
    self,
    prop_name: str,
    values: Collection[str],
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
) -> Resource:
    """
    Add several URI values to the resource.

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

    Args:
        prop_name: name of the property
        values: values to add
        permissions: optional permissions of this value
        comment: optional comment

    Returns:
        The original resource, with the added values
    """
    self.values.extend([UriValue(v, prop_name, permissions, comment, self.res_id) for v in values])
    return self

add_uri_optional

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

See XML documentation for details

Parameters:

Name	Type	Description	Default
prop_name	str	name of the property	required
value	Any	value to add or empty value	required
permissions	Permissions	optional permissions of this value	PROJECT_SPECIFIC_PERMISSIONS
comment	str | None	optional comment	None

Returns:

Type	Description
Resource	The original resource, with the added value if it was not empty, else the unchanged original resource.

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/resource.py

def add_uri_optional(
    self,
    prop_name: str,
    value: Any,
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
) -> Resource:
    """
    If the value is not empty, add it to the resource, otherwise return the resource unchanged.

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

    Args:
        prop_name: name of the property
        value: value to add or empty value
        permissions: optional permissions of this value
        comment: optional comment

    Returns:
        The original resource, with the added value if it was not empty, else the unchanged original resource.
    """
    if is_nonempty_value(value):
        self.values.append(UriValue(value, prop_name, permissions, comment, self.res_id))
    return self

add_file

Add a file (bitstream) to the resource.

See XML documentation for details

Parameters:

Name	Type	Description	Default
filename	str	path to the file	required
permissions	Permissions	optional permissions of this file	PROJECT_SPECIFIC_PERMISSIONS
comment	str | None	optional comment	None

Returns:

Type	Description
Resource	The original resource, with the added value

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/resource.py

def add_file(
    self,
    filename: str,
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
) -> Resource:
    """
    Add a file (bitstream) to the resource.

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

    Args:
        filename: path to the file
        permissions: optional permissions of this file
        comment: optional comment

    Raises:
        InputError: If the resource already has a file or IIIF URI value

    Returns:
        The original resource, with the added value
    """
    if self.file_value:
        raise InputError(
            f"The resource with the ID '{self.res_id}' already contains a file with the name: "
            f"'{self.file_value.value}'.\n"
            f"The new file with the name '{filename}' cannot be added."
        )
    self.file_value = FileValue(filename, permissions, comment, self.res_id)
    return self

add_iiif_uri

Add a IIIF URI to the resource.

See XML documentation for details

Parameters:

Name	Type	Description	Default
iiif_uri	str	valid IIIF URI	required
permissions	Permissions	optional permissions of this value	PROJECT_SPECIFIC_PERMISSIONS
comment	str | None	optional comment	None

Returns:

Type	Description
Resource	The original resource, with the added value

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/resource.py

def add_iiif_uri(
    self,
    iiif_uri: str,
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
) -> Resource:
    """
    Add a IIIF URI to the resource.

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

    Args:
        iiif_uri: valid IIIF URI
        permissions: optional permissions of this value
        comment: optional comment

    Raises:
        InputError: If the resource already has a file or IIIF URI value

    Returns:
        The original resource, with the added value
    """
    if self.file_value:
        raise InputError(
            f"The resource with the ID '{self.res_id}' already contains a file with the name: "
            f"'{self.file_value.value}'.\n"
            f"The new file with the name '{iiif_uri}' cannot be added."
        )
    self.file_value = IIIFUri(iiif_uri, permissions, comment, self.res_id)
    return self

add_migration_metadata

Add metadata from a SALSAH migration.

See XML documentation for details

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
Resource	The original resource, with the added migration metadata

Source code in dsp/dsp-tools/src/dsp_tools/xmllib/models/resource.py

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

    [See XML documentation for details](https://docs.dasch.swiss/latest/DSP-TOOLS/file-formats/xml-data-file/#describing-resources-with-the-resource-element)

    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 migration 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