LinkResource

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

@dataclass
class LinkResource:
    res_id: str
    label: str
    values: list[Value]
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS
    migration_metadata: MigrationMetadata | None = None

    @staticmethod
    def create_new(
        res_id: str,
        label: str,
        link_to: Collection[str],
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    ) -> LinkResource:
        """
        Creates a new link resource.
        A link resource is like a container that groups together several other resources of different classes.

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

        Args:
            res_id: ID of this link resource
            label: label of this link resource
            link_to: IDs of the resources that should be linked together (cardinality 1-n)
            permissions: permissions of this link resource

        Returns:
            A link resource

        Examples:
            ```python
            link_resource = xmllib.LinkResource.create_new(
                res_id="ID",
                label="label",
                link_to=["target_resource_id_1", "target_resource_id_2"],
            )
            ```
        """
        _check_strings(string_to_check=res_id, res_id=res_id, field_name="Resource ID")
        res_id = str(res_id)
        lbl = check_and_fix_is_non_empty_string(value=label, res_id=res_id, value_field="label")
        links_to = check_and_fix_collection_input(link_to, "hasLinkTo", res_id)
        link_vals: list[Value] = [
            LinkValue.new(value=x, prop_name="hasLinkTo", resource_id=res_id, comment=None, permissions=permissions)
            for x in links_to
        ]
        return LinkResource(
            res_id=res_id,
            label=lbl,
            values=link_vals,
            permissions=permissions,
        )

    def add_comment(
        self,
        text: str,
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
        newline_replacement: NewlineReplacement = NewlineReplacement.LINEBREAK,
    ) -> LinkResource:
        """
        Add a comment to the resource

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

        Returns:
            The original resource, with the added comment

        Examples:
            ```python
            link_resource = link_resource.add_comment("comment text")
            ```

            ```python
            link_resource = link_resource.add_comment(text="comment text", comment="Comment about the comment.")
            ```
        """
        self.values.append(
            Richtext.new(
                value=text,
                prop_name="hasComment",
                permissions=permissions,
                comment=comment,
                resource_id=self.res_id,
                newline_replacement=newline_replacement,
            )
        )
        return self

    def add_comment_multiple(
        self,
        texts: Collection[str],
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
        newline_replacement: NewlineReplacement = NewlineReplacement.LINEBREAK,
    ) -> LinkResource:
        """
        Add several comments to the resource

        Args:
            texts: list of texts
            permissions: optional permissions of these values
            comment: optional comment about this comment
            newline_replacement: options how to deal with `\\n` inside the text value. Default: replace with `<br/>`

        Returns:
            The original resource, with the added comments

        Examples:
            ```python
            link_resource = link_resource.add_comment_multiple(["comment 1", "comment 2"])
            ```
        """
        vals = check_and_fix_collection_input(texts, "hasComment", self.res_id)
        for v in vals:
            self.add_comment(v, permissions, comment, newline_replacement)
        return self

    def add_comment_optional(
        self,
        text: Any,
        permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
        comment: str | None = None,
        newline_replacement: NewlineReplacement = NewlineReplacement.LINEBREAK,
    ) -> LinkResource:
        """
        If the value is not empty, add it as comment, otherwise return the resource unchanged.

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

        Returns:
            The original resource, with the added comment

        Examples:
            ```python
            link_resource = link_resource.add_comment_optional("comment text")
            ```

            ```python
            link_resource = link_resource.add_comment_optional(None)
            ```
        """
        if is_nonempty_value(text):
            return self.add_comment(text, permissions, comment, newline_replacement)
        return self

create_new

Creates a new link resource. A link resource is like a container that groups together several other resources of different classes.

See XML documentation for details

Parameters:

Name	Type	Description	Default
res_id	str	ID of this link resource	required
label	str	label of this link resource	required
link_to	Collection[str]	IDs of the resources that should be linked together (cardinality 1-n)	required
permissions	Permissions	permissions of this link resource	PROJECT_SPECIFIC_PERMISSIONS

Returns:

Type	Description
LinkResource	A link resource

Examples:

link_resource = xmllib.LinkResource.create_new(
    res_id="ID",
    label="label",
    link_to=["target_resource_id_1", "target_resource_id_2"],
)

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

