langstring

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

This package is designed to support the management and manipulation of strings in multiple languages, providing a framework for applications that require multilingual support.

Modules and Classes:

controller: Handles the control mechanisms for language strings.
converter: Provides utilities for converting language strings between different formats.
flags: Defines various flag classes used for global settings and specific types of language strings.
- GlobalFlag: A flag for global settings affecting all language string types.
- LangStringFlag: A flag specific to single language strings.
- SetLangStringFlag: A flag specific to sets of language strings.
- MultiLangStringFlag: A flag specific to multi-language strings.
langstring: Represents a single language string, encapsulating its properties and behaviors.
multilangstring: Represents a string in multiple langs, providing methods to manage and manipulate the different language variants.
setlangstring: Represents a set of language strings, facilitating operations on groups of multilingual texts.

Package Contents:

The package exports the following classes and flags for use in external modules:

LangString
SetLangString
MultiLangString
Controller
GlobalFlag
LangStringFlag
SetLangStringFlag
MultiLangStringFlag
Converter

Language Tag Handling:

In this library’s context, language tags are case-insensitive, meaning ,e.g., en and EN are considered equivalent. However, subtags such as en, en-UK, and en-US are treated as distinct entities. Additionally, spaces in language tags are not automatically trimmed unless the classes’ STRIP_LANG flags are True. As an example, “en” is not considered equal to “en “. However, if the STRIP_LANG flag is set to True, “en “ will be converted to “en”, thereby making the languages equal.

Usage:

To use this package, import the necessary classes and flags as follows:

from langstring import (
    LangString, MultiLangString, SetLangString, Controller,
    GlobalFlag, LangStringFlag, SetLangStringFlag, MultiLangStringFlag, Converter
)

Subpackages

langstring.utils

Submodules

Classes

`Controller`	Control class for managing configuration flags, designed to be non-instantiable.
`Converter`	A utility class for converting between different string types used in language processing.
`GlobalFlag`	Enumeration for global control flags.
`LangStringFlag`	Enumeration for LangString control flags.
`MultiLangStringFlag`	Enumeration for MultiLangString control flags.
`SetLangStringFlag`	Enumeration for SetLangString control flags.
`LangString`	A class to encapsulate a string with its language information.
`MultiLangString`	A class for managing multilingual text strings with various language tags.
`SetLangString`	A class to encapsulate a set of strings with a common language tag.

Package Contents

class langstring.Controller

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

This class uses class methods to set and retrieve configuration flags for the behavior of the LangString, SetLangString, and MultiLangString classes, 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:

_DEFAULT_FLAGS – The default state of each flag.
flags (dict[Union[GlobalFlag, LangStringFlag, SetLangStringFlag, MultiLangStringFlag], bool]) – Stores the current state of each flag.

Example:

Set a flag:
>>> Controller.set_flag(GlobalFlag.LOWERCASE_LANG, True)

Get a flag:
>>> print(Controller.get_flag(GlobalFlag.LOWERCASE_LANG))
# Output: True

Reset a flag to its default value:
>>> Controller.reset_flag(GlobalFlag.LOWERCASE_LANG)
>>> print(Controller.get_flag(GlobalFlag.LOWERCASE_LANG))
# Output: False

Print the state of a specific flag:
>>> Controller.print_flag(GlobalFlag.LOWERCASE_LANG)
# Output: GlobalFlag.LOWERCASE_LANG = False

Print the states of all flags:
>>> Controller.print_flags()
# Output: (Output of all flags with their states)

Reset all flags to their default values:
>>> Controller.reset_flags()
>>> Controller.print_flags()
# Output: (Output of all flags reset to their default states)

flags: dict[langstring.flags.GlobalFlag | langstring.flags.LangStringFlag | langstring.flags.SetLangStringFlag | langstring.flags.MultiLangStringFlag, bool]

classmethod set_flag(flag, state)

Set the state of a specified configuration flag for LangString, SetLangString, or MultiLangString.

If a GlobalFlag is set, it also sets the corresponding flags in LangStringFlag, SetLangStringFlag, and MultiLangStringFlag to the same state.

Parameters:

flag (Union[GlobalFlag, LangStringFlag, SetLangStringFlag, MultiLangStringFlag]) – The flag to be set, either an instance of one of the flag enums.
state (bool) – Setting this to True or False will enable or disable the flag, respectively.

Raises:

TypeError – If ‘flag’ is not an instance of one of the flag enums, or if ‘state’ is not a boolean.

Return type:

None

Example:

>>> Controller.set_flag(GlobalFlag.LOWERCASE_LANG, True)
>>> print(Controller.get_flag(GlobalFlag.LOWERCASE_LANG))  # Output: True

classmethod get_flag(flag)

Retrieve the current state of a specified configuration flag.

Available for GlobalFlag, LangString, SetLangString, or MultiLangString.

This class method provides a way to access the state of a flag globally for LangString, SetLangString, and MultiLangString classes.

Parameters:: flag (Union[GlobalFlag, LangStringFlag, SetLangStringFlag, MultiLangStringFlag]) – The flag whose state is to be retrieved, either an instance of GlobalFlag, LangStringFlag, SetLangStringFlag, or MultiLangStringFlag.
Returns:: The current state of the flag.
Return type:: bool
Raises:: TypeError – If ‘flag’ is not a member of GlobalFlag, LangStringFlag, SetLangStringFlag, or MultiLangStringFlag.

Example:

>>> Controller.set_flag(GlobalFlag.LOWERCASE_LANG, True)
>>> print(Controller.get_flag(GlobalFlag.LOWERCASE_LANG))  # Output: True

classmethod get_flags()

Retrieve the current state of all configuration flags.

This class method provides a way to access the states of all flags globally for LangString, SetLangString, and MultiLangString classes. It returns a copy of the flags dictionary, ensuring that the original data is not modified.

Returns:: A dictionary mapping each flag to its boolean state.
Return type:: dict[Union[GlobalFlag, LangStringFlag, SetLangStringFlag, MultiLangStringFlag], bool]

Example:

>>> Controller.set_flag(GlobalFlag.LOWERCASE_LANG, True)
>>> flags = Controller.get_flags()
>>> print(flags[GlobalFlag.LOWERCASE_LANG])  # Output: True

classmethod print_flag(flag)

Print the current state of a specific configuration flag.

This class method prints the state of the specified flag to the console. It is useful for checking the state of an individual flag for LangString, SetLangString, MultiLangString, or GlobalFlag.

Parameters:: flag (Union[GlobalFlag, LangStringFlag, SetLangStringFlag, MultiLangStringFlag]) – The flag whose state is to be printed.
Raises:: TypeError – If ‘flag’ is not an instance of one of the flag enums.
Return type:: None

Example:

>>> Controller.set_flag(GlobalFlag.LOWERCASE_LANG, True)
>>> Controller.print_flag(GlobalFlag.LOWERCASE_LANG)  # Output: GlobalFlag.LOWERCASE_LANG = True

classmethod print_flags(flag_type=None)

Print the current state of configuration flags in alphabetical order.

If a flag type is specified, only flags of that type are printed. If no flag type is specified, all flags are printed.

Parameters:: flag_type (Optional[type]) – The type of flags to print (e.g., GlobalFlag, LangStringFlag). If None, all flags are printed.
Raises:: TypeError – If ‘flag_type’ is not a valid flag type.
Return type:: None

Example:

>>> Controller.set_flag(GlobalFlag.LOWERCASE_LANG, True)
>>> Controller.print_flags()
# Output: Prints all flags and their current state.

classmethod reset_flag(flag)

Reset a specific flag to its default value.

If the flag is of type GlobalFlag, reset all equivalent flags of other types. For example, reset_flag(GlobalFlag.VALID_TEXT) will reset GlobalFlag.VALID_TEXT, LangStringFlag.VALID_TEXT, SetLangStringFlag.VALID_TEXT, and MultiLangStringFlag.VALID_TEXT.

Parameters:: flag (Union[GlobalFlag, LangStringFlag, SetLangStringFlag, MultiLangStringFlag]) – The flag to be reset.
Raises:: TypeError – If ‘flag’ is not an instance of one of the flag enums.
Return type:: None

Example:

>>> Controller.set_flag(GlobalFlag.LOWERCASE_LANG, True)
>>> Controller.reset_flag(GlobalFlag.LOWERCASE_LANG)
>>> print(Controller.get_flag(GlobalFlag.LOWERCASE_LANG))  # Output: False

classmethod reset_flags(flag_type=GlobalFlag)

Reset all flags of a specific type to their default values.

Parameters:: flag_type (Optional[type]) – The type of flags to reset (e.g., GlobalFlag, LangStringFlag). If None, all flags are reset.
Raises:: TypeError – If ‘flag_type’ is not a valid flag type.
Return type:: None

Example:

>>> Controller.set_flag(GlobalFlag.LOWERCASE_LANG, True)
>>> Controller.reset_flags(GlobalFlag)
>>> print(Controller.get_flag(GlobalFlag.LOWERCASE_LANG))  # Output: False

class langstring.Converter

A utility class for converting between different string types used in language processing.

This class provides methods to convert between LangString, SetLangString, and MultiLangString types. It is designed to be non-instantiable as it serves as a utility class with class methods only.

Example:

# Convert a string to a LangString using the 'manual' method:
>>> langstring = Converter.from_string_to_langstring("manual", "Hello", "en")
>>> print(langstring)  #Output: "Hello"@en

# Convert a list of strings to a list of LangStrings using the 'parse' method:
>>> langstrings = Converter.from_strings_to_langstrings("parse", ["Hello@en", "Bonjour@fr"], separator="@")
>>> for ls in langstrings:
>>>     print(ls)  #Output: "Hello"@en
>>>                #        "Bonjour"@fr

# Convert a SetLangString to a MultiLangString:
>>> setlangstring = SetLangString({"Hello", "Hi"}, "en")
>>> multilangstring = Converter.from_setlangstring_to_multilangstring(setlangstring)
>>> print(multilangstring)  #Output: {'Hello', 'Hi'}@en

classmethod from_string_to_langstring(method, input_string, lang=None, separator='@')

Convert a string to a LangString using the specified method.

Parameters:

method (str) – The method to use for conversion (‘manual’ or ‘parse’).
input_string (str) – The text to be converted.
lang (Optional[str]) – The language code (used only with ‘manual’ method).
separator (str) – The separator used to split the text and language (used only with ‘parse’ method).

Returns:

A LangString object with the converted text and language.

Return type:

LangString

Raises:

ValueError – If the method is unknown.

Example:

# Convert a string to a LangString using the 'manual' method:
>>> langstring = Converter.from_string_to_langstring("manual", "Hello", "en")
>>> print(langstring)  # Output: "Hello"@en

# Convert a string to a LangString using the 'parse' method:
>>> langstring = Converter.from_string_to_langstring("parse", "Hello@en")
>>> print(langstring)  # Output: "Hello"@en

static from_string_to_langstring_manual(input_string, lang)

Convert a string to a LangString with the specified language.

Parameters:

input_string (str) – The text to be converted.
lang (Optional[str]) – The language code.

Returns:

A LangString object with the provided text and language.

Return type:

LangString

Example:

# Convert a string to a LangString with the specified language:
>>> langstring = Converter.from_string_to_langstring_manual("Hello", "en")
>>> print(langstring)  # Output: "Hello"@en

static from_string_to_langstring_parse(input_string, separator='@')

Convert a string to a LangString by parsing it with the given separator.

This function splits the input string into text and language components based on the last occurrence of the specified separator. If the separator is not found, the entire string is considered as text and lang is set to “” (empty string).

Parameters:

input_string (str) – The text to be converted.
separator (str) – The separator used to split the text and language.

Returns:

A LangString object with the parsed text and language.

Return type:

LangString

Example:

# Convert a string to a LangString by parsing it with the given separator:
>>> langstring = Converter.from_string_to_langstring_parse("Hello@en", "@")
>>> print(langstring)  # Output: "Hello"@en

# Convert a string to a LangString with no separator found:
>>> langstring = Converter.from_string_to_langstring_parse("Hello", "@")
>>> print(langstring)  # Output: "Hello"@

classmethod from_strings_to_langstrings(method, strings, lang=None, separator='@')

Convert a list of strings to a list of LangStrings using the specified method.

Parameters:

method (str) – The method to use for conversion (‘manual’ or ‘parse’).
strings (list[str]) – List of strings to be converted.
lang (Optional[str]) – The language code for ‘manual’ method.
separator (str) – The separator used in ‘parse’ method.

Returns:

A list of LangString objects.

Return type:

list[LangString]

Raises:

ValueError – If an unknown method is specified.
TypeError – If the input types are incorrect.

Example:

# Convert a list of strings to a list of LangStrings using the 'manual' method:
>>> langstrings = Converter.from_strings_to_langstrings("manual", ["Hello", "Hi"], "en")
>>> for ls in langstrings:
>>>     print(ls)  # Output: "Hello"@en
>>>                #         "Hi"@en

# Convert a list of strings to a list of LangStrings using the 'parse' method:
>>> langstrings = Converter.from_strings_to_langstrings("parse", ["Hello@en", "Bonjour@fr"], separator="@")
>>> for ls in langstrings:
>>>     print(ls)  # Output: "Hello"@en
>>>                #         "Bonjour"@fr

classmethod from_strings_to_setlangstring(strings, lang=None)

Convert a list of strings to a SetLangString using the ‘manual’ method.

Parameters:

strings (list[str]) – List of strings to be converted.
lang (Optional[str]) – Language code for the ‘manual’ method. Optional.

Returns:

A SetLangString object.

Return type:

SetLangString

Example:

# Convert a list of strings to a SetLangString using the 'manual' method:
>>> setlangstring = Converter.from_strings_to_setlangstring(["Hello", "Hi"], "en")
>>> print(setlangstring)  # Output: {'Hello', 'Hi'}@en

classmethod from_strings_to_multilangstring(method, strings, lang=None, separator='@')

Convert a list of strings to a MultiLangString using the specified method.

Parameters:

method (str) – Method to use for conversion (“manual”, or “parse”).
strings (list[str]) – List of strings to be converted.
lang (Optional[str]) – Language code for the “manual” method. Optional.
separator (str) – Separator for the “parse” method. Default is “@”.

Returns:

A MultiLangString object.

Return type:

MultiLangString

Example:

# Convert a list of strings to a MultiLangString using the 'manual' method:
>>> multilangstring = Converter.from_strings_to_multilangstring("manual", ["Hello", "Hi"], "en")
>>> print(multilangstring)  # Output: {'Hello', 'Hi'}@en

# Convert a list of strings to a MultiLangString using the 'parse' method:
>>> multilangstring = Converter.from_strings_to_multilangstring("parse", ["Hello@en", "Bonjour@fr"],
                                                                                            separator="@")
>>> print(multilangstring)  # Output: {'Hello', 'Bonjour'}@en,fr

static from_langstring_to_string(arg, print_quotes=None, separator='@', print_lang=None)

Convert a LangString to a string.

Parameters:

arg (LangString) – The LangString to be converted.
print_quotes (Optional[bool]) – Whether to include quotes around the text in the output.
separator (str) – The separator to use between text and language.
print_lang (Optional[bool]) – Whether to include the language in the output.

Returns:

The string representation of the LangString.

Return type:

str

Example:

# Convert a LangString to a string with quotes and language:
>>> langstring = LangString("Hello", "en")
>>> string = Converter.from_langstring_to_string(langstring, print_quotes=True, separator="@")
>>> print(string)  # Output: "Hello"@en

# Convert a LangString to a string without quotes and language:
>>> string = Converter.from_langstring_to_string(langstring, print_quotes=False, separator="@",
                                                                                        print_lang=False)
>>> print(string)  # Output: "Hello"

static from_langstrings_to_strings(arg, print_quotes=None, separator='@', print_lang=None)

Convert a list of LangStrings to a list of strings.

Parameters:

arg (list[LangString]) – List of LangStrings to be converted.
print_quotes (Optional[bool]) – Whether to include quotes around the text in the output.
separator (str) – The separator to use between text and language.
print_lang (Optional[bool]) – Whether to include the language in the output.

Returns:

A list of string representations of the LangStrings.

Return type:

list[str]

Example:

# Convert a list of LangStrings to a list of strings with quotes and language:
>>> langstrings = [LangString("Hello", "en"), LangString("Bonjour", "fr")]
>>> strings = Converter.from_langstrings_to_strings(langstrings, print_quotes=True, separator="@")
>>> for s in strings:
>>>     print(s)  # Output: "Hello"@en
>>>                #         "Bonjour"@fr

# Convert a list of LangStrings to a list of strings without quotes and language:
>>> strings = Converter.from_langstrings_to_strings(langstrings, print_quotes=False, separator="@",
                                                                                        print_lang=False)
>>> for s in strings:
>>>     print(s)  # Output: "Hello"
>>>                #         "Bonjour"

static from_langstring_to_setlangstring(arg)

Convert a LangString to a SetLangString.

This method creates a SetLangString from a LangString. The resulting SetLangString contains the text of the LangString in a set and retains its language.

Parameters:: arg (LangString) – The LangString to be converted.
Returns:: A SetLangString containing the text from the arg LangString.
Return type:: SetLangString
Raises:: TypeError – If the arg is not of type LangString.

Example:

# Convert a LangString to a SetLangString:
>>> langstring = LangString("Hello", "en")
>>> setlangstring = Converter.from_langstring_to_setlangstring(langstring)
>>> print(setlangstring)  # Output: {'Hello'}@en

static from_langstrings_to_setlangstring(arg)

Convert a list of LangStrings to a SetLangString.

This method merges a list of LangStrings into a single SetLangString. The resulting SetLangString contains all the unique texts from the LangStrings and retains a common language if all LangStrings have the same language.

Parameters:

arg (list[LangString]) – The list of LangStrings to be converted.

Returns:

A SetLangString containing the texts from the list of LangStrings.

Return type:

SetLangString

Raises:

ValueError – If the LangStrings have different languages.
TypeError – If the input types are incorrect.

Example:

# Convert a list of LangStrings to a SetLangString:
>>> langstrings = [LangString("Hello", "en"), LangString("Hi", "en")]
>>> setlangstring = Converter.from_langstrings_to_setlangstring(langstrings)
>>> print(setlangstring)  # Output: {'Hello', 'Hi'}@en

classmethod from_langstrings_to_setlangstrings(arg)

Convert a list of LangStrings to a list of SetLangStrings.

This method merges a list of LangStrings into multiple SetLangStrings based on their languages. Each SetLangString contains all the unique texts for a specific language from the LangStrings.

Parameters:: arg (list[LangString]) – The list of LangStrings to be converted.
Returns:: A list of SetLangStrings, each containing texts of a specific language from the LangStrings.
Return type:: list[SetLangString]
Raises:: TypeError – If the input types are incorrect.

Example:

