From fb5f5a948c7786ad4e3912cf1f87464e07493218 Mon Sep 17 00:00:00 2001
From: Nora-Olivia-Ammann
<103038637+Nora-Olivia-Ammann@users.noreply.github.com>
Date: Thu, 7 Nov 2024 14:06:47 +0100
Subject: [PATCH] docs(xmllib): make args consistent (DEV-4314) (#1259)
---
docs/xmllib-api-reference/value-converters.md | 1 +
mkdocs.yml | 1 +
src/dsp_tools/xmllib/__init__.py | 4 ++
src/dsp_tools/xmllib/models/config_options.py | 6 +-
.../xmllib/models/dsp_base_resources.py | 56 +++++++++----------
src/dsp_tools/xmllib/models/resource.py | 38 ++++++-------
src/dsp_tools/xmllib/models/root.py | 8 +--
src/dsp_tools/xmllib/value_checkers.py | 6 +-
src/dsp_tools/xmllib/value_converters.py | 12 +++-
9 files changed, 72 insertions(+), 60 deletions(-)
create mode 100644 docs/xmllib-api-reference/value-converters.md
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", "
")