dsp-tools 9.1.0.post11__py3-none-any.whl → 18.3.0.post13__py3-none-any.whl

dsp_tools/xmllib/models/internal/values.py

@@ -0,0 +1,342 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+from typing import Protocol
+
+from dsp_tools.error.xmllib_errors import XmllibInputError
+from dsp_tools.error.xmllib_warnings import MessageInfo
+from dsp_tools.error.xmllib_warnings_util import emit_xmllib_input_type_mismatch_warning
+from dsp_tools.error.xmllib_warnings_util import raise_xmllib_input_error
+from dsp_tools.utils.data_formats.uri_util import is_uri
+from dsp_tools.xmllib.internal.checkers import check_and_inform_about_angular_brackets
+from dsp_tools.xmllib.internal.circumvent_circular_imports import parse_richtext_as_xml
+from dsp_tools.xmllib.internal.input_converters import check_and_fix_is_non_empty_string
+from dsp_tools.xmllib.internal.input_converters import check_and_get_corrected_comment
+from dsp_tools.xmllib.models.config_options import NewlineReplacement
+from dsp_tools.xmllib.models.permissions import Permissions
+from dsp_tools.xmllib.value_checkers import is_color
+from dsp_tools.xmllib.value_checkers import is_date
+from dsp_tools.xmllib.value_checkers import is_decimal
+from dsp_tools.xmllib.value_checkers import is_geoname
+from dsp_tools.xmllib.value_checkers import is_integer
+from dsp_tools.xmllib.value_checkers import is_link_value
+from dsp_tools.xmllib.value_checkers import is_nonempty_value
+from dsp_tools.xmllib.value_checkers import is_timestamp
+from dsp_tools.xmllib.value_converters import convert_to_bool_string
+from dsp_tools.xmllib.value_converters import replace_newlines_with_tags
+
+
+class Value(Protocol):
+    value: str
+    prop_name: str
+    permissions: Permissions
+    comment: str | None
+
+
+@dataclass
+class BooleanValue(Value):
+    value: str
+    prop_name: str
+    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS
+    comment: str | None = None
+
+    @classmethod
+    def new(
+        cls,
+        value: Any,
+        prop_name: str,
+        permissions: Permissions,
+        comment: str | None,
+        resource_id: str | None,
+    ) -> BooleanValue:
+        try:
+            val = str(convert_to_bool_string(value)).lower()
+        except XmllibInputError:
+            emit_xmllib_input_type_mismatch_warning(
+                expected_type="bool", value=value, res_id=resource_id, prop_name=prop_name
+            )
+            val = str(value)
+        fixed_comment = check_and_get_corrected_comment(comment, resource_id, prop_name)
+        return cls(value=val, prop_name=prop_name, permissions=permissions, comment=fixed_comment)
+
+
+@dataclass
+class ColorValue(Value):
+    value: str
+    prop_name: str
+    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS
+    comment: str | None = None
+
+    @classmethod
+    def new(
+        cls,
+        value: Any,
+        prop_name: str,
+        permissions: Permissions,
+        comment: str | None,
+        resource_id: str | None,
+    ) -> ColorValue:
+        if not is_color(value):
+            emit_xmllib_input_type_mismatch_warning(
+                expected_type="color", value=value, res_id=resource_id, prop_name=prop_name
+            )
+        fixed_comment = check_and_get_corrected_comment(comment, resource_id, prop_name)
+        return cls(value=str(value), prop_name=prop_name, permissions=permissions, comment=fixed_comment)
+
+
+@dataclass
+class DateValue(Value):
+    value: str
+    prop_name: str
+    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS
+    comment: str | None = None
+
+    @classmethod
+    def new(
+        cls,
+        value: Any,
+        prop_name: str,
+        permissions: Permissions,
+        comment: str | None,
+        resource_id: str | None,
+    ) -> DateValue:
+        if not is_date(value):
+            emit_xmllib_input_type_mismatch_warning(
+                expected_type="date", value=value, res_id=resource_id, prop_name=prop_name
+            )
+        fixed_comment = check_and_get_corrected_comment(comment, resource_id, prop_name)
+        return cls(value=str(value), prop_name=prop_name, permissions=permissions, comment=fixed_comment)
+
+
+@dataclass
+class DecimalValue(Value):
+    value: str
+    prop_name: str
+    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS
+    comment: str | None = None
+
+    @classmethod
+    def new(
+        cls,
+        value: Any,
+        prop_name: str,
+        permissions: Permissions,
+        comment: str | None,
+        resource_id: str | None,
+    ) -> DecimalValue:
+        if not is_decimal(value):
+            emit_xmllib_input_type_mismatch_warning(
+                expected_type="decimal", value=value, res_id=resource_id, prop_name=prop_name
+            )
+        fixed_comment = check_and_get_corrected_comment(comment, resource_id, prop_name)
+        return cls(value=str(value), prop_name=prop_name, permissions=permissions, comment=fixed_comment)
+
+
+@dataclass
+class GeonameValue(Value):
+    value: str
+    prop_name: str
+    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS
+    comment: str | None = None
+
+    @classmethod
+    def new(
+        cls,
+        value: Any,
+        prop_name: str,
+        permissions: Permissions,
+        comment: str | None,
+        resource_id: str | None,
+    ) -> GeonameValue:
+        if not is_geoname(value):
+            emit_xmllib_input_type_mismatch_warning(
+                expected_type="geoname", value=value, res_id=resource_id, prop_name=prop_name
+            )
+        fixed_comment = check_and_get_corrected_comment(comment, resource_id, prop_name)
+        return cls(value=str(value), prop_name=prop_name, permissions=permissions, comment=fixed_comment)
+
+
+@dataclass
+class IntValue(Value):
+    value: str
+    prop_name: str
+    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS
+    comment: str | None = None
+
+    @classmethod
+    def new(
+        cls,
+        value: Any,
+        prop_name: str,
+        permissions: Permissions,
+        comment: str | None,
+        resource_id: str | None,
+    ) -> IntValue:
+        if not is_integer(value):
+            emit_xmllib_input_type_mismatch_warning(
+                expected_type="integer", value=value, res_id=resource_id, prop_name=prop_name
+            )
+        fixed_comment = check_and_get_corrected_comment(comment, resource_id, prop_name)
+        return cls(value=str(value), prop_name=prop_name, permissions=permissions, comment=fixed_comment)
+
+
+@dataclass
+class LinkValue(Value):
+    value: str
+    prop_name: str
+    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS
+    comment: str | None = None
+
+    @classmethod
+    def new(
+        cls,
+        value: Any,
+        prop_name: str,
+        permissions: Permissions,
+        comment: str | None,
+        resource_id: str | None,
+    ) -> LinkValue:
+        if not is_link_value(value):
+            emit_xmllib_input_type_mismatch_warning(
+                expected_type="xsd:ID or DSP resource IRI", value=value, res_id=resource_id, prop_name=prop_name
+            )
+        fixed_comment = check_and_get_corrected_comment(comment, resource_id, prop_name)
+        return cls(value=str(value), prop_name=prop_name, permissions=permissions, comment=fixed_comment)
+
+
+@dataclass
+class ListValue(Value):
+    value: str
+    list_name: str
+    prop_name: str
+    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS
+    comment: str | None = None
+
+    @classmethod
+    def new(
+        cls,
+        value: Any,
+        list_name: Any,
+        prop_name: str,
+        permissions: Permissions,
+        comment: str | None,
+        resource_id: str | None,
+    ) -> ListValue:
+        if str(value).startswith("http://rdfh.ch/lists/"):
+            list_str = ""
+        else:
+            list_str = str(list_name)
+            if not is_nonempty_value(list_name):
+                emit_xmllib_input_type_mismatch_warning(
+                    expected_type="list name", value=list_name, res_id=resource_id, prop_name=prop_name
+                )
+            if not is_nonempty_value(value):
+                emit_xmllib_input_type_mismatch_warning(
+                    expected_type="list node", value=value, res_id=resource_id, prop_name=prop_name
+                )
+        fixed_comment = check_and_get_corrected_comment(comment, resource_id, prop_name)
+        return cls(
+            value=str(value),
+            list_name=str(list_str),
+            prop_name=prop_name,
+            permissions=permissions,
+            comment=fixed_comment,
+        )
+
+
+@dataclass
+class SimpleText(Value):
+    value: str
+    prop_name: str
+    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS
+    comment: str | None = None
+
+    @classmethod
+    def new(
+        cls,
+        value: Any,
+        prop_name: str,
+        permissions: Permissions,
+        comment: str | None,
+        resource_id: str | None,
+    ) -> SimpleText:
+        converted_val = check_and_fix_is_non_empty_string(value=value, res_id=resource_id, prop_name=prop_name)
+        check_and_inform_about_angular_brackets(value=value, res_id=resource_id, prop_name=prop_name)
+        fixed_comment = check_and_get_corrected_comment(comment, resource_id, prop_name)
+        return cls(value=converted_val, prop_name=prop_name, permissions=permissions, comment=fixed_comment)
+
+
+@dataclass
+class Richtext(Value):
+    value: str
+    prop_name: str
+    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS
+    comment: str | None = None
+
+    @classmethod
+    def new(
+        cls,
+        value: Any,
+        prop_name: str,
+        permissions: Permissions,
+        comment: str | None,
+        resource_id: str | None,
+        newline_replacement: NewlineReplacement = NewlineReplacement.NONE,
+    ) -> Richtext:
+        converted_val = check_and_fix_is_non_empty_string(value=value, res_id=resource_id, prop_name=prop_name)
+        converted_val = replace_newlines_with_tags(converted_val, newline_replacement)
+        result = parse_richtext_as_xml(converted_val)
+        if isinstance(result, MessageInfo):
+            raise_xmllib_input_error(result)
+        fixed_comment = check_and_get_corrected_comment(comment, resource_id, prop_name)
+        return cls(value=converted_val, prop_name=prop_name, permissions=permissions, comment=fixed_comment)
+
+
+@dataclass
+class TimeValue(Value):
+    value: str
+    prop_name: str
+    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS
+    comment: str | None = None
+
+    @classmethod
+    def new(
+        cls,
+        value: Any,
+        prop_name: str,
+        permissions: Permissions,
+        comment: str | None,
+        resource_id: str | None,
+    ) -> TimeValue:
+        if not is_timestamp(value):
+            emit_xmllib_input_type_mismatch_warning(
+                expected_type="timestamp", value=value, res_id=resource_id, prop_name=prop_name
+            )
+        fixed_comment = check_and_get_corrected_comment(comment, resource_id, prop_name)
+        return cls(value=str(value), prop_name=prop_name, permissions=permissions, comment=fixed_comment)
+
+
+@dataclass
+class UriValue(Value):
+    value: str
+    prop_name: str
+    permissions: Permissions = Permissions.PROJECT_SPECIFIC_PERMISSIONS
+    comment: str | None = None
+
+    @classmethod
+    def new(
+        cls,
+        value: Any,
+        prop_name: str,
+        permissions: Permissions,
+        comment: str | None,
+        resource_id: str | None,
+    ) -> UriValue:
+        v = str(value)
+        if not is_uri(v):
+            emit_xmllib_input_type_mismatch_warning(
+                expected_type="uri", value=value, res_id=resource_id, prop_name=prop_name
+            )
+        fixed_comment = check_and_get_corrected_comment(comment, resource_id, prop_name)
+        return cls(value=v, prop_name=prop_name, permissions=permissions, comment=fixed_comment)