# Convert a list of LangStrings to a list of SetLangStrings:
>>> langstrings = [LangString("Hello", "en"), LangString("Bonjour", "fr")]
>>> setlangstrings = Converter.from_langstrings_to_setlangstrings(langstrings)
>>> for sls in setlangstrings:
>>>     print(sls)  # Output: {'Hello'}@en
>>>                 #         {'Bonjour'}@fr

static from_langstring_to_multilangstring(arg)

Convert a LangString to a MultiLangString.

This method takes a single LangString and converts it into a MultiLangString. The resulting MultiLangString contains the text and language of the arg LangString.

Parameters:: arg (LangString) – The LangString to be converted.
Returns:: A MultiLangString containing the text and language from the arg LangString.
Return type:: MultiLangString
Raises:: TypeError – If the arg is not of type LangString.

Example:

# Convert a LangString to a MultiLangString:
>>> langstring = LangString("Hello", "en")
>>> multilangstring = Converter.from_langstring_to_multilangstring(langstring)
>>> print(multilangstring)  # Output: {'Hello'}@en

static from_langstrings_to_multilangstring(arg)

Convert a list of LangStrings to a MultiLangString.

This method merges a list of LangStrings into a single MultiLangString. The resulting MultiLangString contains all the unique texts and languages from the LangStrings.

Parameters:: arg (list[LangString]) – The list of LangStrings to be converted.
Returns:: A MultiLangString containing the texts and languages from the list of LangStrings.
Return type:: MultiLangString
Raises:: TypeError – If the input types are incorrect.

Example:

# Convert a list of LangStrings to a MultiLangString:
>>> langstrings = [LangString("Hello", "en"), LangString("Bonjour", "fr")]
>>> multilangstring = Converter.from_langstrings_to_multilangstring(langstrings)
>>> print(multilangstring)  # Output: {'Hello'}@en, {'Bonjour'}@fr

static from_setlangstring_to_string(arg)

Convert a SetLangString to a string.

Parameters:: arg (SetLangString) – The SetLangString to be converted.
Returns:: The string representation of the SetLangString.
Return type:: str

Example:

# Convert a SetLangString to a string:
>>> setlangstring = SetLangString({"Hello", "Hi"}, "en")
>>> string = Converter.from_setlangstring_to_string(setlangstring)
>>> print(string)  # Output: {'Hello', 'Hi'}@en

static from_setlangstring_to_strings(arg, print_quotes=None, separator='@', print_lang=None)

Convert a SetLangString to a list of strings.

Parameters:

arg (SetLangString) – The SetLangString to be converted.
print_quotes (Optional[bool]) – Whether to include quotes around the text in the output.
separator (str) – The separator to use between text and language.
print_lang (Optional[bool]) – Whether to include the language in the output.

Returns:

A list of string representations of the SetLangString.

Return type:

list[str]

Example:

# Convert a SetLangString to a list of strings with quotes and language:
>>> setlangstring = SetLangString({"Hello", "Hi"}, "en")
>>> strings = Converter.from_setlangstring_to_strings(setlangstring, print_quotes=True, separator="@")
>>> for s in strings:
>>>     print(s)  # Output: "Hello"@en
>>>                #         "Hi"@en

# Convert a SetLangString to a list of strings without quotes and language:
>>> strings = Converter.from_setlangstring_to_strings(setlangstring, print_quotes=False, separator="@",
                                                                                        print_lang=False)
>>> for s in strings:
>>>     print(s)  # Output: Hello
>>>                #         Hi

static from_setlangstrings_to_strings(arg, print_quotes=None, separator='@', print_lang=None)

Convert a list of SetLangStrings to a list of strings.

Parameters:

arg (list[SetLangString]) – List of SetLangStrings to be converted.
print_quotes (Optional[bool]) – Whether to include quotes around the text in the output.
separator (str) – The separator to use between text and language.
print_lang (Optional[bool]) – Whether to include the language in the output.

Returns:

A list of string representations of the SetLangStrings.

Return type:

list[str]

Example:

# Convert a list of SetLangStrings to a list of strings with quotes and language:
>>> setlangstrings = [SetLangString({"Hello"}, "en"), SetLangString({"Bonjour"}, "fr")]
>>> strings = Converter.from_setlangstrings_to_strings(setlangstrings, print_quotes=True, separator="@")
>>> for s in strings:
>>>     print(s)  # Output: "Hello"@en
>>>                #         "Bonjour"@fr

# Convert a list of SetLangStrings to a list of strings without quotes and language:
>>> strings = Converter.from_setlangstrings_to_strings(setlangstrings, print_quotes=False, separator="@",
                                                                                        print_lang=False)
>>> for s in strings:
>>>     print(s)  # Output: Hello
>>>                #         Bonjour

static from_setlangstring_to_langstrings(arg)

Convert a SetLangString to a list of LangStrings.

This method takes a SetLangString and converts it into a list of LangStrings, each containing one of the texts from the SetLangString and its associated language.

Parameters:: arg (SetLangString) – The SetLangString to be converted.
Returns:: A list of LangStrings, each corresponding to a text in the arg SetLangString.
Return type:: list[LangString]
Raises:: TypeError – If the arg is not of type SetLangString.

Example:

# Convert a SetLangString to a list of LangStrings:
>>> setlangstring = SetLangString({"Hello", "Hi"}, "en")
>>> langstrings = Converter.from_setlangstring_to_langstrings(setlangstring)
>>> for ls in langstrings:
>>>     print(ls)  # Output: "Hi"@en
>>>                #         "Hello"@en

Note:: The order of elements in the output list is not guaranteed, as sets do not maintain order.

static from_setlangstrings_to_langstrings(arg)

Convert a list of SetLangStrings to a list of LangStrings.

This method merges a list of SetLangStrings into a single list of LangStrings. Each LangString in the output list corresponds to one of the texts in the SetLangStrings, retaining their associated languages.

Parameters:: arg (list[SetLangString]) – The list of SetLangStrings to be converted.
Returns:: A list of LangStrings, each corresponding to a text in the SetLangStrings.
Return type:: list[LangString]
Raises:: TypeError – If the input types are incorrect.

Example:

# Convert a list of SetLangStrings to a list of LangStrings:
>>> setlangstrings = [SetLangString({"Hello"}, "en"), SetLangString({"Bonjour"}, "fr")]
>>> langstrings = Converter.from_setlangstrings_to_langstrings(setlangstrings)
>>> for ls in langstrings:
>>>     print(ls)  # Output: "Hello"@en
>>>                #         "Bonjour"@fr

static from_setlangstring_to_multilangstring(arg)

Convert a SetLangString to a MultiLangString.

This method creates a MultiLangString from a SetLangString. The resulting MultiLangString contains all texts from the SetLangString, associated with its language.

Parameters:: arg (SetLangString) – The SetLangString to be converted.
Returns:: A MultiLangString containing all texts from the arg SetLangString.
Return type:: MultiLangString
Raises:: TypeError – If the arg is not of type SetLangString.

Example:

# Convert a SetLangString to a MultiLangString:
>>> setlangstring = SetLangString({"Hello", "Hi"}, "en")
>>> multilangstring = Converter.from_setlangstring_to_multilangstring(setlangstring)
>>> print(multilangstring)  # Output: {'Hello', 'Hi'}@en

static from_setlangstrings_to_multilangstring(arg)

Convert a list of SetLangString objects to a MultiLangString object.

If there are different casings for the same lang tag among the SetLangString objects in the input list, the casefolded version of the lang tag is used. If only a single case is used, that case is adopted.

Parameters:: arg (list[SetLangString]) – List of SetLangString instances to be converted.
Returns:: A MultiLangString instance with aggregated texts under normalized language tags.
Return type:: MultiLangString
Raises:: TypeError – If the input types are incorrect.

Example:

# Convert a list of SetLangStrings to a MultiLangString:
>>> setlangstrings = [SetLangString({"Hello"}, "en"), SetLangString({"Bonjour"}, "fr")]
>>> multilangstring = Converter.from_setlangstrings_to_multilangstring(setlangstrings)
>>> print(multilangstring)  # Output: {'Hello'}@en, {'Bonjour'}@fr

static from_multilangstring_to_string(arg)

Convert a MultiLangString to a string.

Parameters:: arg (MultiLangString) – The MultiLangString to be converted.
Returns:: The string representation of the MultiLangString.
Return type:: str

Example:

# Convert a MultiLangString to a string:
>>> multilangstring = MultiLangString(mls_dict={"en": {"Hello", "Hi"}, "fr": {"Bonjour"}})
>>> string = Converter.from_multilangstring_to_string(multilangstring)
>>> print(string)  # Output: {'Hello', 'Hi'}@en, {'Bonjour'}@fr

static from_multilangstring_to_strings(arg, langs=None, print_quotes=None, separator='@', print_lang=None)

Convert a MultiLangString to a list of strings.

The method sorts the output strings both by language and by text within each language.

Parameters:

arg (MultiLangString) – The MultiLangString to be converted.
langs (Optional[list[str]]) – List of languages to include in the output. If None, all languages are included.
print_quotes (Optional[bool]) – Whether to include quotes around the text in the output.
separator (str) – The separator to use between text and language.
print_lang (Optional[bool]) – Whether to include the language in the output.

Returns:

A list of string representations of the MultiLangString.

Return type:

list[str]

Example:

# Convert a MultiLangString to a list of strings with quotes and language:
>>> multilangstring = MultiLangString(mls_dict={"en": {"Hello", "Hi"}, "fr": {"Bonjour"}})
>>> strings = Converter.from_multilangstring_to_strings(multilangstring, print_quotes=True, separator="@")
>>> for s in strings:
>>>     print(s)  # Output: "Bonjour"@fr
>>>                #         "Hello"@en
>>>                #         "Hi"@en

# Convert a MultiLangString to a list of strings without quotes and language:
>>> strings = Converter.from_multilangstring_to_strings(multilangstring, print_quotes=False, separator="@",
                                                                                        print_lang=False)
>>> for s in strings:
>>>     print(s)  # Output: Bonjour
>>>                #         Hello
>>>                #         Hi

Note:: The output strings are sorted by language and by text within each language.

static from_multilangstrings_to_strings(arg, languages=None, print_quotes=True, separator='@', print_lang=True)

Convert a list of MultiLangStrings to a list of strings.

The method sorts the output strings both by language and by text within each language.

Parameters:

arg (list[MultiLangString]) – List of MultiLangStrings to be converted.
languages (Optional[list[str]]) – List of languages to include in the output. If None, all languages are included.
print_quotes (bool) – Whether to include quotes around the text in the output.
separator (str) – The separator to use between text and language.
print_lang (bool) – Whether to include the language in the output.

Returns:

A list of string representations of the MultiLangStrings.

Return type:

list[str]

Example:

# Convert a list of MultiLangStrings to a list of strings with quotes and language:
>>> mls1 = MultiLangString(mls_dict={"en": {"Hello"}, "fr": {"Bonjour"}})
>>> mls2 = MultiLangString(mls_dict={"en": {"Hi"}, "fr": {"Salut"}})
>>> strings = Converter.from_multilangstrings_to_strings([mls1, mls2], print_quotes=True, separator="@")
>>> for s in strings:
>>>     print(s)  # Output: "Bonjour"@fr
>>>                #         "Hello"@en
>>>                #         "Hi"@en
>>>                #         "Salut"@fr

# Convert a list of MultiLangStrings to a list of strings without quotes and language:
>>> strings = Converter.from_multilangstrings_to_strings([mls1, mls2], print_quotes=False, separator="@",
                                                                                        print_lang=False)
>>> for s in strings:
>>>     print(s)  # Output: Bonjour
>>>                #         Hello
>>>                #         Hi
>>>                #         Salut

Note:: The output strings are sorted by language and by text within each language.

static from_multilangstring_to_langstrings(arg, languages=None)

Convert a MultiLangString to a list of LangStrings.

This method takes a MultiLangString and converts it into a list of LangStrings, each representing one of the texts in the MultiLangString along with its associated language.

Parameters:

arg (MultiLangString) – The MultiLangString to be converted.
languages (Optional[list[str]]) – List of languages to include in the output. If None, all languages are included.

Returns:

A list of LangStrings, each corresponding to a text in the arg MultiLangString.

Return type:

list[LangString]

Raises:

TypeError – If the arg is not of type MultiLangString.

Example:

# Convert a MultiLangString to a list of LangStrings:
>>> multilangstring = MultiLangString(mls_dict={"en": {"Hi", "Hello"}, "fr": {"Bonjour"}})
>>> langstrings = Converter.from_multilangstring_to_langstrings(multilangstring)
>>> for ls in langstrings:
>>>     print(ls)  # Output: "Hi"@en
>>>                #         "Hello"@en
>>>                #         "Bonjour"@fr

Note:: The output strings are in the order of insertion within each language.

static from_multilangstrings_to_langstrings(arg, languages=None)

Convert a list of MultiLangStrings to a list of LangStrings.

This method takes a list of MultiLangStrings and converts them into a list of LangStrings, each representing one of the texts in the MultiLangStrings along with its associated language.

Parameters:

arg (list[MultiLangString]) – List of MultiLangStrings to be converted.
languages (Optional[list[str]]) – List of languages to include in the output. If None, all languages are included.

Returns:

A list of LangStrings, each corresponding to a text in the MultiLangStrings.

Return type:

list[LangString]

Raises:

TypeError – If any of the arguments are not of the expected type.

Example:

# Convert a list of MultiLangStrings to a list of LangStrings:
>>> mls1 = MultiLangString(mls_dict={"en": {"Hello", "Hi"}, "fr": {"Bonjour"}})
>>> mls2 = MultiLangString(mls_dict={"en": {"Hey"}, "fr": {"Salut"}})
>>> langstrings = Converter.from_multilangstrings_to_langstrings([mls1, mls2])
>>> for ls in langstrings:
>>>     print(ls)  # Output could vary as texts within each language may not be sorted. Possible outputs:
>>>                #         "Hello"@en
>>>                #         "Hi"@en
>>>                #         "Hey"@en
>>>                #         "Bonjour"@fr
>>>                #         "Salut"@fr

static from_multilangstring_to_setlangstrings(arg, languages=None)

Convert a MultiLangString to a list of SetLangStrings.

This method creates a list of SetLangStrings from a MultiLangString. Each SetLangString in the list contains texts of a single language from the MultiLangString.

Parameters:

arg (MultiLangString) – The MultiLangString to be converted.
languages (Optional[list[str]]) – List of languages to include in the output. If None, all languages are included.

Returns:

A list of SetLangStrings, each containing texts of a single language from the arg MultiLangString.

Return type:

list[SetLangString]

Raises:

TypeError – If the arg is not of type MultiLangString.

Example:

# Convert a MultiLangString to a list of SetLangStrings:
>>> multilangstring = MultiLangString(mls_dict={"en": {"Hello", "Hi"}, "fr": {"Bonjour", "Salut"}})
>>> setlangstrings = Converter.from_multilangstring_to_setlangstrings(multilangstring)
>>> for sls in setlangstrings:
>>>     print(sls)  # Output: {'Hello', 'Hi'}@en
>>>                #         {'Bonjour', 'Salut'}@fr

Note:: The texts within each language are sorted.

static from_multilangstrings_to_setlangstrings(arg, languages=None)

Convert a list of MultiLangString objects to a list of SetLangString objects.

This method creates a list of SetLangStrings from multiple MultiLangStrings. Each SetLangString in the list contains texts of a single language from the merged MultiLangStrings.

Parameters:

arg (list[MultiLangString]) – List of MultiLangStrings to be converted.
languages (Optional[list[str]]) – List of languages to include in the output. If None, all languages are included.

Returns:

A list of SetLangStrings, each containing texts of a single language from the merged MultiLangStrings.

Return type:

list[SetLangString]

Raises:

TypeError – If any of the arguments are not of the expected type.

Example:

# Convert a list of MultiLangStrings to a list of SetLangStrings:
>>> mls1 = MultiLangString(mls_dict={"en": {"Hello"}, "fr": {"Bonjour"}})
>>> mls2 = MultiLangString(mls_dict={"en": {"Hi"}, "fr": {"Salut"}})
>>> setlangstrings = Converter.from_multilangstrings_to_setlangstrings([mls1, mls2])
>>> for sls in setlangstrings:
>>>     print(sls)  # Output: {'Hello', 'Hi'}@en
>>>                #         {'Bonjour', 'Salut'}@fr

Note:: The texts within each language are sorted.

class langstring.GlobalFlag(*args, **kwds)

Bases: enum.Enum

Enumeration for global control flags.

This enum defines various flags that can be used to configure the behavior of all classes in the multilingual text handling system. These flags provide a flexible way to enforce constraints and manage behavior consistently across different classes.

Variables:

DEFINED_LANG (Enum) – Ensures that a non-empty string is used for the ‘lang’ field of all classes.
DEFINED_TEXT (Enum) – Ensures that a non-empty string is used for the ‘text’ field of all classes.
ENFORCE_EXTRA_DEPEND (Enum) – Enforces additional dependencies required by all classes.
LOWERCASE_LANG (Enum) – Converts all language codes to lowercase.
METHODS_MATCH_TYPES (Enum) – Ensures that methods match the expected types for arguments and return values.
PRINT_WITH_LANG (Enum) – Includes language tags when printing multilingual text.
PRINT_WITH_QUOTES (Enum) – Wraps text entries in quotes when printing multilingual text.
STRIP_LANG (Enum) – Removes leading and trailing whitespace from language codes.
STRIP_TEXT (Enum) – Removes leading and trailing whitespace from text entries.
VALID_LANG (Enum) – Ensures that a valid language code string is used for the ‘lang’ field of all classes.

DEFINED_LANG

DEFINED_TEXT

ENFORCE_EXTRA_DEPEND

LOWERCASE_LANG

METHODS_MATCH_TYPES

PRINT_WITH_LANG

PRINT_WITH_QUOTES

STRIP_LANG

STRIP_TEXT

VALID_LANG

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. These flags provide a flexible way to enforce constraints and manage the behavior of multilingual text handling within the LangString class.

Variables:

DEFINED_LANG (Enum) – Ensures that a non-empty string is used for the ‘lang’ field of a LangString.
DEFINED_TEXT (Enum) – Ensures that a non-empty string is used for the ‘text’ field of a LangString.
LOWERCASE_LANG (Enum) – Converts all language codes to lowercase within a LangString.
METHODS_MATCH_TYPES (Enum) – Ensures that methods match the expected types for arguments and return values within a LangString.
PRINT_WITH_LANG (Enum) – Includes language tags when printing a LangString.
PRINT_WITH_QUOTES (Enum) – Wraps text entries in quotes when printing a LangString.
STRIP_LANG (Enum) – Removes leading and trailing whitespace from language codes within a LangString.
STRIP_TEXT (Enum) – Removes leading and trailing whitespace from text entries within a LangString.
VALID_LANG (Enum) – Ensures that a valid language code string is used for the ‘lang’ field of a LangString.

DEFINED_LANG

