Value Converters

`convert_to_bool_string`

Turns a value into a bool string, suitable for an XML. It is case-insensitive, meaning that the words can also be capitalised.

Accepted values

false, 0, 0.0, no, non, nein -> False
true, 1, 1.0, yes, oui, ja, sì -> True

Parameters:

Name	Type	Description	Default
`value`	`Any`	value to transform	required

Returns:

Type	Description
`bool`	`True` or `False` if it is an accepted value.

Examples:

result = xmllib.convert_to_bool_string(1)
# result == True

result = xmllib.convert_to_bool_string("nein")
# result == False

result = xmllib.convert_to_bool_string(None)
# raises XmllibInputError

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

def convert_to_bool_string(value: Any) -> bool:
    """
    Turns a value into a bool string, suitable for an XML.
    It is case-insensitive, meaning that the words can also be capitalised.

    Accepted values:
         - `false`, `0`, `0.0`, `no`, `non`, `nein` -> `False`
         - `true`, `1`, `1.0`, `yes`, `oui`, `ja`, `sì` -> `True`

    Args:
        value: value to transform

    Returns:
        `True` or `False` if it is an accepted value.

    Raises:
        XmllibInputError: If the value is not convertable to a boolean

    Examples:
        ```python
        result = xmllib.convert_to_bool_string(1)
        # result == True
        ```

        ```python
        result = xmllib.convert_to_bool_string("nein")
        # result == False
        ```

        ```python
        result = xmllib.convert_to_bool_string(None)
        # raises XmllibInputError
        ```
    """
    str_val = str(value).lower().strip()
    if str_val in ("false", "0", "0.0", "no", "non", "nein"):
        return False
    elif str_val in ("true", "1", "1.0", "yes", "oui", "ja", "sì"):
        return True
    raise_xmllib_input_error(MessageInfo(f"The entered value '{value}' cannot be converted to a bool."))

`replace_newlines_with_tags`

Converts the newlines in a string to XML tags.

Parameters:

Name	Type	Description	Default
`text`	`str`	string to convert	required
`converter_option`	`NewlineReplacement`	specifies what tag to use instead of the newline	required

Returns:

Type	Description
`str`	String with replaced values

Examples:

result = xmllib.replace_newlines_with_tags(
    "Start\nEnd", xmllib.NewlineReplacement.NONE
)
# result == "Start\nEnd"

result = xmllib.replace_newlines_with_tags(
    "Start\nEnd", xmllib.NewlineReplacement.LINEBREAK
)
# result == "Start<br/>End"

result = xmllib.replace_newlines_with_tags(
    "Start\n\nEnd", xmllib.NewlineReplacement.PARAGRAPH
)
# result == "<p>Start</p><p>End</p>"

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

def replace_newlines_with_tags(text: str, converter_option: NewlineReplacement) -> str:
    """
    Converts the newlines in a string to XML tags.

    Args:
        text: string to convert
        converter_option: specifies what tag to use instead of the newline

    Returns:
        String with replaced values

    Raises:
        XmllibInputError: If an invalid conversion option is given

    Examples:
        ```python
        result = xmllib.replace_newlines_with_tags(
            "Start\\nEnd", xmllib.NewlineReplacement.NONE
        )
        # result == "Start\\nEnd"
        ```

        ```python
        result = xmllib.replace_newlines_with_tags(
            "Start\\nEnd", xmllib.NewlineReplacement.LINEBREAK
        )
        # result == "Start<br/>End"
        ```

        ```python
        result = xmllib.replace_newlines_with_tags(
            "Start\\n\\nEnd", xmllib.NewlineReplacement.PARAGRAPH
        )
        # result == "<p>Start</p><p>End</p>"
        ```
    """
    match converter_option:
        case NewlineReplacement.NONE:
            return text
        case NewlineReplacement.LINEBREAK:
            return replace_newlines_with_br_tags(text)
        case NewlineReplacement.PARAGRAPH:
            return replace_newlines_with_paragraph_tags(text)

