diff --git a/docs/xmllib-api-reference/value-converters.md b/docs/xmllib-api-reference/value-converters.md new file mode 100644 index 0000000000..324a0ccd72 --- /dev/null +++ b/docs/xmllib-api-reference/value-converters.md @@ -0,0 +1 @@ +::: xmllib.value_converters diff --git a/mkdocs.yml b/mkdocs.yml index 6c5129b543..9b64b6cbbf 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -46,6 +46,7 @@ nav: - AudioSegmentResource: xmllib-api-reference/dsp-base-resources/audio-segment-resource.md - Configuration options: xmllib-api-reference/config-options.md - Value Checkers: xmllib-api-reference/value-checkers.md + - Value Converters: xmllib-api-reference/value-converters.md - Helpers: xmllib-api-reference/helpers.md theme: diff --git a/src/dsp_tools/xmllib/__init__.py b/src/dsp_tools/xmllib/__init__.py index f8927d3967..cf8d4c3bc4 100644 --- a/src/dsp_tools/xmllib/__init__.py +++ b/src/dsp_tools/xmllib/__init__.py @@ -20,3 +20,7 @@ from .value_checkers import is_nonempty_value as is_nonempty_value from .value_checkers import is_string_like as is_string_like from .value_checkers import is_timestamp as is_timestamp +from .value_converters import convert_to_bool_string +from .value_converters import replace_newlines_with_br_tags +from .value_converters import replace_newlines_with_paragraph_tags +from .value_converters import replace_newlines_with_tags diff --git a/src/dsp_tools/xmllib/models/config_options.py b/src/dsp_tools/xmllib/models/config_options.py index c5d67af5c3..8486870e2a 100644 --- a/src/dsp_tools/xmllib/models/config_options.py +++ b/src/dsp_tools/xmllib/models/config_options.py @@ -23,9 +23,9 @@ class NewlineReplacement(Enum): """ Options how to deal with `\\n` inside rich text values. - - `NONE`: Don't modify the rich text (`\\n` will be lost, because it is meaningless in an XML file) - - `PARAGRAPH`: Replace `Start\\nEnd` with `

Start

End

` - - `LINEBREAK`: Replace `Start\\nEnd` with `Start
End` + - `NONE`: don't modify the rich text (`\\n` will be lost, because it is meaningless in an XML file) + - `PARAGRAPH`: replace `Start\\nEnd` with `

Start

End

` + - `LINEBREAK`: replace `Start\\nEnd` with `Start
End` """ NONE = auto() diff --git a/src/dsp_tools/xmllib/models/dsp_base_resources.py b/src/dsp_tools/xmllib/models/dsp_base_resources.py index 295585aa96..f3071279c1 100644 --- a/src/dsp_tools/xmllib/models/dsp_base_resources.py +++ b/src/dsp_tools/xmllib/models/dsp_base_resources.py @@ -104,7 +104,7 @@ def add_comment_optional(self, comment: Any) -> AnnotationResource: If the value is not empty, add it as comment, otherwise return the resource unchanged. Args: - comment: Comment or empty value + comment: text or empty value Returns: The original resource, with the added comment @@ -120,7 +120,7 @@ def add_migration_metadata( Add metadata from a SALSAH migration. Args: - creation_date: Creation date of the resource in SALSAH + creation_date: creation date of the resource in SALSAH iri: Original IRI in SALSAH ark: Original ARK in SALSAH @@ -224,7 +224,7 @@ def add_comment(self, comment: str) -> RegionResource: Add a comment to the resource Args: - comment: Comment text + comment: text Returns: The original resource, with the added comment @@ -237,7 +237,7 @@ def add_comment_multiple(self, comments: list[str]) -> RegionResource: Add several comments to the resource Args: - comments: List of comment texts + comments: list of texts Returns: The original resource, with the added comments @@ -250,7 +250,7 @@ def add_comment_optional(self, comment: Any) -> RegionResource: If the value is not empty, add it as comment, otherwise return the resource unchanged. Args: - comment: Comment or empty value + comment: text or empty value Returns: The original resource, with the added comment @@ -266,7 +266,7 @@ def add_migration_metadata( Add metadata from a SALSAH migration. Args: - creation_date: Creation date of the resource in SALSAH + creation_date: creation date of the resource in SALSAH iri: Original IRI in SALSAH ark: Original ARK in SALSAH @@ -359,7 +359,7 @@ def add_comment(self, comment: str) -> LinkResource: Add a comment to the resource Args: - comment: Comment text + comment: text Returns: The original resource, with the added comment @@ -372,7 +372,7 @@ def add_comment_multiple(self, comments: list[str]) -> LinkResource: Add several comments to the resource Args: - comments: List of comment texts + comments: list of texts Returns: The original resource, with the added comments @@ -385,7 +385,7 @@ def add_comment_optional(self, comment: Any) -> LinkResource: If the value is not empty, add it as comment, otherwise return the resource unchanged. Args: - comment: Comment or empty value + comment: text or empty value Returns: The original resource, with the added comment @@ -401,7 +401,7 @@ def add_migration_metadata( Add metadata from a SALSAH migration. Args: - creation_date: Creation date of the resource in SALSAH + creation_date: creation date of the resource in SALSAH iri: Original IRI in SALSAH ark: Original ARK in SALSAH @@ -518,7 +518,7 @@ def add_title(self, title: str) -> VideoSegmentResource: Add a title to the resource. Args: - title: Title text + title: text Returns: The original resource, with the added title @@ -533,7 +533,7 @@ def add_title_optional(self, title: Any) -> VideoSegmentResource: If the value is not empty, add it as title, otherwise return the resource unchanged. Args: - title: Title or empty value + title: text or empty value Returns: The original resource, with the added title @@ -549,7 +549,7 @@ def add_comment(self, comment: str) -> VideoSegmentResource: Add a comment to the resource Args: - comment: Comment text + comment: text Returns: The original resource, with the added comment @@ -562,7 +562,7 @@ def add_comment_multiple(self, comments: list[str]) -> VideoSegmentResource: Add several comments to the resource Args: - comments: List of comment texts + comments: list of texts Returns: The original resource, with the added comments @@ -575,7 +575,7 @@ def add_comment_optional(self, comment: Any) -> VideoSegmentResource: If the value is not empty, add it as comment, otherwise return the resource unchanged. Args: - comment: Comment or empty value + comment: text or empty value Returns: The original resource, with the added comment @@ -602,7 +602,7 @@ def add_description_multiple(self, descriptions: list[str]) -> VideoSegmentResou Add several descriptions to the resource Args: - descriptions: list of text + descriptions: list of texts Returns: The original resource, with the added descriptions @@ -642,7 +642,7 @@ def add_keyword_multiple(self, keywords: list[str]) -> VideoSegmentResource: Add several keywords to the resource Args: - keywords: list of text + keywords: list of texts Returns: The original resource, with the added keywords @@ -682,7 +682,7 @@ def add_relates_to_multiple(self, relates_to: list[str]) -> VideoSegmentResource Add several links to related resources Args: - relates_to: IDs of the related resources + relates_to: list of IDs of the related resources Returns: The original resource, with the added related resources @@ -711,7 +711,7 @@ def add_migration_metadata( Add metadata from a SALSAH migration. Args: - creation_date: Creation date of the resource in SALSAH + creation_date: creation date of the resource in SALSAH iri: Original IRI in SALSAH ark: Original ARK in SALSAH @@ -801,7 +801,7 @@ def add_title(self, title: str) -> AudioSegmentResource: Add a title to the resource. Args: - title: Title text + title: text Returns: The original resource, with the added title @@ -816,7 +816,7 @@ def add_title_optional(self, title: Any) -> AudioSegmentResource: If the value is not empty, add it as title, otherwise return the resource unchanged. Args: - title: Title text or empty value + title: text or empty value Returns: The original resource, with the added title @@ -832,7 +832,7 @@ def add_comment(self, comment: str) -> AudioSegmentResource: Add a comment to the resource Args: - comment: Comment text + comment: text Returns: The original resource, with the added comment @@ -845,7 +845,7 @@ def add_comment_multiple(self, comments: list[str]) -> AudioSegmentResource: Add several comments to the resource Args: - comments: List of comment texts + comments: list of texts Returns: The original resource, with the added comments @@ -858,7 +858,7 @@ def add_comment_optional(self, comment: Any) -> AudioSegmentResource: If the value is not empty, add it as comment, otherwise return the resource unchanged. Args: - comment: Comment or empty value + comment: text or empty value Returns: The original resource, with the added comment @@ -885,7 +885,7 @@ def add_description_multiple(self, descriptions: list[str]) -> AudioSegmentResou Add several descriptions to the resource Args: - descriptions: list of text + descriptions: list of texts Returns: The original resource, with the added descriptions @@ -925,7 +925,7 @@ def add_keyword_multiple(self, keywords: list[str]) -> AudioSegmentResource: Add several keywords to the resource Args: - keywords: list of text + keywords: list of texts Returns: The original resource, with the added keywords @@ -965,7 +965,7 @@ def add_relates_to_multiple(self, relates_to: list[str]) -> AudioSegmentResource Add several links to related resources Args: - relates_to: IDs of the related resources + relates_to: list of IDs of the related resources Returns: The original resource, with the added related resources @@ -994,7 +994,7 @@ def add_migration_metadata( Add metadata from a SALSAH migration. Args: - creation_date: Creation date of the resource in SALSAH + creation_date: creation date of the resource in SALSAH iri: Original IRI in SALSAH ark: Original ARK in SALSAH diff --git a/src/dsp_tools/xmllib/models/resource.py b/src/dsp_tools/xmllib/models/resource.py index 02783a7ab0..96c5b3aa00 100644 --- a/src/dsp_tools/xmllib/models/resource.py +++ b/src/dsp_tools/xmllib/models/resource.py @@ -77,9 +77,9 @@ def create_new( Create a new resource. Args: - res_id: Resource ID - restype: Resource type - label: Resource label + res_id: resource ID + restype: resource type + label: resource label permissions: optional permissions of this resource Returns: @@ -174,7 +174,7 @@ def add_bool_optional( comment: optional comment Returns: - The original resource, with the added value + 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)) @@ -251,7 +251,7 @@ def add_color_optional( comment: optional comment Returns: - The original resource, with the added value + 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)) @@ -327,7 +327,7 @@ def add_date_optional( comment: optional comment Returns: - The original resource, with the added value + 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)) @@ -407,7 +407,7 @@ def add_decimal_optional( comment: optional comment Returns: - The original resource, with the added value + 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)) @@ -491,7 +491,7 @@ def add_geoname_optional( comment: optional comment Returns: - The original resource, with the added value + 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)) @@ -571,7 +571,7 @@ def add_integer_optional( comment: optional comment Returns: - The original resource, with the added value + 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)) @@ -649,7 +649,7 @@ def add_link_optional( comment: optional comment Returns: - The original resource, with the added value + 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)) @@ -732,7 +732,7 @@ def add_list_optional( comment: optional comment Returns: - The original resource, with the added value + 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)) @@ -809,7 +809,7 @@ def add_simpletext_optional( comment: optional comment Returns: - The original resource, with the added value + 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)) @@ -844,7 +844,7 @@ def add_richtext( 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 `
`. + newline_replacement: options how to deal with `\\n` inside the text value. Default: replace with `
` Returns: The original resource, with the added value @@ -878,7 +878,7 @@ def add_richtext_multiple( 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 `
`. + newline_replacement: options how to deal with `\\n` inside the text value. Default: replace with `
` Returns: The original resource, with the added values @@ -912,10 +912,10 @@ def add_richtext_optional( 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 `
`. + newline_replacement: options how to deal with `\\n` inside the text value. Default: replace with `
` Returns: - The original resource, with the added value + 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) @@ -993,7 +993,7 @@ def add_time_optional( comment: optional comment Returns: - The original resource, with the added value + 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)) @@ -1070,7 +1070,7 @@ def add_uri_optional( comment: optional comment Returns: - The original resource, with the added value + 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)) @@ -1155,7 +1155,7 @@ def add_migration_metadata( [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 + creation_date: creation date of the resource in SALSAH iri: Original IRI in SALSAH ark: Original ARK in SALSAH diff --git a/src/dsp_tools/xmllib/models/root.py b/src/dsp_tools/xmllib/models/root.py index 03249a2b21..2d919cc6bc 100644 --- a/src/dsp_tools/xmllib/models/root.py +++ b/src/dsp_tools/xmllib/models/root.py @@ -55,7 +55,7 @@ def add_resource(self, resource: AnyResource) -> XMLRoot: Add one resource to the root. Args: - resource: Any one of: + resource: any one of: `Resource`, `AnnotationResource`, `RegionResource`, @@ -74,7 +74,7 @@ def add_resource_multiple(self, resources: list[AnyResource]) -> XMLRoot: Add a list of resources to the root. Args: - resources: A list of: + resources: a list of: `Resource`, `AnnotationResource`, `RegionResource`, @@ -94,7 +94,7 @@ def add_resource_optional(self, resource: AnyResource | None) -> XMLRoot: If the resource is not None, add it to the XMLRoot, otherwise return the XMLRoot unchanged. Args: - resource: Any one of: + resource: any one of: `Resource`, `AnnotationResource`, `RegionResource`, @@ -103,7 +103,7 @@ def add_resource_optional(self, resource: AnyResource | None) -> XMLRoot: `AudioSegmentResource` Returns: - The original XMLRoot, with the added resource + The original XMLRoot, with the added value if it was not empty. Else the unchanged original XMLRoot. """ if resource: self.resources.append(resource) diff --git a/src/dsp_tools/xmllib/value_checkers.py b/src/dsp_tools/xmllib/value_checkers.py index eff25f2ffb..64496227bb 100644 --- a/src/dsp_tools/xmllib/value_checkers.py +++ b/src/dsp_tools/xmllib/value_checkers.py @@ -7,13 +7,13 @@ def is_nonempty_value(value: Any) -> bool: """ - Check if a value is non-empty. + Check if a value is not empty. Args: value: value to check Returns: - True if it is non-empty + True if it is not empty """ if isinstance(value, str) and len(value) == 0: return False @@ -175,7 +175,7 @@ def find_geometry_problem(value: Any) -> str: value: geometry object Returns: - string with the validation message if it fails + String with the validation message if it fails, else an empty string. """ msg = "" try: diff --git a/src/dsp_tools/xmllib/value_converters.py b/src/dsp_tools/xmllib/value_converters.py index 54714fbc29..51b4bad4b5 100644 --- a/src/dsp_tools/xmllib/value_converters.py +++ b/src/dsp_tools/xmllib/value_converters.py @@ -37,7 +37,7 @@ def replace_newlines_with_tags(text: str, converter_option: NewlineReplacement) converter_option: tag options Returns: - string with replaced values + String with replaced values Raises: InputError: If an invalid conversion option is given @@ -55,11 +55,14 @@ def replace_newlines_with_paragraph_tags(text: str) -> str: """ Replace `Start\\nEnd` with `

Start

End

` + Multiple consecutive newlines will be treated as one newline: + `Start\\nMiddle\\n\\nEnd` becomes `

Start

Middle

End

` + Args: text: string to be formatted Returns: - formatted string with tags + Formatted string with paragraph tags """ splt = [x for x in text.split("\n") if x != ""] formatted = [f"

{x}

" for x in splt] @@ -70,10 +73,13 @@ def replace_newlines_with_br_tags(text: str) -> str: """ Replaces `Start\\nEnd` with `Start
End` + Multiple consecutive newlines will be converted into multiple break-lines: + `Start\\n\\nEnd` with `Start

End` + Args: text: string to be formatted Returns: - formatted string with tags + Formatted string with break-line tags """ return text.replace("\n", "
")