DEFINED_TEXT

LOWERCASE_LANG

METHODS_MATCH_TYPES

PRINT_WITH_LANG

PRINT_WITH_QUOTES

STRIP_LANG

STRIP_TEXT

VALID_LANG

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

Bases: enum.Enum

Enumeration for MultiLangString control flags.

This enum defines various flags that can be used to configure the behavior of the MultiLangString class. These flags provide a flexible way to enforce constraints and manage the behavior of multilingual text handling within the MultiLangString class.

Variables:

DEFINED_LANG (Enum) – Ensures that a non-empty string is used for the ‘lang’ field of a MultiLangString.
DEFINED_TEXT (Enum) – Ensures that a non-empty string is used for the ‘text’ field of a MultiLangString.
LOWERCASE_LANG (Enum) – Converts all language codes to lowercase within a MultiLangString.
PRINT_WITH_LANG (Enum) – Includes language tags when printing a MultiLangString.
PRINT_WITH_QUOTES (Enum) – Wraps text entries in quotes when printing a MultiLangString.
STRIP_LANG (Enum) – Removes leading and trailing whitespace from language codes within a MultiLangString.
STRIP_TEXT (Enum) – Removes leading and trailing whitespace from text entries within a MultiLangString.
VALID_LANG (Enum) – Ensures that a valid language code string is used for the ‘lang’ field of a MultiLangString.

DEFINED_LANG

DEFINED_TEXT

LOWERCASE_LANG

PRINT_WITH_LANG

PRINT_WITH_QUOTES

STRIP_LANG

STRIP_TEXT

VALID_LANG

class langstring.SetLangStringFlag(*args, **kwds)

Bases: enum.Enum

Enumeration for SetLangString control flags.

This enum defines various flags that can be used to configure the behavior of the SetLangString class. These flags provide a flexible way to enforce constraints and manage the behavior of multilingual text handling within the SetLangString class.

Variables:

DEFINED_LANG (Enum) – Ensures that a non-empty string is used for the ‘lang’ field of a SetLangString.
DEFINED_TEXT (Enum) – Ensures that a non-empty string is used for the ‘text’ field of a SetLangString.
LOWERCASE_LANG (Enum) – Converts all language codes to lowercase within a SetLangString.
METHODS_MATCH_TYPES (Enum) – Ensures that methods match the expected types for arguments and return values within a SetLangString.
PRINT_WITH_LANG (Enum) – Includes language tags when printing a SetLangString.
PRINT_WITH_QUOTES (Enum) – Wraps text entries in quotes when printing a SetLangString.
STRIP_LANG (Enum) – Removes leading and trailing whitespace from language codes within a SetLangString.
STRIP_TEXT (Enum) – Removes leading and trailing whitespace from text entries within a SetLangString.
VALID_LANG (Enum) – Ensures that a valid language code string is used for the ‘lang’ field of a SetLangString.

DEFINED_LANG

DEFINED_TEXT

LOWERCASE_LANG

METHODS_MATCH_TYPES

PRINT_WITH_LANG

PRINT_WITH_QUOTES

STRIP_LANG

STRIP_TEXT

VALID_LANG

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

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 Controller class, which can enforce non-empty text, valid language tags, and other constraints.

Many standard string methods are overridden to return LangString objects, allowing seamless integration and extended functionality. This design ensures that users can work with LangString instances similarly to regular strings.

Variables:

text (Optional[str]) – The text string.
lang (str) – The language tag of the text.

Raises:

ValueError – If control flags enforce non-empty text and the text is empty.
TypeError – If the types of parameters are incorrect based on validation.

Parameters:

text (str)
lang (str)

property text: str

Get the text string.

Returns:: The text string.
Return type:: str

property lang: str

Get the language tag.

Returns:: The language tag.
Return type:: str

capitalize()

Return a copy of the LangString with its first character capitalized and the rest lowercased.

This method mimics the behavior of the standard string’s capitalize method but returns a LangString object.

Returns:: A new LangString with the first character capitalized.
Return type:: LangString

Example:

>>> lang_str = LangString("hello, world!", "en")
>>> capitalized_lang_str = lang_str.capitalize()
>>> print(capitalized_lang_str)  # Output: "Hello, world!"@en

casefold()

Return a casefolded copy of the LangString. Casefolding is a more aggressive version of lowercasing.

This method mimics the behavior of the standard string’s casefold method but returns a LangString object.

Returns:: A new LangString that is casefolded.
Return type:: LangString

Example:

>>> lang_str = LangString("Hello, WORLD!", "en")
>>> casefolded_lang_str = lang_str.casefold()
>>> print(casefolded_lang_str)  # Output: "hello, world!"@en

center(width, fillchar=' ')

Return a centered LangString of length width.

Padding is done using the specified fill character (default is a space).

This method mimics the behavior of the standard string’s center method but returns a LangString object.

Parameters:

width (int) – The total width of the resulting LangString.
fillchar (str) – The character to fill the padding with.

Returns:

A new LangString centered with padding.

Return type:

LangString

Example:

>>> lang_str = LangString("hello", "en")
>>> centered_lang_str = lang_str.center(11, "*")
>>> print(centered_lang_str)  # Output: "***hello***"@en

count(sub, start=0, end=None)

Return the number of non-overlapping occurrences of substring sub in the LangString.

This method mimics the behavior of the standard string’s count method.

Parameters:

sub (str) – The substring to count.
start (int, optional) – The starting position (default is 0).
end (int, optional) – The ending position (default is the end of the string).

Returns:

The number of occurrences of the substring.

Return type:

int

Example:

>>> lang_str = LangString("hello, hello, hello!", "en")
>>> count_hello = lang_str.count("hello")
>>> print(count_hello)  # Output: 3

endswith(suffix, start=0, end=None)

Return True if the LangString ends with the specified suffix, otherwise return False.

This method mimics the behavior of the standard string’s endswith method.

Parameters:

suffix (str) – The suffix to check.
start (int, optional) – The starting position (default is 0).
end (int, optional) – The ending position (default is the end of the string).

Returns:

True if the LangString ends with the suffix, otherwise False.

Return type:

bool

Example:

>>> lang_str = LangString("hello, world!", "en")
>>> ends_with_world = lang_str.endswith("world!")
>>> print(ends_with_world)  # Output: True

expandtabs(tabsize=8)

Return a copy of the LangString where all tab characters are expanded using spaces.

This method mimics the behavior of the standard string’s expandtabs method but returns a LangString object.

Parameters:: tabsize (int) – The number of spaces to use for each tab character.
Returns:: A new LangString with tabs expanded.
Return type:: LangString

Example:

>>> lang_str = LangString("hello\tworld", "en")
>>> expanded_lang_str = lang_str.expandtabs(4)
>>> print(expanded_lang_str)  # Output: "hello   world"@en

find(sub, start=0, end=None)

Return the lowest index in the LangString where substring sub is found.

This method mimics the behavior of the standard string’s find method.

Parameters:

sub (str) – The substring to find.
start (int, optional) – The starting position (default is 0).
end (int, optional) – The ending position (default is the end of the string).

Returns:

The lowest index where the substring is found, or -1 if not found.

Return type:

int

Example:

>>> lang_str = LangString("hello, world", "en")
>>> index = lang_str.find("world")
>>> print(index)  # Output: 7

format(*args, **kwargs)

Perform a string formatting operation on the LangString.

This method mimics the behavior of the standard string’s format method but returns a LangString object.

Parameters:

args (Any) – Positional arguments for formatting.
kwargs (Any) – Keyword arguments for formatting.

Returns:

A new LangString with the formatted text.

Return type:

LangString

Example:

>>> lang_str = LangString("Hello, {}!", "en")
>>> formatted_lang_str = lang_str.format("world")
>>> print(formatted_lang_str)  # Output: "Hello, world!"@en

format_map(mapping)

Perform a string formatting operation using a dictionary.

This method mimics the behavior of the standard string’s format_map method but returns a LangString object.

Parameters:: mapping (dict) – A dictionary for formatting.
Returns:: A new LangString with the formatted text.
Return type:: LangString
Raises:: TypeError – If the provided mapping is not a dictionary.

Example:

>>> lang_str = LangString("Hello, {name}!", "en")
>>> formatted_lang_str = lang_str.format_map({"name": "world"})
>>> print(formatted_lang_str)  # Output: "Hello, world!"@en

index(sub, start=0, end=None)

Return the lowest index in the LangString where substring sub is found.

This method mimics the behavior of the standard string’s index method.

Parameters:

sub (str) – The substring to find.
start (int, optional) – The starting position (default is 0).
end (int, optional) – The ending position (default is the end of the string).

Returns:

The lowest index where the substring is found.

Return type:

int

Raises:

ValueError – If the substring is not found.

Example:

>>> lang_str = LangString("hello, world", "en")
>>> index = lang_str.index("world")
>>> print(index)  # Output: 7

isalnum()

Return True if all characters in the LangString are alphanumeric and there is at least one character.

This method mimics the behavior of the standard string’s isalnum method.

Returns:: True if the LangString is alphanumeric, otherwise False.
Return type:: bool

Example:

>>> lang_str = LangString("Hello123", "en")
>>> is_alnum = lang_str.isalnum()
>>> print(is_alnum)  # Output: True

>>> lang_str = LangString("Hello 123", "en")
>>> is_alnum = lang_str.isalnum()
>>> print(is_alnum)  # Output: False

isalpha()

Return True if all characters in the LangString are alphabetic and there is at least one character.

This method mimics the behavior of the standard string’s isalpha method.

Returns:: True if the LangString is alphabetic, otherwise False.
Return type:: bool

Example:

>>> lang_str = LangString("Hello", "en")
>>> is_alpha = lang_str.isalpha()
>>> print(is_alpha)  # Output: True

>>> lang_str = LangString("Hello123", "en")
>>> is_alpha = lang_str.isalpha()
>>> print(is_alpha)  # Output: False

isascii()

Return True if all characters in the LangString are ASCII characters.

This method mimics the behavior of the standard string’s isascii method.

Returns:: True if the LangString is ASCII, otherwise False.
Return type:: bool

Example:

>>> lang_str = LangString("Hello", "en")
>>> is_ascii = lang_str.isascii()
>>> print(is_ascii)  # Output: True

>>> lang_str = LangString("Héllo", "en")
>>> is_ascii = lang_str.isascii()
>>> print(is_ascii)  # Output: False

isdecimal()

Return True if all characters in the LangString are decimal characters and there is at least one character.

This method mimics the behavior of the standard string’s isdecimal method.

Returns:: True if the LangString is decimal, otherwise False.
Return type:: bool

Example:

>>> lang_str = LangString("12345", "en")
>>> is_decimal = lang_str.isdecimal()
>>> print(is_decimal)  # Output: True

>>> lang_str = LangString("123.45", "en")
>>> is_decimal = lang_str.isdecimal()
>>> print(is_decimal)  # Output: False

isdigit()

Return True if all characters in the LangString are digits and there is at least one character.

This method mimics the behavior of the standard string’s isdigit method.

Returns:: True if the LangString is numeric, otherwise False.
Return type:: bool

Example:

>>> lang_str = LangString("12345", "en")
>>> is_digit = lang_str.isdigit()
>>> print(is_digit)  # Output: True

>>> lang_str = LangString("123.45", "en")
>>> is_digit = lang_str.isdigit()
>>> print(is_digit)  # Output: False

isidentifier()

Return True if the LangString is a valid identifier according to Python language definition.

This method mimics the behavior of the standard string’s isidentifier method.

Returns:: True if the LangString is a valid identifier, otherwise False.
Return type:: bool

Example:

>>> lang_str = LangString("variable_name", "en")
>>> is_identifier = lang_str.isidentifier()
>>> print(is_identifier)  # Output: True

>>> lang_str = LangString("123variable", "en")
>>> is_identifier = lang_str.isidentifier()
>>> print(is_identifier)  # Output: False

islower()

Return True if all cased characters in the LangString are lowercase and there is at least one cased character.

This method mimics the behavior of the standard string’s islower method.

Returns:: True if the LangString is in lowercase, otherwise False.
Return type:: bool

Example:

>>> lang_str = LangString("hello", "en")
>>> is_lower = lang_str.islower()
>>> print(is_lower)  # Output: True

>>> lang_str = LangString("Hello", "en")
>>> is_lower = lang_str.islower()
>>> print(is_lower)  # Output: False

isnumeric()

Return True if all characters in the LangString are numeric characters and there is at least one character.

This method mimics the behavior of the standard string’s isnumeric method.

Returns:: True if the LangString is numeric, otherwise False.
Return type:: bool

Example:

>>> lang_str = LangString("12345", "en")
>>> is_numeric = lang_str.isnumeric()
>>> print(is_numeric)  # Output: True

>>> lang_str = LangString("123.45", "en")
>>> is_numeric = lang_str.isnumeric()
>>> print(is_numeric)  # Output: False

isprintable()

Return True if all characters in the LangString are printable or the LangString is empty.

This method mimics the behavior of the standard string’s isprintable method.

Returns:: True if the LangString is printable, otherwise False.
Return type:: bool

Example:

>>> lang_str = LangString("Hello, world!", "en")
>>> is_printable = lang_str.isprintable()
>>> print(is_printable)  # Output: True

>>> lang_str = LangString("Hello,\tworld!", "en")
>>> is_printable = lang_str.isprintable()
>>> print(is_printable)  # Output: False

isspace()

Return True if there are only whitespace characters in the LangString and there is at least one character.

This method mimics the behavior of the standard string’s isspace method.

Returns:: True if the LangString is whitespace, otherwise False.
Return type:: bool

Example:

>>> lang_str = LangString("   ", "en")
>>> is_space = lang_str.isspace()
>>> print(is_space)  # Output: True

>>> lang_str = LangString("Hello, world!", "en")
>>> is_space = lang_str.isspace()
>>> print(is_space)  # Output: False

istitle()

Return True if the LangString is a titlecased string and there is at least one character.

This method mimics the behavior of the standard string’s istitle method.

Returns:: True if the LangString is titlecased, otherwise False.
Return type:: bool

Example:

>>> lang_str = LangString("Hello, World!", "en")
>>> is_title = lang_str.istitle()
>>> print(is_title)  # Output: True

>>> lang_str = LangString("hello, world!", "en")
>>> is_title = lang_str.istitle()
>>> print(is_title)  # Output: False

isupper()

Return True if all cased characters in the LangString are uppercase and there is at least one cased character.

This method mimics the behavior of the standard string’s isupper method.

Returns:: True if the LangString is in uppercase, otherwise False.
Return type:: bool

Example:

>>> lang_str = LangString("HELLO, WORLD!", "en")
>>> is_upper = lang_str.isupper()
>>> print(is_upper)  # Output: True

>>> lang_str = LangString("Hello, World!", "en")
>>> is_upper = lang_str.isupper()
>>> print(is_upper)  # Output: False

join(iterable)

Join an iterable of strings with the LangString’s text.

This method mimics the behavior of the standard string’s join method but returns a LangString object.

Parameters:: iterable (Iterable[str]) – An iterable of strings to be joined.
Returns:: A new LangString with the joined text.
Return type:: LangString

Example:

>>> lang_str = LangString(", ", "en")
>>> joined_lang_str = lang_str.join(["Hello", "world"])
>>> print(joined_lang_str)  # Output: "Hello, world"@en

ljust(width, fillchar=' ')

Return a left-justified LangString of length width.

Padding is done using the specified fill character (default is a space).

This method mimics the behavior of the standard string’s ljust method but returns a LangString object.

Parameters:

width (int) – The total width of the resulting LangString.
fillchar (str) – The character to fill the padding with.

Returns:

A new LangString left-justified with padding.

Return type:

LangString

Example:

>>> lang_str = LangString("hello", "en")
>>> left_justified_lang_str = lang_str.ljust(10, "*")
>>> print(left_justified_lang_str)  # Output: "hello*****"@en

lower()

Return a copy of the LangString with all the cased characters converted to lowercase.

This method mimics the behavior of the standard string’s lower method but returns a LangString object.

Returns:: A new LangString with all characters in lowercase.
Return type:: LangString

Example:

>>> lang_str = LangString("HELLO, WORLD!", "en")
>>> lower_lang_str = lang_str.lower()
>>> print(lower_lang_str)  # Output: "hello, world!"@en

lstrip(chars=None)

Return a copy of the LangString with leading characters removed.

This method mimics the behavior of the standard string’s lstrip method but returns a LangString object.

Parameters:: chars (Optional[str]) – A string specifying the set of characters to be removed. If None, whitespace characters are removed.
Returns:: A new LangString with leading characters removed.
Return type:: LangString

Example:

>>> lang_str = LangString("   Hello, world!", "en")
>>> stripped_lang_str = lang_str.lstrip()
>>> print(stripped_lang_str)  # Output: "Hello, world!"@en

>>> lang_str = LangString("...Hello, world!", "en")
>>> stripped_lang_str = lang_str.lstrip(".")
>>> print(stripped_lang_str)  # Output: "Hello, world!"@en

partition(sep)

Split the LangString at the first occurrence of sep, and return a 3-tuple containing the part before the separator, the separator itself, and the part after the separator.

This method mimics the behavior of the standard string’s partition method but returns LangString objects.

Parameters:: sep (str) – The separator to split the LangString.
Returns:: A 3-tuple containing the part before the separator, the separator itself, and the part after the separator.
Return type:: tuple[LangString, LangString, LangString]

Example:

>>> lang_str = LangString("Hello, world!", "en")
>>> before, sep, after = lang_str.partition(", ")
>>> print(before)  # Output: "Hello"@en
>>> print(sep)     # Output: ", "@en
>>> print(after)   # Output: "world!"@en

replace(old, new, count=-1)

Return a copy of the LangString with all occurrences of substring old replaced by new.

This method mimics the behavior of the standard string’s replace method but returns a LangString object.

Parameters:

old (str) – The substring to be replaced.
new (str) – The substring to replace with.
count (int) – The maximum number of occurrences to replace. If -1, all occurrences are replaced.

Returns:

A new LangString with the replacements.

Return type:

LangString

Example:

>>> lang_str = LangString("Hello, world!", "en")
>>> replaced_lang_str = lang_str.replace("world", "Python")
>>> print(replaced_lang_str)  # Output: "Hello, Python!"@en

>>> lang_str = LangString("abababab", "en")
>>> replaced_lang_str = lang_str.replace("ab", "cd", 2)
>>> print(replaced_lang_str)  # Output: "cdcdabab"@en

removeprefix(prefix)

Remove the specified prefix from the LangString’s text.

If the text starts with the prefix string, return a new LangString with the prefix string removed. Otherwise, return a copy of the original LangString.

This method mimics the behavior of the standard string’s removeprefix method but returns a LangString object.

Parameters:: prefix (str) – The prefix to remove from the text.
Returns:: A new LangString with the prefix removed, or the original LangString if the prefix is not found.
Return type:: LangString

Example:

>>> lang_str = LangString("Hello, world!", "en")
>>> removed_prefix_lang_str = lang_str.removeprefix("Hello, ")
>>> print(removed_prefix_lang_str)  # Output: "world!"@en

>>> lang_str = LangString("Hello, world!", "en")
>>> removed_prefix_lang_str = lang_str.removeprefix("Goodbye, ")
>>> print(removed_prefix_lang_str)  # Output: "Hello, world!"@en

removesuffix(suffix)

Remove the specified suffix from the LangString’s text.

If the text ends with the suffix string, return a new LangString with the suffix string removed. Otherwise, return a copy of the original LangString.

This method mimics the behavior of the standard string’s removesuffix method but returns a LangString object.

Parameters:: suffix (str) – The suffix to remove from the text.
Returns:: A new LangString with the suffix removed, or the original LangString if the suffix is not found.
Return type:: LangString

Example:

>>> lang_str = LangString("Hello, world!", "en")
>>> removed_suffix_lang_str = lang_str.removesuffix(", world!")
>>> print(removed_suffix_lang_str)  # Output: "Hello"@en

>>> lang_str = LangString("Hello, world!", "en")
>>> removed_suffix_lang_str = lang_str.removesuffix("planet")
>>> print(removed_suffix_lang_str)  # Output: "Hello, world!"@en

rfind(sub, start=0, end=None)

Return the highest index in the LangString where substring sub is found, such that sub is contained within [start, end].

Optional arguments start and end are interpreted as in slice notation. Return -1 if sub is not found.

This method mimics the behavior of the standard string’s rfind method.

Parameters:

sub (str) – The substring to find.
start (int, optional) – The starting position (default is 0).
end (int, optional) – The ending position (default is the end of the string).

Returns:

The highest index where the substring is found, or -1 if not found.

Return type:

int

Example:

>>> lang_str = LangString("Hello, world! Hello, universe!", "en")
>>> index = lang_str.rfind("Hello")
>>> print(index)  # Output: 14

rindex(sub, start=0, end=None)

Return the highest index in the LangString where substring sub is found, such that sub is contained within [start, end].

Optional arguments start and end are interpreted as in slice notation. Raises ValueError when the substring is not found.

This method mimics the behavior of the standard string’s rindex method.

Parameters:

sub (str) – The substring to find.
start (int, optional) – The starting position (default is 0).
end (int, optional) – The ending position (default is the end of the string).

Returns:

The highest index where the substring is found.

Return type:

int

Raises:

ValueError – If the substring is not found.

Example:

>>> lang_str = LangString("Hello, world! Hello, universe!", "en")
>>> index = lang_str.rindex("Hello")
>>> print(index)  # Output: 14

>>> lang_str = LangString("Hello, world!", "en")
>>> index = lang_str.rindex("Hi")
>>> print(index)  # Output: ValueError

rjust(width, fillchar=' ')

Return a right-justified LangString of length width.

Padding is done using the specified fill character (default is a space).

This method mimics the behavior of the standard string’s rjust method but returns a LangString object.

Parameters:

width (int) – The total width of the resulting LangString.
fillchar (str) – The character to fill the padding with.

Returns:

A new LangString right-justified with padding.

Return type:

LangString

Example:

>>> lang_str = LangString("hello", "en")
>>> right_justified_lang_str = lang_str.rjust(10, "*")
>>> print(right_justified_lang_str)  # Output: "*****hello"@en

rpartition(sep)

Split the LangString at the last occurrence of sep, and return a 3-tuple containing the part before the separator, the separator itself, and the part after the separator.

This method mimics the behavior of the standard string’s rpartition method but returns LangString objects.

Parameters:: sep (str) – The separator to split the LangString.
Returns:: A 3-tuple containing the part before the separator, the separator itself, and the part after the separator.
Return type:: tuple[LangString, LangString, LangString]

Example:

>>> lang_str = LangString("Hello, world! Hello, universe!", "en")
>>> before, sep, after = lang_str.rpartition("Hello")
>>> print(before)  # Output: "Hello, world! "@en
>>> print(sep)     # Output: "Hello"@en
>>> print(after)   # Output: ", universe!"@en

rsplit(sep=None, maxsplit=-1)

Return a list of the words in the LangString, using sep as the delimiter string.

The list is split from the right starting from the end of the string.

This method mimics the behavior of the standard string’s rsplit method but returns a list of LangString objects.

Parameters:

sep (Optional[str]) – The delimiter string. If None, any whitespace string is a separator.
maxsplit (int) – Maximum number of splits. If -1, there is no limit.

Returns:

A list of LangString objects.

Return type:

list[LangString]

Example:

>>> lang_str = LangString("one two three", "en")
>>> split_lang_str = lang_str.rsplit()
>>> for part in split_lang_str:
...     print(part)
...
>>> # Output: "one"@en
>>> #         "two"@en
>>> #         "three"@en

>>> lang_str = LangString("one,two,three", "en")
>>> split_lang_str = lang_str.rsplit(",", 1)
>>> for part in split_lang_str:
...     print(part)
...
>>> # Output: "one,two"@en
>>> #         "three"@en

rstrip(chars=None)

Return a copy of the LangString with trailing characters removed.

This method mimics the behavior of the standard string’s rstrip method but returns a LangString object.

Parameters:: chars (Optional[str]) – A string specifying the set of characters to be removed. If None, whitespace characters are removed.
Returns:: A new LangString with trailing characters removed.
Return type:: LangString

Example:

>>> lang_str = LangString("Hello, world!   ", "en")
>>> stripped_lang_str = lang_str.rstrip()
>>> print(stripped_lang_str)  # Output: "Hello, world!"@en

>>> lang_str = LangString("Hello, world!!!", "en")
>>> stripped_lang_str = lang_str.rstrip("!")
>>> print(stripped_lang_str)  # Output: "Hello, world"@en

split(sep=None, maxsplit=-1)

Return a list of the words in the LangString, using sep as the delimiter string.

This method mimics the behavior of the standard string’s split method but returns a list of LangString objects.

Parameters:

sep (Optional[str]) – The delimiter string. If None, any whitespace string is a separator.
maxsplit (int) – Maximum number of splits. If -1, there is no limit.

Returns:

A list of LangString objects.

Return type:

list[LangString]

Example:

>>> lang_str = LangString("one two three", "en")
>>> split_lang_str = lang_str.split()
>>> for part in split_lang_str:
...     print(part)
...
>>> # Output: "one"@en
>>> #         "two"@en
>>> #         "three"@en

>>> lang_str = LangString("one,two,three", "en")
>>> split_lang_str = lang_str.split(",")
>>> for part in split_lang_str:
...     print(part)
...
>>> # Output: "one"@en
>>> #         "two"@en
>>> #         "three"@en

splitlines(keepends=False)

Return a list of the lines in the LangString, breaking at line boundaries.

This method mimics the behavior of the standard string’s splitlines method but returns a list of LangString objects.

Parameters:: keepends (bool) – If True, line breaks are included in the resulting list.
Returns:: A list of LangString objects.
Return type:: list[LangString]

Example:

>>> lang_str = LangString("Hello\\nworld", "en") # To test, remove one escape char before the line break.
>>> split_lang_str = lang_str.splitlines()
>>> print(split_lang_str)
# Output: [LangString(text='Hello', lang='en'), LangString(text='world', lang='en')]

>>> lang_str = LangString("Hello\\nworld", "en") # To test, remove one escape char before the line break.
>>> split_lang_str = lang_str.splitlines(True)
>>> print(split_lang_str)
# Output: [LangString(text='Hello\n', lang='en'), LangString(text='world', lang='en')]

startswith(prefix, start=0, end=None)

Return True if the LangString starts with the specified prefix, otherwise return False.

This method mimics the behavior of the standard string’s startswith method.

Parameters:

prefix (str) – The prefix to check.
start (int, optional) – The starting position (default is 0).
end (int, optional) – The ending position (default is the end of the string).

Returns:

True if the LangString starts with the prefix, otherwise False.

Return type:

bool

Example:

>>> lang_str = LangString("Hello, world!", "en")
>>> starts_with_hello = lang_str.startswith("Hello")
>>> print(starts_with_hello)  # Output: True

>>> lang_str = LangString("Hello, world!", "en")
>>> starts_with_hello = lang_str.startswith("world")
>>> print(starts_with_hello)  # Output: False

strip(chars=None)

Return a copy of the LangString with leading and trailing characters removed.

This method mimics the behavior of the standard string’s strip method but returns a LangString object.

Parameters:: chars (Optional[str]) – A string specifying the set of characters to be removed. If None, whitespace characters are removed.
Returns:: A new LangString with leading and trailing characters removed.
Return type:: LangString

Example:

>>> lang_str = LangString("   Hello, world!   ", "en")
>>> stripped_lang_str = lang_str.strip()
>>> print(stripped_lang_str)  # Output: "Hello, world!"@en

>>> lang_str = LangString("***Hello, world!***", "en")
>>> stripped_lang_str = lang_str.strip("*")
>>> print(stripped_lang_str)  # Output: "Hello, world!"@en

swapcase()

Return a copy of the LangString with uppercase characters converted to lowercase and vice versa.

This method mimics the behavior of the standard string’s swapcase method but returns a LangString object.

Returns:: A new LangString with swapped case.
Return type:: LangString

Example:

>>> lang_str = LangString("Hello, WORLD!", "en")
>>> swapcase_lang_str = lang_str.swapcase()
>>> print(swapcase_lang_str)  # Output: "hELLO, world!"@en

title()

Return a titlecased version of the LangString where words start with an uppercase character and the remaining characters are lowercase.

This method mimics the behavior of the standard string’s title method but returns a LangString object.

Returns:: A new LangString that is titlecased.
Return type:: LangString

Example:

>>> lang_str = LangString("hello world", "en")
>>> title_lang_str = lang_str.title()
>>> print(title_lang_str)  # Output: "Hello World"@en

translate(table)

Return a copy of the LangString in which each character has been mapped through the given translation table.

This method mimics the behavior of the standard string’s translate method but returns a LangString object.

Parameters:: table (dict[int, str]) – A translation table mapping Unicode ordinals to Unicode ordinals, strings, or None.
Returns:: A new LangString with the characters translated.
Return type:: LangString

Example:

>>> translation_table = str.maketrans("aeiou", "12345")
>>> lang_str = LangString("hello world", "en")
>>> translated_lang_str = lang_str.translate(translation_table)
>>> print(translated_lang_str) # Output: "h2ll4 w4rld"@en

upper()

Return a copy of the LangString with all the characters converted to uppercase.

This method mimics the behavior of the standard string’s upper method but returns a LangString object.

Returns:: A new LangString with all characters in uppercase.
Return type:: LangString

Example:

>>> lang_str = LangString("hello world", "en")
>>> upper_lang_str = lang_str.upper()
>>> print(upper_lang_str)  # Output: "HELLO WORLD"@en

zfill(width)

Return a copy of the LangString left filled with ASCII ‘0’ digits to make a string of length width.

This method mimics the behavior of the standard string’s zfill method but returns a LangString object.

Parameters:: width (int) – The total width of the resulting LangString.
Returns:: A new LangString left filled with ‘0’ digits.
Return type:: LangString

Example:

>>> lang_str = LangString("42", "en")
>>> zfilled_lang_str = lang_str.zfill(5)
>>> print(zfilled_lang_str)  # Output: "00042"@en

to_string(print_quotes=None, separator='@', print_lang=None)

Return a string representation of the LangString with options for including quotes and language tag.

Parameters:

print_quotes (Optional[bool]) – If True, wrap the text in quotes. If None, use the default setting from the Controller.
separator (str) – The separator to use between the text and language tag.
print_lang (Optional[bool]) – If True, include the language tag. If None, use the default setting from the Controller.

Returns:

A string representation of the LangString.

Return type:

str

Example:

>>> lang_str = LangString("Hello, World!", "en")
>>> print(lang_str.to_string())  # Output: '"Hello, World!"@en'
>>> print(lang_str.to_string(print_quotes=False))  # Output: 'Hello, World!@en'
>>> print(lang_str.to_string(print_lang=False))  # Output: '"Hello, World!"'

equals_str(other)

Compare the LangString’s text with a given string for equality.

Parameters:: other (str) – The string to compare with.
Returns:: True if the text matches the given string, otherwise False.
Return type:: bool

Example:

>>> lang_str = LangString("Hello, World!", "en")
>>> print(lang_str.equals_str("Hello, World!"))  # Output: True
>>> print(lang_str.equals_str("hello, world!"))  # Output: False

equals_langstring(other)

Compare the LangString with another LangString for equality of text and language tag (case-insensitive).

Parameters:: other (LangString) – The LangString to compare with.
Returns:: True if both text and language tag match (case-insensitive), otherwise False.
Return type:: bool

Example:

>>> lang_str1 = LangString("Hello, World!", "en")
>>> lang_str2 = LangString("Hello, World!", "EN")
>>> print(lang_str1.equals_langstring(lang_str2))  # Output: True
>>> lang_str3 = LangString("Hello, World!", "fr")
>>> print(lang_str1.equals_langstring(lang_str3))  # Output: False

__add__(other)

Add another LangString or a string to this LangString.

The operation can only be performed if:

Both are LangString objects with the same language tag.
The other is a string, which will be concatenated to the text of this LangString.

Parameters:: other (Union[LangString, str]) – The LangString or string to add.
Returns:: A new LangString with the concatenated text.
Return type:: LangString
Raises:: TypeError – If the objects are not compatible for addition.

Example:

>>> lang_str1 = LangString("Hello", "en")
>>> lang_str2 = LangString(" World", "en")
>>> result = lang_str1 + lang_str2
>>> print(result)  # Output: "Hello World"@en

>>> lang_str3 = LangString("Hello", "en")
>>> result = lang_str3 + " World"
>>> print(result)  # Output: "Hello World"@en

__contains__(item)

Check if a substring exists within the LangString’s text.

Parameters:: item (str) – The substring to check.
Returns:: True if the substring exists within the text, otherwise False.
Return type:: bool

Example:

>>> lang_str = LangString("Hello, World!", "en")
>>> contains = "World" in lang_str
>>> print(contains)  # Output: True

>>> contains = "Python" in lang_str
>>> print(contains)  # Output: False

__eq__(other)

Check equality of this LangString with another object.

Parameters:: other (object) – Another object to compare with.
Returns:: True if the objects are equal, otherwise False.
Return type:: bool

Example:

>>> lang_str1 = LangString("Hello, World!", "en")
>>> lang_str2 = LangString("Hello, World!", "en")
>>> is_equal = lang_str1 == lang_str2
>>> print(is_equal)  # Output: True

>>> lang_str3 = LangString("Hello, World!", "fr")
>>> is_equal = lang_str1 == lang_str3
>>> print(is_equal)  # Output: False

>>> is_equal = lang_str1 == "Hello, World!"
>>> print(is_equal)  # Output: True

>>> is_equal = lang_str1 == "Bonjour, Monde!"
>>> print(is_equal)  # Output: False

__ge__(other)

Check if this LangString is greater than or equal to another str or LangString object.

Parameters:

other (object) – The str or LangString object to compare with.

Returns:

True if this LangString is greater than or equal to the other, otherwise False.

Return type:

bool

Raises:

TypeError – If the objects are not compatible for comparison.
ValueError – If the language tags are incompatible.

Example:

>>> lang_str1 = LangString("banana", "en")
>>> lang_str2 = LangString("apple", "en")
>>> is_ge = lang_str1 >= lang_str2
>>> print(is_ge)  # Output: True

>>> lang_str3 = LangString("apple", "en")
>>> is_ge = lang_str2 >= lang_str3
>>> print(is_ge)  # Output: True

>>> is_ge = lang_str1 >= "banana"
>>> print(is_ge)  # Output: True

>>> is_ge = lang_str2 >= "cherry"
>>> print(is_ge)  # Output: False

__getitem__(key)

Retrieve a substring or a reversed string from the LangString’s text.

Parameters:: key (Union[int, slice]) – The index or slice to access.
Returns:: A new LangString with the substring or single character.
Return type:: LangString

Example:

>>> lang_str = LangString("hello, world", "en")
>>> substring = lang_str[0:5]
>>> print(substring)  # Output: "hello"@en

>>> single_char = lang_str[1]
>>> print(single_char)  # Output: "e"@en

__gt__(other)

Check if this LangString is greater than another LangString object.

Parameters:

other (object) – The str or LangString object to compare with.

Returns:

True if this LangString is greater than the other, otherwise False.

Return type:

bool

Raises:

TypeError – If the objects are not compatible for comparison.
ValueError – If the language tags are incompatible.

Example:

>>> lang_str1 = LangString("banana", "en")
>>> lang_str2 = LangString("apple", "en")
>>> is_gt = lang_str1 > lang_str2
>>> print(is_gt)  # Output: True

>>> lang_str3 = LangString("apple", "en")
>>> is_gt = lang_str2 > lang_str3
>>> print(is_gt)  # Output: False

>>> is_gt = lang_str1 > "apple"
>>> print(is_gt)  # Output: True

>>> is_gt = lang_str2 > "cherry"
>>> print(is_gt)  # Output: False

__hash__()

Generate a hash value for a LangString object.

The hash value is computed based on the text and a casefolded version of the language tag.

Returns:: The hash value of the LangString object, based on its text and language tag.
Return type:: int

Example:

>>> lang_str = LangString("hello", "en")
>>> hash_value = hash(lang_str)
>>> print(hash_value)  # Output: A unique integer representing the hash value

__iadd__(other)

Implement in-place addition for LangString objects.

This method allows the LangString’s text to be concatenated with another LangString’s text or a regular string. The operation is only allowed if both LangString objects have the same language tag or if the other operand is a string.

Parameters:

other (Union[LangString, str]) – The LangString or string to add.

Returns:

A new LangString instance with the concatenated text.

Return type:

LangString

Raises:

TypeError – If the objects are not compatible for addition.
ValueError – If the language tags are incompatible.

Example:

>>> lang_str1 = LangString("Hello", "en")
>>> lang_str2 = LangString(" World", "en")
>>> lang_str1 += lang_str2
>>> print(lang_str1)  # Output: "Hello World"@en

>>> lang_str1 += "!"
>>> print(lang_str1)  # Output: "Hello World!"@en

__imul__(other)

Implement in-place multiplication of the LangString’s text.

This method allows the LangString’s text to be repeated a specified number of times.

Parameters:: other (int) – The number of times to repeat the text.
Returns:: The same LangString instance with the text repeated.
Return type:: LangString
Raises:: TypeError – If the operand is not an integer.

Example:

>>> lang_str = LangString("Hello", "en")
>>> lang_str *= 3
>>> print(lang_str)  # Output: "HelloHelloHello"@en

__iter__()

Enable iteration over the text part of the LangString.

This method allows the LangString to be iterable, returning each character in the text part one by one.

Returns:: An iterator over the characters in the text.
Return type:: Iterator[str]

