langstring

The langstring package provides classes and utilities for handling multilingual text.

It includes classes for single and multiple language strings, along with their control and validation mechanisms.

Subpackages

• langstring.utils
  • langstring.utils.controls_base
  • langstring.utils.validation_base

Submodules

• langstring.langstring
• langstring.langstring_control
• langstring.multilangstring
• langstring.multilangstring_control

Package Contents

Classes

LangString	A class to encapsulate a string with its language information.
LangStringControl	Control class for managing LangString configuration flags, designed to be non-instantiable.
LangStringFlag	Enumeration for LangString control flags.
MultiLangString	A class for managing multilingual text strings with various language tags.
MultiLangStringControl	A control class for managing the configuration flags of MultiLangString instances.
MultiLangStringFlag	Enumeration for LangString control flags.

class langstring.LangString(text='', lang=None)

Bases: langstring.utils.validation_base.ValidationBase

A class to encapsulate a string with its language information.

This class provides functionality to associate a text string with a language tag, offering methods for string representation, equality comparison, and hashing. The behavior of this class is influenced by control flags from the LangStringControl class, which can enforce non-empty text, valid language tags, and other constraints.

Variables:

• text (Optional[str]) – The text string.

• lang (Optional[str]) – The language tag of the text, or None if not specified.

Parameters:

• text (str) –

• lang (Optional[str]) –

_get_control_and_flags_type()

Retrieve the control class and its corresponding flags enumeration used in the LangString class.

This method provides the specific control class (LangStringControl) and the flags enumeration (LangStringFlag) that are used for configuring and validating the LangString instances. It is essential for the functioning of the ValidationBase methods, which rely on these control settings.

Returns:

A tuple containing the LangStringControl class and the LangStringFlag enumeration.

Return type:

tuple[type[LangStringControl], type[LangStringFlag]]

to_string()

Convert the LangString object to a string representation.

This method is a convenience wrapper for the __str__ method.

Returns:

The string representation of the LangString object, including the language tag if present.

Return type:

str

__str__()

Define the string representation of the LangString object.

Returns:

The string representation of the LangString object. Format: ‘“text”@lang’ or ‘text’ if lang is None.

Return type:

str

__eq__(other)

Check equality of this LangString with another object.

Parameters:

other (object) – Another object to compare with.

Returns:

True if ‘other’ is a LangString object with the same text and language tag, False otherwise.

Return type:

bool

__hash__()

Generate a hash value for a LangString object.

Returns:

The hash value of the LangString object, based on its text and language tag.

Return type:

int

class langstring.LangStringControl

Bases: langstring.utils.controls_base.ControlBase

Control class for managing LangString configuration flags, designed to be non-instantiable.

This class uses class methods to set and retrieve configuration flags for LangString behavior, ensuring a consistent global configuration state. It is made non-instantiable by using the NonInstantiable metaclass, emphasizing its role as a static configuration manager rather than an object to be instantiated.

Variables:

_flags (dict[LangStringFlag, bool]) – Stores the state of each LangStringFlag.

_flags: dict[LangStringFlag, bool]

classmethod _get_flags_type()

Retrieve the control class and its corresponding flags enumeration used in the LangString class.

This method provides the specific control class (LangStringControl) and the flags enumeration (LangStringFlag) that are used for configuring and validating the LangString instances. It is essential for the functioning of the ValidationBase methods, which rely on these control settings.

Returns:

The LangStringFlag enumeration.

Return type:

type[LangStringFlag]

class langstring.LangStringFlag(*args, **kwds)

Bases: enum.Enum

Enumeration for LangString control flags.

This enum defines various flags that can be used to configure the behavior of the LangString class.

Variables:

• ENSURE_TEXT (Enum) – Makes mandatory the use of a non-empty string for the field ‘text’ of a LangString.

• ENSURE_ANY_LANG (Enum) – Makes mandatory the use of a non-empty string for the field ‘lang’ of a LangString.

• ENSURE_VALID_LANG (Enum) – Makes mandatory the use of a valid language code string for the LangString’s field ‘lang’.

ENSURE_TEXT

ENSURE_ANY_LANG

ENSURE_VALID_LANG

class langstring.MultiLangString(mls_dict=None, pref_lang='en')

Bases: langstring.utils.validation_base.ValidationBase

A class for managing multilingual text strings with various language tags.

Utilizes a global control strategy set in MultiLangStringControl to handle duplicate language tags. Supports operations like adding, removing, and retrieving language strings in multiple languages.

Variables:

• mls_dict (Optional[dict[str, set[str]]]) – A dictionary representing the internal structure of the MultiLangString.

