[](https://doi.org/10.5281/zenodo.10211480)
[](https://www.repostatus.org/#active)
[](https://github.com/pre-commit/pre-commit)
[](https://results.pre-commit.ci/latest/github/pedropaulofb/langstring/main)
[](https://www.bestpractices.dev/projects/8328)
# LangString Python Library
LangString is a Python library designed to handle multilingual text data with precision and flexibility. Although the need for robust management of multilingual content is critical, existing solutions often lack the necessary features to manage language-tagged strings, sets of strings, and collections of multilingual strings effectively. LangString addresses this gap by providing classes and utilities that enable the creation, manipulation, and validation of multilingual text data consistently and accurately. Inspired by [RDFS's langstrings](https://www.w3.org/TR/rdf-schema/), LangString integrates seamlessly into Python applications, offering familiar methods that mimic those of regular Python types, making it intuitive for developers to adopt and use.
**📦 PyPI Package:**
The library is conveniently [available as a PyPI package](https://pypi.org/project/langstring/), allowing users to easily import it into other Python projects.
**📚 Documentation:**
For detailed documentation and code examples, please refer to the library's [docstring-generated documentation](https://pedropaulofb.github.io/langstring).
## Contents
<!-- TOC -->
* [LangString Python Library](#langstring-python-library)
* [Contents](#contents)
* [Installation and Usage](#installation-and-usage)
* [Dependencies](#dependencies)
* [Mandatory Dependencies](#mandatory-dependencies)
* [Optional Dependencies](#optional-dependencies)
* [Dev Dependencies](#dev-dependencies)
* [Installation](#installation)
* [Basic Installation](#basic-installation)
* [Full Installation](#full-installation)
* [Dev Installation](#dev-installation)
* [Importing Elements](#importing-elements)
* [Basic Usage](#basic-usage)
* [Basic Reference](#basic-reference)
* [Classes](#classes)
* [LangString Class](#langstring-class)
* [SetLangString Class](#setlangstring-class)
* [MultiLangString Class](#multilangstring-class)
* [Controller Class](#controller-class)
* [Converter Class](#converter-class)
* [Configuration via Flags](#configuration-via-flags)
* [Elements' Relationships](#elements-relationships)
* [Testing](#testing)
* [Test Organization](#test-organization)
* [Running the Tests](#running-the-tests)
* [Continuous Integration](#continuous-integration)
* [How to Contribute](#how-to-contribute)
* [Reporting Issues](#reporting-issues)
* [Code Contributions](#code-contributions)
* [Test Contributions](#test-contributions)
* [General Guidelines](#general-guidelines)
* [Related Libraries and Differences](#related-libraries-and-differences)
* [License](#license)
* [Author](#author)
<!-- TOC -->
## Installation and Usage
### Dependencies
The LangString Python Library has been designed to be lightweight and easy to install. It has no mandatory dependencies and a single optional dependency to keep the installation process straightforward and ensure compatibility with various environments.
All dependencies of the LangString library can be found in its [`pyproject.toml` file](https://github.com/pedropaulofb/langstring/blob/main/pyproject.toml).
#### Mandatory Dependencies
The LangString Library does not require mandatory dependencies.
#### Optional Dependencies
The LangString Library has a single optional dependency, the [langcodes package](https://pypi.org/project/langcodes/). It is used particularly for validating language tags when the `ENSURE_VALID_LANG` flag is enabled. This dependency is crucial for ensuring that language tags used in LangString and `MultiLangString` instances are valid and conform to international standards, thereby maintaining the integrity and reliability of multilingual text processing.
#### Dev Dependencies
For a complete list of development dependencies, please refer to the [Dev Dependencies List](https://github.com/pedropaulofb/langstring/blob/main/documentation/dev_dependencies.md).
### Installation
#### Basic Installation
To install the LangString library using `pip`, which is the package installer for Python, run the following command in your terminal or command prompt:
```sh
pip install langstring
```
This will download and install the latest version of the LangString library from [PyPI (Python Package Index)](https://pypi.org/project/langstring/).
#### Full Installation
For the full functionally of the LangString library, you need to install it together with its [optional dependency](#optional-dependencies) [langcodes](https://github.com/rspeer/langcodes/). To do that, use the following `pip` command:
```sh
pip install langstring[langcodes]
```
This command will install LangString along with the `langcodes` package.
#### Dev Installation
If you are planning to contribute to the development of `langstring`, you should install the [development dependencies](#dev-dependencies). First, you need to clone the repository. Run the following commands:
```sh
git clone https://github.com/pedropaulofb/langstring.git
cd langstring
pip install -r requirements.txt
```
This will clone the repository, navigate into the project directory, and install all the necessary packages needed for development.
### Importing Elements
After installation, you can use the following elements in your project: LangString, SetLangString, MultiLangString, Controller, GlobalFlag, LangStringFlag, SetLangStringFlag, MultiLangStringFlag, and Converter.
To import these elements, use the following import statement:
```python
from langstring import LangString, SetLangString, MultiLangString, Controller, GlobalFlag, LangStringFlag, SetLangStringFlag, MultiLangStringFlag, Converter
```
### Basic Usage
1. **LangString** is used to handle a string in a specific language.
```python
from langstring import LangString
# Create a LangString object
lang_str = LangString("Hello, World!", "en")
# Print the string representation
print(lang_str) # Output: "Hello, World!"@en
```
2. **SetLangString** allows you to handle a set of strings in a specific language.
```python
from langstring import SetLangString
# Create a SetLangString object
set_lang_str = SetLangString({"Hello", "Hi"}, "en")
# Print the set of strings
print(set_lang_str) # Output: {'Hello', 'Hi'}@en
```
3. **MultiLangString** manages strings in multiple languages.
```python
from langstring import MultiLangString
# Create a MultiLangString object
multi_lang_str = MultiLangString({"en": {"Hello", "Hi"}, "es": {"Hola"}})
# Print the multilingual string representation
print(multi_lang_str) # Output: en: {'Hello', 'Hi'}, es: {'Hola'}
```
4. **Controller** and **Flags** are used to manage global and specific language string states.
```python
from langstring import Controller, GlobalFlag
# Set a flag
Controller.set_flag(GlobalFlag.LOWERCASE_LANG, True)
# Print the state of a specific flag
Controller.print_flag(GlobalFlag.LOWERCASE_LANG) # Output: GlobalFlag.LOWERCASE_LANG = True
```
5. **Converter** is used to convert language strings between different formats.
```python
from langstring import Converter, LangString, SetLangString, MultiLangString
# 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
```
## Basic Reference
### Classes
#### LangString Class
The `LangString` class encapsulates a string along with its associated language information. It is designed to work seamlessly with text strings that require language tags, providing functionalities such as validation of language tags, handling of empty strings, and enforcement of constraints through control flags. It is also possible to validate language tags using the `langcodes` library, ensuring that the language information is accurate.
Using the `LangString` class is beneficial when you need to manage multilingual text data in your applications. It is particularly useful in scenarios where strings need to be associated with specific languages, such as in internationalization and localization projects, or when processing text data that must be tagged with its language for further analysis or processing. The class can be utilized in any context where you need to ensure the integrity of language-tagged strings, enhancing data consistency and reducing errors.
To use the `LangString` class, simply create an instance by providing the text and the corresponding language tag. The class supports many standard string operations, which have been overridden to return `LangString` objects, allowing for seamless integration and extended functionality. For example, you can concatenate two `LangString` objects, convert the text to uppercase, or check if the text contains a specific substring, all while maintaining the associated language tag. This makes it easy to work with multilingual text data as if you were handling regular strings, but with the added benefit of language context.
Note that in this library's context, language tags are case-insensitive, meaning `en`, `EN`, `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 set to 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.
- [Functionalities' Descriptions](https://github.com/pedropaulofb/langstring/blob/main/documentation/methods_langstring.md)
- [Documentation with Examples](https://pedropaulofb.github.io/langstring/autoapi/langstring/langstring/)
#### SetLangString Class
The `SetLangString` class is a structure designed to encapsulate a set of strings with a common language tag. This class provides a way to manage collections of text strings, ensuring that each string within the set is associated with a specified language tag. By using the `SetLangString` class, you can easily handle multilingual datasets, validate language tags, and manage string sets with enhanced functionality compared to standard Python sets.
Using `SetLangString` is beneficial when working with multilingual text data, as it integrates validation mechanisms and control flags to enforce constraints such as non-empty text strings and valid language tags. This ensures data integrity and consistency across your application. The class also overrides many standard set methods to return `SetLangString` objects, allowing seamless integration and extending the functionality of regular sets. This makes it an excellent choice for developers needing a more sophisticated way to manage and manipulate text data in different languages.
You should consider using `SetLangString` when you need to manage sets of text strings that are tagged with specific languages, such as in internationalization and localization projects, or when handling datasets that require strict validation of language tags. The `SetLangString` class makes it straightforward to add, remove, and manipulate text strings while maintaining the association with their respective language tags. For example, you can create a `SetLangString` object, add new strings, check for the existence of a string, and perform set operations like union and intersection, all while preserving language tag integrity.
- [Functionalities' Descriptions](https://github.com/pedropaulofb/langstring/blob/main/documentation/methods_setlangstring.md)
- [Documentation with Examples](https://pedropaulofb.github.io/langstring/autoapi/langstring/setlangstring/)
#### MultiLangString Class
The `MultiLangString` class is designed to manage and manipulate multilingual text strings, providing a flexible and efficient way to handle multilingual content in various applications. It uses a dictionary to store text entries associated with language tags, allowing easy representation and manipulation of text in different languages. The class supports adding new entries, removing entries, and retrieving entries based on specific languages or across all languages. Additionally, it allows setting a preferred language, which can be used as a default for operations involving text retrieval.
Using `MultiLangString` is beneficial when you need to manage and organize text data in multiple languages within your application. This class integrates seamlessly with other components like `LangString` and `SetLangString`, offering extensive functionality for handling multilingual text data. By encapsulating text entries within a structured dictionary, it ensures that language-specific data is maintained with integrity, making it ideal for internationalization and localization projects. Furthermore, the class provides methods for merging multilingual data, validating inputs, and performing various set operations, enhancing its utility in complex multilingual environments.
You should consider using `MultiLangString` when your application requires management of text data in multiple languages. The class simplifies tasks like adding new language entries, retrieving texts in a specific language, and ensuring data consistency across languages. For instance, you can create a `MultiLangString` object, add or remove text entries in different languages, and easily access or manipulate these entries as needed.
- [Functionalities' Descriptions](https://github.com/pedropaulofb/langstring/blob/main/documentation/methods_multilangstring.md)
- [Documentation with Examples](https://pedropaulofb.github.io/langstring/autoapi/langstring/multilangstring/)
#### Controller Class
The `Controller` class is a non-instantiable class (hence, it provides only static methods) designed to manage and manipulate [configuration flags](#configuration-via-flags) for the `LangString`, `SetLangString`, and `MultiLangString` classes. By centralizing the management of these flags, the `Controller` ensures consistent behavior and validation rules across the entire system. The class offers methods to set, retrieve, print, and reset these flags.
Using the `Controller` is beneficial because it enforces uniformity and reduces the potential for configuration errors across different parts of the application. It allows developers to dynamically adjust the behavior of multilingual text handling classes at runtime, catering to various needs and use cases. The centralized flag management system simplifies the maintenance and debugging processes, making it easier to track and modify configuration states.
You should use the `Controller` class when you need to enforce specific constraints or behaviors across multiple instances of multilingual text classes. It is especially useful in applications that require dynamic adjustments to text handling rules, such as ensuring non-empty strings, validating language codes, or controlling the inclusion of quotes and language tags in output. To use the `Controller`, simply call its class methods to set or get flag values, print the current states, or reset flags to their default settings. For example, `Controller.set_flag(GlobalFlag.LOWERCASE_LANG, True)` will set the lowercase language flag to true, affecting all relevant text handling classes.
- [Functionalities' Descriptions](https://github.com/pedropaulofb/langstring/blob/main/documentation/methods_controller.md)
- [Documentation with Examples](https://pedropaulofb.github.io/langstring/autoapi/langstring/controller/)
#### Converter Class
The `Converter` class is a utility class designed to facilitate conversions between different string types used in language processing, specifically regular `str`, `LangString`, `SetLangString`, and `MultiLangString`. These string types are integral to managing and manipulating multilingual text data, ensuring that language-specific text handling is seamless. The `Converter` class provides a range of static methods to perform these conversions.
Using the `Converter` class ensures compatibility and ease of use when transforming between various string representations. This is particularly beneficial in scenarios where data interchange between different components or modules is required. By leveraging the `Converter`, developers can maintain consistency in data representation and avoid common pitfalls associated with manual string manipulation. The utility nature of the class, providing only static methods streamlines its integration into different parts of an application.
The `Converter` class should be used whenever there is a need to convert between regular `str`, `LangString`, `SetLangString`, and `MultiLangString` objects. For instance, if an application requires converting a list of language-tagged strings into a unified multilingual format, the `Converter` provides the necessary methods to accomplish this efficiently. By calling methods like `Converter.from_string_to_langstring()` or `Converter.from_langstring_to_multilangstring()`, developers can perform these conversions with minimal code and maximum reliability.
- [Functionalities' Descriptions](https://github.com/pedropaulofb/langstring/blob/main/documentation/methods_converter.md)
- [Documentation with Examples](https://pedropaulofb.github.io/langstring/autoapi/langstring/converter/)
### Configuration via Flags
The configuration of behavior in this library is managed through a robust system of flags. These flags are predefined settings that control various aspects of how the library functions, allowing users to tailor its behavior to meet specific requirements. By adjusting these flags, users can enable or disable features, modify processing rules, and optimize performance for their particular use case. The flags are designed to be easily configurable, providing a flexible way to manage the library’s behavior without altering the underlying code.
Configuring behavior using flags is essential for several reasons. Firstly, it provides a high level of customization, enabling users to fine-tune the library’s operations to better align with their specific needs and workflows. This customization can lead to improved efficiency and effectiveness, as the library can be adapted to handle specific tasks more optimally. Additionally, configuring flags allows for better maintenance and scalability. As requirements evolve, users can adjust the flags to meet new demands without the need for significant code changes, thus ensuring the library remains versatile and future-proof.
Users should configure flags when they need to modify the default behavior of the library to suit their particular needs. For example, if a user needs to process multilingual data differently, they can set the appropriate flags to adjust the handling of language-tagged strings. Configurations can be made at the beginning of a session or dynamically throughout the usage of the library, depending on the context. To configure a flag, users simply need to call the `Controller` class’s methods designed for this purpose, such as `Controller.set_flag(flag_name, value)`. This straightforward approach makes it easy to manage and update configurations, ensuring the library operates as intended for any given application.
- [Flags' List](https://github.com/pedropaulofb/langstring/blob/main/documentation/flags_list.md)
- [Documentation with Examples](https://pedropaulofb.github.io/langstring/autoapi/langstring/flags/)
### Elements' Relationships
The elements of the library are interconnected to handle and manipulate multilingual data. Understanding these relationships is important for understanding the library's operations and how its components interact.
At the core are the Controller and flags, which manage configurations and settings. The `Controller` class interacts directly with the main data handling classes: `LangString`, `SetLangString`, and `MultiLangString`. The flags, manipulated via the `Controller`, provides the settings that dictate how the other classes should behave, allowing customization based on user requirements.
The data handling classes (`LangString`, `SetLangString`, and `MultiLangString`) are the backbone of the library, providing structures for representing and manipulating language-tagged strings. These classes are used by the `Converter` class, which offers functions for converting between these string types. This conversion ensures compatibility and ease of use across language processing tasks.
In summary, the `Controller` and the flags define and manage configurations. The core data handling classes (`LangString`, `SetLangString`, `MultiLangString`) are manipulated based on these configurations and are used by the `Converter` class to enable transformations between different string representations. This structure, represented in the image below, allows the library to provide solutions for multilingual data processing.
<p align="center">
<img src="https://raw.githubusercontent.com/pedropaulofb/langstring/main/documentation/import_schema_basic.png" alt="Basic Import Scheme" style="width:500px">
</p>
## Testing
The LangString Python Library is rigorously tested to ensure robustness and reliability. We have achieved 100% test coverage, with tests implemented for each method provided by the library. This ensures that every aspect of the library is thoroughly validated and any potential issues are caught early.
### Test Organization
The tests are organized into [several directories](https://github.com/pedropaulofb/langstring/tree/main/tests), each focusing on different components of the library:
- `tests_langstring`: Tests for the core LangString functionalities.
- `tests_utils`: Utility tests to ensure the correctness of helper functions.
- `tests_setlangstring`: Tests for SetLangString functionalities.
- `tests_multilangstring`: Tests for MultiLangString functionalities.
- `tests_converter`: Tests for Conversor functionalities.
- `tests_controller`: Tests for Controller functionalities.
### Running the Tests
To run the tests, you can use the following command in the command line within the test directory of the project:
```sh
pytest
```
This command will execute all the tests and provide a detailed report on the coverage and any potential issues.
### Continuous Integration
We use GitHub Actions to automatically run our tests on every push to the repository. The [Action's workflow](https://github.com/pedropaulofb/langstring/blob/main/.github/workflows/code_testing.yml) execute the tests across multiple operating systems and Python versions to ensure compatibility and reliability.
- **Operating Systems**: Windows, Linux, and macOS.
- **Python Versions**: 3.11 and 3.12.
## How to Contribute
We welcome and appreciate contributions from the community! Whether you want to report a bug, suggest a new feature, or improve our codebase, your input is valuable.
### Reporting Issues
- If you find a bug or wish to suggest a feature, please [open a new issue](https://github.com/pedropaulofb/langstring/issues/new).
- If you notice any discrepancies in the documentation created with the aid of AI, feel free to [report them by opening an issue](https://github.com/pedropaulofb/langstring/issues/new).
### Code Contributions
1. Fork the project repository and create a new feature branch for your work: `git checkout -b feature/YourFeatureName`.
2. Make and commit your changes with descriptive commit messages.
3. Push your work back up to your fork: `git push origin feature/YourFeatureName`.
4. Submit a pull request to propose merging your feature branch into the main project repository.
### Test Contributions
- Enhance the project's reliability by adding new tests or improving existing ones.
### General Guidelines
- Ensure your code follows our coding standards.
- Update the documentation as necessary.
- Make sure your contributions do not introduce new issues.
We appreciate your time and expertise in contributing to this project!
## Related Libraries and Differences
The LangString Library offers unique functionalities for handling multilingual text in Python applications. While there are several libraries and tools available for internationalization, localization, and language processing, they differ from the LangString Library in scope and functionality. Below is an overview of related work and how they compare to the LangString library:
- **Babel**
- https://pypi.org/project/Babel/
- Babel is a Python library for internationalization and localization. It primarily focuses on formatting dates, numbers, and currency values for different locales.
- Difference: Unlike Babel, the LangString Library specifically manages multilingual text strings, providing a more direct approach to handling language-specific text data.
- **gettext**
- https://pypi.org/project/python-gettext/
- gettext is a GNU system used for internationalizing applications. It allows for translating fixed strings in different languages using message catalogs.
- Difference: The LangString Library, in contrast, is designed for dynamic management of multilingual content, not just for translation of static strings.
- **langcodes**
- https://pypi.org/project/langcodes/
- langcodes provides tools for parsing and understanding language tags.
- Difference: While langcodes is useful for handling language codes, the LangString Library extends beyond this by managing actual multilingual text strings associated with these codes.
- **Polyglot**
- https://pypi.org/project/polyglot/
- Polyglot is a natural language pipeline that supports multiple languages for various NLP tasks.
- Difference: Polyglot focuses on language processing rather than the structured management of multilingual text, which is the core functionality of the LangString Library.
- **CLD3**
- https://pypi.org/project/gcld3/
- Google's CLD3 is a model for language identification.
- Difference: CLD3 is specialized in detecting the language of a text, whereas the LangString Library is about storing and manipulating text in multiple languages.
- **spaCy**
- https://pypi.org/project/spacy/
- spaCy is a comprehensive NLP library that supports multiple languages.
- Difference: spaCy is geared towards analyzing text, not managing it. The LangString Library, on the other hand, is designed for the structured handling and storage of multilingual text.
In summary, while these related tools and libraries offer valuable functionalities for internationalization, localization, and language processing, the LangString Library has specific focus on managing and manipulating multilingual text strings in a structured and efficient manner.
## License
This project is licensed under the Apache License 2.0. See the [LICENSE](https://github.com/pedropaulofb/langstring/blob/main/LICENSE) file for details.
## Author
The LangString library is developed and maintained by:
- Pedro Paulo Favato Barcelos [[GitHub](https://github.com/pedropaulofb)] [[LinkedIn](https://www.linkedin.com/in/pedro-paulo-favato-barcelos/)]
Feel free to reach out using the provided links. For inquiries, contributions, or to report any issues, you can [open a new issue](https://github.com/pedropaulofb/langstring/issues/new) on this repository.
Raw data
{
"_id": null,
"home_page": "https://github.com/pedropaulofb/langstring",
"name": "langstring",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.11",
"maintainer_email": null,
"keywords": "string, langstring, multilangstring, language-string, multilanguage-string, language-representation, multilanguage",
"author": "Pedro Paulo F. Barcelos",
"author_email": "p.p.favatobarcelos@utwente.nl",
"download_url": "https://files.pythonhosted.org/packages/ee/36/eba1a53df9398bd5fb8be719c86a3da0c1f0994f908d0af239bf1d6a2253/langstring-3.0.2.tar.gz",
"platform": null,
"description": "[](https://doi.org/10.5281/zenodo.10211480)\n[](https://www.repostatus.org/#active)\n\n\n\n\n\n\n\n\n\n\n[](https://github.com/pre-commit/pre-commit)\n[](https://results.pre-commit.ci/latest/github/pedropaulofb/langstring/main)\n\n\n[](https://www.bestpractices.dev/projects/8328)\n\n\n# LangString Python Library\n\nLangString is a Python library designed to handle multilingual text data with precision and flexibility. Although the need for robust management of multilingual content is critical, existing solutions often lack the necessary features to manage language-tagged strings, sets of strings, and collections of multilingual strings effectively. LangString addresses this gap by providing classes and utilities that enable the creation, manipulation, and validation of multilingual text data consistently and accurately. Inspired by [RDFS's langstrings](https://www.w3.org/TR/rdf-schema/), LangString integrates seamlessly into Python applications, offering familiar methods that mimic those of regular Python types, making it intuitive for developers to adopt and use.\n\n**\ud83d\udce6 PyPI Package:**\nThe library is conveniently [available as a PyPI package](https://pypi.org/project/langstring/), allowing users to easily import it into other Python projects.\n\n**\ud83d\udcda Documentation:**\nFor detailed documentation and code examples, please refer to the library's [docstring-generated documentation](https://pedropaulofb.github.io/langstring).\n\n## Contents\n\n<!-- TOC -->\n* [LangString Python Library](#langstring-python-library)\n * [Contents](#contents)\n * [Installation and Usage](#installation-and-usage)\n * [Dependencies](#dependencies)\n * [Mandatory Dependencies](#mandatory-dependencies)\n * [Optional Dependencies](#optional-dependencies)\n * [Dev Dependencies](#dev-dependencies)\n * [Installation](#installation)\n * [Basic Installation](#basic-installation)\n * [Full Installation](#full-installation)\n * [Dev Installation](#dev-installation)\n * [Importing Elements](#importing-elements)\n * [Basic Usage](#basic-usage)\n * [Basic Reference](#basic-reference)\n * [Classes](#classes)\n * [LangString Class](#langstring-class)\n * [SetLangString Class](#setlangstring-class)\n * [MultiLangString Class](#multilangstring-class)\n * [Controller Class](#controller-class)\n * [Converter Class](#converter-class)\n * [Configuration via Flags](#configuration-via-flags)\n * [Elements' Relationships](#elements-relationships)\n * [Testing](#testing)\n * [Test Organization](#test-organization)\n * [Running the Tests](#running-the-tests)\n * [Continuous Integration](#continuous-integration)\n * [How to Contribute](#how-to-contribute)\n * [Reporting Issues](#reporting-issues)\n * [Code Contributions](#code-contributions)\n * [Test Contributions](#test-contributions)\n * [General Guidelines](#general-guidelines)\n * [Related Libraries and Differences](#related-libraries-and-differences)\n * [License](#license)\n * [Author](#author)\n<!-- TOC -->\n\n## Installation and Usage\n\n### Dependencies\n\nThe LangString Python Library has been designed to be lightweight and easy to install. It has no mandatory dependencies and a single optional dependency to keep the installation process straightforward and ensure compatibility with various environments.\n\nAll dependencies of the LangString library can be found in its [`pyproject.toml` file](https://github.com/pedropaulofb/langstring/blob/main/pyproject.toml).\n\n#### Mandatory Dependencies\nThe LangString Library does not require mandatory dependencies.\n\n#### Optional Dependencies\n\nThe LangString Library has a single optional dependency, the [langcodes package](https://pypi.org/project/langcodes/). It is used particularly for validating language tags when the `ENSURE_VALID_LANG` flag is enabled. This dependency is crucial for ensuring that language tags used in LangString and `MultiLangString` instances are valid and conform to international standards, thereby maintaining the integrity and reliability of multilingual text processing.\n\n#### Dev Dependencies\n\nFor a complete list of development dependencies, please refer to the [Dev Dependencies List](https://github.com/pedropaulofb/langstring/blob/main/documentation/dev_dependencies.md).\n\n### Installation\n\n#### Basic Installation\n\nTo install the LangString library using `pip`, which is the package installer for Python, run the following command in your terminal or command prompt:\n\n```sh\npip install langstring\n```\n\nThis will download and install the latest version of the LangString library from [PyPI (Python Package Index)](https://pypi.org/project/langstring/).\n\n#### Full Installation\n\nFor the full functionally of the LangString library, you need to install it together with its [optional dependency](#optional-dependencies) [langcodes](https://github.com/rspeer/langcodes/). To do that, use the following `pip` command:\n\n```sh\npip install langstring[langcodes]\n```\n\nThis command will install LangString along with the `langcodes` package.\n\n#### Dev Installation\n\nIf you are planning to contribute to the development of `langstring`, you should install the [development dependencies](#dev-dependencies). First, you need to clone the repository. Run the following commands:\n\n```sh\ngit clone https://github.com/pedropaulofb/langstring.git\ncd langstring\npip install -r requirements.txt\n```\n\nThis will clone the repository, navigate into the project directory, and install all the necessary packages needed for development.\n\n### Importing Elements\n\nAfter installation, you can use the following elements in your project: LangString, SetLangString, MultiLangString, Controller, GlobalFlag, LangStringFlag, SetLangStringFlag, MultiLangStringFlag, and Converter.\n\nTo import these elements, use the following import statement:\n\n```python\nfrom langstring import LangString, SetLangString, MultiLangString, Controller, GlobalFlag, LangStringFlag, SetLangStringFlag, MultiLangStringFlag, Converter\n```\n\n### Basic Usage\n\n1. **LangString** is used to handle a string in a specific language.\n\n ```python\n from langstring import LangString\n\n # Create a LangString object\n lang_str = LangString(\"Hello, World!\", \"en\")\n\n # Print the string representation\n print(lang_str) # Output: \"Hello, World!\"@en\n ```\n\n2. **SetLangString** allows you to handle a set of strings in a specific language.\n\n ```python\n from langstring import SetLangString\n\n # Create a SetLangString object\n set_lang_str = SetLangString({\"Hello\", \"Hi\"}, \"en\")\n\n # Print the set of strings\n print(set_lang_str) # Output: {'Hello', 'Hi'}@en\n ```\n\n3. **MultiLangString** manages strings in multiple languages.\n\n ```python\n from langstring import MultiLangString\n\n # Create a MultiLangString object\n multi_lang_str = MultiLangString({\"en\": {\"Hello\", \"Hi\"}, \"es\": {\"Hola\"}})\n\n # Print the multilingual string representation\n print(multi_lang_str) # Output: en: {'Hello', 'Hi'}, es: {'Hola'}\n ```\n\n4. **Controller** and **Flags** are used to manage global and specific language string states.\n\n ```python\n from langstring import Controller, GlobalFlag\n\n # Set a flag\n Controller.set_flag(GlobalFlag.LOWERCASE_LANG, True)\n\n # Print the state of a specific flag\n Controller.print_flag(GlobalFlag.LOWERCASE_LANG) # Output: GlobalFlag.LOWERCASE_LANG = True\n ```\n\n5. **Converter** is used to convert language strings between different formats.\n\n ```python\n from langstring import Converter, LangString, SetLangString, MultiLangString\n\n # Convert a string to a LangString using the 'manual' method\n langstring = Converter.from_string_to_langstring(\"manual\", \"Hello\", \"en\")\n print(langstring) # Output: \"Hello\"@en\n\n # Convert a list of strings to a list of LangStrings using the 'parse' method\n langstrings = Converter.from_strings_to_langstrings(\"parse\", [\"Hello@en\", \"Bonjour@fr\"], separator=\"@\")\n for ls in langstrings:\n print(ls) # Output: \"Hello\"@en\n # \"Bonjour\"@fr\n ```\n\n\n## Basic Reference\n\n### Classes\n\n#### LangString Class\n\nThe `LangString` class encapsulates a string along with its associated language information. It is designed to work seamlessly with text strings that require language tags, providing functionalities such as validation of language tags, handling of empty strings, and enforcement of constraints through control flags. It is also possible to validate language tags using the `langcodes` library, ensuring that the language information is accurate.\n\nUsing the `LangString` class is beneficial when you need to manage multilingual text data in your applications. It is particularly useful in scenarios where strings need to be associated with specific languages, such as in internationalization and localization projects, or when processing text data that must be tagged with its language for further analysis or processing. The class can be utilized in any context where you need to ensure the integrity of language-tagged strings, enhancing data consistency and reducing errors.\n\nTo use the `LangString` class, simply create an instance by providing the text and the corresponding language tag. The class supports many standard string operations, which have been overridden to return `LangString` objects, allowing for seamless integration and extended functionality. For example, you can concatenate two `LangString` objects, convert the text to uppercase, or check if the text contains a specific substring, all while maintaining the associated language tag. This makes it easy to work with multilingual text data as if you were handling regular strings, but with the added benefit of language context.\n\nNote that in this library's context, language tags are case-insensitive, meaning `en`, `EN`, `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 set to 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.\n\n\n- [Functionalities' Descriptions](https://github.com/pedropaulofb/langstring/blob/main/documentation/methods_langstring.md)\n- [Documentation with Examples](https://pedropaulofb.github.io/langstring/autoapi/langstring/langstring/)\n\n#### SetLangString Class\n\nThe `SetLangString` class is a structure designed to encapsulate a set of strings with a common language tag. This class provides a way to manage collections of text strings, ensuring that each string within the set is associated with a specified language tag. By using the `SetLangString` class, you can easily handle multilingual datasets, validate language tags, and manage string sets with enhanced functionality compared to standard Python sets.\n\nUsing `SetLangString` is beneficial when working with multilingual text data, as it integrates validation mechanisms and control flags to enforce constraints such as non-empty text strings and valid language tags. This ensures data integrity and consistency across your application. The class also overrides many standard set methods to return `SetLangString` objects, allowing seamless integration and extending the functionality of regular sets. This makes it an excellent choice for developers needing a more sophisticated way to manage and manipulate text data in different languages.\n\nYou should consider using `SetLangString` when you need to manage sets of text strings that are tagged with specific languages, such as in internationalization and localization projects, or when handling datasets that require strict validation of language tags. The `SetLangString` class makes it straightforward to add, remove, and manipulate text strings while maintaining the association with their respective language tags. For example, you can create a `SetLangString` object, add new strings, check for the existence of a string, and perform set operations like union and intersection, all while preserving language tag integrity.\n\n- [Functionalities' Descriptions](https://github.com/pedropaulofb/langstring/blob/main/documentation/methods_setlangstring.md)\n- [Documentation with Examples](https://pedropaulofb.github.io/langstring/autoapi/langstring/setlangstring/)\n\n#### MultiLangString Class\n\nThe `MultiLangString` class is designed to manage and manipulate multilingual text strings, providing a flexible and efficient way to handle multilingual content in various applications. It uses a dictionary to store text entries associated with language tags, allowing easy representation and manipulation of text in different languages. The class supports adding new entries, removing entries, and retrieving entries based on specific languages or across all languages. Additionally, it allows setting a preferred language, which can be used as a default for operations involving text retrieval.\n\nUsing `MultiLangString` is beneficial when you need to manage and organize text data in multiple languages within your application. This class integrates seamlessly with other components like `LangString` and `SetLangString`, offering extensive functionality for handling multilingual text data. By encapsulating text entries within a structured dictionary, it ensures that language-specific data is maintained with integrity, making it ideal for internationalization and localization projects. Furthermore, the class provides methods for merging multilingual data, validating inputs, and performing various set operations, enhancing its utility in complex multilingual environments.\n\nYou should consider using `MultiLangString` when your application requires management of text data in multiple languages. The class simplifies tasks like adding new language entries, retrieving texts in a specific language, and ensuring data consistency across languages. For instance, you can create a `MultiLangString` object, add or remove text entries in different languages, and easily access or manipulate these entries as needed.\n\n- [Functionalities' Descriptions](https://github.com/pedropaulofb/langstring/blob/main/documentation/methods_multilangstring.md)\n- [Documentation with Examples](https://pedropaulofb.github.io/langstring/autoapi/langstring/multilangstring/)\n\n#### Controller Class\n\nThe `Controller` class is a non-instantiable class (hence, it provides only static methods) designed to manage and manipulate [configuration flags](#configuration-via-flags) for the `LangString`, `SetLangString`, and `MultiLangString` classes. By centralizing the management of these flags, the `Controller` ensures consistent behavior and validation rules across the entire system. The class offers methods to set, retrieve, print, and reset these flags.\n\nUsing the `Controller` is beneficial because it enforces uniformity and reduces the potential for configuration errors across different parts of the application. It allows developers to dynamically adjust the behavior of multilingual text handling classes at runtime, catering to various needs and use cases. The centralized flag management system simplifies the maintenance and debugging processes, making it easier to track and modify configuration states.\n\nYou should use the `Controller` class when you need to enforce specific constraints or behaviors across multiple instances of multilingual text classes. It is especially useful in applications that require dynamic adjustments to text handling rules, such as ensuring non-empty strings, validating language codes, or controlling the inclusion of quotes and language tags in output. To use the `Controller`, simply call its class methods to set or get flag values, print the current states, or reset flags to their default settings. For example, `Controller.set_flag(GlobalFlag.LOWERCASE_LANG, True)` will set the lowercase language flag to true, affecting all relevant text handling classes.\n\n- [Functionalities' Descriptions](https://github.com/pedropaulofb/langstring/blob/main/documentation/methods_controller.md)\n- [Documentation with Examples](https://pedropaulofb.github.io/langstring/autoapi/langstring/controller/)\n\n\n#### Converter Class\n\nThe `Converter` class is a utility class designed to facilitate conversions between different string types used in language processing, specifically regular `str`, `LangString`, `SetLangString`, and `MultiLangString`. These string types are integral to managing and manipulating multilingual text data, ensuring that language-specific text handling is seamless. The `Converter` class provides a range of static methods to perform these conversions.\n\nUsing the `Converter` class ensures compatibility and ease of use when transforming between various string representations. This is particularly beneficial in scenarios where data interchange between different components or modules is required. By leveraging the `Converter`, developers can maintain consistency in data representation and avoid common pitfalls associated with manual string manipulation. The utility nature of the class, providing only static methods streamlines its integration into different parts of an application.\n\nThe `Converter` class should be used whenever there is a need to convert between regular `str`, `LangString`, `SetLangString`, and `MultiLangString` objects. For instance, if an application requires converting a list of language-tagged strings into a unified multilingual format, the `Converter` provides the necessary methods to accomplish this efficiently. By calling methods like `Converter.from_string_to_langstring()` or `Converter.from_langstring_to_multilangstring()`, developers can perform these conversions with minimal code and maximum reliability.\n\n\n- [Functionalities' Descriptions](https://github.com/pedropaulofb/langstring/blob/main/documentation/methods_converter.md)\n- [Documentation with Examples](https://pedropaulofb.github.io/langstring/autoapi/langstring/converter/)\n\n### Configuration via Flags\n\nThe configuration of behavior in this library is managed through a robust system of flags. These flags are predefined settings that control various aspects of how the library functions, allowing users to tailor its behavior to meet specific requirements. By adjusting these flags, users can enable or disable features, modify processing rules, and optimize performance for their particular use case. The flags are designed to be easily configurable, providing a flexible way to manage the library\u2019s behavior without altering the underlying code.\n\nConfiguring behavior using flags is essential for several reasons. Firstly, it provides a high level of customization, enabling users to fine-tune the library\u2019s operations to better align with their specific needs and workflows. This customization can lead to improved efficiency and effectiveness, as the library can be adapted to handle specific tasks more optimally. Additionally, configuring flags allows for better maintenance and scalability. As requirements evolve, users can adjust the flags to meet new demands without the need for significant code changes, thus ensuring the library remains versatile and future-proof.\n\nUsers should configure flags when they need to modify the default behavior of the library to suit their particular needs. For example, if a user needs to process multilingual data differently, they can set the appropriate flags to adjust the handling of language-tagged strings. Configurations can be made at the beginning of a session or dynamically throughout the usage of the library, depending on the context. To configure a flag, users simply need to call the `Controller` class\u2019s methods designed for this purpose, such as `Controller.set_flag(flag_name, value)`. This straightforward approach makes it easy to manage and update configurations, ensuring the library operates as intended for any given application.\n\n- [Flags' List](https://github.com/pedropaulofb/langstring/blob/main/documentation/flags_list.md)\n- [Documentation with Examples](https://pedropaulofb.github.io/langstring/autoapi/langstring/flags/)\n\n### Elements' Relationships\n\nThe elements of the library are interconnected to handle and manipulate multilingual data. Understanding these relationships is important for understanding the library's operations and how its components interact.\n\nAt the core are the Controller and flags, which manage configurations and settings. The `Controller` class interacts directly with the main data handling classes: `LangString`, `SetLangString`, and `MultiLangString`. The flags, manipulated via the `Controller`, provides the settings that dictate how the other classes should behave, allowing customization based on user requirements.\n\nThe data handling classes (`LangString`, `SetLangString`, and `MultiLangString`) are the backbone of the library, providing structures for representing and manipulating language-tagged strings. These classes are used by the `Converter` class, which offers functions for converting between these string types. This conversion ensures compatibility and ease of use across language processing tasks.\n\nIn summary, the `Controller` and the flags define and manage configurations. The core data handling classes (`LangString`, `SetLangString`, `MultiLangString`) are manipulated based on these configurations and are used by the `Converter` class to enable transformations between different string representations. This structure, represented in the image below, allows the library to provide solutions for multilingual data processing.\n\n<p align=\"center\">\n <img src=\"https://raw.githubusercontent.com/pedropaulofb/langstring/main/documentation/import_schema_basic.png\" alt=\"Basic Import Scheme\" style=\"width:500px\">\n</p>\n\n## Testing\n\nThe LangString Python Library is rigorously tested to ensure robustness and reliability. We have achieved 100% test coverage, with tests implemented for each method provided by the library. This ensures that every aspect of the library is thoroughly validated and any potential issues are caught early.\n\n### Test Organization\n\nThe tests are organized into [several directories](https://github.com/pedropaulofb/langstring/tree/main/tests), each focusing on different components of the library:\n\n- `tests_langstring`: Tests for the core LangString functionalities.\n- `tests_utils`: Utility tests to ensure the correctness of helper functions.\n- `tests_setlangstring`: Tests for SetLangString functionalities.\n- `tests_multilangstring`: Tests for MultiLangString functionalities.\n- `tests_converter`: Tests for Conversor functionalities.\n- `tests_controller`: Tests for Controller functionalities.\n\n### Running the Tests\n\nTo run the tests, you can use the following command in the command line within the test directory of the project:\n\n```sh\npytest\n```\n\nThis command will execute all the tests and provide a detailed report on the coverage and any potential issues.\n\n### Continuous Integration\n\nWe use GitHub Actions to automatically run our tests on every push to the repository. The [Action's workflow](https://github.com/pedropaulofb/langstring/blob/main/.github/workflows/code_testing.yml) execute the tests across multiple operating systems and Python versions to ensure compatibility and reliability.\n\n- **Operating Systems**: Windows, Linux, and macOS.\n- **Python Versions**: 3.11 and 3.12.\n\n## How to Contribute\n\nWe welcome and appreciate contributions from the community! Whether you want to report a bug, suggest a new feature, or improve our codebase, your input is valuable.\n\n### Reporting Issues\n\n- If you find a bug or wish to suggest a feature, please [open a new issue](https://github.com/pedropaulofb/langstring/issues/new).\n- If you notice any discrepancies in the documentation created with the aid of AI, feel free to [report them by opening an issue](https://github.com/pedropaulofb/langstring/issues/new).\n\n### Code Contributions\n\n1. Fork the project repository and create a new feature branch for your work: `git checkout -b feature/YourFeatureName`.\n2. Make and commit your changes with descriptive commit messages.\n3. Push your work back up to your fork: `git push origin feature/YourFeatureName`.\n4. Submit a pull request to propose merging your feature branch into the main project repository.\n\n### Test Contributions\n\n- Enhance the project's reliability by adding new tests or improving existing ones.\n\n### General Guidelines\n\n- Ensure your code follows our coding standards.\n- Update the documentation as necessary.\n- Make sure your contributions do not introduce new issues.\n\nWe appreciate your time and expertise in contributing to this project!\n\n## Related Libraries and Differences\n\nThe LangString Library offers unique functionalities for handling multilingual text in Python applications. While there are several libraries and tools available for internationalization, localization, and language processing, they differ from the LangString Library in scope and functionality. Below is an overview of related work and how they compare to the LangString library:\n\n- **Babel**\n - https://pypi.org/project/Babel/\n - Babel is a Python library for internationalization and localization. It primarily focuses on formatting dates, numbers, and currency values for different locales.\n - Difference: Unlike Babel, the LangString Library specifically manages multilingual text strings, providing a more direct approach to handling language-specific text data.\n\n- **gettext**\n - https://pypi.org/project/python-gettext/\n - gettext is a GNU system used for internationalizing applications. It allows for translating fixed strings in different languages using message catalogs.\n - Difference: The LangString Library, in contrast, is designed for dynamic management of multilingual content, not just for translation of static strings.\n\n- **langcodes**\n - https://pypi.org/project/langcodes/\n - langcodes provides tools for parsing and understanding language tags.\n - Difference: While langcodes is useful for handling language codes, the LangString Library extends beyond this by managing actual multilingual text strings associated with these codes.\n\n- **Polyglot**\n - https://pypi.org/project/polyglot/\n - Polyglot is a natural language pipeline that supports multiple languages for various NLP tasks.\n - Difference: Polyglot focuses on language processing rather than the structured management of multilingual text, which is the core functionality of the LangString Library.\n\n- **CLD3**\n - https://pypi.org/project/gcld3/\n - Google's CLD3 is a model for language identification.\n - Difference: CLD3 is specialized in detecting the language of a text, whereas the LangString Library is about storing and manipulating text in multiple languages.\n\n- **spaCy**\n - https://pypi.org/project/spacy/\n - spaCy is a comprehensive NLP library that supports multiple languages.\n - Difference: spaCy is geared towards analyzing text, not managing it. The LangString Library, on the other hand, is designed for the structured handling and storage of multilingual text.\n\nIn summary, while these related tools and libraries offer valuable functionalities for internationalization, localization, and language processing, the LangString Library has specific focus on managing and manipulating multilingual text strings in a structured and efficient manner.\n\n## License\n\nThis project is licensed under the Apache License 2.0. See the [LICENSE](https://github.com/pedropaulofb/langstring/blob/main/LICENSE) file for details.\n\n## Author\n\nThe LangString library is developed and maintained by:\n\n- Pedro Paulo Favato Barcelos [[GitHub](https://github.com/pedropaulofb)] [[LinkedIn](https://www.linkedin.com/in/pedro-paulo-favato-barcelos/)]\n\nFeel free to reach out using the provided links. For inquiries, contributions, or to report any issues, you can [open a new issue](https://github.com/pedropaulofb/langstring/issues/new) on this repository.\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "LangString Python Library",
"version": "3.0.2",
"project_urls": {
"Documentation": "https://pedropaulofb.github.io/langstring",
"Homepage": "https://github.com/pedropaulofb/langstring",
"PyPi Project": "https://pypi.org/project/langstring/",
"Repository": "https://github.com/pedropaulofb/langstring"
},
"split_keywords": [
"string",
" langstring",
" multilangstring",
" language-string",
" multilanguage-string",
" language-representation",
" multilanguage"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d0ab7f53a7a48c59524eb3234ebf24d29e406520798239310b17e4164d385157",
"md5": "86a02801d7112a4b7a065dc5f5cafb89",
"sha256": "2dc95275b56c34d488edffaf2dfcc1de03679708b284b9d703752cdac5c00c8c"
},
"downloads": -1,
"filename": "langstring-3.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "86a02801d7112a4b7a065dc5f5cafb89",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.11",
"size": 64413,
"upload_time": "2024-08-18T16:17:46",
"upload_time_iso_8601": "2024-08-18T16:17:46.243577Z",
"url": "https://files.pythonhosted.org/packages/d0/ab/7f53a7a48c59524eb3234ebf24d29e406520798239310b17e4164d385157/langstring-3.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ee36eba1a53df9398bd5fb8be719c86a3da0c1f0994f908d0af239bf1d6a2253",
"md5": "5ad4f4036d76ce011427bc9472146251",
"sha256": "2ba7ac495907398224ba1eaf5f211b0a5d96bb8f529d08555bfc842c7ef6f313"
},
"downloads": -1,
"filename": "langstring-3.0.2.tar.gz",
"has_sig": false,
"md5_digest": "5ad4f4036d76ce011427bc9472146251",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.11",
"size": 61321,
"upload_time": "2024-08-18T16:17:48",
"upload_time_iso_8601": "2024-08-18T16:17:48.420640Z",
"url": "https://files.pythonhosted.org/packages/ee/36/eba1a53df9398bd5fb8be719c86a3da0c1f0994f908d0af239bf1d6a2253/langstring-3.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-18 16:17:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pedropaulofb",
"github_project": "langstring",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "langstring"
}
JSON