Example:

>>> lang_str = LangString("Hello", "en")
>>> for char in lang_str:
...     print(char)
...
# Output:   H
#           e
#           l
#           l
#           o

__le__(other)

Check if this LangString is less than or equal to another LangString object or string.

This method compares the LangString’s text with another LangString’s text or a regular string.

Parameters:

other (object) – The LangString or string to compare with.

Returns:

True if this LangString’s text is less than or equal to the other text, otherwise False.

Return type:

bool

Raises:

TypeError – If the objects are not compatible for comparison.
ValueError – If the language tags are incompatible.

Example:

>>> lang_str1 = LangString("apple", "en")
>>> lang_str2 = LangString("banana", "en")
>>> print(lang_str1 <= lang_str2)  # Output: True
>>> print(lang_str1 <= "apple")  # Output: True

__len__()

Return the length of the LangString’s text.

Returns:: The length of the text.
Return type:: int

Example:

>>> lang_str = LangString("hello", "en")
>>> length = len(lang_str)
>>> print(length)  # Output: 5

__lt__(other)

Check if this LangString is less than another LangString object or string.

This method compares the LangString’s text with another LangString’s text or a regular string.

Parameters:

other (object) – The LangString or string to compare with.

Returns:

True if this LangString’s text is less than the other text, otherwise False.

Return type:

bool

Raises:

TypeError – If the objects are not compatible for comparison.
ValueError – If the language tags are incompatible.

Example:

>>> lang_str1 = LangString("apple", "en")
>>> lang_str2 = LangString("banana", "en")
>>> print(lang_str1 < lang_str2)  # Output: True
>>> print(lang_str1 < "banana")  # Output: True

__mul__(other)

Multiply the LangString’s text a specified number of times.

This method repeats the LangString’s text a specified number of times and returns a new LangString.

Parameters:: other (int) – The number of times to repeat the text.
Returns:: A new LangString with the text repeated.
Return type:: LangString
Raises:: TypeError – If the operand is not an integer.

Example:

>>> lang_str = LangString("hello", "en")
>>> multiplied_lang_str = lang_str * 3
>>> print(multiplied_lang_str)  # Output: "hellohellohello"@en

__radd__(other)

Handle concatenation when LangString is on the right side of the ‘+’ operator.

This method is only defined for ‘other’ of type string because the __add__ method is used when ‘other’ is a LangString. It concatenates the other’s text to the LangString’s text (in this order) and returns a string, which loses its language tag.

Parameters:: other (str) – The string to concatenate with.
Returns:: A new string with the concatenated text.
Return type:: str
Raises:: TypeError – If ‘other’ is not a string.

Example:

>>> lang_str = LangString("world", "en")
>>> result = "hello " + lang_str
>>> print(result)  # Output: 'hello world'

__repr__()

Return an unambiguous string representation of the LangString.

Returns:: The unambiguous string representation of the LangString.
Return type:: str

Example:

>>> lang_str = LangString("hello", "en")
>>> print(repr(lang_str))  # Output: 'LangString(text="hello", lang="en")'

__rmul__(other)

Implement right multiplication.

This method is called for the reversed operation of multiplication, i.e., when LangString is on the right side. It is typically used for repeating the LangString’s text a specified number of times.

Parameters:: other (int) – The number of times the LangString’s text should be repeated.
Returns:: A new LangString with the text repeated.
Return type:: LangString
Raises:: TypeError – If ‘other’ is not an integer.

Example:

>>> lang_str = LangString("hello", "en")
>>> multiplied_lang_str = 3 * lang_str
>>> print(multiplied_lang_str)  # Output: "hellohellohello"@en

__str__()

Define the string representation of the LangString object.

Returns:: The string representation of the LangString object.
Return type:: str

Example:

>>> lang_str = LangString("hello", "en")
>>> print(lang_str)  # Output: '"hello"@en'

static merge_langstrings(langstrings)

Merge duplicated LangStrings in a list based on content and language tags.

This method processes a list of LangString instances, identifying and merging duplicates based on their text and language tags. If there are multiple LangStrings with the same text but different language tag casings, the resulting LangString will use a casefolded version of the language tag.

Parameters:: langstrings (list[LangString]) – List of LangString instances to be merged.
Returns:: A list of merged LangString instances without duplicates.
Return type:: list[LangString]

Example:

>>> lang_str1 = LangString("Hello", "en")
>>> lang_str2 = LangString("Hello", "EN")
>>> lang_str3 = LangString("Bonjour", "fr")
>>> merged_list = LangString.merge_langstrings([lang_str1, lang_str2, lang_str3])
>>> for ls in merged_list:
...     print(ls)
...
>>> # Output: '"Hello"@en'
>>> #         '"Bonjour"@fr'

static print_list(langstring_list, print_quotes=None, separator='@', print_lang=None)

Print a string representation of a list of LangString instances using the to_string method with specified formatting options.

Parameters:

langstring_list (list[LangString]) – The list of LangString instances.
print_quotes (Optional[bool]) – If True, wrap the text in quotes. If None, use the default setting from the Controller.
separator (str) – The separator to use between the text and language tag.
print_lang (Optional[bool]) – If True, include the language tag. If None, use the default setting from the Controller.

Return type:

None

Example:

>>> lang_str1 = LangString("a", "b")
>>> lang_str2 = LangString("c", "d")
>>> ls_list = [lang_str1, lang_str2]
>>> LangString.print_list(ls_list)  # Output: ['"a"@b', '"c"@d']

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

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

This class provides functionality for storing, retrieving, and manipulating text strings in multiple languages. It uses a dictionary to maintain text entries associated with language tags, allowing efficient handling of multilingual content. The MultiLangString class supports operations like adding new entries, removing entries, and retrieving entries in specific languages or across all languages. Additionally, it allows setting a preferred language, which can be used as a default for text retrieval operations.

The behavior of this class is influenced by control flags set in the Controller, which can enforce constraints like valid language tags and non-empty text entries. The class integrates seamlessly with other components like LangString and SetLangString, providing a comprehensive solution for managing multilingual text data.

Variables:

mls_dict (Optional[dict[str, set[str]]]) – A dictionary representing the internal structure of the MultiLangString, where keys are language codes and values are sets of text entries.
pref_lang (str) – The preferred language for this MultiLangString. Defaults to “en”.

Parameters:

mls_dict (Optional[dict[str, set[str]]])
pref_lang (Optional[str])

property mls_dict: dict[str, set[str]]

Get the dictionary representing the internal structure of the MultiLangString.

Returns:: The dictionary where keys are language codes and values are sets of text entries.
Return type:: dict[str, set[str]]

property pref_lang: str

Get the preferred language for this MultiLangString.

Returns:: The preferred language as a string.
Return type:: str

add(arg)

Add an element to the MultiLangString.

This method determines the type of the argument and calls the appropriate add method.

Parameters:: arg (Union[tuple[str, str], LangString, SetLangString, MultiLangString]) – The element to add, which can be a tuple of (text, language), LangString, SetLangString, or MultiLangString.
Raises:: TypeError – If the argument is not of a supported type.
Return type:: None

Example:

>>> mls = MultiLangString()
>>> mls.add(("Hello", "en"))
>>> mls.add(LangString("Bonjour", "fr"))
>>> print(mls)  # Output: {'Hello'}@en, {'Bonjour'}@fr

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

Example:

>>> mls = MultiLangString()
>>> mls.add_entry("Hello", "en")
>>> mls.add_entry("Bonjour", "fr")
>>> print(mls)  # Output: {'Hello'}@en, {'Bonjour'}@fr

add_text_in_pref_lang(text)

Add a text entry to the preferred language.

Parameters:: text (str) – The text to be added to the preferred language.
Return type:: None

Example:

>>> mls = MultiLangString(pref_lang="en")
>>> mls.add_text_in_pref_lang("Hello")
>>> print(mls)  # Output: {'Hello'}@en

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

Example:

>>> mls = MultiLangString()
>>> langstring = LangString("Hello", "en")
>>> mls.add_langstring(langstring)
>>> print(mls)  # Output: {'Hello'}@en

add_setlangstring(setlangstring)

Add a SetLangString to the MultiLangString.

This method adds all text entries from a SetLangString to the MultiLangString under the specified language.

Parameters:: setlangstring (SetLangString) – The SetLangString object to be added, representing a text in a specific language.
Return type:: None

Example:

>>> mls = MultiLangString()
>>> setlangstring = SetLangString({"Hello", "Hi"}, "en")
>>> mls.add_setlangstring(setlangstring)
>>> print(mls)  # Output: {'Hello', 'Hi'}@en

add_multilangstring(multilangstring)

Add a MultiLangString to the MultiLangString.

This method adds all text entries from another MultiLangString to the current MultiLangString.

Parameters:: multilangstring (MultiLangString) – The MultiLangString object to be added.
Return type:: None

Example:

>>> mls1 = MultiLangString()
>>> mls2 = MultiLangString({"en": {"Hello"}, "fr": {"Bonjour"}})
>>> mls1.add_multilangstring(mls2)
>>> print(mls1)  # Output: {'Hello'}@en, {'Bonjour'}@fr

add_empty_lang(lang)

Add an empty language to the MultiLangString.

This method adds an empty set for the specified language to the MultiLangString if it does not already exist.

Parameters:: lang (str) – The language to add.
Return type:: None

Example:

>>> mls = MultiLangString()
>>> mls.add_empty_lang("en")
>>> print(mls)  # Output: {}@en

discard(arg, clean_empty=False)

Discard an entry, LangString, SetLangString, or MultiLangString from the MultiLangString.

This method discards the specified entry from the MultiLangString. It can handle tuples, LangString, SetLangString, or MultiLangString objects. Optionally, it can remove empty language entries after discarding.

Parameters:

arg (Union[tuple[str, str], LangString, SetLangString, MultiLangString]) – The entry to discard, which can be a tuple, LangString, SetLangString, or MultiLangString.
clean_empty (bool) – If True, remove empty language entries after discarding. Defaults to False.

Return type:

None

Example:

>>> mls = MultiLangString({"en": {"Hello"}, "fr": {"Bonjour"}})
>>> mls.discard(("Hello", "en"))
>>> print(mls)  # Output: {}@en, {'Bonjour'}@fr
>>> lang_str = LangString("Bonjour", "fr")
>>> mls.discard(lang_str)
>>> print(mls)  # Output: {}@en, {}@fr

discard_entry(text, lang, clean_empty=False)

Discard a text entry from a specified language in the MultiLangString.

This method removes the specified text entry from the set associated with the given language. If the set becomes empty and clean_empty is True, the language entry is removed.

Parameters:

text (str) – The text to discard.
lang (str) – The language of the text to discard.
clean_empty (bool) – If True, remove the language entry if it becomes empty. Defaults to False.

Return type:

None

Example:

>>> mls = MultiLangString({"en": {"Hello", "World"}, "fr": {"Bonjour"}})
>>> mls.discard_entry("Hello", "en")
>>> print(mls)  # Output: {'World'}@en, {'Bonjour'}@fr
>>> mls.discard_entry("World", "en", clean_empty=True)
>>> print(mls)  # Output: {'Bonjour'}@fr

discard_text_in_pref_lang(text, clean_empty=False)

Discard a text entry from the preferred language.

This method removes the specified text entry from the set associated with the preferred language. If the set becomes empty and clean_empty is True, the language entry is removed.

Parameters:

text (str) – The text to discard.
clean_empty (bool) – If True, remove the language entry if it becomes empty. Defaults to False.

Return type:

None

Example:

>>> mls = MultiLangString({"en": {"Hello", "World"}, "fr": {"Bonjour"}})
>>> mls.discard_text_in_pref_lang("Hello")
>>> print(mls)  # Output: {'World'}@en, {'Bonjour'}@fr
>>> mls.discard_text_in_pref_lang("World", clean_empty=True)
>>> print(mls)  # Output: {'Bonjour'}@fr

discard_langstring(langstring, clean_empty=False)

Discard a LangString from the MultiLangString.

This method removes the specified LangString from the set associated with its language. If the set becomes empty and clean_empty is True, the language entry is removed.

Parameters:

langstring (LangString) – The LangString object to discard.
clean_empty (bool) – If True, remove the language entry if it becomes empty. Defaults to False.

Return type:

None

Example:

>>> mls = MultiLangString({"en": {"Hello", "World"}, "fr": {"Bonjour"}})
>>> lang_str = LangString("Hello", "en")
>>> mls.discard_langstring(lang_str)
>>> print(mls)  # Output: {'World'}@en, {'Bonjour'}@fr
>>> lang_str = LangString("World", "en")
>>> mls.discard_langstring(lang_str, clean_empty=True)
>>> print(mls)  # Output: {'Bonjour'}@fr

discard_setlangstring(setlangstring, clean_empty=False)

Discard a SetLangString from the MultiLangString.

This method removes the specified SetLangString from the sets associated with its language. If the set becomes empty and clean_empty is True, the language entry is removed.

Parameters:

setlangstring (SetLangString) – The SetLangString object to discard.
clean_empty (bool) – If True, remove the language entry if it becomes empty. Defaults to False.

Return type:

None

Example:

>>> mls = MultiLangString({"en": {"Hello", "World"}, "fr": {"Bonjour"}})
>>> set_lang_str = SetLangString({"Hello", "World"}, "en")
>>> mls.discard_setlangstring(set_lang_str)
>>> print(mls)  # Output: {}@en, {'Bonjour'}@fr
>>> set_lang_str = SetLangString({"Bonjour"}, "fr")
>>> mls.discard_setlangstring(set_lang_str, clean_empty=True)
>>> print(mls)  # Output: {}@en

discard_multilangstring(multilangstring, clean_empty=False)

Discard a MultiLangString from the current MultiLangString.

This method removes the specified MultiLangString from the sets associated with its languages. If a set becomes empty and clean_empty is True, the language entry is removed.

Parameters:

multilangstring (MultiLangString) – The MultiLangString object to discard.
clean_empty (bool) – If True, remove empty language entries after discarding. Defaults to False.

Return type:

None

Example:

>>> mls = MultiLangString({"en": {"Hello", "World"}, "fr": {"Bonjour", "Salut"}})
>>> mls_to_discard = MultiLangString({"en": {"Hello"}, "fr": {"Salut"}})
>>> mls.discard_multilangstring(mls_to_discard)
>>> print(mls)  # Output: {'World'}@en, {'Bonjour'}@fr
>>> mls_to_discard = MultiLangString({"en": {"World"}, "fr": {"Bonjour"}})
>>> mls.discard_multilangstring(mls_to_discard, clean_empty=True)
>>> print(mls)  # Output: {}

discard_lang(lang)

Discard all entries for a specified language.

This method removes all entries associated with the given language from the MultiLangString.

Parameters:: lang (str) – The language to discard.
Return type:: None

Example:

>>> mls = MultiLangString({"en": {"Hello", "World"}, "fr": {"Bonjour", "Salut"}})
>>> mls.discard_lang("en")
>>> print(mls)  # Output: {'Bonjour', 'Salut'}@fr
>>> mls.discard_lang("fr")
>>> print(mls)  # Output: {}

remove(arg, clean_empty=False)

Remove an entry, LangString, SetLangString, or MultiLangString from the MultiLangString.

This method removes the specified entry from the MultiLangString. It can handle tuples, LangString, SetLangString, or MultiLangString objects. Optionally, it can remove empty language entries after removing.

Parameters:

arg (Union[tuple[str, str], LangString, SetLangString, MultiLangString]) – The entry to remove, which can be a tuple, LangString, SetLangString, or MultiLangString.
clean_empty (bool) – If True, remove empty language entries after removing. Defaults to False.

Return type:

None

Example:

>>> mls = MultiLangString({"en": {"Hello"}, "fr": {"Bonjour"}})
>>> mls.remove(("Hello", "en"))
>>> print(mls)  # Output: {}@en, {'Bonjour'}@fr
>>> lang_str = LangString("Bonjour", "fr")
>>> mls.remove(lang_str)
>>> print(mls)  # Output: {}@en, {}@fr

remove_entry(text, lang, clean_empty=False)

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.
clean_empty (bool) – If True, remove the language entry if it becomes empty. Defaults to False.

Return type:

None

Example:

>>> mls = MultiLangString({"en": {"Hello", "World"}, "fr": {"Bonjour"}})
>>> mls.remove_entry("Hello", "en")
>>> print(mls)  # Output: {'World'}@en, {'Bonjour'}@fr
>>> mls.remove_entry("World", "en", clean_empty=True)
>>> print(mls)  # Output: {'Bonjour'}@fr

remove_text_in_pref_lang(text, clean_empty=False)

Remove a text entry from the preferred language.

This method removes the specified text entry from the set associated with the preferred language. If the set becomes empty and clean_empty is True, the language entry is removed.

Parameters:

text (str) – The text to remove.
clean_empty (bool) – If True, remove the language entry if it becomes empty. Defaults to False.

Return type:

None

Example:

>>> mls = MultiLangString({"en": {"Hello", "World"}, "fr": {"Bonjour"}})
>>> mls.remove_text_in_pref_lang("Hello")
>>> print(mls)  # Output: {'World'}@en, {'Bonjour'}@fr
>>> mls.remove_text_in_pref_lang("World", clean_empty=True)
>>> print(mls)  # Output: {'Bonjour'}@fr

remove_langstring(langstring, clean_empty=False)

Remove a LangString from the MultiLangString.

This method removes the specified LangString from the set associated with its language. If the set becomes empty and clean_empty is True, the language entry is removed.

Parameters:

langstring (LangString) – The LangString object to remove.
clean_empty (bool) – If True, remove the language entry if it becomes empty. Defaults to False.

Return type:

None

Example:

>>> mls = MultiLangString({"en": {"Hello", "World"}, "fr": {"Bonjour"}})
>>> lang_str = LangString("Hello", "en")
>>> mls.remove_langstring(lang_str)
>>> print(mls)  # Output: {'World'}@en, {'Bonjour'}@fr
>>> lang_str = LangString("World", "en")
>>> mls.remove_langstring(lang_str, clean_empty=True)
>>> print(mls)  # Output: {'Bonjour'}@fr

remove_setlangstring(setlangstring, clean_empty=False)

Remove a SetLangString from the MultiLangString.

This method removes the specified SetLangString from the sets associated with its language. If the set becomes empty and clean_empty is True, the language entry is removed.

Parameters:

setlangstring (SetLangString) – The SetLangString object to remove.
clean_empty (bool) – If True, remove the language entry if it becomes empty. Defaults to False.

Return type:

None

Example:

>>> mls = MultiLangString({"en": {"Hello", "World"}, "fr": {"Bonjour"}})
>>> set_lang_str = SetLangString({"Hello", "World"}, "en")
>>> mls.remove_setlangstring(set_lang_str)
>>> print(mls)  # Output: {}@en, {'Bonjour'}@fr
>>> set_lang_str = SetLangString({"Bonjour"}, "fr")
>>> mls.remove_setlangstring(set_lang_str, clean_empty=True)
>>> print(mls)  # Output: {}@en