`replace_newlines_with_paragraph_tags`

Replace Start\nEnd with StartEnd

Parameters:

Name	Type	Description	Default
`text`	`str`	string to be formatted	required

Returns:

Type	Description
`str`	Formatted string with paragraph tags

Examples:

result = xmllib.replace_newlines_with_paragraph_tags("Start\nEnd")
# result == "<p>Start</p><p>End</p>"

# multiple consecutive newlines will be treated as one newline

result = xmllib.replace_newlines_with_paragraph_tags("Start\n\nEnd")
# result == "<p>Start</p><p>End</p>"

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

def replace_newlines_with_paragraph_tags(text: str) -> str:
    """
    Replace `Start\\nEnd` with `<p>Start</p><p>End</p>`

    Args:
        text: string to be formatted

    Returns:
        Formatted string with paragraph tags

    Examples:
        ```python
        result = xmllib.replace_newlines_with_paragraph_tags("Start\\nEnd")
        # result == "<p>Start</p><p>End</p>"
        ```

        ```python
        # multiple consecutive newlines will be treated as one newline

        result = xmllib.replace_newlines_with_paragraph_tags("Start\\n\\nEnd")
        # result == "<p>Start</p><p>End</p>"
        ```
    """
    splt = [x for x in text.split("\n") if x != ""]
    formatted = [f"<p>{x}</p>" for x in splt]
    return "".join(formatted)

`replace_newlines_with_br_tags`

Replaces \n with  

Parameters:

Name	Type	Description	Default
`text`	`str`	string to be formatted	required

Returns:

Type	Description
`str`	Formatted string with break-line tags

Examples:

result = xmllib.replace_newlines_with_br_tags("Start\nEnd")
# result == "Start<br/>End"

# multiple consecutive newlines will be converted into multiple break-lines

result = xmllib.replace_newlines_with_br_tags("Start\n\nEnd")
# result == "Start<br/><br/>End"

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

def replace_newlines_with_br_tags(text: str) -> str:
    """
    Replaces `\\n` with `<br/>`

    Args:
        text: string to be formatted

    Returns:
        Formatted string with break-line tags

    Examples:
        ```python
        result = xmllib.replace_newlines_with_br_tags("Start\\nEnd")
        # result == "Start<br/>End"
        ```

        ```python
        # multiple consecutive newlines will be converted into multiple break-lines

        result = xmllib.replace_newlines_with_br_tags("Start\\n\\nEnd")
        # result == "Start<br/><br/>End"
        ```
    """
    return text.replace("\n", "<br/>")

`reformat_date`

Reformats a date string into the DSP format.

If the input cannot be reformatted according to the configuration, or if the result is not a valid DSP date, a warning is emitted and the original input is returned.
If the input is empty, a warning is emitted and an empty string is returned.
If the input is already a correctly formatted DSP-date, the original input is returned.

Parameters:

Name	Type	Description	Default
`date`	`str \| int`	date string to be reformatted	required
`date_precision_separator`	`str \| None`	the separation between the day, month and year	required
`date_range_separator`	`str \| None`	the separation between two dates	required
`date_format`	`DateFormat`	the format of the date, see `DateFormat` for options	required
`calendar`	`Calendar`	the calendar of the date, see `Calendar` for options	`GREGORIAN`
`era`	`Era \| None`	the era of the date, see `Era` for options	`CE`
`resource_id`	`str \| None`	the ID of the associated resource, this is to improve the error message	`None`

Returns:

Type	Description
`str`	A reformatted date or the original input if the reformatted result is not a valid DSP date

Examples:

# default configuration, starting with the day
result = xmllib.reformat_date(
    date="1.11.2000",
    date_precision_separator=".",
    date_range_separator=None,
    date_format=xmllib.DateFormat.DD_MM_YYYY
)
# result == "GREGORIAN:CE:2000-11-1:CE:2000-11-1"