• pref_lang (str) – The preferred language for this MultiLangString. Defaults to “en”.

Parameters:

• mls_dict (Optional[dict[str, set[str]]]) –

• pref_lang (str) –

property preferred_lang: str

Get the preferred language for this MultiLangString.

Returns:

The preferred language as a string.

Return type:

str

_get_control_and_flags_type()

Retrieve the control class and its corresponding flags enumeration used in the MultiLangString class.

This method provides the specific control class (MultiLangStringControl) and the flags enumeration (MultiLangStringFlag) that are used for configuring and validating the MultiLangString instances. It is essential for the functioning of the ValidationBase methods, which rely on these control settings.

Returns:

A tuple containing the MultiLangStringControl class and the MultiLangStringFlag enumeration.

Return type:

tuple[type[MultiLangStringControl], type[MultiLangStringFlag]]

_validate_langstring_arg(arg)

Private helper method to validate if the argument is a LangString.

Parameters:

arg (Any) – Argument to be checked.

Raises:

TypeError – If the passed argument is not an instance of LangString.

Return type:

None

add_entry(text, lang='')

Add a text entry to the MultiLangString under a specified language.

Validates the provided text and language against the current flag settings before adding. If the specified language does not exist in the mls_dict, a new set for that language is created. The text is then added to this set. If the language already exists, the text is added to the existing set for that language.

Parameters:

• text (str) – The text to be added to the MultiLangString.

• lang (str) – The language under which the text should be added. If not specified, defaults to an empty string.

Return type:

None

add_langstring(langstring)

Add a LangString to the MultiLangString.

Parameters:

langstring (LangString) – The LangString object to be added, representing a text in a specific language.

Return type:

None

remove_entry(text, lang)

Remove a single entry from the set of a given language key in the dictionary.

If the specified language key exists and the text is in its set, the text is removed. If this results in an empty set for the language, the language key is also removed from the dictionary.

Parameters:

• text (str) – The text to be removed.

• lang (str) – The language key from which the text should be removed.

Return type:

None

remove_lang(lang)

Remove all entries of a given language from the dictionary.

If the specified language key exists, it and all its associated texts are removed from the dictionary.

Parameters:

lang (str) – The language key to be removed along with all its texts.

Return type:

None

get_langstring(text, lang)

Retrieve a LangString object for a specific text and language.

Parameters:

• text (str) – The text of the LangString.

• lang (str) – The language of the LangString.

Returns:

A LangString object with the specified text and language.

Return type:

LangString

Raises:

ValueError – If the text/lang combination is not in mls_dict.

get_langstrings_lang(lang)

Retrieve a list of LangStrings for a given language.

Parameters:

lang (str) – The language for which to retrieve LangStrings.

Returns:

A list of LangStrings, each containing a single entry for the specified language. Returns an empty list if the specified language is not in mls_dict.

Return type:

list[LangString]

get_langstrings_all()

Retrieve a list of all LangStrings in mls_dict.

Returns:

A list of LangStrings, each representing a single entry from mls_dict.

Return type:

list[LangString]

get_langstrings_pref_lang()

Retrieve a list of LangStrings for the preferred language.

This method returns LangStrings for the language specified in the pref_lang attribute. If pref_lang is not a key in mls_dict, an empty list is returned.

Returns:

A list of LangStrings for the preferred language.

Return type:

list[LangString]

get_strings_lang(lang)

Retrieve all text entries for a specific language.

Parameters:

lang (str) – The language key to retrieve entries for.

Returns:

A list of text entries for the specified language.

Return type:

list[str]

get_strings_pref_lang()

Retrieve all text entries for the preferred language.

Returns:

A list of text entries for the specified language.

Return type:

list[str]

get_strings_all()

Retrieve all text entries across all languages.

Returns:

A list of all text entries.

Return type:

list[str]

get_strings_langstring_lang(lang)

Retrieve all text entries for a specific language, formatted as ‘“text”@lang’.

Parameters:

lang (str) – The language key to retrieve entries for.

Returns:

A list of formatted text entries for the specified language.

Return type:

list[str]

get_strings_langstring_pref_lang()

Retrieve all text entries for the preferred language, formatted as ‘“text”@lang’.

Returns:

A list of formatted text entries for the specified language.

Return type:

list[str]

get_strings_langstring_all()

Retrieve all text entries across all languages, formatted as ‘“text”@lang’.

Returns:

A list of formatted text entries for all languages.

Return type:

list[str]

len_entries_all()

Calculate the total number of elements across all sets in the dictionary.