remove_multilangstring(multilangstring, clean_empty=False)

Remove a MultiLangString from the current MultiLangString.

This method removes the specified MultiLangString from the sets associated with its languages. If a set becomes empty and clean_empty is True, the language entry is removed.

Parameters:

multilangstring (MultiLangString) – The MultiLangString object to remove.
clean_empty (bool) – If True, remove empty language entries after removing. Defaults to False.

Return type:

None

Example:

>>> mls = MultiLangString({"en": {"Hello", "World"}, "fr": {"Bonjour", "Salut"}})
>>> mls_to_remove = MultiLangString({"en": {"Hello"}, "fr": {"Salut"}})
>>> mls.remove_multilangstring(mls_to_remove)
>>> print(mls)  # Output: {'World'}@en, {'Bonjour'}@fr
>>> mls_to_remove = MultiLangString({"en": {"World"}, "fr": {"Bonjour"}})
>>> mls.remove_multilangstring(mls_to_remove, clean_empty=True)
>>> print(mls)  # Output: {}

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

Example:

>>> mls = MultiLangString({"en": {"Hello", "World"}, "fr": {"Bonjour", "Salut"}})
>>> mls.remove_lang("en")
>>> print(mls)  # Output: {'Bonjour', 'Salut'}@fr
>>> mls.remove_lang("fr")
>>> print(mls)  # Output: {}

remove_empty_langs()

Remove all empty language entries from the dictionary.

This method checks for languages that have no associated text entries and removes them from the dictionary.

Example:

>>> mls = MultiLangString({"en": {"Hello"}, "fr": set()})
>>> mls.remove_empty_langs()
>>> print(mls)  # Output: {'Hello'}@en

Return type:: None

to_strings(langs=None, print_quotes=None, separator='@', print_lang=None)

Convert the MultiLangString to a list of formatted strings.

This method converts the text entries of the MultiLangString into a list of strings, optionally formatted with quotes and language tags. The resulting list of strings is sorted to generate a deterministic output.

Parameters:

langs (Optional[list[str]]) – A list of languages to include in the output. If None, includes all languages.
print_quotes (Optional[bool]) – If True, wraps the text in quotes. Defaults to the controller flag.
separator (str) – The separator between the text and the language tag. Defaults to “@”.
print_lang (Optional[bool]) – If True, includes the language tag in the output. Defaults to the controller flag.

Returns:

A sorted list of formatted strings.

Return type:

list[str]

Example:

>>> mls = MultiLangString({"en": {"Hello", "World"}, "fr": {"Bonjour"}})
>>> strings = mls.to_strings()
>>> print(strings)  # Output: ['"Bonjour"@fr', '"Hello"@en', '"World"@en']
>>> strings = mls.to_strings(print_quotes=False, print_lang=False)
>>> print(strings)  # Output: ['Bonjour', 'Hello', 'World']

to_langstrings(langs=None)

Convert the MultiLangString to a list of LangString objects.

This method converts the text entries of the MultiLangString into a list of LangString objects.

Parameters:: langs (Optional[list[str]]) – A list of languages to include in the output. If None, includes all languages.
Returns:: A list of LangString objects.
Return type:: list[LangString]

Example:

>>> mls = MultiLangString({"en": {"Hello", "World"}, "fr": {"Bonjour"}})
>>> langstrings = mls.to_langstrings()
>>> for langstring in langstrings:
...     print(langstring)
...
# Output:   "Hello"@en
#           "World"@en
#           "Bonjour"@fr

to_setlangstrings(langs=None)

Convert the MultiLangString to a list of SetLangString objects.

This method converts the text entries of the MultiLangString into a list of SetLangString objects.

Parameters:: langs (Optional[list[str]]) – A list of languages to include in the output. If None, includes all languages.
Returns:: A list of SetLangString objects.
Return type:: list[SetLangString]

Example:

>>> mls = MultiLangString({"en": {"Hello", "World"}, "fr": {"Bonjour"}})
>>> setlangstrings = mls.to_setlangstrings()
>>> for setlangstring in setlangstrings:
...     print(setlangstring)
...
# Output:   {'Hello', 'World'}@en
#           {'Bonjour'}@fr

count_entries_of_lang(lang)

Count the number of text entries for a given language.

This method returns the number of text entries associated with the specified language.

Parameters:: lang (str) – The language to count the entries for.
Returns:: The number of text entries for the specified language.
Return type:: int

Example:

>>> mls = MultiLangString({"en": {"Hello", "World"}, "fr": {"Bonjour"}})
>>> count = mls.count_entries_of_lang("en")
>>> print(count)  # Output: 2
>>> count = mls.count_entries_of_lang("fr")
>>> print(count)  # Output: 1

count_entries_per_lang()

Return the number of text entries for each language.

This method returns a dictionary with language codes as keys and the counts of text entries as values.

Returns:: A dictionary with language codes as keys and counts of text entries as values.
Return type:: dict[str, int]

Example:

>>> mls = MultiLangString({"en": {"Hello", "World"}, "fr": {"Bonjour"}})
>>> counts = mls.count_entries_per_lang()
>>> print(counts)  # Output: {'en': 2, 'fr': 1}

count_entries_total()

Return the total number of text entries across all languages.

This method returns the total count of text entries in the MultiLangString.

Returns:: The total number of text entries.
Return type:: int

Example:

>>> mls = MultiLangString({"en": {"Hello", "World"}, "fr": {"Bonjour"}})
>>> total_count = mls.count_entries_total()
>>> print(total_count)  # Output: 3

count_langs_total()

Count the total number of languages in the MultiLangString.

This method returns the number of unique languages in the MultiLangString.

Returns:: The total number of languages.
Return type:: int

Example:

>>> mls = MultiLangString({"en": {"Hello", "World"}, "fr": {"Bonjour"}})
>>> total_langs = mls.count_langs_total()
>>> print(total_langs)  # Output: 2

contains(arg)

Check if the MultiLangString contains the specified entry, LangString, SetLangString, or MultiLangString.

This method checks if the specified entry is present in the MultiLangString. It can handle tuples, LangString, SetLangString, or MultiLangString objects.

Parameters:: arg (Union[tuple[str, str], LangString, SetLangString, MultiLangString]) – The entry to check, which can be a tuple, LangString, SetLangString, or MultiLangString.
Returns:: True if the entry is present, False otherwise.
Return type:: bool

Example:

>>> mls = MultiLangString({"en": {"Hello"}, "fr": {"Bonjour"}})
>>> result = mls.contains(("Hello", "en"))
>>> print(result)  # Output: True
>>> lang_str = LangString("Bonjour", "fr")
>>> result = mls.contains(lang_str)
>>> print(result)  # Output: True
>>> set_lang_str = SetLangString({"Hello"}, "en")
>>> result = mls.contains(set_lang_str)
>>> print(result)  # Output: True
>>> mls_to_check = MultiLangString({"en": {"Hello"}, "fr": {"Bonjour"}})
>>> result = mls.contains(mls_to_check)
>>> print(result)  # Output: True

contains_entry(text, lang)

Check if a specific text entry exists in a given language.

This method checks if the specified text entry is present in the set associated with the given language.

Parameters:

text (str) – The text entry to check.
lang (str) – The language of the text entry.

Returns:

True if the text entry is present, False otherwise.

Return type:

bool

Example:

>>> mls = MultiLangString({"en": {"Hello"}, "fr": {"Bonjour"}})
>>> result = mls.contains_entry("Hello", "en")
>>> print(result)  # Output: True
>>> result = mls.contains_entry("Bonjour", "fr")
>>> print(result)  # Output: True
>>> result = mls.contains_entry("Hello", "fr")
>>> print(result)  # Output: False

contains_lang(lang)

Check if a specific language exists in the MultiLangString.

This method checks if the specified language is present in the MultiLangString.

Parameters:: lang (str) – The language to check.
Returns:: True if the language is present, False otherwise.
Return type:: bool

Example:

>>> mls = MultiLangString({"en": {"Hello"}, "fr": {"Bonjour"}})
>>> result = mls.contains_lang("en")
>>> print(result)  # Output: True
>>> result = mls.contains_lang("fr")
>>> print(result)  # Output: True
>>> result = mls.contains_lang("es")
>>> print(result)  # Output: False

contains_text_in_pref_lang(text)

Check if a specific text exists in the preferred language.

This method checks if the specified text entry is present in the set associated with the preferred language.

Parameters:: text (str) – The text entry to check.
Returns:: True if the text entry is present in the preferred language, False otherwise.
Return type:: bool

Example:

>>> mls = MultiLangString({"en": {"Hello"}, "fr": {"Bonjour"}})
>>> result = mls.contains_text_in_pref_lang("Hello")
>>> print(result)  # Output: True
>>> result = mls.contains_text_in_pref_lang("Bonjour")
>>> print(result)  # Output: False

contains_text_in_any_lang(text)

Check if a specific text exists in any language.

This method checks if the specified text entry is present in the sets associated with any language in the MultiLangString.

Parameters:: text (str) – The text entry to check.
Returns:: True if the text entry is present in any language, False otherwise.
Return type:: bool

Example:

>>> mls = MultiLangString({"en": {"Hello"}, "fr": {"Bonjour"}})
>>> result = mls.contains_text_in_any_lang("Hello")
>>> print(result)  # Output: True
>>> result = mls.contains_text_in_any_lang("Bonjour")
>>> print(result)  # Output: True
>>> result = mls.contains_text_in_any_lang("Hola")
>>> print(result)  # Output: False

contains_langstring(langstring)

Check if the given LangString’s text and language are part of this MultiLangString.

This method checks if the specified LangString is present in the set associated with its language.

Parameters:: langstring (LangString) – A LangString object to check.
Returns:: True if the LangString’s text is found within the specified language’s set; otherwise, False.
Return type:: bool

Example:

>>> mls = MultiLangString({"en": {"Hello"}, "fr": {"Bonjour"}})
>>> lang_str = LangString("Hello", "en")
>>> result = mls.contains_langstring(lang_str)
>>> print(result)  # Output: True
>>> lang_str = LangString("Hola", "es")
>>> result = mls.contains_langstring(lang_str)
>>> print(result)  # Output: False

contains_setlangstring(setlangstring)

Check if all texts and the language of a SetLangString are part of this MultiLangString.

This method checks if the specified SetLangString’s language exists and all its texts are found within the specified language’s set.

Parameters:: setlangstring (SetLangString) – A SetLangString object to check.
Returns:: True if the SetLangString’s language exists and all its texts are found within the specified language’s set; otherwise, False.
Return type:: bool

Example:

>>> mls = MultiLangString({"en": {"Hello", "World"}, "fr": {"Bonjour"}})
>>> set_lang_str = SetLangString({"Hello"}, "en")
>>> result = mls.contains_setlangstring(set_lang_str)
>>> print(result)  # Output: True
>>> set_lang_str = SetLangString({"Bonjour"}, "fr")
>>> result = mls.contains_setlangstring(set_lang_str)
>>> print(result)  # Output: True
>>> set_lang_str = SetLangString({"Hola"}, "es")
>>> result = mls.contains_setlangstring(set_lang_str)
>>> print(result)  # Output: False

contains_multilangstring(multilangstring)

Check if the current instance contains all languages and texts of another MultiLangString instance.

This method checks if all languages and their respective texts in the specified MultiLangString are contained in this instance.

Parameters:: multilangstring (MultiLangString) – The MultiLangString instance to check against.
Returns:: True if all languages and their respective texts in multilangstring are contained in this instance, False otherwise.
Return type:: bool

Example:

>>> mls = MultiLangString({"en": {"Hello", "World"}, "fr": {"Bonjour"}})
>>> mls_to_check = MultiLangString({"en": {"Hello"}, "fr": {"Bonjour"}})
>>> result = mls.contains_multilangstring(mls_to_check)
>>> print(result)  # Output: True
>>> mls_to_check = MultiLangString({"en": {"Hello"}, "fr": {"Salut"}})
>>> result = mls.contains_multilangstring(mls_to_check)
>>> print(result)  # Output: False

get_langs(casefold=False)

Return a list of all languages in the MultiLangString.

This method returns a list of all language codes present in the MultiLangString. If casefold is True, the language codes are returned in lowercase.

Parameters:: casefold (bool) – If True, return the language codes in lowercase. Defaults to False.
Returns:: A list of language codes.
Return type:: list[str]

Example:

>>> mls = MultiLangString({"en": {"Hello"}, "fr": {"Bonjour"}})
>>> langs = mls.get_langs()
>>> print(langs)  # Output: ['en', 'fr']
>>> langs_casefolded = mls.get_langs(casefold=True)
>>> print(langs_casefolded)  # Output: ['en', 'fr']

get_texts()

Return a sorted list of all texts in the MultiLangString.

This method returns a list of all text entries present in the MultiLangString, sorted in alphabetical order.

Returns:: A sorted list of text entries.
Return type:: list[str]

Example:

>>> mls = MultiLangString({"en": {"Hello", "World"}, "fr": {"Bonjour"}})
>>> texts = mls.get_texts()
>>> print(texts)  # Output: ['Bonjour', 'Hello', 'World']

get_langstring(text, lang)

Retrieve a LangString from the MultiLangString.

This method returns a LangString object if the specified text and language are present in the MultiLangString. If the text and language are not found, it returns a LangString with only the language set.

Parameters:

text (str) – The text entry to retrieve.
lang (str) – The language of the text entry.

Returns:

A LangString object with the specified text and language, or a LangString with only the language if not found.

Return type:

LangString

Example:

>>> mls = MultiLangString({"en": {"Hello"}, "fr": {"Bonjour"}})
>>> lang_str = mls.get_langstring("Hello", "en")
>>> print(lang_str)  # Output: "Hello"@en
>>> lang_str = mls.get_langstring("Hola", "es")
>>> print(lang_str)  # Output: ""@es

get_setlangstring(lang)

Retrieve a SetLangString from the MultiLangString.

This method returns a SetLangString object if the specified language is present in the MultiLangString. If the language is not found, it returns an empty SetLangString with the language set.

Parameters:: lang (str) – The language to retrieve the SetLangString for.
Returns:: A SetLangString object with the texts for the specified language, or an empty SetLangString if not found.
Return type:: SetLangString

Example:

>>> mls = MultiLangString({"en": {"Hello", "World"}, "fr": {"Bonjour"}})
>>> set_lang_str = mls.get_setlangstring("en")
>>> print(set_lang_str)  # Output: {'Hello', 'World'}@en
>>> set_lang_str = mls.get_setlangstring("es")
>>> print(set_lang_str)  # Output: {}es

get_multilangstring(langs)

Retrieve a MultiLangString containing only the specified languages.

This method returns a new MultiLangString object containing only the specified languages and their texts from the current MultiLangString.

Parameters:: langs (list[str]) – A list of languages to include in the new MultiLangString.
Returns:: A new MultiLangString object with the specified languages and their texts.
Return type:: MultiLangString

Example:

>>> mls = MultiLangString({"en": {"Hello", "World"}, "fr": {"Bonjour"}, "es": {"Hola"}})
>>> new_mls = mls.get_multilangstring(["en", "es"])
>>> print(new_mls)  # Output: {'Hello', 'World'}@en, {'Hola'}@es

pop_langstring(text, lang)

Remove and return a LangString from the MultiLangString.

This method removes the specified text entry and its language from the MultiLangString, and returns it as a LangString object. If the entry is not found, it returns None.

Parameters:

text (str) – The text entry to remove.
lang (str) – The language of the text entry.

Returns:

The removed LangString object, or None if the entry was not found.

Return type:

Optional[LangString]

Example:

>>> mls = MultiLangString({"en": {"Hello"}, "fr": {"Bonjour"}})
>>> lang_str = mls.pop_langstring("Hello", "en")
>>> print(lang_str)  # Output: "Hello"@en
>>> print(mls)  # Output: {}@en, {'Bonjour'}@fr,
>>> lang_str = mls.pop_langstring("Hola", "es")
>>> print(lang_str)  # Output: None
>>> print(mls)  # Output: {}@en, {'Bonjour'}@fr

pop_setlangstring(lang)

Remove and return a SetLangString from the MultiLangString.

This method removes all text entries associated with the specified language from the MultiLangString, and returns them as a SetLangString object. If the language is not found, it returns None.

Parameters:: lang (str) – The language to remove the SetLangString for.
Returns:: The removed SetLangString object, or None if the language was not found.
Return type:: Optional[SetLangString]

Example:

>>> mls = MultiLangString({"en": {"Hello", "World"}, "fr": {"Bonjour"}})
>>> set_lang_str = mls.pop_setlangstring("en")
>>> print(set_lang_str)  # Output: {'Hello', 'World'}@en
>>> print(mls)  # Output: {'Bonjour'}@fr
>>> set_lang_str = mls.pop_setlangstring("es")
>>> print(set_lang_str)  # Output: None
>>> print(mls)  # Output: {'Bonjour'}@fr

pop_multilangstring(langs)

Remove and return a MultiLangString containing the specified languages.

This method removes all text entries associated with the specified languages from the MultiLangString, and returns them as a new MultiLangString object.

Parameters:: langs (list[str]) – A list of languages to remove.
Returns:: A new MultiLangString object with the specified languages and their texts.
Return type:: MultiLangString

Example:

>>> mls = MultiLangString({"en": {"Hello", "World"}, "fr": {"Bonjour"}, "es": {"Hola"}})
>>> new_mls = mls.pop_multilangstring(["en", "es"])
>>> print(new_mls)  # Output: {'Hello', 'World'}@en, {'Hola'}@es
>>> print(mls)  # Output: {'Bonjour'}@fr

has_pref_lang_entries()

Check if there are any entries in the preferred language.

This method checks whether there are any text entries in the MultiLangString for the preferred language.

Returns:: True if there are entries in the preferred language, False otherwise.
Return type:: bool

Example:

>>> mls = MultiLangString({"en": {"Hello"}, "fr": {"Bonjour"}})
>>> has_entries = mls.has_pref_lang_entries()
>>> print(has_entries)  # Output: True
>>> mls.pop_setlangstring("en")
>>> has_entries = mls.has_pref_lang_entries()
>>> print(has_entries)  # Output: False

__contains__(lang)

Check if a language is in the MultiLangString.

This method mimics the behavior of the ‘in’ operator for dictionaries, allowing users to check if a language exists in the MultiLangString.

Parameters:: lang (str) – The language code to check for.
Returns:: True if the language is present, False otherwise.
Return type:: bool

Example:

>>> mls = MultiLangString({"en": {"Hello"}, "fr": {"Bonjour"}})
>>> print("en" in mls)  # Output: True
>>> print("es" in mls)  # Output: False

__delitem__(lang)

Allow deletion of language entries.

This method mimics the behavior of the ‘del’ operator for dictionaries, allowing users to delete a language entry from the MultiLangString.