# default configuration, but starting with the year
result = xmllib.reformat_date(
    date="2000.11.1",
    date_precision_separator=".",
    date_range_separator=None,
    date_format=xmllib.DateFormat.YYYY_MM_DD,
)
# result == "GREGORIAN:CE:2000-11-1:CE:2000-11-1"

# with a date range
result = xmllib.reformat_date(
    date="1.11.2000-2001",
    date_precision_separator=".",
    date_range_separator="-",
    date_format=xmllib.DateFormat.DD_MM_YYYY,
)
# result == "GREGORIAN:CE:2000-11-1:CE:2001"

# islamic calendar, where eras are not allowed
result = xmllib.reformat_date(
    date="1.11.2000",
    date_precision_separator=".",
    date_range_separator=None,
    date_format=xmllib.DateFormat.DD_MM_YYYY,
    calendar=xmllib.Calendar.ISLAMIC,
    era=None
)
# result == "ISLAMIC:2000-11-1:2000-11-1"

# with a different era
result = xmllib.reformat_date(
    date="1.11.2000",
    date_precision_separator=".",
    date_range_separator="-",
    date_format=xmllib.DateFormat.DD_MM_YYYY,
    era=xmllib.Era.AD
)
# result == "GREGORIAN:AD:2000-11-1:AD:2000-11-1"

# reformatted date, no precision in the date string is required
result = xmllib.reformat_date(
    date="2000",
    date_precision_separator=".",
    date_range_separator="-",
    date_format=xmllib.DateFormat.DD_MM_YYYY,
)
# result == "GREGORIAN:CE:2000:CE:2000"

# already correctly formatted date
result = xmllib.reformat_date(
    date="GREGORIAN:CE:2000:CE:2000",
    date_precision_separator=".",
    date_range_separator="-",
    date_format=xmllib.DateFormat.DD_MM_YYYY,
)
# result == "GREGORIAN:CE:2000:CE:2000"

# invalid input: a warning is emitted and the original input is returned
result = xmllib.reformat_date(
    date="not-a-date",
    date_precision_separator=".",
    date_range_separator="-",
    date_format=xmllib.DateFormat.DD_MM_YYYY,
)
# WARNING is emitted
# result == "not-a-date"

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