dsp_tools/xmllib/models/licenses/other.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from dsp_tools.xmllib.models.licenses.recommended import License
+
+
+class LicenseOther:
+    """
+    Pre-defined licenses that are available in DSP.
+    If the user is free to choose a license, we recommend to choose from our [recommended licenses](https://docs.dasch.swiss/latest/DSP-TOOLS/xmllib-docs/licenses/recommended/).
+
+    - `Public`: [See `Public` for details](https://docs.dasch.swiss/latest/DSP-TOOLS/xmllib-docs/licenses/other/#xmllib.models.licenses.other.Public).
+    - `Various`: [See `Various` for details](https://docs.dasch.swiss/latest/DSP-TOOLS/xmllib-docs/licenses/other/#xmllib.models.licenses.other.Various).
+
+    Examples:
+        ```python
+        # adding a BORIS Standard License to a file
+        resource = resource.add_file(
+            filename="images/cat.jpg",
+            license=xmllib.LicenseOther.Various.BORIS_STANDARD,
+            copyright_holder="Meow University",
+            authorship=["Kitty Meow"],
+        )
+        ```
+    """
+
+    Public: type[Public]
+    Various: type[Various]
+
+
+class Public(License):
+    """
+    Pre-defined public domain licenses.
+    [See the API documentation for details about the licenses.](https://docs.dasch.swiss/latest/DSP-API/01-introduction/legal-info/#license)
+
+    - `CC_0_1_0`: CC0 1.0 Universal
+    - `CC_PDM_1_0`: Public Domain Mark 1.0 Universal
+    """
+
+    CC_0_1_0 = "http://rdfh.ch/licenses/cc-0-1.0"
+    CC_PDM_1_0 = "http://rdfh.ch/licenses/cc-pdm-1.0"
+
+
+class Various(License):
+    """
+    A collection of various, pre-defined licenses.
+    [See the API documentation for details about the licenses.](https://docs.dasch.swiss/latest/DSP-API/01-introduction/legal-info/#license)
+
+    - `BORIS_STANDARD`: BORIS Standard License
+    - `FRANCE_OUVERTE`: LICENCE OUVERTE 2.0
+    - `RIGHTSSTATEMENTS_NOC_NC`: Rightsstatements: No Copyright - Non-Commercial Use Only
+    """
+
+    BORIS_STANDARD = "http://rdfh.ch/licenses/boris"
+    FRANCE_OUVERTE = "http://rdfh.ch/licenses/open-licence-2.0"
+    RIGHTSSTATEMENTS_NOC_NC = "http://rdfh.ch/licenses/noc-nc-1.0"
+
+
+LicenseOther.Public = Public
+LicenseOther.Various = Various