Parameters:: lang (str) – The language code to delete.
Raises:: KeyError – If the language is not found in the MultiLangString.
Return type:: None

Example:

>>> mls = MultiLangString({"en": {"Hello"}, "fr": {"Bonjour"}})
>>> del mls["en"]
>>> print(mls)  # Output: {'Bonjour'}@fr
>>> del mls["es"]  # Raises KeyError

__eq__(other)

Check equality of this MultiLangString with another MultiLangString.

This method mimics the behavior of the ‘==’ operator for dictionaries, allowing users to compare two MultiLangString objects for equality based on their mls_dict attributes. 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

Example:

>>> mls1 = MultiLangString({"en": {"Hello"}, "fr": {"Bonjour"}})
>>> mls2 = MultiLangString({"en": {"Hello"}, "fr": {"Bonjour"}})
>>> print(mls1 == mls2)  # Output: True
>>> mls3 = MultiLangString({"en": {"Hi"}, "fr": {"Salut"}})
>>> print(mls1 == mls3)  # Output: False

__getitem__(lang)

Allow retrieval of entries by language.

This method mimics the behavior of the dictionary ‘getitem’ method, allowing users to retrieve the set of text entries associated with a specified language code from the MultiLangString. Raises KeyError if the language is not found.

Parameters:: lang (str) – The language code to retrieve entries for.
Returns:: A set of text entries associated with the specified language.
Return type:: set[str]
Raises:: KeyError – If the language is not found in the MultiLangString.

Example:

>>> mls = MultiLangString({"en": {"Hello", "World"}, "fr": {"Bonjour"}})
>>> print(mls["en"])  # Output: {'Hello', 'World'}
>>> print(mls["es"])  # Raises KeyError

__hash__()

Generate a hash value for a MultiLangString object.

This method mimics the behavior of the dictionary ‘hash’ method, allowing users to obtain a hash value for the MultiLangString. The hash is computed based on the ‘mls_dict’ attribute, ensuring that MultiLangString objects with the same content will have the same hash value. I.e., the pref_lang attribute is not considered in the hash creation.

Returns:: The hash value of the MultiLangString object.
Return type:: int

Example:

>>> mls1 = MultiLangString({"en": {"Hello", "World"}, "fr": {"Bonjour"}}, pref_lang="en")
>>> mls2 = MultiLangString({"en": {"Hello", "World"}, "fr": {"Bonjour"}}, pref_lang="pt")
>>> print(hash(mls1) == hash(mls2))  # Output: True

__iter__()

Allow iteration over the dictionary keys (language codes).

This method mimics the behavior of the dictionary ‘iter’ method, allowing users to iterate over the language codes present in the MultiLangString.

Returns:: An iterator over the language codes.
Return type:: iterator

Example:

>>> mls = MultiLangString({"en": {"Hello"}, "fr": {"Bonjour"}})
>>> for lang in mls:
>>>     print(lang)
>>> # Output:   en
>>> #           fr

__len__()

Return the number of languages in the dictionary.

This method mimics the behavior of the dictionary ‘len’ method, allowing users to get the number of language entries present in the MultiLangString.

Returns:: The number of language entries.
Return type:: int

Example:

>>> mls = MultiLangString({"en": {"Hello"}, "fr": {"Bonjour"}})
>>> print(len(mls))  # Output: 2

__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

Example:

>>> mls = MultiLangString({"en": {"Hello"}, "fr": {"Bonjour"}})
>>> print(repr(mls))
# Output: 'MultiLangString(mls_dict={'en': {'Hello'}, 'fr': {'Bonjour'}}, pref_lang='en')'

__reversed__()

Return a reverse iterator over the dictionary keys.

This method allows for iterating over the language codes in the MultiLangString in reverse order.

Returns:: A reverse iterator over the dictionary keys.
Return type:: reverse_iterator

Example:

>>> mls = MultiLangString({"en": {"Hello"}, "fr": {"Bonjour"}})
>>> reversed_langs = list(reversed(mls))
>>> print(reversed_langs)  # Output: ['fr', 'en']

__setitem__(lang, texts)

Allow setting entries by language.

This method allows for setting the text entries for a given language in the MultiLangString, mimicking dictionary behavior. If the language does not exist, it is added.

Parameters:

lang (str) – The language code.
texts (set[str]) – A set of text entries to associate with the language.

Return type:

None

Example:

>>> mls = MultiLangString()
>>> mls["en"] = {"Hello", "World"}
>>> mls["es"] = {"Hola"}
>>> print(mls)  # Output: {'Hello', 'World'}@en, {'Hola'}@es
>>> mls["en"] = {"Bye"}
>>> print(mls)  # Output: {'Bye'}@en, {'Hola'}@es

__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. The output is sorted alphabetically by language and then by text within each language.

Returns:: A string representation of the MultiLangString with language tags.
Return type:: str

Example:

>>> mls = MultiLangString({"en": {"World", "Hello"}, "fr": {"Bonjour"}})
>>> print(mls)  # Output: {'Hello', 'World'}@en, {'Bonjour'}@fr

static merge_multilangstrings(multilangstrings)

Merge multiple MultiLangString instances into a single MultiLangString.

This static method takes a list of MultiLangString instances and merges them into a single MultiLangString. The resulting MultiLangString contains all languages and texts from the provided instances. If the list is empty, an empty MultiLangString is returned.

Parameters:: multilangstrings (list[MultiLangString]) – A list of MultiLangString instances to merge.
Returns:: A new MultiLangString containing all languages and texts from the provided instances.
Return type:: MultiLangString

Example:

>>> mls1 = MultiLangString({"en": {"Hello"}, "fr": {"Bonjour"}})
>>> mls2 = MultiLangString({"es": {"Hola"}, "en": {"World"}})
>>> merged_mls = MultiLangString.merge_multilangstrings([mls1, mls2])
>>> print(merged_mls)  # Output: {'Hello', 'World'}@en, {'Hola'}@es, {'Bonjour'}@fr

class langstring.SetLangString(texts=None, lang='')

A class to encapsulate a set of strings with a common language tag.

This class provides functionality to associate a set of text strings with a single language tag, offering methods for set representation, element addition, removal, and various set operations. The behavior of this class is influenced by control flags from the Controller class, which can enforce non-empty text, valid language tags, and other constraints.

Many standard set methods are overridden to return SetLangString objects, allowing seamless integration and extended functionality. This design ensures that users can work with SetLangString instances similarly to regular sets.

Variables:

texts (set[str]) – The set of text strings.
lang (str) – The language tag for the set of texts.

Raises:

ValueError – If control flags enforce non-empty text and any text in the set is empty.
TypeError – If the types of parameters are incorrect based on validation.

Parameters:

texts (Optional[Union[set[str], list[str]]])
lang (str)

property texts: set[str]

Get the set of text strings.

Returns:: The set of text strings.
Return type:: set[str]

property lang: str

Get the language tag.

Returns:: The language tag.
Return type:: str

add_langstring(langstring)

Add a LangString object to the set of texts.

This method validates the type and language of the LangString object and adds its text to the set. The behavior is influenced by control flags set in the Controller.

Parameters:

langstring (LangString) – The LangString object to add.

Raises:

TypeError – If the provided langstring is not of type LangString.
ValueError – If the control flags enforce valid language tags and the langstring’s language tag is invalid, or if the language tag of the langstring does not match the set’s language tag.

Return type:

None

Example:

>>> set_lang_str = SetLangString({"Hello"}, "en")
>>> lang_str = LangString("World", "en")
>>> set_lang_str.add_langstring(lang_str)
>>> print(set_lang_str)  # Output: {'Hello', 'World'}@en

add_text(text)

Add a text string to the set of texts.

This method validates the type of the text string and adds it to the set. The behavior is influenced by control flags set in the Controller.

Parameters:

text (str) – The text string to add.

Raises:

TypeError – If the provided text is not of type str.
ValueError – If the control flags enforce non-empty text and the text string is empty.

Return type:

None

Example:

>>> set_lang_str = SetLangString({"Hello"}, "en")
>>> set_lang_str.add_text("World")
>>> print(set_lang_str)  # Output: {'Hello', 'World'}@en

discard_text(text)

Discard a text string from the set of texts.

This method removes the text string from the set if it is present. If the text string is not present, the set remains unchanged. The method does not raise an error if the text is not found.

Parameters:: text (str) – The text string to discard.
Raises:: TypeError – If the provided text is not of type str.
Return type:: None

Example:

>>> set_lang_str = SetLangString({"Hello", "World"}, "en")
>>> set_lang_str.discard_text("World")
>>> print(set_lang_str)  # Output: {'Hello'}@en
>>> set_lang_str.discard_text("Python")
>>> print(set_lang_str)  # Output: {'Hello'}@en

discard_langstring(langstring)

Discard a LangString object from the set of texts.

This method validates the type and language of the LangString object and removes its text from the set if it is present. If the text is not present, the set remains unchanged. The method does not raise an error if the text is not found.

Parameters:

langstring (LangString) – The LangString object to discard.

Raises:

TypeError – If the provided langstring is not of type LangString.
ValueError – If the language tag of the langstring does not match the set’s language tag.

Return type:

None

Example:

>>> set_lang_str = SetLangString({"Hello", "World"}, "en")
>>> lang_str = LangString("World", "en")
>>> set_lang_str.discard_langstring(lang_str)
>>> print(set_lang_str)  # Output: {'Hello'}@en
>>> lang_str = LangString("Python", "en")
>>> set_lang_str.discard_langstring(lang_str)
>>> print(set_lang_str)  # Output: {'Hello'}@en

remove_langstring(langstring)

Remove a text string from the set of texts.

This method removes the text string from the set. If the text string is not present, a KeyError is raised.

Parameters:

text (str) – The text string to remove.
langstring (langstring.langstring.LangString)

Raises:

TypeError – If the provided text is not of type str.
KeyError – If the text string is not found in the set.

Return type:

None

Example:

>>> set_lang_str = SetLangString({"Hello", "World"}, "en")
>>> set_lang_str.remove_text("World")
>>> print(set_lang_str)  # Output: {'Hello'}@en
>>> set_lang_str.remove_text("Python")  # Raises KeyError

remove_text(text)

Remove a LangString object from the set of texts.

This method validates the type and language of the LangString object and removes its text from the set. If the text is not present, a KeyError is raised.

Parameters:

langstring (LangString) – The LangString object to remove.
text (str)

Raises:

TypeError – If the provided langstring is not of type LangString.
ValueError – If the language tag of the langstring does not match the set’s language tag.
KeyError – If the text string is not found in the set.

Return type:

None

Example:

>>> set_lang_str = SetLangString({"Hello", "World"}, "en")
>>> lang_str = LangString("World", "en")
>>> set_lang_str.remove_langstring(lang_str)
>>> print(set_lang_str)  # Output: {'Hello'}@en
>>> lang_str = LangString("Python", "en")
>>> set_lang_str.remove_langstring(lang_str)  # Raises KeyError

to_langstrings()

Convert the set of texts to a list of LangString objects.

This method creates a LangString object for each text in the set, associating it with the set’s language tag.

Returns:: A list of LangString objects.
Return type:: list[LangString]

Example:

>>> set_lang_str = SetLangString({"Hello", "World"}, "en")
>>> langstrings = set_lang_str.to_langstrings()
>>> for lang_str in langstrings:
...     print(lang_str)
...
# Output:
# "Hello"@en
# "World"en

to_strings(print_quotes=None, separator='@', print_lang=None)

Convert the set of texts to a list of formatted strings.

Converts each text in the set to a formatted string, optionally including quotes and the language tag. The behavior is influenced by control flags set in the Controller. The resulting list of strings is sorted to generate a deterministic output.

Parameters:

print_quotes (Optional[bool]) – If True, wrap the text in quotes. If None, use the default setting from the Controller.
separator (str) – The separator to use between the text and language tag.
print_lang (Optional[bool]) – If True, include the language tag. If None, use the default setting from the Controller.

Returns:

A sorted list of formatted strings.

Return type:

list[str]

Example:

>>> set_lang_str = SetLangString({"Hello", "World"}, "en")
>>> strings = set_lang_str.to_strings()
>>> for s in strings:
...     print(s)
...
# Output:
# "Hello"@en
# "World"@en
>>> strings = set_lang_str.to_strings(print_quotes=False, print_lang=False)
>>> for s in strings:
...     print(s)
...
# Output:
# Hello
# World

add(new_element)

Add a new element to the set of texts.

This method adds a new element, which can be a string or a LangString object, to the set. It mimics the behavior of the standard set’s add method, allowing for seamless integration and extended functionality. The behavior is influenced by control flags set in the Controller.

Parameters:

new_element (Union[str, LangString]) – The element to add, either a text string or a LangString object.

Raises:

TypeError – If the provided new_element is neither a str nor a LangString.
ValueError – If the control flags enforce valid language tags and the new_element’s language tag is invalid, or if the language tag of the new_element does not match the set’s language tag.

Return type:

None

Example:

>>> set_lang_str = SetLangString({"Hello"}, "en")
>>> set_lang_str.add("World")
>>> print(set_lang_str)  # Output: {'Hello', 'World'}@en
>>> lang_str = LangString("New String", "en")
>>> set_lang_str.add(lang_str)
>>> print(set_lang_str)  # Output: {'Hello', 'New String', 'World'}@en

clear()

Remove all elements from the set of texts.

This method clears all elements from the set, mimicking the behavior of the standard set’s clear method, resulting in an empty set.

Example:

>>> set_lang_str = SetLangString({"Hello", "World"}, "en")
>>> set_lang_str.clear()
>>> print(set_lang_str)  # Output: {}@en

Return type:: None

copy()

Create a shallow copy of the SetLangString.

This method returns a new SetLangString object that is a shallow copy of the original, mimicking the behavior of the standard set’s copy method.

Returns:: A shallow copy of the SetLangString.
Return type:: SetLangString

Example:

>>> set_lang_str = SetLangString({"Hello", "World"}, "en")
>>> copied_set_lang_str = set_lang_str.copy()
>>> print(copied_set_lang_str)  # Output: {'Hello', 'World'}@en

discard(element)

Discard an element from the set of texts.

This method removes the element from the set if it is present. If the element is not present, the set remains unchanged. It mimics the behavior of the standard set’s discard method and does not raise an error if the element is not found.

Parameters:

element (Union[str, LangString]) – The element to discard, either a text string or a LangString object.

Raises:

TypeError – If the provided element is neither a str nor a LangString.
ValueError – If the language tag of the LangString does not match the set’s language tag.

Return type:

None

Example:

>>> set_lang_str = SetLangString({"Hello", "World"}, "en")
>>> set_lang_str.discard("World")
>>> print(set_lang_str)  # Output: {'Hello'}@en
>>> lang_str = LangString("Python", "en")
>>> set_lang_str.discard(lang_str)
>>> print(set_lang_str)  # Output: {'Hello'}@en

pop()

Remove and return an arbitrary element from the set of texts.

This method removes and returns an arbitrary element from the set, mimicking the behavior of the standard set’s pop method. If the set is empty, a KeyError is raised.

Returns:: An arbitrary element from the set.
Return type:: str
Raises:: KeyError – If the set is empty.

Example:

>>> set_lang_str = SetLangString({"Hello", "World"}, "en")
>>> element = set_lang_str.pop()
>>> print(element)  # Output: 'Hello' or 'World'
>>> print(set_lang_str)  # Output: {'World'}@en or {'Hello'}@en

remove(element)

Remove an element from the set of texts.

This method removes the specified element from the set. If the element is not present, a KeyError is raised. It mimics the behavior of the standard set’s remove method.

Parameters:

element (Union[str, LangString]) – The element to remove, either a text string or a LangString object.

Raises:

TypeError – If the provided element is neither a str nor a LangString.
ValueError – If the language tag of the LangString does not match the set’s language tag.
KeyError – If the element is not found in the set.

Return type:

None

Example:

>>> set_lang_str = SetLangString({"Hello", "World"}, "en")
>>> set_lang_str.remove("World")
>>> print(set_lang_str)  # Output: {'Hello'}@en
>>> lang_str = LangString("Python", "en")
>>> set_lang_str.remove(lang_str)  # Raises KeyError

difference(*others)

Return the difference of the set and another set or sets.

This method returns a new SetLangString containing elements that are in the set but not in the others. It mimics the behavior of the standard set’s difference method.

Parameters:: others (Union[set[str], SetLangString]) – One or more sets or SetLangString objects to compute the difference with.
Returns:: A new SetLangString containing the difference of the sets.
Return type:: SetLangString
Raises:: ValueError – If the language tag of any SetLangString in others does not match the set’s language tag.

Example:

>>> set_lang_str1 = SetLangString({"Hello", "World"}, "en")
>>> set_lang_str2 = SetLangString({"World", "Python"}, "en")
>>> diff_set_lang_str = set_lang_str1.difference(set_lang_str2)
>>> print(diff_set_lang_str)  # Output: {'Hello'}@en

difference_update(*others)

Update the set, removing elements found in others.

This method updates the set, removing all elements that are also in another set or sets. It mimics the behavior of the standard set’s difference_update method.

Parameters:: others (Union[set[str], SetLangString]) – One or more sets or SetLangString objects to compute the difference with.
Raises:: ValueError – If the language tag of any SetLangString in others does not match the set’s language tag.
Return type:: None

Example:

>>> set_lang_str1 = SetLangString({"Hello", "World"}, "en")
>>> set_lang_str2 = SetLangString({"World", "Python"}, "en")
>>> set_lang_str1.difference_update(set_lang_str2)
>>> print(set_lang_str1)  # Output: {'Hello'}@en

isdisjoint(other)

Return True if the set has no elements in common with another set.

This method checks if the set has no elements in common with another set or SetLangString, mimicking the behavior of the standard set’s isdisjoint method.

Parameters:: other (Union[set[str], SetLangString]) – The other set or SetLangString to compare with.
Returns:: True if the sets are disjoint, False otherwise.
Return type:: bool
Raises:: ValueError – If the language tag of the SetLangString in other does not match the set’s language tag.

Example:

>>> set_lang_str1 = SetLangString({"Hello", "World"}, "en")
>>> set_lang_str2 = SetLangString({"Python", "Java"}, "en")
>>> disjoint = set_lang_str1.isdisjoint(set_lang_str2)
>>> print(disjoint)  # Output: True

issubset(other)

Return True if the set is a subset of another set.

This method checks if the set is a subset of another set or SetLangString, mimicking the behavior of the standard set’s issubset method.

Parameters:: other (Union[set[str], SetLangString]) – The other set or SetLangString to compare with.
Returns:: True if the set is a subset, False otherwise.
Return type:: bool
Raises:: ValueError – If the language tag of the SetLangString in other does not match the set’s language tag.

Example:

>>> set_lang_str1 = SetLangString({"Hello"}, "en")
>>> set_lang_str2 = SetLangString({"Hello", "World"}, "en")
>>> subset = set_lang_str1.issubset(set_lang_str2)
>>> print(subset)  # Output: True