def reformat_date(
    date: str | int,
    date_precision_separator: str | None,
    date_range_separator: str | None,
    date_format: DateFormat,
    calendar: Calendar = Calendar.GREGORIAN,
    era: Era | None = Era.CE,
    resource_id: str | None = None,
) -> str:
    """
    Reformats a date string into the DSP format.

    - If the input cannot be reformatted according to the configuration, or if the result
      is not a valid DSP date, a warning is emitted and the original input is returned.
    - If the input is empty, a warning is emitted and an empty string is returned.
    - If the input is already a correctly formatted DSP-date, the original input is returned.

    Args:
        date: date string to be reformatted
        date_precision_separator: the separation between the day, month and year
        date_range_separator: the separation between two dates
        date_format: the format of the date, see [`DateFormat` for options](https://docs.dasch.swiss/latest/DSP-TOOLS/xmllib-docs/date_formats/#xmllib.models.date_formats.DateFormat)
        calendar: the calendar of the date, see [`Calendar` for options](https://docs.dasch.swiss/latest/DSP-TOOLS/xmllib-docs/date_formats/#xmllib.models.date_formats.Calendar)
        era: the era of the date, see [`Era` for options](https://docs.dasch.swiss/latest/DSP-TOOLS/xmllib-docs/date_formats/#xmllib.models.date_formats.Era)
        resource_id: the ID of the associated resource, this is to improve the error message

    Returns:
        A reformatted date or the original input if the reformatted result is not a valid DSP date

    Examples:
        ```python
        # default configuration, starting with the day
        result = xmllib.reformat_date(
            date="1.11.2000",
            date_precision_separator=".",
            date_range_separator=None,
            date_format=xmllib.DateFormat.DD_MM_YYYY
        )
        # result == "GREGORIAN:CE:2000-11-1:CE:2000-11-1"
        ```

        ```python
        # default configuration, but starting with the year
        result = xmllib.reformat_date(
            date="2000.11.1",
            date_precision_separator=".",
            date_range_separator=None,
            date_format=xmllib.DateFormat.YYYY_MM_DD,
        )
        # result == "GREGORIAN:CE:2000-11-1:CE:2000-11-1"
        ```

        ```python
        # with a date range
        result = xmllib.reformat_date(
            date="1.11.2000-2001",
            date_precision_separator=".",
            date_range_separator="-",
            date_format=xmllib.DateFormat.DD_MM_YYYY,
        )
        # result == "GREGORIAN:CE:2000-11-1:CE:2001"
        ```

        ```python
        # islamic calendar, where eras are not allowed
        result = xmllib.reformat_date(
            date="1.11.2000",
            date_precision_separator=".",
            date_range_separator=None,
            date_format=xmllib.DateFormat.DD_MM_YYYY,
            calendar=xmllib.Calendar.ISLAMIC,
            era=None
        )
        # result == "ISLAMIC:2000-11-1:2000-11-1"
        ```

        ```python
        # with a different era
        result = xmllib.reformat_date(
            date="1.11.2000",
            date_precision_separator=".",
            date_range_separator="-",
            date_format=xmllib.DateFormat.DD_MM_YYYY,
            era=xmllib.Era.AD
        )
        # result == "GREGORIAN:AD:2000-11-1:AD:2000-11-1"
        ```

        ```python
        # reformatted date, no precision in the date string is required
        result = xmllib.reformat_date(
            date="2000",
            date_precision_separator=".",
            date_range_separator="-",
            date_format=xmllib.DateFormat.DD_MM_YYYY,
        )
        # result == "GREGORIAN:CE:2000:CE:2000"
        ```

        ```python
        # already correctly formatted date
        result = xmllib.reformat_date(
            date="GREGORIAN:CE:2000:CE:2000",
            date_precision_separator=".",
            date_range_separator="-",
            date_format=xmllib.DateFormat.DD_MM_YYYY,
        )
        # result == "GREGORIAN:CE:2000:CE:2000"
        ```

        ```python
        # invalid input: a warning is emitted and the original input is returned
        result = xmllib.reformat_date(
            date="not-a-date",
            date_precision_separator=".",
            date_range_separator="-",
            date_format=xmllib.DateFormat.DD_MM_YYYY,
        )
        # WARNING is emitted
        # result == "not-a-date"
        ```
    """
    if not is_nonempty_value_internal(date):
        msg_info = MessageInfo(
            "The date to be reformatted is empty. An empty string is returned.", resource_id=resource_id
        )
        emit_xmllib_input_warning(msg_info)
        return ""
    date = str(date).strip()
    invalid_date_info = MessageInfo(
        f"The provided date '{date}' does not conform to the expected format, the original value is returned.",
        resource_id=resource_id,
    )
    # Here we want to check if the input is already a reformatted date. In that case, we would expect a calendar.
    # The function that checks if an input is a valid date does not require a calendar,
    # so unformatted input for example, '2000' may be accepted as a valid date.
    if regex.search(r"(GREGORIAN|JULIAN|ISLAMIC)", date):
        if is_date_internal(date):
            return date
        else:
            emit_xmllib_input_warning(invalid_date_info)
            return date
    if date_precision_separator and date_range_separator:
        if date_precision_separator == date_range_separator:
            msg_info = MessageInfo(
                f"The precision separator and range separator provided are identical: '{date_precision_separator}'. "
                f"This is not allowed.",
                resource_id=resource_id,
            )
            raise_xmllib_input_error(msg_info)
    if date_range_separator is not None:
        date_split = [found for x in date.split(date_range_separator) if (found := x.strip())]
    else:
        date_split = [date.strip()]
    all_dates = [_reformat_single_date(x, date_precision_separator, date_format, resource_id) for x in date_split]
    if era:
        all_dates = [f"{era.value}:{x}" for x in all_dates]
    if len(all_dates) == 1:
        all_dates.append(all_dates[0])
    reformatted_str = ":".join(all_dates)
    if calendar:
        reformatted_str = f"{calendar.value}:{reformatted_str}"
    if is_date_internal(reformatted_str):
        return reformatted_str
    emit_xmllib_input_warning(invalid_date_info)
    return date