dsp_tools/xmllib/models/licenses/recommended.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class License(StrEnum): ...
+
+
+class LicenseRecommended:
+    """
+    Recommended licenses:
+
+    - `DSP`: Licenses created and curated by DaSCH, [see `DSP` for details.](https://docs.dasch.swiss/latest/DSP-TOOLS/xmllib-docs/licenses/recommended/#xmllib.models.licenses.recommended.DSP)
+    - `CC`: Creative Commons licenses, [see `CC` for details.](https://docs.dasch.swiss/latest/DSP-TOOLS/xmllib-docs/licenses/recommended/#xmllib.models.licenses.recommended.CC)
+
+    Tip:
+        Use the helper function [`find_license_in_string()`](https://docs.dasch.swiss/latest/DSP-TOOLS/xmllib-docs/general-functions/#xmllib.general_functions.find_license_in_string)
+        to parse a license from a string.
+
+    Examples:
+        ```python
+        # adding a Creative Commons license to a file
+        resource = resource.add_file(
+            filename="images/cat.jpg",
+            license=xmllib.LicenseRecommended.CC.BY,
+            copyright_holder="Meow University",
+            authorship=["Kitty Meow"],
+        )
+        ```
+
+        ```python
+        # adding a DSP license to a file
+        resource = resource.add_file(
+            filename="images/dog.jpg",
+            license=xmllib.LicenseRecommended.DSP.PUBLIC_DOMAIN,
+            copyright_holder="Bark University",
+            authorship=["Bark McDog"],
+        )
+        ```
+    """
+
+    CC: type[CC]
+    DSP: type[DSP]
+
+
+class CC(License):
+    """
+    Pre-defined and recommended [Creative Commons licenses:](https://creativecommons.org/share-your-work/)
+
+    - `BY`: [Attribution 4.0](https://creativecommons.org/licenses/by/4.0/)
+    - `BY_SA`: [Attribution-ShareAlike 4.0](https://creativecommons.org/licenses/by-sa/4.0/)
+    - `BY_NC`: [Attribution-NonCommercial 4.0](https://creativecommons.org/licenses/by-nc/4.0/)
+    - `BY_NC_SA`: [Attribution-NonCommercial-ShareAlike 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/)
+    - `BY_ND`: [Attribution-NoDerivatives 4.0](https://creativecommons.org/licenses/by-nd/4.0/)
+    - `BY_NC_ND`: [Attribution-NonCommercial-NoDerivatives 4.0](https://creativecommons.org/licenses/by-nc-nd/4.0/)
+
+    Tip:
+        Use the helper function [find_license_in_string()](https://docs.dasch.swiss/latest/DSP-TOOLS/xmllib-docs/general-functions/#xmllib.general_functions.find_license_in_string)
+        to parse a license from a string.
+
+    Examples:
+        ```python
+        # adding a Creative Commons license to a file
+        resource = resource.add_file(
+            filename="images/dog.jpg",
+            license=xmllib.LicenseRecommended.CC.BY_NC_ND,
+            copyright_holder="Bark University",
+            authorship=["Bark McDog"],
+        )
+        ```
+    """
+
+    BY = "http://rdfh.ch/licenses/cc-by-4.0"
+    BY_SA = "http://rdfh.ch/licenses/cc-by-sa-4.0"
+    BY_NC = "http://rdfh.ch/licenses/cc-by-nc-4.0"
+    BY_NC_SA = "http://rdfh.ch/licenses/cc-by-nc-sa-4.0"
+    BY_ND = "http://rdfh.ch/licenses/cc-by-nd-4.0"
+    BY_NC_ND = "http://rdfh.ch/licenses/cc-by-nc-nd-4.0"
+
+
+class DSP(License):
+    """
+    Pre-defined and recommended licenses created and curated by DaSCH:
+
+    - `AI_GENERATED`: AI-Generated Content - Not Protected by Copyright
+    - `UNKNOWN`: Unknown License - Ask Copyright Holder for Permission
+    - `PUBLIC_DOMAIN`: Public Domain - Not Protected by Copyright
+
+    Examples:
+        ```python
+        # adding a DSP license to a file
+        resource = resource.add_file(
+            filename="images/cat.jpg",
+            license=xmllib.LicenseRecommended.DSP.PUBLIC_DOMAIN,
+            copyright_holder="Meow University",
+            authorship=["Kitty Meow"],
+        )
+        ```
+    """
+
+    AI_GENERATED = "http://rdfh.ch/licenses/ai-generated"
+    UNKNOWN = "http://rdfh.ch/licenses/unknown"
+    PUBLIC_DOMAIN = "http://rdfh.ch/licenses/public-domain"
+
+
+LicenseRecommended.CC = CC
+LicenseRecommended.DSP = DSP