issuperset(other)

Return True if the set is a superset of another set.

This method checks if the set is a superset of another set or SetLangString, mimicking the behavior of the standard set’s issuperset method.

Parameters:: other (Union[set[str], SetLangString]) – The other set or SetLangString to compare with.
Returns:: True if the set is a superset, False otherwise.
Return type:: bool
Raises:: ValueError – If the language tag of the SetLangString in other does not match the set’s language tag.

Example:

>>> set_lang_str1 = SetLangString({"Hello", "World"}, "en")
>>> set_lang_str2 = SetLangString({"Hello"}, "en")
>>> superset = set_lang_str1.issuperset(set_lang_str2)
>>> print(superset)  # Output: True

intersection(*others)

Return the intersection of the set and other sets.

This method returns a new SetLangString containing elements that are common to the set and all of the others. It mimics the behavior of the standard set’s intersection method.

Parameters:: others (Union[set[str], SetLangString]) – One or more sets or SetLangString objects to compute the intersection with.
Returns:: A new SetLangString containing the intersection of the sets.
Return type:: SetLangString
Raises:: ValueError – If the language tag of any SetLangString in others does not match the set’s language tag.

Example:

>>> set_lang_str1 = SetLangString({"Hello", "World"}, "en")
>>> set_lang_str2 = SetLangString({"World", "Python"}, "en")
>>> intersect_set_lang_str = set_lang_str1.intersection(set_lang_str2)
>>> print(intersect_set_lang_str)  # Output: {'World'}@en

intersection_update(*others)

Update the set, keeping only elements found in it and all others.

This method updates the set, keeping only elements that are common to the set and all of the others. It mimics the behavior of the standard set’s intersection_update method.

Parameters:: others (Union[set[str], SetLangString]) – One or more sets or SetLangString objects to compute the intersection with.
Raises:: ValueError – If the language tag of any SetLangString in others does not match the set’s language tag.
Return type:: None

Example:

>>> set_lang_str1 = SetLangString({"Hello", "World"}, "en")
>>> set_lang_str2 = SetLangString({"World", "Python"}, "en")
>>> set_lang_str1.intersection_update(set_lang_str2)
>>> print(set_lang_str1)  # Output: {'World'}@en

symmetric_difference(other)

Return the symmetric difference of the set and another set.

This method returns a new SetLangString containing elements that are in either the set or the other set, but not in both. It mimics the behavior of the standard set’s symmetric_difference method.

Parameters:: other (Union[set[str], SetLangString]) – The other set or SetLangString to compare with.
Returns:: A new SetLangString containing the symmetric difference of the sets.
Return type:: SetLangString
Raises:: ValueError – If the language tag of the SetLangString in other does not match the set’s language tag.

Example:

>>> set_lang_str1 = SetLangString({"Hello", "World"}, "en")
>>> set_lang_str2 = SetLangString({"World", "Python"}, "en")
>>> sym_diff_set_lang_str = set_lang_str1.symmetric_difference(set_lang_str2)
>>> print(sym_diff_set_lang_str)  # Output: {'Hello', 'Python'}@en

symmetric_difference_update(other)

Update the set, keeping only elements found in either set, but not in both.

This method updates the set, keeping only elements that are in either the set or the other set, but not in both. It mimics the behavior of the standard set’s symmetric_difference_update method.

Parameters:: other (Union[set[str], SetLangString]) – The other set or SetLangString to compare with.
Raises:: ValueError – If the language tag of the SetLangString in other does not match the set’s language tag.
Return type:: None

Example:

>>> set_lang_str1 = SetLangString({"Hello", "World"}, "en")
>>> set_lang_str2 = SetLangString({"World", "Python"}, "en")
>>> set_lang_str1.symmetric_difference_update(set_lang_str2)
>>> print(set_lang_str1)  # Output: {'Hello', 'Python'}@en

union(*others)

Return the union of the set and other sets.

This method returns a new SetLangString containing all elements that are in the set, in others, or in both. It mimics the behavior of the standard set’s union method.

Parameters:: others (Union[set[str], SetLangString]) – One or more sets or SetLangString objects to compute the union with.
Returns:: A new SetLangString containing the union of the sets.
Return type:: SetLangString
Raises:: ValueError – If the language tag of any SetLangString in others does not match the set’s language tag.

Example:

>>> set_lang_str1 = SetLangString({"Hello"}, "en")
>>> set_lang_str2 = SetLangString({"World"}, "en")
>>> union_set_lang_str = set_lang_str1.union(set_lang_str2)
>>> print(union_set_lang_str)  # Output: {'Hello', 'World'}@en

update(*others)

Update the set, adding elements from all others.

This method updates the set, adding all elements that are in others. It mimics the behavior of the standard set’s update method.

Parameters:: others (Union[set[str], SetLangString]) – One or more sets or SetLangString objects to update the set with.
Raises:: ValueError – If the language tag of any SetLangString in others does not match the set’s language tag.
Return type:: None

Example:

>>> set_lang_str1 = SetLangString({"Hello"}, "en")
>>> set_lang_str2 = SetLangString({"World"}, "en")
>>> set_lang_str1.update(set_lang_str2)
>>> print(set_lang_str1)  # Output: {'Hello', 'World'}@en

__and__(other)

Return the intersection of the set and another set.

This method returns a new SetLangString containing elements that are common to the set and the other set. It mimics the behavior of the standard set’s __and__ method (set intersection operator &).

Parameters:: other (Union[set[str], SetLangString]) – The other set or SetLangString to intersect with.
Returns:: A new SetLangString containing the intersection of the sets.
Return type:: SetLangString
Raises:: ValueError – If the language tag of the SetLangString in other does not match the set’s language tag.

Example:

>>> set_lang_str1 = SetLangString({"Hello", "World"}, "en")
>>> set_lang_str2 = SetLangString({"World", "Python"}, "en")
>>> intersect_set_lang_str = set_lang_str1 & set_lang_str2
>>> print(intersect_set_lang_str)  # Output: {'World'}@en

__contains__(element)

Return True if the set contains the specified element.

This method checks if the specified element is in the set, mimicking the behavior of the standard set’s __contains__ method (membership test operator in).

Parameters:

element (Union[str, LangString]) – The element to check for membership, either a text string or a LangString object.

Returns:

True if the element is in the set, False otherwise.

Return type:

bool

Raises:

TypeError – If the provided element is neither a str nor a LangString.
ValueError – If the language tag of the LangString does not match the set’s language tag.

Example:

>>> set_lang_str = SetLangString({"Hello", "World"}, "en")
>>> contains_hello = "Hello" in set_lang_str
>>> print(contains_hello)  # Output: True
>>> lang_str = LangString("Python", "en")
>>> contains_python = lang_str in set_lang_str
>>> print(contains_python)  # Output: False

__eq__(other)

Return True if the set is equal to another set.

This method checks if the set is equal to another SetLangString, mimicking the behavior of the standard set’s __eq__ method (equality operator ==).

Parameters:: other (object) – The other SetLangString to compare with.
Returns:: True if the sets are equal, False otherwise.
Return type:: bool
Raises:: NotImplementedError – If the other object is not a SetLangString.

Example:

>>> set_lang_str1 = SetLangString({"Hello", "World"}, "en")
>>> set_lang_str2 = SetLangString({"World", "Hello"}, "en")
>>> is_equal = set_lang_str1 == set_lang_str2
>>> print(is_equal)  # Output: True

__ge__(other)

Return True if the set is a superset of another set.

This method checks if the set is a superset of another set or SetLangString, mimicking the behavior of the standard set’s __ge__ method (superset operator >=).

Parameters:: other (Union[set[str], SetLangString]) – The other set or SetLangString to compare with.
Returns:: True if the set is a superset, False otherwise.
Return type:: bool
Raises:: ValueError – If the language tag of the SetLangString in other does not match the set’s language tag.

Example:

>>> set_lang_str1 = SetLangString({"Hello", "World"}, "en")
>>> set_lang_str2 = SetLangString({"Hello"}, "en")
>>> is_superset = set_lang_str1 >= set_lang_str2
>>> print(is_superset)  # Output: True

__gt__(other)

Return True if the set is a proper superset of another set.

This method checks if the set is a proper superset of another set or SetLangString, mimicking the behavior of the standard set’s __gt__ method (proper superset operator >).

Parameters:: other (Union[set[str], SetLangString]) – The other set or SetLangString to compare with.
Returns:: True if the set is a proper superset, False otherwise.
Return type:: bool
Raises:: ValueError – If the language tag of the SetLangString in other does not match the set’s language tag.

Example:

>>> set_lang_str1 = SetLangString({"Hello", "World"}, "en")
>>> set_lang_str2 = SetLangString({"Hello"}, "en")
>>> is_proper_superset = set_lang_str1 > set_lang_str2
>>> print(is_proper_superset)  # Output: True

__hash__()

Generate a hash for a SetLangString object.

This method generates a hash value for the SetLangString object, mimicking the behavior of the standard set’s __hash__ method. The set of texts is converted to a frozenset for hashing, as sets are mutable and unhashable.

Returns:: The hash value of the SetLangString object.
Return type:: int

Example:

>>> set_lang_str = SetLangString({"Hello", "World"}, "en")
>>> hash_value = hash(set_lang_str)
>>> print(hash_value)  # Output: A unique integer representing the hash value

__iand__(other)

Update the set, keeping only elements found in it and another set.

This method updates the set, keeping only elements that are common to the set and the other set, mimicking the behavior of the standard set’s __iand__ method (in-place intersection operator &=).

Parameters:: other (Union[set[str], SetLangString]) – The other set or SetLangString to intersect with.
Returns:: The updated SetLangString.
Return type:: SetLangString
Raises:: ValueError – If the language tag of the SetLangString in other does not match the set’s language tag.

Example:

>>> set_lang_str1 = SetLangString({"Hello", "World"}, "en")
>>> set_lang_str2 = SetLangString({"World", "Python"}, "en")
>>> set_lang_str1 &= set_lang_str2
>>> print(set_lang_str1)  # Output: {'World'}@en

__ior__(other)

Update the set, adding elements from another set.

This method updates the set, adding all elements that are in the other set, mimicking the behavior of the standard set’s __ior__ method (in-place union operator |=).

Parameters:: other (Union[set[str], SetLangString]) – The other set or SetLangString to union with.
Returns:: The updated SetLangString.
Return type:: SetLangString
Raises:: ValueError – If the language tag of the SetLangString in other does not match the set’s language tag.

Example:

>>> set_lang_str1 = SetLangString({"Hello"}, "en")
>>> set_lang_str2 = SetLangString({"World"}, "en")
>>> set_lang_str1 |= set_lang_str2
>>> print(set_lang_str1)  # Output: {'Hello', 'World'}@en

__isub__(other)

Update the set, removing elements found in another set.

This method updates the set, removing all elements that are also in the other set, mimicking the behavior of the standard set’s __isub__ method (in-place difference operator -=).

Parameters:: other (Union[set[str], SetLangString]) – The other set or SetLangString to difference with.
Returns:: The updated SetLangString.
Return type:: SetLangString
Raises:: ValueError – If the language tag of the SetLangString in other does not match the set’s language tag.

Example:

>>> set_lang_str1 = SetLangString({"Hello", "World"}, "en")
>>> set_lang_str2 = SetLangString({"World"}, "en")
>>> set_lang_str1 -= set_lang_str2
>>> print(set_lang_str1)  # Output: {'Hello'}@en

__iter__()

Return an iterator over the elements of the set.

This method returns an iterator over the elements of the set, mimicking the behavior of the standard set’s __iter__ method.

Returns:: An iterator over the elements of the set.
Return type:: Iterator[str]

Example:

>>> set_lang_str = SetLangString({"Hello", "World"}, "en")
>>> for text in set_lang_str:
...     print(text)
...
# Output: 'Hello'
#         'World'

__ixor__(other)

Update the set, keeping only elements found in either set, but not in both.

This method updates the set, keeping only elements that are in either the set or the other set, but not in both, mimicking the behavior of the standard set’s __ixor__ method (in-place symmetric difference operator ^=).

Parameters:: other (Union[set[str], SetLangString]) – The other set or SetLangString to symmetric difference with.
Returns:: The updated SetLangString.
Return type:: SetLangString
Raises:: ValueError – If the language tag of the SetLangString in other does not match the set’s language tag.

Example:

>>> set_lang_str1 = SetLangString({"Hello", "World"}, "en")
>>> set_lang_str2 = SetLangString({"World", "Python"}, "en")
>>> set_lang_str1 ^= set_lang_str2
>>> print(set_lang_str1)  # Output: {'Hello', 'Python'}@en

__le__(other)

Return True if the set is a subset of another set.

This method checks if the set is a subset of another set or SetLangString, mimicking the behavior of the standard set’s __le__ method (subset operator <=).

Parameters:: other (Union[set[str], SetLangString]) – The other set or SetLangString to compare with.
Returns:: True if the set is a subset, False otherwise.
Return type:: bool
Raises:: ValueError – If the language tag of the SetLangString in other does not match the set’s language tag.

Example:

>>> set_lang_str1 = SetLangString({"Hello"}, "en")
>>> set_lang_str2 = SetLangString({"Hello", "World"}, "en")
>>> is_subset = set_lang_str1 <= set_lang_str2
>>> print(is_subset)  # Output: True

__len__()

Return the number of elements in the set.

This method returns the number of elements in the set, mimicking the behavior of the standard set’s __len__ method.

Returns:: The number of elements in the set.
Return type:: int

Example:

>>> set_lang_str = SetLangString({"Hello", "World"}, "en")
>>> length = len(set_lang_str)
>>> print(length)  # Output: 2

__lt__(other)

Return True if the set is a proper subset of another set.

This method checks if the set is a proper subset of another set or SetLangString, mimicking the behavior of the standard set’s __lt__ method (proper subset operator <).

Parameters:: other (Union[set[str], SetLangString]) – The other set or SetLangString to compare with.
Returns:: True if the set is a proper subset, False otherwise.
Return type:: bool
Raises:: ValueError – If the language tag of the SetLangString in other does not match the set’s language tag.

Example:

>>> set_lang_str1 = SetLangString({"Hello"}, "en")
>>> set_lang_str2 = SetLangString({"Hello", "World"}, "en")
>>> is_proper_subset = set_lang_str1 < set_lang_str2
>>> print(is_proper_subset)  # Output: True

__or__(other)

Return the union of the set and another set.

This method returns a new SetLangString containing all elements that are in the set, in the other set, or in both. It mimics the behavior of the standard set’s __or__ method (union operator |).

Parameters:: other (Union[set[str], SetLangString]) – The other set or SetLangString to union with.
Returns:: A new SetLangString containing the union of the sets.
Return type:: SetLangString
Raises:: ValueError – If the language tag of the SetLangString in other does not match the set’s language tag.

Example:

>>> set_lang_str1 = SetLangString({"Hello"}, "en")
>>> set_lang_str2 = SetLangString({"World"}, "en")
>>> union_set_lang_str = set_lang_str1 | set_lang_str2
>>> print(union_set_lang_str)  # Output: {'Hello', 'World'}@en

__repr__()

Return the official string representation of the SetLangString object.

This method returns an official string representation of the SetLangString object, mimicking the behavior of the standard set’s __repr__ method. This representation can be used for debugging and logging.

Returns:: The official string representation of the SetLangString object.
Return type:: str

Example:

>>> set_lang_str = SetLangString({"Hello", "World"}, "en")
>>> repr_str = repr(set_lang_str)
>>> print(repr_str)  # Output: SetLangString(texts={'Hello', 'World'}, lang='en')

__str__()

Return the string representation of the SetLangString object.

This method provides a concise string representation of the SetLangString, listing each text entry with its associated language tag if the corresponding flags are set. It mimics the behavior of the standard set’s __str__ method. The method provide a deterministic output by sorting the elements before printing.

Returns:: The string representation of the SetLangString object.
Return type:: str

Example:

>>> set_lang_str = SetLangString({"Hello", "World"}, "en")
>>> print(str(set_lang_str))  # Output: {'Hello', 'World'}@en

__sub__(other)

Return the difference of the set and another set.

This method returns a new SetLangString containing elements that are in the set but not in the other set. It mimics the behavior of the standard set’s __sub__ method (difference operator -).

Parameters:: other (Union[set[str], SetLangString]) – The other set or SetLangString to difference with.
Returns:: A new SetLangString containing the difference of the sets.
Return type:: SetLangString
Raises:: ValueError – If the language tag of the SetLangString in other does not match the set’s language tag.

Example:

>>> set_lang_str1 = SetLangString({"Hello", "World"}, "en")
>>> set_lang_str2 = SetLangString({"World", "Python"}, "en")
>>> diff_set_lang_str = set_lang_str1 - set_lang_str2
>>> print(diff_set_lang_str)  # Output: {'Hello'}@en

__xor__(other)

Return the symmetric difference of the set and another set.

This method returns a new SetLangString containing elements that are in either the set or the other set, but not in both. It mimics the behavior of the standard set’s __xor__ method (symmetric difference operator ^).

Parameters:: other (Union[set[str], SetLangString]) – The other set or SetLangString to symmetric difference with.
Returns:: A new SetLangString containing the symmetric difference of the sets.
Return type:: SetLangString
Raises:: ValueError – If the language tag of the SetLangString in other does not match the set’s language tag.

Example:

>>> set_lang_str1 = SetLangString({"Hello", "World"}, "en")
>>> set_lang_str2 = SetLangString({"World", "Python"}, "en")
>>> sym_diff_set_lang_str = set_lang_str1 ^ set_lang_str2
>>> print(sym_diff_set_lang_str)  # Output: {'Hello', 'Python'}@en

static merge_setlangstrings(setlangstrings)

Merge duplicated SetLangStrings based on their language tags using the union method.

This method processes a list of SetLangString instances, identifying and merging duplicates based on their language tags. If there’s no case variation in the language tags among duplicates, the original casing is preserved. If case variations are found, the casefolded version of the language tag is used in the merged SetLangString.

Parameters:: setlangstrings (list[SetLangString]) – The list of SetLangString instances to be merged.
Returns:: A list of merged SetLangString instances without duplicates.
Return type:: list[SetLangString]
Raises:: TypeError – If the input is not a list of SetLangString instances.

Example:

>>> setlangstr1 = SetLangString({"Hello"}, "en")
>>> setlangstr2 = SetLangString({"World"}, "en")
>>> setlangstr3 = SetLangString({"Bonjour"}, "fr")
>>> setlangstr4 = SetLangString({"Hello"}, "EN")
>>> merged_list = SetLangString.merge_setlangstrings([setlangstr1, setlangstr2, setlangstr3, setlangstr4])
>>> for s in merged_list:
...     print(s)
...
# Output: {'Hello', 'World'}@en
#         {'Bonjour'}@fr