`find_dates_in_string`

Checks if a string contains date values (single dates, or date ranges), and return all found dates as set of DSP-formatted strings. Returns an empty set if no date was found. See XML documentation for details.

Notes

If no era or calendar is given, dates are interpreted in the Common Era and the Gregorian calendar.
Standalone numbers from 000-2999, in 3/4-digit form, are interpreted as years CE.
If a number (with any number of digits) is followed by CE, C.E., AD, A.D., it is interpreted as years CE.
If a number (with any number of digits) is followed by BCE, BC, B.C., B.C.E., av. J.-C., it is interpreted as years BCE.
Dates written with slashes are always interpreted in a European manner: 5/11/2021 is the 5th of November.
In the European notation, 2-digit years are expanded to 4 digits, with the current year as watershed:
- 30.4.24 -> 30.04.2024
- 30.4.50 -> 30.04.1950

Currently supported date formats

0476-09-04 -> GREGORIAN:CE:0476-09-04:CE:0476-09-04
0476_09_04 -> GREGORIAN:CE:0476-09-04:CE:0476-09-04
30.4.2021 -> GREGORIAN:CE:2021-04-30:CE:2021-04-30
30.4.21 -> GREGORIAN:CE:2021-04-30:CE:2021-04-30
5/11/2021 -> GREGORIAN:CE:2021-11-05:CE:2021-11-05
Jan 26, 1993 -> GREGORIAN:CE:1993-01-26:CE:1993-01-26
26 Jan 1993 -> GREGORIAN:CE:1993-01-26:CE:1993-01-26
26 January 1993 -> GREGORIAN:CE:1993-01-26:CE:1993-01-26
1. Jan. 1993 -> GREGORIAN:CE:1993-01-26:CE:1993-01-26
1. Januar 1993 -> GREGORIAN:CE:1993-01-26:CE:1993-01-26
28.2.-1.12.1515 -> GREGORIAN:CE:1515-02-28:CE:1515-12-01
25.-26.2.0800 -> GREGORIAN:CE:0800-02-25:CE:0800-02-26
1.9.2022-3.1.2024 -> GREGORIAN:CE:2022-09-01:CE:2024-01-03
1848 -> GREGORIAN:CE:1848:CE:1848
1849/1850 -> GREGORIAN:CE:1849:CE:1850
1849/50 -> GREGORIAN:CE:1849:CE:1850
1845-50 -> GREGORIAN:CE:1845:CE:1850
840-50 -> GREGORIAN:CE:840:CE:850
840-1 -> GREGORIAN:CE:840:CE:841
9 BC / 9 B.C. / 9 B.C.E. / 9 BCE -> GREGORIAN:BC:9:BC:9
20 BCE - 50 CE -> GREGORIAN:BC:20:CE:50
1000-900 av. J.-C. -> GREGORIAN:BC:1000:BC:900
45 av. J.-C. -> GREGORIAN:BC:45:BC:45

Parameters:

Name	Type	Description	Default
`string`	`str`	string to check	required

Returns:

Type	Description
`set[str]`	(possibly empty) set of DSP-formatted date strings

Examples:

result = xmllib.find_dates_in_string("1849/1850")
# result == {"GREGORIAN:CE:1849:CE:1850"}

result = xmllib.find_dates_in_string("not a valid date")
# result == {}

result = xmllib.find_dates_in_string("first date: 2024. Second: 2025.")
# result == {"GREGORIAN:CE:2024:CE:2024", "GREGORIAN:CE:2025:CE:2025"}

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

