From 2fba613ae82b38d6e6a0d700df6f66a7597f066a Mon Sep 17 00:00:00 2001 From: Alexander Date: Thu, 2 Oct 2025 18:08:16 +0300 Subject: [PATCH] 20251002 --- .../extensions/StringExtension.php | 136 ------------- .../extensions/string_extension.py | 180 ++++++++++++++++- .../class_desc/extensions/string_extension.md | 186 ++++++++++++++++++ .../extensions/string_extension_constant.md | 60 ++++++ help/index.md | 67 +++++++ 5 files changed, 485 insertions(+), 144 deletions(-) delete mode 100644 anb_python_components/extensions/StringExtension.php create mode 100644 help/class_desc/extensions/string_extension.md create mode 100644 help/class_desc/extensions/string_extension_constant.md create mode 100644 help/index.md diff --git a/anb_python_components/extensions/StringExtension.php b/anb_python_components/extensions/StringExtension.php deleted file mode 100644 index 9e52f99..0000000 --- a/anb_python_components/extensions/StringExtension.php +++ /dev/null @@ -1,136 +0,0 @@ -['-' => '#', '$' => '%'] - * заменит все дефисы на # и все доллары на %. - * @param string $subject Строка, в которой нужно выполнить замену. - * @param string $encoding (необязательный) Кодировка (по умолчанию, UTF-8). - * - * @return string Возвращает новую строку с выполненными заменами. - */ - public static function ReplaceAll (array $searchReplace, string $subject, string $encoding = 'UTF-8'): string - { - // Создаю результат - $result = $subject; - - // Для каждой пары поиска и замены - foreach ($searchReplace as $search => $replace) - // - заменяю все вхождения строки поиска на строку замены в заданной строке - $result = self::Replace($search, $replace, $result, $encoding); - - // Возвращаю результат - return $result; - } - - /** - * Функция заменяет все вхождения строки поиска на строку замены в заданной строке (аналог mb_str_replace). - * - * @param string $search Строка, которую нужно найти и заменить. - * @param string $replace Строка, на которую нужно заменить найденную строку. - * @param string $subject Строка, в которой нужно выполнить замену. - * @param string $encoding (необязательный) Кодировка (по умолчанию, UTF-8). - * - * @return string Возвращает новую строку с выполненной заменой. - */ - public static function Replace (string $search, string $replace, string $subject, - string $encoding = 'UTF-8'): string - { - // Если кодировка не UTF-8 - if ($encoding != 'UTF-8') { - // - то перекодируем строку поиска, замены и исходную строку в UTF-8 - $search = mb_convert_encoding($search, 'UTF-8', $encoding); - // - и перекодируем строку замены в UTF-8 - $replace = mb_convert_encoding($replace, 'UTF-8', $encoding); - // - и перекодируем исходную строку в UTF-8 - $subject = mb_convert_encoding($subject, 'UTF-8', $encoding); - } - - // С помощью регулярного выражения заменяем все вхождения строки поиска на строку замены - $result = preg_replace('/' . preg_quote($search, '/') . '/u', $replace, $subject); - - // Если кодировка не UTF-8 - if ($encoding != 'UTF-8') - // - то перекодируем результат в исходную кодировку - $result = mb_convert_encoding($result, $encoding, 'UTF-8'); - - // Возвращаем результат - return $result; - } -} \ No newline at end of file diff --git a/anb_python_components/extensions/string_extension.py b/anb_python_components/extensions/string_extension.py index 951c119..80e8fe8 100644 --- a/anb_python_components/extensions/string_extension.py +++ b/anb_python_components/extensions/string_extension.py @@ -1,4 +1,5 @@ # anb_python_components/extensions/string_extension.py +import re from string_extension_constant import StringExtensionConstants @@ -14,8 +15,8 @@ class StringExtension: """ pass - @classmethod - def is_null_or_empty(cls, text: str) -> bool: + @staticmethod + def is_none_or_empty(text: str) -> bool: """ Проверяет, пуста ли строка. :param text: Проверяемая строка. @@ -24,16 +25,16 @@ class StringExtension: return text is None or text == "" @classmethod - def is_null_or_whitespace(cls, text: str) -> bool: + def is_none_or_whitespace(cls, text: str) -> bool: """ Проверяет, пуста ли строка, содержит ли вместо текста только пробелы. :param text: Проверяемая строка. :return: Bool Результат проверки. """ - return cls.is_null_or_empty(text) or text.strip() == '' + return cls.is_none_or_empty(text) or text.strip() == '' - @classmethod - def is_russian_letter(cls, letter: str) -> bool: + @staticmethod + def is_russian_letter(letter: str) -> bool: """ Проверяет, является ли символ русским буквой. :param letter: Проверяемый символ. @@ -42,8 +43,8 @@ class StringExtension: return letter in StringExtensionConstants.russian_letters - @classmethod - def get_russian_letter_transliteration(cls, letter: str) -> bool | None: + @staticmethod + def get_russian_letter_transliteration(letter: str) -> bool | None: """ Получаю транслитерированную букву русского алфавита. :param letter: Буква русского алфавита. @@ -95,3 +96,166 @@ class StringExtension: # Вывожу результат return result + + @classmethod + def compare(cls, str1: str | None, str2: str | None, ignore_case: bool = False) -> int: + """ + Сравнивает две строки. + :param str1: Первая строка. + :param str2: Вторая строка. + :param ignore_case: Нужно ли учитывать регистр (по умолчанию, нет). + :return: Результат сравнения. Возвращаемые значения: + -1 | значение str1 меньше значения str2. + 0 | значения str1 и str2 равны. + 1 | значение str1 больше значения str2. + """ + # Если обе строки пусты + if cls.is_none_or_whitespace(str1) and cls.is_none_or_whitespace(str2): + # - то считаем их равными + return 0 + + # Если первый из них не пуст, а второй пуст + if not cls.is_none_or_whitespace(str1) and cls.is_none_or_whitespace(str2): + # - то первый больше + return 1 + + # Если первый из них пуст, а второй не пуст + if cls.is_none_or_whitespace(str1) and not cls.is_none_or_whitespace(str2): + # - то первый меньше + return -1 + + # Если не нужно учитывать регистр + # - преобразую (или нет) первую строку + compare_str_1 = str1 if not ignore_case else str1.lower() + # - преобразую (или нет) вторую строку + compare_str_2 = str2 if not ignore_case else str2.lower() + + # Проверяю равенство + if compare_str_1 == compare_str_2: + # - и если равны, то возвращаю 0 + return 0 + + # Они не равны, поэтому получим длину первого слова и второго + len1 = len(compare_str_1) + len2 = len(compare_str_2) + + # Если длина первого больше и равна второго, то верну 1, иначе -1 + return 1 if len1 >= len2 else -1 + + @staticmethod + def get_short_text(text: str, max_length: int, end_symbols: str = '') -> str: + """ + Обрезает строку до указанных в параметре max_length символов. + :param text: Исходный текст. + :param max_length: Максимальная длина текста. + :param end_symbols: Суффикс, которым завершается обрезанная строка (по умолчанию, ""). + :return: Обрезанный текст. + """ + # Если длина текста меньше максимальной + if len(text) <= max_length: + # - то возвращаем сам текст + return text + + # Если длина текста больше максимальной, то получаю длину текста без суффикса + len_no_end_symbols = max_length - len(end_symbols) + + # Возвращаю обрезанный текст + return text[:len_no_end_symbols] + end_symbols + + @staticmethod + def to_utf8(subject: str, encoding: str = 'UTF-8') -> str: + """ + Перекодирует строку в UTF-8. + :param subject: Исходная строка. + :param encoding: Исходная кодировка (по умолчанию, UTF-8). + :return: Перекодированная строка. + """ + # Если текущая кодировка уже UTF-8 + if encoding == 'UTF-8': + # - то возвращаю исходную строку + return subject + + # Получаем байты оригинальной строки + bytes_original = subject.encode(encoding) + + # Преобразовываем в Unicode (используя указанную кодировку) + unicode_string = bytes_original.decode(encoding) + + # Кодируем в UTF-8 + utf8_bytes = unicode_string.encode('UTF-8') + + # Возвращаем результат + return utf8_bytes.decode('UTF-8') + + @staticmethod + def from_utf8(subject: str, to_encoding: str = 'UTF-8') -> str: + """ + Перекодирует строку из UTF-8. + :param subject: Исходная строка. + :param to_encoding: Кодировка, в которую нужно перекодировать (по умолчанию, UTF-8). + :return: Перекодированная строка. + """ + # Если нужно перекодировать в UTF-8 + if to_encoding == 'UTF-8': + # - то возвращаю исходную строку + return subject + + # Получаю байты строки + target_bytes = subject.encode('UTF-8') + + # Преобразовываю в нужную кодировку и возвращаю результат + return str(target_bytes.decode('UTF-8').encode(to_encoding)) + + @classmethod + def replace(cls, subject: str, search: str, replace: str, encoding: str = 'UTF-8') -> str: + """ + Заменяет в строке все вхождения строки поиска на строку замены. + :param subject: Исходная строка. + :param search: Строка поиска. + :param replace: Строка замены. + :param encoding: Кодировка (по умолчанию, UTF-8). + :return: Результат замены. + """ + # Если кодировка не UTF-8 + if encoding != 'UTF-8': + # - то перекодируем строку поиска, замены и исходную строку в UTF-8 + search = cls.to_utf8(search, encoding) + # - и перекодируем строку замены в UTF-8 + replace = cls.to_utf8(replace, encoding) + # - и перекодируем исходную строку в UTF-8 + subject = cls.to_utf8(subject, encoding) + + # Используем re.escape для экранирования спецсимволов + pattern = re.escape(search) + + # Замена всех вхождений search на replace + result = re.sub(pattern, replace, subject) + + # Если кодировка не UTF-8 + if encoding != 'UTF-8': + # - то перекодируем результат в нужную кодировку + result = cls.from_utf8(result, encoding) + + # Возвращаем результат + return result + + @classmethod + def replace_all(cls, search_replace: dict[str, str], subject: str, encoding: str = 'UTF-8') -> str: + """ + Заменяет в строке все вхождения строки поиска на строку замены. + :param search_replace: Словарь с парами поиска и замены. Например, {'-': '#', '$': '%'} + заменит все дефисы на # и все доллары на %. + :param subject: Исходная строка. + :param encoding: Кодировка (по умолчанию, UTF-8). + :return: Результат замены. + """ + # Создаю результат + result = subject + + # Для каждой пары поиска и замены + for search, replace in search_replace.items(): + # - заменяю все вхождения строки поиска на строку замены в заданной строке + result = cls.replace(result, search, replace, encoding) + + # Возвращаю результат + return result diff --git a/help/class_desc/extensions/string_extension.md b/help/class_desc/extensions/string_extension.md new file mode 100644 index 0000000..a1ce8f6 --- /dev/null +++ b/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) \ No newline at end of file diff --git a/help/class_desc/extensions/string_extension_constant.md b/help/class_desc/extensions/string_extension_constant.md new file mode 100644 index 0000000..0ae4939 --- /dev/null +++ b/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) \ No newline at end of file diff --git a/help/index.md b/help/index.md new file mode 100644 index 0000000..b7d0e1a --- /dev/null +++ b/help/index.md @@ -0,0 +1,67 @@ +# Добро пожаловать в справочное руководство по компонентам PHP DB COMPONENTS PACK! + +**Руководство актуально для версии v1.0.2** + +**Автор: Александр Бабаев** + +## Выберете интересующий Вас раздел: + +## Базовое использование: + +1. [x] [Подготовка к использованию](basic_usage/usage_preparation.md) +2. [x] [Создание таблицы](basic_usage/create_table.md) +3. [x] [Вставка данных](basic_usage/insert_data.md) +4. [x] [Получение данных](basic_usage/get_data.md) +5. [x] [Проверка существования данных и их количество](basic_usage/count_exist_data.md) +6. [x] [Обновление данных](basic_usage/update_data.md) +7. [x] [Удаление данных](basic_usage/delete_data.md) +8. [x] [Удаление таблицы](basic_usage/drop_table.md) + +## Описание интерфейсов, классов и перечислений: + +### Атрибуты + +- [AutoIncrement](class_desc/attributes/AutoIncrement.md) +- [Check](class_desc/attributes/Check.md) +- [Compare](class_desc/attributes/Compare.md) +- [ConvertToDB](class_desc/attributes/ConvertToDB.md) +- [DataType](class_desc/attributes/DataType.md) +- [DefaultValue](class_desc/attributes/DefaultValue.md) +- [FieldName](class_desc/attributes/FieldName.md) +- [ForeignKey](class_desc/attributes/ForeignKey.md) +- [IgnoredInDB](class_desc/attributes/IgnoredInDB.md) +- [NotNull](class_desc/attributes/NotNull.md) +- [PrimaryKey](class_desc/attributes/PrimaryKey.md) +- [Unique](class_desc/attributes/Unique.md) + +### Модели + +- [DataBaseColumn](class_desc/models/DataBaseColumn.md) +- [DBConfig](class_desc/models/DBConfig.md) +- [DBItemProperty](class_desc/models/DBItemProperty.md) + +### Перечисления + +- [DBDriver](class_desc/extensions/string_extension_constant.md) +- [DBOperation](class_desc/extensions/str_ex.md) +- [DBType](class_desc/extensions/string_extension.md) + +### Интерфейсы + +- [IDBItem](class_desc/interfaces/IDBItem.md) +- [ITableManager](class_desc/interfaces/ITableManager.md) + +### Классы + +- [Condition](class_desc/classes/Condition.md) +- [ConditionBuilder](class_desc/classes/ConditionBuilder.md) +- [ConditionGroup](class_desc/classes/ConditionGroup.md) +- [Database](class_desc/classes/Database.md) + +#### Драйвера управления таблицами + +- [MySQLTableManager](class_desc/classes/tm_drivers/MySQLTableManager.md) +- [MSSQLTableManager](class_desc/classes/tm_drivers/MSSQLTableManager.md) +- [PostgreSQLTableManager](class_desc/classes/tm_drivers/PostgreSQLTableManager.md) +- [OracleDBTableManager](class_desc/classes/tm_drivers/OracleDBTableManager.md) +- [SQLiteTableManager](class_desc/classes/tm_drivers/SQLiteTableManager.md) \ No newline at end of file