anb-python-components 1.2.1__tar.gz → 1.4.0__tar.gz

anb_python_components-1.4.0/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: anb_python_components
+Version: 1.4.0
+Summary: Набор компонентов Python, которые упрощают разработку / A set of Python components that simplify development
+Home-page: https://gitflic.ru/project/babaev-an/anb-python-components
+Author: Александр Бабаев
+Author-email: contact_with_us@babaev-an.ru
+Project-URL: Documentation, https://gitflic.ru/project/babaev-an/anb-python-components/wiki
+Project-URL: Source, https://gitflic.ru/project/babaev-an/anb-python-components
+Project-URL: Tracker, https://gitflic.ru/project/babaev-an/anb-python-components/issue?page=0
+Keywords: python components development utils
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.14.0
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: setuptools>=80.9.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# 📌🇷🇺 Русская версия
+
+---
+
+## Набор компонентов Python для упрощения разработки приложений
+
+**ANB Python Components** — это библиотека полезных классов и модулей, предназначенная для ускорения процесса разработки
+программного обеспечения на языке программирования Python. Библиотека включает широкий спектр инструментов, облегчающих
+выполнение повседневных задач разработчика, от обработки файлов и сетевых запросов до автоматизации тестирования и
+интеграции с популярными фреймворками.
+
+### ✅ Основные возможности:
+
+- Удобные инструменты для работы с файлами и каталогами.
+- Классы для работы с файлами и директориями.
+- Классы для удобной передачи состояния.
+- Новые
+  типы [GUID](https://gitflic.ru/project/babaev-an/anb-python-components/wiki/page?file=class_desc%2Ftypes%2Fguid.md),
+  [TwoDimSize](https://gitflic.ru/project/babaev-an/anb-python-components/wiki/page?file=class_desc%2Ftypes%2Ftwo_dim_size.md)
+  и [VersionInfo](https://gitflic.ru/project/babaev-an/anb-python-components/wiki/page?file=class_desc%2Ftypes%2Fversion_info.md).
+- Расширение массивов, типа `bool`, типа `GUID`, типа `str`.
+- Класс для перевода любого типа в строку и наоборот.
+
+### ⚙️ Установка и использование:
+
+Установить пакет можно через pip:
+
+```bash
+pip install anb-python-components --index-url https://registry.gitflic.ru/project/babaev-an/anb-python-components/package/-/pypi/simple
+```
+
+Подключайте необходимые модули и начните пользоваться ими прямо сейчас:
+
+```python
+from anb_python_components.custom_types.two_dim_size import TwoDimSize
+
+# Пример использования
+two_dim = TwoDimSize.parse('100x150', 'x')
+
+# Теперь присваиваем какому-либо объекту
+some_object_width = two_dim.width
+some_object_height = two_dim.height
+```
+
+### 🛠️ Поддерживаемые технологии:
+
+- `Python` версии 3.13.7 и выше
+- Совместима с большинством популярных веб-фреймворков и библиотек Python
+- Оптимизирован для работы с большими объемами данных и высоконагруженными приложениями
+
+### 💬 Вопросы и поддержка:
+
+Для подробной справки обратитесь к руководству по библиотеке в разделе документации:
+
+🔗 Справочное руководство → [Документация библиотеки](https://gitflic.ru/project/babaev-an/anb-python-components/wiki)
+
+---
+
+# 📌🇬🇧 English Version
+
+---
+
+## Python Component Collection for Streamlining Application Development
+
+**ANB Python Components** is a collection of useful classes and modules specifically tailored to accelerate the process
+of developing software using the Python programming language. It offers a broad spectrum of tools that simplify everyday
+developer tasks, from file manipulation and network requests to test automation and seamless integration with widely
+used frameworks.
+
+### ✅ Main Features:
+
+- Handy tools for working with files and directories.
+- Classes for handling files and folders.
+- Classes for convenient state transfer.
+- New custom_types such
+  as [GUID](https://gitflic.ru/project/babaev-an/anb-python-components/wiki/page?file=class_desc%2Ftypes%2Fguid.md), [TwoDimSize](https://gitflic.ru/project/babaev-an/anb-python-components/wiki/page?file=class_desc%2Ftypes%2Ftwo_dim_size.md),
+  and [VersionInfo](https://gitflic.ru/project/babaev-an/anb-python-components/wiki/page?file=class_desc%2Ftypes%2Fversion_info.md).
+- Extensions for arrays, `bool`, `GUID`, and `str` custom_types.
+- Class for converting any type into string representation and vice versa.
+
+### ⚙️ Installation and Usage:
+
+You can install this package via pip:
+
+```bash
+pip install anb-python-components --index-url https://registry.gitflic.ru/project/babaev-an/anb-python-components/package/-/pypi/simple
+```
+
+Import required modules and start using them immediately:
+
+```python
+from anb_python_components.custom_types.two_dim_size import TwoDimSize
+
+# Example usage
+two_dim = TwoDimSize.parse('100x150', 'x')
+
+# Now assign it to some object
+some_object_width = two_dim.width
+some_object_height = two_dim.height
+```
+
+### 🛠️ Supported Technologies:
+
+- **Python**: version 3.13.7 or higher
+- Compatibility with most popular Python web frameworks and libraries
+- Optimized for performance with large-scale datasets and highly loaded applications
+
+### 💬 Questions and Support:
+
+For comprehensive guidance and support, consult the library's documentation section:
+
+🔗 Reference Guide → [Library Documentation](https://gitflic.ru/project/babaev-an/anb-python-components/wiki) (in Russian
+Only)

anb_python_components-1.4.0/anb_python_components/__init__.py

@@ -0,0 +1,46 @@
+# anb_python_components/__init__.py
+
+# classes
+from anb_python_components.classes import ActionState, DataclassAnalyzer, Directory, File, Interface, ShortCodeParser
+# custom_types
+from anb_python_components.custom_types import GUID, ObjectArray, ShortCodeAttributes, TwoDimSize, VersionInfo
+# decorators
+from anb_python_components.decorators import implement, interface_required
+# enums
+from anb_python_components.enums import MessageType, NotBoolAction, TypeCopyStrategy
+# exceptions
+from anb_python_components.exceptions import WrongTypeException
+# extensions
+from anb_python_components.extensions import (
+    ArrayExtension, BoolExtension, DataClassExtension, StringExtension,
+    TypeExtension
+    )
+# models
+from anb_python_components.models import ActionStateMessage, ShortCodeModel
+
+__all__ = [
+        'ActionState',
+        'Directory',
+        'File',
+        'DataclassAnalyzer',
+        'Interface',
+        'ShortCodeParser',
+        'GUID',
+        'ObjectArray',
+        'ShortCodeAttributes',
+        'TwoDimSize',
+        'VersionInfo',
+        'interface_required',
+        'implement',
+        'MessageType',
+        'NotBoolAction',
+        'TypeCopyStrategy',
+        'WrongTypeException',
+        'ArrayExtension',
+        'BoolExtension',
+        'StringExtension',
+        "TypeExtension",
+        "DataClassExtension",
+        'ActionStateMessage',
+        'ShortCodeModel'
+        ]

anb_python_components-1.4.0/anb_python_components/classes/__init__.py

@@ -0,0 +1,8 @@
+# anb_python_components/classes/__init__.py
+
+from anb_python_components.classes.action_state import ActionState
+from anb_python_components.classes.dataclass_analyzer import DataclassAnalyzer
+from anb_python_components.classes.directory import Directory
+from anb_python_components.classes.file import File
+from anb_python_components.classes.interface import Interface
+from anb_python_components.classes.shortcode_parser import ShortCodeParser

{anb_python_components-1.2.1 → anb_python_components-1.4.0}/anb_python_components/classes/action_state.py

@@ -2,8 +2,9 @@
 import copy
 from typing import Callable
 
+from anb_python_components.enums.message_type import MessageType
 from anb_python_components.exceptions.wrong_type_exception import WrongTypeException
-from anb_python_components.models.action_state_message import ActionStateMessage, MessageType
+from anb_python_components.models.action_state_message import ActionStateMessage
 
 class ActionState[T]:
     """

anb_python_components-1.4.0/anb_python_components/classes/dataclass_analyzer.py

@@ -0,0 +1,97 @@
+# anb_python_components/classes/dataclass_analyzer.py
+from dataclasses import fields, is_dataclass
+from typing import Any
+
+class DataclassAnalyzer:
+    """
+    Класс анализа классов отмеченных как dataclass.
+    """
+    
+    @staticmethod
+    def analyze_properties (cls, prop_name: str) -> dict[str, Any]:
+        """
+        Анализирует декораторы (метаданные) указанного свойства класса.
+        :param cls: Класс (должен реализовывать dataclass).
+        :param prop_name: Имя свойства.
+        :return: Словарь с информацией о применённых декораторах.
+        """
+        # Проверяем, что класс является dataclass
+        if not is_dataclass(cls):
+            # - иначе бросаем исключение
+            raise TypeError(f"Класс {cls.__name__} не является dataclass / Class {cls.__name__} is not a dataclass")
+        
+        # Находим поле по имени
+        # - задаём начальное значение None
+        field_obj = None
+        
+        # Перебираем поля класса
+        for field in fields(cls):
+            # - ищем поле с указанным именем
+            if field.name == prop_name:
+                # - если нашли, сохраняем объект поля
+                field_obj = field
+                # - и выходим из цикла
+                break
+        
+        # Если поле не найдено
+        if field_obj is None:
+            # - бросаем исключение
+            raise AttributeError(
+                    f"Свойство '{prop_name}' не найдено в классе {cls.__name__} / Property '{prop_name}' not found in class {cls.__name__}"
+                    )
+        
+        # Создаем словарь для результатов
+        results = {}
+        
+        # Собираем метаданные
+        metadata = field_obj.metadata or {}
+        
+        # Перебираем метаданные
+        for key, value in metadata.items():
+            # - добавляем в словарь
+            results[key] = value
+        
+        # Возвращаем результаты
+        return results
+    
+    @staticmethod
+    def analyze_class (cls) -> dict[str, dict[str, Any]]:
+        """
+        Анализирует все свойства dataclass-класса и класс‑уровневые метаданные.
+        :param cls: Dataclass-класс.
+        :return: Словарь с метаданными полей и класса.
+        """
+        # Проверяем, что класс является dataclass
+        if not is_dataclass(cls):
+            # - иначе бросаем исключение
+            raise TypeError(f"Класс {cls.__name__} не является dataclass / Class {cls.__name__} is not a dataclass")
+        
+        results = {}
+        
+        # Собираем класс‑уровневые метаданные (всё, что начинается с __meta_)
+        # - создаём пустой словарь
+        class_metadata = {}
+        
+        # Перебираем атрибуты класса
+        for attr_name in dir(cls):
+            # - ищем атрибуты, начинающиеся с __meta_
+            if attr_name.startswith("__meta_"):
+                # -- удаляем префикс __meta_ и берём значение
+                key = attr_name[len("__meta_"):]
+                # -- добавляем в словарь
+                class_metadata[key] = getattr(cls, attr_name)
+        
+        # Если есть метаданные
+        if class_metadata:
+            # - добавляем в результаты
+            results["__CLASS__"] = class_metadata
+        
+        # Анализируем каждое поле
+        for field in fields(cls):
+            # - получаем имя поля
+            field_name = field.name
+            # - анализируем поле и сохраняем результаты в словарь
+            results[field_name] = DataclassAnalyzer.analyze_properties(cls, field_name)
+        
+        # Возвращаем результаты
+        return results

anb_python_components-1.4.0/anb_python_components/classes/interface.py

@@ -0,0 +1,192 @@
+# anb_python_components/classes/interface.py
+
+import inspect
+from functools import lru_cache
+from typing import Any, Protocol, get_origin, runtime_checkable
+
+@runtime_checkable
+class Interface(Protocol):
+    """
+    Базовый класс для объявления интерфейсов с расширенной проверкой.
+    """
+    
+    @classmethod
+    @lru_cache(maxsize = 128)
+    def verify (cls, obj_or_class) -> tuple[bool, list[str]]:
+        """
+        Проверяет, что объект или класс реализует интерфейс.
+        :param obj_or_class: Объект (созданный класс) или класс (или, точнее, его имя), который должен реализовывать интерфейс.
+        :return: Кортеж (is_ok, problems), где is_ok — True, если объект или класс реализует интерфейс, иначе False,
+            а problems — список сообщений об ошибках, если is_ok == False.
+        """
+        # Разбираем аргумент на объект или имя класса. Если аргумент — имя класса, то получаем его класс. В противном случае,
+        # возвращаем аргумент как объект.
+        target = obj_or_class if isinstance(obj_or_class, type) else obj_or_class.__class__
+        
+        # Инициализируем список проблем
+        problems = []
+        
+        # Собираем все методы интерфейса (включая унаследованные)
+        interface_methods = cls._get_all_interface_methods()
+        
+        # Проходим по методам интерфейса
+        for method_name, signature in interface_methods.items():
+            # - если метод отсутствует в объекте
+            if not hasattr(target, method_name):
+                # -- добавляем в список проблем
+                problems.append(f"отсутствует метод '{method_name}' / missing method '{method_name}'")
+                # -- идём к следующему методу
+                continue
+            
+            # - получаем именованный атрибут метода
+            target_method = getattr(target, method_name)
+            
+            # - проверяем, что метод — вызываемый
+            if not callable(target_method):
+                # -- если нет, добавляем в список проблем
+                problems.append(f"'{method_name}' it is not callable")
+                # -- идём к следующему методу
+                continue
+            
+            try:
+                # - получаем сигнатуру метода
+                target_signature = inspect.signature(target_method)
+                
+                # - сравниваем сигнатуры метода и интерфейса
+                cls._compare_signatures(signature, target_signature, method_name, problems)
+            except (ValueError, TypeError) as e:
+                # Если сигнатуру нельзя получить, добавляем в список проблем
+                problems.append(f"ошибка проверки сигнатуры / signature verification error '{method_name}': {e}")
+        
+        # В результат вернём кортеж (is_ok, problems), где is_ok — True, если проблем нет, иначе False, а problems — список проблем.
+        return len(problems) == 0, problems
+    
+    @classmethod
+    def check (cls, obj_or_class) -> bool:
+        """
+        Строгая проверка — поднимает исключение при несоответствии.
+        :param obj_or_class: Объект (созданный класс) или класс (или, точнее, его имя), который должен реализовывать интерфейс.
+        :return: True, если объект или класс реализует интерфейс.
+        """
+        # Проверяем, что объект или класс реализует интерфейс методом verify и получаем результат проверки
+        is_ok, problems = cls.verify(obj_or_class)
+        
+        # Если объект или класс не реализует интерфейс
+        if not is_ok:
+            # - получаем имя объекта или класса
+            target_name = obj_or_class.__name__ if isinstance(obj_or_class, type) else obj_or_class.__class__.__name__
+            
+            # - генерируем исключение с проблемами
+            raise TypeError(
+                    f"{target_name} не реализует интерфейс {cls.__name__}.\n" +
+                    f"{target_name} not implements interface {cls.__name__}.\n" +
+                    f"Проблемы / Problems:\n" +
+                    "\n  ".join(problems)
+                    )
+        
+        # Возвращаем True, если объект или класс реализует интерфейс
+        return True
+    
+    @classmethod
+    def get_methods (cls) -> dict[str, inspect.Signature]:
+        """
+        Возвращает словарь методов интерфейса с их сигнатурами.
+        :return: Словарь методов интерфейса с их сигнатурами.
+        """
+        return cls._get_interface_methods(cls)
+    
+    @classmethod
+    def _get_all_interface_methods (cls) -> dict[str, inspect.Signature]:
+        """
+        Собирает все методы из иерархии наследования интерфейсов.
+        :return: Словарь методов с их сигнатурами.
+        """
+        # Создаем словарь методов
+        methods = {}
+        
+        # Проходим по иерархии наследования интерфейсов рекурсивно
+        for base in reversed(cls.__mro__):
+            # - пропускаем базовый класс и сам интерфейс
+            if base is Interface or not issubclass(base, Interface):
+                continue
+            
+            # - добавляем методы базового интерфейса
+            methods.update(cls._get_interface_methods(base))
+        
+        # Возвращаем собранные методы
+        return methods
+    
+    @staticmethod
+    def _get_interface_methods (interface_cls) -> dict[str, inspect.Signature]:
+        """Извлекает методы интерфейса и их сигнатуры."""
+        methods = {}
+        for attr_name in dir(interface_cls):
+            if attr_name.startswith('_') or attr_name == 'verify':
+                continue
+            attr = getattr(interface_cls, attr_name)
+            if callable(attr):
+                try:
+                    signature = inspect.signature(attr)
+                    methods[attr_name] = signature
+                except (ValueError, TypeError):
+                    # Если сигнатуру нельзя получить, оставляем пустую
+                    methods[attr_name] = inspect.Signature()
+        return methods
+    
+    @staticmethod
+    def _compare_signatures (
+            expected: inspect.Signature,
+            actual: inspect.Signature,
+            method_name: str,
+            problems: list[str]
+            ) -> None:
+        """
+        Сравнивает сигнатуры методов.
+        :param expected: Ожидаемая сигнатура.
+        :param actual: Текущая сигнатура.
+        :param method_name: Имя метода.
+        :param problems: Список проблем.
+        :return: None
+        """
+        # Проверяем количество параметров
+        expected_params = list(expected.parameters.values())
+        actual_params = list(actual.parameters.values())
+        
+        # Проверяем количество параметров
+        if len(expected_params) != len(actual_params):
+            # - если количество параметров не совпадает, добавляем в список проблем
+            problems.append(
+                    f"'{method_name}': ожидается {len(expected_params)} параметров, получено {len(actual_params)} / {method_name}': expected {len(expected_params)} parameters, got {len(actual_params)}"
+                    )
+            
+            # - прерываем выполнение
+            return
+        
+        # Проверяем типы параметров (если указаны)
+        for i, (exp_param, act_param) in enumerate(zip(expected_params, actual_params)):
+            # - проверяем, что у ожидаемого параметра (exp_param) есть аннотация
+            if exp_param.annotation is not exp_param.empty:
+                # -- получаем тип ожидаемого параметра
+                expected_type = exp_param.annotation
+                # -- получаем тип текущего параметра
+                actual_type = act_param.annotation if act_param.annotation is not act_param.empty else Any
+                
+                # -- сравниваем типы
+                if get_origin(expected_type) != get_origin(actual_type):
+                    # --- если типы не совпадают, добавляем в список проблем
+                    problems.append(
+                            f"Тип аннотации не совпадает для / annotation type mismatch for parameter '{exp_param.name}'"
+                            )
+    
+    @classmethod
+    def register (cls, target_class):
+        """
+        Регистрирует класс как реализующий интерфейс (для документации).
+        :param target_class: Класс, который должен реализовывать интерфейс.
+        :return: Регистрированный класс.
+        """
+        # Проверяем, что класс реализует интерфейс
+        cls.check(target_class)
+        
+        # Возвращаем класс
+        return target_class

{anb_python_components-1.2.1 → anb_python_components-1.4.0}/anb_python_components/classes/shortcode_parser.py

@@ -4,8 +4,8 @@ import re
 from typing import Callable, Dict
 
 from anb_python_components.classes.action_state import ActionState
-from anb_python_components.models.shortcode_model import ShortCodeModel
 from anb_python_components.custom_types.shortcode_attributes import ShortCodeAttributes
+from anb_python_components.models.shortcode_model import ShortCodeModel
 
 class ShortCodeParser:
     """

anb_python_components-1.4.0/anb_python_components/custom_types/__init__.py

@@ -0,0 +1,7 @@
+# anb_python_components/custom_types/__init__.py
+
+from anb_python_components.custom_types.guid import GUID
+from anb_python_components.custom_types.object_array import ObjectArray
+from anb_python_components.custom_types.shortcode_attributes import ShortCodeAttributes
+from anb_python_components.custom_types.two_dim_size import TwoDimSize
+from anb_python_components.custom_types.version_info import VersionInfo

anb_python_components-1.4.0/anb_python_components/decorators/__init__.py

@@ -0,0 +1,2 @@
+# anb_python_components/decorators/__init__.py
+from anb_python_components.decorators.interface_decorators import implement, interface_required

anb_python_components-1.4.0/anb_python_components/decorators/interface_decorators.py

@@ -0,0 +1,74 @@
+# anb_python_components/decorators/interface_decorators.py
+import inspect
+from typing import Callable
+
+from anb_python_components import Interface
+
+def interface_required (signature: Callable | None = None, **kwargs) -> Callable:
+    """
+    Декоратор для явного указания обязательных методов интерфейса.
+    Позволяет задать сигнатуру через аннотации.
+    """
+    
+    def decorator (func) -> Callable:
+        """
+        Декоратор для проверки сигнатуры.
+        :param func: Функция для проверки.
+        :return: Проверенная функция.
+        """
+        # Если сигнатура указана
+        if signature is not None:
+            # - сохраняем сигнатуру в атрибуте сигнатуры
+            func.__signature__ = inspect.signature(signature)
+        else:
+            # - иначе сохраняем сигнатуру в атрибуте аннотаций
+            func.__annotations__ = kwargs
+        
+        # Возвращаем функцию
+        return func
+    
+    # Возвращаем функцию-декоратор
+    return decorator
+
+def implement (interface):
+    """
+    Декоратор для явного указания реализации интерфейса.
+    :param interface: Класс-интерфейс (наследник Interface)
+    :raise: TypeError: если класс не реализует интерфейс
+    :return: Оригинальный класс (с добавленным атрибутом __implements__)
+    """
+    
+    def decorator (cls):
+        """
+        Декоратор для реализации интерфейса.
+        :param cls: Класс для реализации интерфейса.
+        :return: Оригинальный класс с реализацией интерфейса.
+        """
+        # 1. Проверяем, что interface действительно является интерфейсом
+        if not isinstance(interface, type) or not issubclass(interface, Interface):
+            raise TypeError(
+                    f"{interface} не является интерфейсом (не наследуется от Interface) / is not an interface (does not inherit from Interface)"
+                    )
+        
+        # 2. Выполняем строгую проверку реализации
+        try:
+            interface.check(cls)
+        except TypeError as e:
+            raise TypeError(
+                    f"Класс {cls.__name__} не реализует интерфейс {interface.__name__} / class {cls.__name__} does not implement interface {interface.__name__}\n  {e}"
+                    ) from e
+        
+        # 3. Добавляем метаданные о реализации
+        if not hasattr(cls, '__implements__'):
+            cls.__implements__ = []
+        cls.__implements__.append(interface)
+        
+        # 4. Сохраняем ссылку на интерфейс для интроспекции
+        impl_attr = f'__implements_{interface.__name__}'
+        setattr(cls, impl_attr, True)
+        
+        # 5. Декоратор должен вернуть оригинальный класс
+        return cls
+    
+    # Возвращаем функцию-декоратор
+    return decorator

anb_python_components-1.4.0/anb_python_components/enums/__init__.py

@@ -0,0 +1,5 @@
+# anb_python_components/enums/__init__.py
+
+from anb_python_components.enums.message_type import MessageType
+from anb_python_components.enums.not_bool_action import NotBoolAction
+from anb_python_components.enums.type_copy_strategy import TypeCopyStrategy

anb_python_components-1.4.0/anb_python_components/exceptions/__init__.py

@@ -0,0 +1,3 @@
+# anb_python_components/exceptions/__init__.py
+
+from anb_python_components.exceptions.wrong_type_exception import WrongTypeException

anb_python_components-1.4.0/anb_python_components/extensions/__init__.py

@@ -0,0 +1,7 @@
+# anb_python_components/extensions/__init__.py
+
+from anb_python_components.extensions.array_extension import ArrayExtension
+from anb_python_components.extensions.bool_extension import BoolExtension
+from anb_python_components.extensions.dataclass_extension import DataClassExtension
+from anb_python_components.extensions.string_extension import StringExtension
+from anb_python_components.extensions.type_extension import TypeExtension