def find_dates_in_string(string: str) -> set[str]:
    """
    Checks if a string contains date values (single dates, or date ranges),
    and return all found dates as set of DSP-formatted strings.
    Returns an empty set if no date was found.
    [See XML documentation for details](https://docs.dasch.swiss/latest/DSP-TOOLS/file-formats/xml-data-file/#date).

    Notes:
        - If no era or calendar is given, dates are interpreted in the Common Era and the Gregorian calendar.
        - Standalone numbers from 000-2999, in 3/4-digit form, are interpreted as years CE.
        - If a number (with any number of digits) is followed by CE, C.E., AD, A.D., it is interpreted as years CE.
        - If a number (with any number of digits) is followed by BCE, BC, B.C., B.C.E., av. J.-C.,
          it is interpreted as years BCE.
        - Dates written with slashes are always interpreted in a European manner: 5/11/2021 is the 5th of November.
        - In the European notation, 2-digit years are expanded to 4 digits, with the current year as watershed:
            - 30.4.24 -> 30.04.2024
            - 30.4.50 -> 30.04.1950

    Currently supported date formats:
        - 0476-09-04 -> GREGORIAN:CE:0476-09-04:CE:0476-09-04
        - 0476_09_04 -> GREGORIAN:CE:0476-09-04:CE:0476-09-04
        - 30.4.2021 -> GREGORIAN:CE:2021-04-30:CE:2021-04-30
        - 30.4.21 -> GREGORIAN:CE:2021-04-30:CE:2021-04-30
        - 5/11/2021 -> GREGORIAN:CE:2021-11-05:CE:2021-11-05
        - Jan 26, 1993 -> GREGORIAN:CE:1993-01-26:CE:1993-01-26
        - 26 Jan 1993 -> GREGORIAN:CE:1993-01-26:CE:1993-01-26
        - 26 January 1993 -> GREGORIAN:CE:1993-01-26:CE:1993-01-26
        - 26. Jan. 1993 -> GREGORIAN:CE:1993-01-26:CE:1993-01-26
        - 26. Januar 1993 -> GREGORIAN:CE:1993-01-26:CE:1993-01-26
        - 28.2.-1.12.1515 -> GREGORIAN:CE:1515-02-28:CE:1515-12-01
        - 25.-26.2.0800 -> GREGORIAN:CE:0800-02-25:CE:0800-02-26
        - 1.9.2022-3.1.2024 -> GREGORIAN:CE:2022-09-01:CE:2024-01-03
        - 1848 -> GREGORIAN:CE:1848:CE:1848
        - 1849/1850 -> GREGORIAN:CE:1849:CE:1850
        - 1849/50 -> GREGORIAN:CE:1849:CE:1850
        - 1845-50 -> GREGORIAN:CE:1845:CE:1850
        - 840-50 -> GREGORIAN:CE:840:CE:850
        - 840-1 -> GREGORIAN:CE:840:CE:841
        - 9 BC / 9 B.C. / 9 B.C.E. / 9 BCE -> GREGORIAN:BC:9:BC:9
        - 20 BCE - 50 CE -> GREGORIAN:BC:20:CE:50
        - 1000-900 av. J.-C. -> GREGORIAN:BC:1000:BC:900
        - 45 av. J.-C. -> GREGORIAN:BC:45:BC:45

    Args:
        string: string to check

    Returns:
        (possibly empty) set of DSP-formatted date strings

    Examples:
        ```python
        result = xmllib.find_dates_in_string("1849/1850")
        # result == {"GREGORIAN:CE:1849:CE:1850"}
        ```

        ```python
        result = xmllib.find_dates_in_string("not a valid date")
        # result == {}
        ```

        ```python
        result = xmllib.find_dates_in_string("first date: 2024. Second: 2025.")
        # result == {"GREGORIAN:CE:2024:CE:2024", "GREGORIAN:CE:2025:CE:2025"}
        ```
    """

    # sanitise input, just in case that the function was called on an empty or N/A cell
    if not is_nonempty_value_internal(string):
        return set()
    return _find_dates_in_string(string)