20251002

help/class_desc/extensions/string_extension.md

@@ -0,0 +1,186 @@
+# Класс `StringExtension`
+
+Этот класс предназначен для расширения базовых возможностей работы со строками на Python. Основной целью является
+поддержка удобной обработки текста на русском языке и предоставление функций для нормирования и трансформирования строк.
+Методы класса реализуют проверку на пустоту, работу с русскими символами, транслитерацию, замену фрагментов текста и
+работу с кодировкой.
+
+## Основная информация
+
+**Имя файла**: anb_python_components\extensions\string_extension.py
+**Автор**: Александр Бабаев
+**Версия**: 1.0.0
+**Дата начала поддержки**: с версии 1.0
+
+## Атрибуты и методы класса
+
+### Метод `is_none_or_empty`
+
+Проверяет, является ли строка пустой или None. Это удобно для быстрой предварительной обработки перед дальнейшими
+действиями.
+
+Пример использования:
+
+```python
+from anb_python_components.extensions.string_extension import StringExtension
+
+result = StringExtension.is_none_or_empty("")
+
+print(result)  # True
+```
+
+### Метод `is_none_or_whitespace`
+
+Проверяет, содержит ли строка только пробельные символы или пустые места. Полезно для очистки вводимых значений.
+
+Пример использования:
+
+```python
+from anb_python_components.extensions.string_extension import StringExtension
+
+result = StringExtension.is_none_or_whitespace("\t\n ")
+
+print(result)  # True
+```
+
+### Метод `is_russian_letter`
+
+Проверяет, является ли символ русской буквой. Удобно для фильтраций и анализа текста на предмет наличия кириллицы.
+
+Пример использования:
+
+```python
+from anb_python_components.extensions.string_extension import StringExtension
+
+char = 'П'
+result = StringExtension.is_russian_letter(char)
+print(result)  # True
+```
+
+### Метод `get_russian_letter_transliteration`
+
+Возвращает транслитерированное представление русской буквы. Это полезно для интеграций с иностранными сервисами и API,
+которые требуют текст в латинском представлении.
+
+Пример использования:
+
+```python
+from anb_python_components.extensions.string_extension import StringExtension
+
+letter = 'Ч'
+result = StringExtension.get_russian_letter_transliteration(letter)
+print(result)  # Ch
+```
+
+### Метод `convert_to_latin`
+
+Переводит весь текст в транслитерационное представление. Подходит для ситуаций, когда нужно сохранить содержание текста,
+но представить его в другом алфавите.
+
+Пример использования:
+
+```python
+from anb_python_components.extensions.string_extension import StringExtension
+
+text = "Привет мир!"
+result = StringExtension.convert_to_latin(text)
+print(result)  # Privet mir!
+```
+
+### Метод `compare`
+
+Позволяет сравнивать две строки, учитывая возможность игнорирования регистра символов. Очень полезно для проверок
+условий в программах, обрабатывающих текстовую информацию.
+
+Пример использования:
+
+```python
+from anb_python_components.extensions.string_extension import StringExtension
+
+result = StringExtension.compare("привет", "Привет", ignore_case=True)
+print(result)  # 0
+```
+
+### Метод `get_short_text`
+
+Обрезает длинную строку до определённой длины, оставляя указанный символ окончания (например, многоточие). Идеально
+подходит для вывода коротких заголовков или аннотаций.
+
+Пример использования:
+
+```python
+from anb_python_components.extensions.string_extension import StringExtension
+
+text = "Это очень длинный текст..."
+shortened = StringExtension.get_short_text(text, max_length=10,
+                                           end_symbols="...")
+print(shortened)  # Это оче...
+```
+
+### Метод `to_utf8`
+
+Преобразует строку в кодировку UTF-8. Этот метод необходим, если работа ведётся с другими кодировками, отличающимися от
+стандартной (например, Windows-1251).
+
+Пример использования:
+
+```python
+from anb_python_components.extensions.string_extension import StringExtension
+
+subject = "ТЕКСТ"
+utf8_encoded = StringExtension.to_utf8(subject, encoding='windows-1251')
+print(utf8_encoded)  # ТЕКСТ
+```
+
+### Метод `from_utf8`
+
+Преобразует строку обратно из UTF-8 в требуемую кодировку. Необходимость метода возникает при обработке данных,
+полученных из разных источников.
+
+Пример использования:
+
+```python
+from anb_python_components.extensions.string_extension import StringExtension
+
+subject = "ТЕКСТ"
+decoded = StringExtension.from_utf8(subject, to_encoding='windows-1251')
+print(decoded)  # ТЕКСТ
+```
+
+### Метод `replace`
+
+Производит замену указанного шаблона на новую строку внутри исходного текста. Поддерживает использование регулярных
+выражений для сложных случаев поиска.
+
+Пример использования:
+
+```python
+from anb_python_components.extensions.string_extension import StringExtension
+
+source = "Меняю слово"
+new_source = StringExtension.replace(source, "слово", "текст")
+print(new_source)  # Меняю текст
+```
+
+### Метод `replace_all`
+
+Производит серию последовательных замен по переданному словарю соответствий. Эффективен для массовой модификации текста.
+
+Пример использования:
+
+```python
+from anb_python_components.extensions.string_extension import StringExtension
+
+search_replace = {"слово": "текст", "-": "#"}
+source = "Меняю слово-слово"
+new_source = StringExtension.replace_all(search_replace, source)
+print(new_source)  # Меняю текст#текст
+```
+
+## Заключение
+
+Методы класса обеспечивают широкие возможности для обработки и подготовки текстовых данных на русском языке. Эти
+инструменты полезны для любых проектов, связанных с обработкой текстовой информации на Python, будь то веб-приложения,
+скрипты автоматизации или обработка файлов.
+
+[На главную](../../index.md)