Iterates through each set in the dictionary values and sums their lengths to get the total number of elements.

Returns:

The total number of elements across all sets.

Return type:

int

len_entries_lang(lang)

Calculate the number of entries of a given language in the dictionary.

Returns:

The number of entries for a given language in a MultiLangString.

Return type:

int

Parameters:

lang (str) –

len_langs()

Calculate the number of keys (languages) in the dictionary.

This method returns the count of distinct keys in the dictionary, which represents the number of languages.

Returns:

The number of keys in the dictionary.

Return type:

int

__repr__()

Return a detailed string representation of the MultiLangString object.

This method provides a more verbose string representation of the MultiLangString, which includes the full dictionary of language strings and the preferred language, making it useful for debugging.

Returns:

A detailed string representation of the MultiLangString.

Return type:

str

__str__()

Return a string representation of the MultiLangString, including language tags.

This method provides a concise string representation of the MultiLangString, listing each text entry with its associated language tag.

Returns:

A string representation of the MultiLangString with language tags.

Return type:

str

__eq__(other)

Check equality of this MultiLangString with another MultiLangString.

Equality is determined based on the mls_dict attribute. The pref_lang attribute is not considered in the equality check.

Parameters:

other (object) – Another object to compare with.

Returns:

True if both MultiLangString objects have the same mls_dict, False otherwise.

Return type:

bool

__hash__()

Generate a hash value for a MultiLangString object.

The hash is computed based on the ‘mls_dict’ attribute of the MultiLangString. This approach ensures that MultiLangString objects with the same content will have the same hash value.

Returns:

The hash value of the MultiLangString object.

Return type:

int

_validate_mls_dict(mls_dict)

Validate all elements in the provided mls_dict against the current flags’ values.

Iterates through each language and its associated texts in the mls_dict, applying validation methods to ensure compliance with the current flag settings.

Parameters:

mls_dict (dict[str, set[str]]) – A dictionary where keys are language codes and values are sets of text entries.

Raises:

• TypeError – If any text or language in mls_dict does not comply with the expected types.

• ValueError – If any text or language in mls_dict violates the rules set by the control flags.

Return type:

None

class langstring.MultiLangStringControl

Bases: langstring.utils.controls_base.ControlBase

A control class for managing the configuration flags of MultiLangString instances.

Inherits from ControlBase and utilizes a static approach to manage global settings that influence the behavior of MultiLangString objects. This class is non-instantiable and operates through class methods to ensure a consistent configuration state across all MultiLangString instances.

The class manages flags defined in the MultiLangStringFlag enumeration, allowing for dynamic control over various aspects of MultiLangString behavior, such as text validation and language code enforcement.

Usage:

MultiLangStringControl is used to configure global settings for MultiLangString instances. It affects how these instances validate and process multilingual text data based on the set flags.

Example:

MultiLangStringControl.set_flag(MultiLangStringFlag.ENSURE_VALID_LANG, True) is_valid_lang_enforced = MultiLangStringControl.get_flag(MultiLangStringFlag.ENSURE_VALID_LANG) print(f”ENSURE_VALID_LANG flag is set to {is_valid_lang_enforced}.”)

Note:

As a static configuration manager, MultiLangStringControl should not be instantiated. It is designed to provide a centralized way to manage settings for all MultiLangString instances.

Variables:

_flags (dict[MultiLangStringFlag, bool]) – A class-level dictionary storing the state of each configuration flag for MultiLangString instances.

_flags: dict[MultiLangStringFlag, bool]

classmethod _get_flags_type()

Retrieve the control class and its corresponding flags enumeration used in the LangString class.

This method provides the specific control class (LangStringControl) and the flags enumeration (LangStringFlag) that are used for configuring and validating the LangString instances. It is essential for the functioning of the ValidationBase methods, which rely on these control settings.

Returns:

The LangStringFlag enumeration.

Return type:

type[MultiLangStringFlag]

class langstring.MultiLangStringFlag(*args, **kwds)

Bases: enum.Enum

Enumeration for LangString control flags.

This enum defines various flags that can be used to configure the behavior of the LangString class.

Variables:

• ENSURE_TEXT (Enum) – Makes mandatory the use of a non-empty string for the field ‘text’ of a LangString.

• ENSURE_ANY_LANG (Enum) – Makes mandatory the use of a non-empty string for the field ‘lang’ of a LangString.

• ENSURE_VALID_LANG (Enum) – Makes mandatory the use of a valid language code string for the LangString’s field ‘lang’.

ENSURE_TEXT

ENSURE_ANY_LANG

ENSURE_VALID_LANG