dcc_quantities.dcc_lang_text

Classes to operate with data stored in multiple languages.

The dcc_lang_text module defines a class to support XML contents that allow some type of text in different languages. For example, the label <dcc:name> allows defining names in different languages.

DccLangText 

DccLangText(content: dict[str, dict[str, Any]])

Bases: UserDict, ABC

A mapping containing any XML label information that supports multiple languages.

This mapping is defined as the base class for any more specific DCC label, such as <dcc:name> and <dcc:description>. This class is just to be defined as an AbstractBaseClass and should not be used directly anywhere. Instead, other classes (that would contain information in multiple languages) should inherit from it.

DccLangText allows string representation by the str() call. This representation displays a single name, no matter how many languages are contained within the instance. The selected name is based on the current system language.

Only the names contained in the instance can be displayed, even if they don't match the system language. The priority level to display a name is displaying:

  • The name that matches with the system language.
  • The name in English.
  • The first found name, no matter the language.
  • The tag '' if the instance does not contain any name tag.

Examples:

The DccLangName {'de': 'X deutscher Name', 'en': 'X English Name'} is analogous to the following XML code: 

<dcc:name>
    <dcc:content lang="de">X deutscher Name</dcc:content>
    <dcc:content lang="en">X English Name</dcc:content>
</dcc:name>

Assuming the system language is English, the string representation is then displayed as following: 

>>> names = DccLangName({'de': 'X deutscher Name', 'en': 'X English Name'})
>>> str(names)
X English Name

Derived Classes

General constructor based on the provided content.

Parameters:
  • content (dict) –

    Information about the texts and the languages they are written. This content can be provided in either of the following structures:

    1. A python dictionary, where the keys are the languages and the values are the texts. E.G.: 
      names = DccLangName({"de": "X deutscher Name", "en": "X English Name"})
    2. An DCC structured dictionary based on the tag to use. This structure is analogous to the one obtained by the .to_json_dict() method

    Empty dictionaries are also a valid content.

in_use_language_tag property 

in_use_language_tag: str | None

The short representation of the used language tag (EN, DE, etc.) when the 'str' method is called.

matches 

matches(other: DccLangText | str) -> bool

Matching algorithm for items and subsets of the data.

Parameters:
  • other (DccLangText | str) –

    Another DccLangText (or subclass from it), or a string of the name to be matched.
Returns:
  • bool –

    Whether if the provided information parsed as other is:

    • a string contained within the values of the mapping.
    • a dictionary which can be defined as a subset of the mapping.
Raises:
  • TypeError –

    When the type of other is neither a string nor a subtype of a dictionary.

Examples:

>>> names = DccLangName({"en": "Frequency", "de": "Frequenz", "fr": "Fréquence"})
>>> names.matches("Frequency")
True  # The name 'Frequency' is contained wihtin the `names` instance.
>>> names.matches("Speed")
False  # The name 'Speed' is not within `names`.
>>> names.matches({"en": "Frequency", "de": "Frequenz"})
True  # The provided dictionary is a subset of the `names` instance.
>>> names.matches({"en": "Frequency", "it": "Frequenza"})
False  # The provided dictionary is not a subset of the `names` instance.

to_json_dict 

to_json_dict()

Class representations as a JSON dict with the same keys as required for the XML code.

Returns:
  • dict –

    Structured content as a dictionary that follows the DCC schema.

Examples:

Considering the previous example case: 

>>> names = DccLangName({'de': 'X deutscher Name', 'en': 'X English Name'})
>>> names.to_json_dict()
{'dcc:name': {
    'dcc:content': [
            {'@lang': 'de', '$': 'X deutscher Name'},
            {'@lang': 'en', '$': 'X English Name'}
        ]
    }
}

DccLangName 

DccLangName(content: dict[str, dict[str, Any]])

Bases: DccLangText

Mapping for contents under the tag '<dcc:name>'.

General constructor based on the provided content.

Parameters:
  • content (dict) –

    Information about the texts and the languages they are written. This content can be provided in either of the following structures:

    1. A python dictionary, where the keys are the languages and the values are the texts. E.G.: 
      names = DccLangName({"de": "X deutscher Name", "en": "X English Name"})
    2. An DCC structured dictionary based on the tag to use. This structure is analogous to the one obtained by the .to_json_dict() method

    Empty dictionaries are also a valid content.

DccLangDescription 

DccLangDescription(content: dict[str, dict[str, Any]])

Bases: DccLangText

Mapping for contents under the tag '<dcc:description>'.

General constructor based on the provided content.

Parameters:
  • content (dict) –

    Information about the texts and the languages they are written. This content can be provided in either of the following structures:

    1. A python dictionary, where the keys are the languages and the values are the texts. E.G.: 
      names = DccLangName({"de": "X deutscher Name", "en": "X English Name"})
    2. An DCC structured dictionary based on the tag to use. This structure is analogous to the one obtained by the .to_json_dict() method

    Empty dictionaries are also a valid content.