dsp_tools/xmllib/models/permissions.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from enum import Enum
+
+
+class Permissions(Enum):
+    """
+    Options of permissions for resources and values:
+
+    - `PROJECT_SPECIFIC_PERMISSIONS`: the permissions defined on project level will be applied
+    - `PUBLIC`: the resource/value is visible for everyone
+    - `PRIVATE`: the resource/value is only visible for project members
+    - `LIMITED_VIEW`: the resource/value is visible for everyone,
+      but images are blurred/watermarked for non-project members
+
+    Deprecated terms:
+
+    - `OPEN`: use `PUBLIC` instead
+    - `RESTRICTED`: use `PRIVATE` instead
+    - `RESTRICTED_VIEW`: use `LIMITED_VIEW` instead
+
+    Examples:
+        ```python
+        resource = xmllib.Resource.create_new(
+            res_id="ID",
+            restype=":ResourceType",
+            label="label",
+            permissions=xmllib.Permissions.PRIVATE,
+        )
+        ```
+    """
+
+    PROJECT_SPECIFIC_PERMISSIONS = ""
+    PUBLIC = "public"
+    PRIVATE = "private"
+    LIMITED_VIEW = "limited_view"
+
+    # Deprecated terminology
+    OPEN = "open"
+    RESTRICTED = "restricted"
+    RESTRICTED_VIEW = "restricted-view"