help/class_desc/extensions/string_extension_constant.md

@@ -0,0 +1,60 @@
+# Класс `StringExtensionConstants`
+
+Этот класс предназначен для хранения констант, используемых при расширениях функционала работы со строками на Python.
+Основные цели класса включают поддержку русской транслитерации и удобство обработки текста на кириллице.
+
+Класс включает два основных атрибута-константы:
+* атрибут `russian_letters`;
+* атрибут `russian_letters_transliteration`.
+
+## Основная информация
+
+- **Имя файла**: anb_python_components\extensions\string_extension_constant.py
+- **Автор**: Александр Бабаев
+- **Версия**: 1.0.0
+- **Дата начала поддержки**: с версии 1.0
+
+## Атрибуты и методы класса
+### Атрибут `russian_letters`
+Это кортеж, содержащий все русские буквы (строчные и прописные). Используется для проверки принадлежности символов
+русским буквам, операций сортировки и фильтрации текста.
+
+Пример использования:
+```python
+from anb_python_components.extensions.string_extension_constant import StringExtensionConstants
+
+char = 'в'
+
+if char in StringExtensionConstants.russian_letters:
+    print("Символ является русской буквой")
+```
+
+### Атрибут `russian_letters_transliteration`
+Это кортеж, соответствующий русскому алфавиту в транслитерированном виде латиницей. Например, русская буква «А»
+соответствует английскому символу «A», а буква «Ч» соответствует последовательности «Ch».
+
+Используется для преобразования русского текста в транслитерационный вид, что полезно для интеграции с международными
+системами, упрощения экспорта данных и поддержки кросс-платформенных решений.
+
+Пример использования:
+
+```python
+from anb_python_components.extensions.string_extension_constant import StringExtensionConstants
+
+translit_map = dict(
+    zip(
+        StringExtensionConstants.russian_letters,
+        StringExtensionConstants.russian_letters_transliteration
+    ))
+
+
+def transliterate(text):
+    return ''.join(translit_map.get(char, char) for char in text)
+```
+
+## Вывод
+
+Таким образом, этот класс позволяет легко реализовать базовые операции для нормализации и трансформации строки на
+русском языке.
+
+[На главную](../../index.md)