@staticmethod
def create_new(
    res_id: str,
    label: str,
    link_to: Collection[str],
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
) -> LinkResource:
    """
    Creates a new link resource.
    A link resource is like a container that groups together several other resources of different classes.

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

    Args:
        res_id: ID of this link resource
        label: label of this link resource
        link_to: IDs of the resources that should be linked together (cardinality 1-n)
        permissions: permissions of this link resource

    Returns:
        A link resource

    Examples:
        ```python
        link_resource = xmllib.LinkResource.create_new(
            res_id="ID",
            label="label",
            link_to=["target_resource_id_1", "target_resource_id_2"],
        )
        ```
    """
    _check_strings(string_to_check=res_id, res_id=res_id, field_name="Resource ID")
    res_id = str(res_id)
    lbl = check_and_fix_is_non_empty_string(value=label, res_id=res_id, value_field="label")
    links_to = check_and_fix_collection_input(link_to, "hasLinkTo", res_id)
    link_vals: list[Value] = [
        LinkValue.new(value=x, prop_name="hasLinkTo", resource_id=res_id, comment=None, permissions=permissions)
        for x in links_to
    ]
    return LinkResource(
        res_id=res_id,
        label=lbl,
        values=link_vals,
        permissions=permissions,
    )

add_comment

Add a comment to the resource

Parameters:

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

Returns:

Type	Description
LinkResource	The original resource, with the added comment

Examples:

link_resource = link_resource.add_comment("comment text")

link_resource = link_resource.add_comment(text="comment text", comment="Comment about the comment.")

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

def add_comment(
    self,
    text: str,
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
    newline_replacement: NewlineReplacement = NewlineReplacement.LINEBREAK,
) -> LinkResource:
    """
    Add a comment to the resource

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

    Returns:
        The original resource, with the added comment

    Examples:
        ```python
        link_resource = link_resource.add_comment("comment text")
        ```

        ```python
        link_resource = link_resource.add_comment(text="comment text", comment="Comment about the comment.")
        ```
    """
    self.values.append(
        Richtext.new(
            value=text,
            prop_name="hasComment",
            permissions=permissions,
            comment=comment,
            resource_id=self.res_id,
            newline_replacement=newline_replacement,
        )
    )
    return self

add_comment_multiple

Add several comments to the resource

Parameters:

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

Returns:

Type	Description
LinkResource	The original resource, with the added comments

Examples:

link_resource = link_resource.add_comment_multiple(["comment 1", "comment 2"])

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

def add_comment_multiple(
    self,
    texts: Collection[str],
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
    newline_replacement: NewlineReplacement = NewlineReplacement.LINEBREAK,
) -> LinkResource:
    """
    Add several comments to the resource

    Args:
        texts: list of texts
        permissions: optional permissions of these values
        comment: optional comment about this comment
        newline_replacement: options how to deal with `\\n` inside the text value. Default: replace with `<br/>`

    Returns:
        The original resource, with the added comments

    Examples:
        ```python
        link_resource = link_resource.add_comment_multiple(["comment 1", "comment 2"])
        ```
    """
    vals = check_and_fix_collection_input(texts, "hasComment", self.res_id)
    for v in vals:
        self.add_comment(v, permissions, comment, newline_replacement)
    return self

add_comment_optional

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

Parameters:

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

Returns:

Type	Description
LinkResource	The original resource, with the added comment

Examples:

link_resource = link_resource.add_comment_optional("comment text")

link_resource = link_resource.add_comment_optional(None)

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

def add_comment_optional(
    self,
    text: Any,
    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS,
    comment: str | None = None,
    newline_replacement: NewlineReplacement = NewlineReplacement.LINEBREAK,
) -> LinkResource:
    """
    If the value is not empty, add it as comment, otherwise return the resource unchanged.

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

    Returns:
        The original resource, with the added comment

    Examples:
        ```python
        link_resource = link_resource.add_comment_optional("comment text")
        ```

        ```python
        link_resource = link_resource.add_comment_optional(None)
        ```
    """
    if is_nonempty_value(text):
        return self.add_comment(text, permissions, comment, newline_replacement)
    return self