babaev-an/anb_python_components
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

20251002

Browse Source
This commit is contained in:
Александр Бабаев
2025-10-02 18:08:16 +03:00
parent 9bf4a43cce
commit 2fba613ae8
5 changed files with 485 additions and 144 deletions
Download Patch File Download Diff File Expand all files Collapse all files

136
anb_python_components/extensions/StringExtension.php
View File

@@ -1,136 +0,0 @@
<?php
namespace goodboyalex\php_components_pack\extensions;
/**
* Расширение строк.
*
* @author Александр Бабаев
* @package php_components_pack
* @version 1.0
* @since 1.0
*/
final class StringExtension
{
/**
* Сравнивает две строки.
*
* @param string|null $str1 Первая строка.
* @param string|null $str2 Вторая строка.
* @param bool $ignoreCase Игнорировать регистр.
*
* @return int Результат сравнения. Возвращаемые значения:
*
* -1 | значение $str1 меньше значения $str2.
* 0 | значения $str1 и $str2 равны.
* 1 | значение $str1 больше значения $str2.
*/
public static function Compare (string|null $str1, string|null $str2, bool $ignoreCase = false): int
{
// Если оба пусты
if (self::IsNullOrWhitespace($str1) && self::IsNullOrWhitespace($str2))
// - то равны
return 0;
// Если первый из них не пуст, а второй пуст
if (!self::IsNullOrWhitespace($str1) && self::IsNullOrWhitespace($str2))
// - то первый больше
return 1;
// Если первый из них пуст, а второй не пуст
if (!self::IsNullOrWhitespace($str1) && self::IsNullOrWhitespace($str2))
// - то первый меньше
return -1;
// Если нужно игнорировать регистр
if ($ignoreCase)
// - то сравниваем по "человечески" без учёта регистра
return strnatcasecmp($str1, $str2);
// Иначе сравниваем по "человечески" с учётом регистра
return strnatcmp($str1, $str2);
}
/**
* Обрезает строку до указанных в параметре $maxLength символов
*
* @param string $text Исходный текст
* @param int $maxLength Максимальная длина текста
* @param string $endDots Суффикс, которым завершается обрезанная строка
*
* @return string Обрезанный текст
*/
public static function GetShortText (string $text, int $maxLength, string $endDots = ''): string
{
// Если длина текста меньше максимальной
if (mb_strlen($text) <= $maxLength)
// - то возвращаю исходный текст
return $text;
// Если длина текста больше максимальной, то получаю длину текста без суффикса
$lengthWithoutEndDots = $maxLength - mb_strlen($endDots);
// Возвращаю обрезанный текст
return mb_substr($text, 0, $lengthWithoutEndDots) . $endDots;
}
/**
* Функция заменяет все вхождения строк поиск на соответствующие строки замены в заданной строке.
*
* @param array $searchReplace Массив с парами поиска и замены. Например, <code>['-' => '#', '$' => '%']</code>
* заменит все дефисы на # и все доллары на %.
* @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;
}
}

180
anb_python_components/extensions/string_extension.py
View File

@@ -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

186
help/class_desc/extensions/string_extension.md Normal file
View File

@@ -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)

60
help/class_desc/extensions/string_extension_constant.md Normal file
View File

@@ -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)

67
help/index.md Normal file
View File

@@ -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)