edu-rdm-integration 3.9.1__py3-none-any.whl → 3.10.0__py3-none-any.whl

edu_rdm_integration/__init__.py

@@ -1 +0,0 @@
-default_app_config = 'edu_rdm_integration.apps.EduRDMIntegrationConfig'

edu_rdm_integration/adapters/apps.py

@@ -4,8 +4,21 @@ from django.apps import (
 
 
 class WebEduFunctionToolsConfig(AppConfig):
-    """
-    Конфиг приложения edu_rdm_integration.adapters.function_tools.
+    """Конфигурация приложения для интеграции с function_tools.
+    
+    Определяет основные параметры Django-приложения, которое
+    обеспечивает работу с библиотекой function_tools в контексте
+    продуктов Образования.
+    
+    Attributes:
+        name (str): Полное имя приложения в системе Django
+        verbose_name (str): Человекочитаемое название приложения
+        label (str): Уникальная метка приложения для Django
+        
+    Note:
+        Приложение автоматически регистрируется в Django при старте
+        и обеспечивает всю необходимую инфраструктуру для работы
+        с function_tools.
     """
 
     name = 'edu_rdm_integration.adapters.function_tools'

edu_rdm_integration/adapters/caches.py

@@ -11,14 +11,22 @@ from function_tools.caches import (
 
 
 class WebEduEntityCache(EntityCache, metaclass=ABCMeta):
-    """
-    Базовый класс кеша объектов сущности продуктов Образования.
+    """Базовый класс кэша для сущностей продуктов Образования.
+    
+    Предоставляет механизм кэширования отдельных сущностей системы.
+    Используется для:
+    - Хранения часто запрашиваемых объектов
+    - Снижения нагрузки на базу данных
+    - Ускорения доступа к данным
+    
+    Note:
+        Конкретные реализации должны определить специфику кэширования
+        для каждого типа сущности.
     """
 
 
 class WebEduPeriodicalEntityCache(PeriodicalEntityCache, metaclass=ABCMeta):
-    """
-    Базовый класс периодического кеша продуктов Образования.
+    """Базовый класс периодического кеша продуктов Образования.
 
     Кеш создается для определенной модели с указанием двух дат, на которые
     должны быть собраны кеши актуальных объектов модели.
@@ -26,18 +34,23 @@ class WebEduPeriodicalEntityCache(PeriodicalEntityCache, metaclass=ABCMeta):
 
 
 class WebEduRunnerCacheStorage(CacheStorage, metaclass=ABCMeta):
-    """
-    Базовый класс кешей помощников ранеров функций продуктов Образования.
-    """
+    """Базовый класс кешей помощников ранеров функций продуктов Образования."""
 
 
 class WebEduFunctionCacheStorage(CacheStorage, metaclass=ABCMeta):
-    """
-    Базовый класс кешей функций продуктов Образования.
-    """
+    """Базовый класс кешей функций продуктов Образования."""
 
 
 class WebEduFunctionPatchedGlobalCacheStorage(PatchedGlobalCacheStorage, metaclass=ABCMeta):
-    """
-    Базовый класс кешей функций продуктов Образования с возможностью патчинга кешем глобального хелпера.
+    """Базовый класс глобального хранилища кэша с поддержкой патчинга.
+    
+    Расширяет стандартное хранилище кэша, добавляя возможность
+    модификации данных через механизм патчинга. Это позволяет:
+    - Обновлять кэшированные данные без полной перезагрузки
+    - Синхронизировать кэш между разными компонентами
+    - Эффективно управлять общими данными
+    
+    Note:
+        Патчинг должен использоваться с осторожностью, чтобы избежать
+        несогласованности данных между разными частями системы.
     """

edu_rdm_integration/adapters/errors.py

@@ -8,6 +8,17 @@ from function_tools.errors import (
 
 
 class WebEduError(BaseError, metaclass=ABCMeta):
-    """
-    Базовый класс ошибок функций продуктов Образования.
+    """Базовый класс для ошибок в системе интеграции с продуктами Образования.
+    
+    Предоставляет основную функциональность для обработки ошибок:
+    - Форматирование сообщений об ошибках
+    - Сохранение контекста возникновения ошибки
+    - Классификация типов ошибок
+    - Механизм обработки вложенных ошибок
+        
+    Note:
+        При создании конкретных типов ошибок рекомендуется:
+        - Определять специфичные коды ошибок
+        - Предоставлять информативные сообщения
+        - Включать контекстную информацию в details
     """

edu_rdm_integration/adapters/functions.py

@@ -1,3 +1,11 @@
+"""Базовые классы функций для интеграции с продуктами Образования.
+
+Этот модуль содержит базовые классы функций, которые используются для создания
+конкретных реализаций функций обработки данных в системе. Модуль предоставляет
+различные варианты базовых классов с разными стратегиями сохранения данных
+и управления очередями объектов.
+"""
+
 from abc import (
     ABCMeta,
 )
@@ -20,32 +28,55 @@ from edu_rdm_integration.adapters.validators import (
 
 
 class WebEduFunction(BaseFunction, metaclass=ABCMeta):
-    """
-    Базовый класс для создания функций продуктов Образования.
+    """Базовый класс для создания функций продуктов Образования.
+    
+    Предоставляет основной интерфейс для создания функций обработки данных.
+    Наследуется от BaseFunction и добавляет специфичную для продуктов
+    Образования функциональность.
+    
+    Note:
+        Этот класс является абстрактным и должен быть расширен конкретными
+        реализациями функций.
     """
 
 
 class WebEduLazySavingPredefinedQueueFunction(LazySavingPredefinedQueueFunction, metaclass=ABCMeta):
-    """
-    Базовый класс для создания функций с отложенным сохранением объектов
-    моделей с предустановленной очередью продуктов Образования.
+    """Базовый класс для создания функций с отложенным сохранением.
+    
+    Реализует паттерн отложенного сохранения (lazy saving) с предустановленной
+    очередью объектов. Это позволяет:
+    - Накапливать объекты для сохранения в течение выполнения функции
+    - Сохранять все объекты атомарно после успешного выполнения всех операций
+    - Откатывать все изменения в случае ошибки
+    - Оптимизировать производительность за счет пакетного сохранения
+    
+    Attributes:
+        helper (WebEduFunctionHelper): Помощник функции для вспомогательных операций
+        validator (WebEduFunctionValidator): Валидатор для проверки данных
+        result (WebEduFunctionResult): Объект для хранения результатов работы
     """
 
     def _prepare_helper_class(self) -> type[WebEduFunctionHelper]:
-        """
-        Возвращает класс помощника функции.
+        """Возвращает класс помощника функции.
+        
+        Returns:
+            type[WebEduFunctionHelper]: Класс помощника для работы с данными
         """
         return WebEduFunctionHelper
 
     def _prepare_validator_class(self) -> type[WebEduFunctionValidator]:
-        """
-        Возвращает класс валидатора функции.
+        """Возвращает класс валидатора функции.
+        
+        Returns:
+            type[WebEduFunctionValidator]: Класс для валидации входных данных
         """
         return WebEduFunctionValidator
 
     def _prepare_result_class(self) -> type[WebEduFunctionResult]:
-        """
-        Возвращает класс результата функции.
+        """Возвращает класс результата функции.
+        
+        Returns:
+            type[WebEduFunctionResult]: Класс для хранения результатов выполнения
         """
         return WebEduFunctionResult
 
@@ -54,7 +85,15 @@ class WebEduLazySavingPredefinedQueueGlobalHelperFunction(
     LazySavingPredefinedQueueGlobalHelperFunction,
     metaclass=ABCMeta,
 ):
+    """Базовый класс для создания функций с глобальным помощником.
+    
+    Расширяет функциональность WebEduLazySavingPredefinedQueueFunction,
+    добавляя поддержку глобального помощника. Это позволяет:
+    - Использовать общие вспомогательные методы между разными функциями
+    - Кэшировать часто используемые данные на уровне всего приложения
+    - Оптимизировать использование ресурсов при массовой обработке данных
+    
+    Note:
+        Глобальный помощник должен быть потокобезопасным, так как может
+        использоваться одновременно несколькими функциями.
     """
-    Базовый класс для создания функций с отложенным сохранением,
-    предустановленной очередью на сохранение и глобальным помощником продуктов Образования.
-    """

edu_rdm_integration/adapters/helpers.py

@@ -14,24 +14,50 @@ from edu_rdm_integration.adapters.caches import (
 
 
 class WebEduRunnerHelper(BaseRunnerHelper, metaclass=ABCMeta):
-    """
-    Базовый класс помощников ранеров функций продуктов Образования.
+    """Базовый класс помощников для исполнителей функций.
+    
+    Предоставляет вспомогательную функциональность для исполнителей,
+    включая:
+    - Кэширование данных исполнителя
+    - Общие утилиты для работы с функциями
+    - Доступ к разделяемым ресурсам
+    
+    Attributes:
+        cache (WebEduRunnerCacheStorage): Хранилище кэша для исполнителя
     """
 
     def _prepare_cache_class(self) -> type[WebEduRunnerCacheStorage]:
-        """
-        Возвращает класс кеша помощника ранера.
+        """Возвращает класс хранилища кэша для исполнителя.
+        
+        Returns:
+            type[WebEduRunnerCacheStorage]: Класс для кэширования данных
+            исполнителя
         """
         return WebEduRunnerCacheStorage
 
 
 class WebEduFunctionHelper(BaseFunctionHelper, metaclass=ABCMeta):
-    """
-    Базовый класс помощников функций продуктов Образования.
+    """Базовый класс помощников для функций обработки данных.
+    
+    Предоставляет вспомогательную функциональность для функций,
+    включая:
+    - Кэширование данных функции
+    - Общие утилиты для обработки данных
+    - Доступ к разделяемым ресурсам
+    
+    Note:
+        Каждая конкретная функция может расширить этот класс,
+        добавив специфичные для неё вспомогательные методы.
+    
+    Attributes:
+        cache (WebEduFunctionCacheStorage): Хранилище кэша для функции
     """
 
     def _prepare_cache_class(self) -> type[WebEduFunctionCacheStorage]:
-        """
-        Возвращает класс кеша помощника функции.
+        """Возвращает класс хранилища кэша для функции.
+        
+        Returns:
+            type[WebEduFunctionCacheStorage]: Класс для кэширования данных
+            функции
         """
         return WebEduFunctionCacheStorage

edu_rdm_integration/adapters/managers.py

@@ -12,14 +12,50 @@ from edu_rdm_integration.adapters.runners import (
 
 
 class WebEduRunnerManager(RunnerManager, metaclass=ABCMeta):
-    """
-    Базовый класс менеджеров пускателей функций продуктов Образования.
+    """Базовый класс менеджеров исполнителей функций продуктов Образования.
+
+    Предоставляет базовую функциональность для управления исполнителями
+    (runners) функций в контексте образовательных продуктов. Наследует
+    возможности RunnerManager и адаптирует их для специфики образовательной
+    системы.
+
+    Основные возможности:
+    - Создание и инициализация исполнителей функций
+    - Управление жизненным циклом исполнителей
+    - Конфигурация исполнителей для образовательных задач
+    - Интеграция с системой образовательных продуктов
+
+    Note:
+        - Является абстрактным классом
+        - Требует реализации в конкретных менеджерах
+        - Использует WebEduRunner как базовый класс исполнителей
+        - Интегрируется с другими компонентами системы образования
+        - Обеспечивает единообразное управление исполнителями
+
+    See Also:
+        - RunnerManager: базовый класс для управления исполнителями
+        - WebEduRunner: базовый класс исполнителей
+        - WebEduRunnerCacheStorage: хранилище кеша для исполнителей
     """
 
     @classmethod
     def _prepare_runner_class(cls) -> type[WebEduRunner]:
-        """
-        Возвращает класс ранера.
+        """Возвращает класс исполнителя для образовательных функций.
+
+        Определяет WebEduRunner как базовый класс для всех исполнителей
+        в системе образовательных продуктов. Этот метод вызывается при
+        создании новых исполнителей.
+
+        Returns:
+            type[WebEduRunner]: Класс исполнителя WebEduRunner
+
+        Note:
+            - Метод является частью инициализации исполнителей
+            - Переопределяет метод базового класса RunnerManager
+            - Гарантирует использование правильного типа исполнителя
+            - Может быть переопределен в наследниках для специфических исполнителей
+
+        See Also:
+            - WebEduRunner: базовый класс исполнителей
         """
         return WebEduRunner
-

edu_rdm_integration/adapters/presenters.py

@@ -8,6 +8,30 @@ from function_tools.presenters import (
 
 
 class WebEduResultPresenter(ResultPresenter, metaclass=ABCMeta):
-    """
-    Базовый класс презентеров результатов работы функций продуктов Образования.
+    """Базовый класс презентеров результатов работы функций продуктов Образования.
+
+    Предоставляет базовую функциональность для форматирования и представления
+    результатов выполнения функций в контексте образовательных продуктов.
+    Наследует возможности ResultPresenter и адаптирует их для специфики
+    образовательной системы.
+
+    Основные возможности:
+    - Форматирование результатов выполнения функций
+    - Адаптация данных для различных потребителей
+    - Поддержка различных форматов вывода
+    - Интеграция с системой отчетности
+
+    Note:
+        - Является абстрактным классом
+        - Требует реализации в конкретных презентерах
+        - Поддерживает различные форматы представления данных
+        - Учитывает специфику образовательных данных
+        - Интегрируется с другими компонентами системы
+        - Обеспечивает единообразное представление результатов
+
+
+    See Also:
+        - ResultPresenter: базовый класс для презентеров результатов
+        - WebEduRunner: исполнитель функций образовательных продуктов
+        - WebEduRunnerManager: менеджер исполнителей функций
     """

edu_rdm_integration/adapters/receivers.py

@@ -4,8 +4,22 @@ from sys import (
 
 
 def m3_edu_function_tools_after_migrate_receiver(sender, **kwargs):
-    """
-    Действия выполняемые после прогона миграций.
+    """Обработчик сигнала, выполняющийся после применения миграций.
+    
+    Автоматически регистрирует сущности в системе после успешного
+    выполнения миграций базы данных. Это обеспечивает:
+    - Синхронизацию моделей с системой регистрации
+    - Корректную инициализацию новых сущностей
+    - Обновление существующих регистраций
+    
+    Args:
+        sender: Отправитель сигнала (обычно приложение Django)
+        **kwargs: Дополнительные параметры сигнала
+        
+    Note:
+        В случае возникновения ошибок при регистрации, они будут
+        перехвачены и залогированы, но не будут прерывать процесс
+        миграции.
     """
     from function_tools.management.commands.register_entities import (
         EntityRegistrar,

edu_rdm_integration/adapters/results.py

@@ -8,12 +8,58 @@ from function_tools.results import (
 
 
 class WebEduRunnerResult(BaseRunnableResult, metaclass=ABCMeta):
-    """
-    Базовый класс результатов работы ранеров функций продуктов Образования.
+    """Базовый класс результатов работы исполнителей функций продуктов Образования.
+
+    Предоставляет базовую структуру для представления результатов выполнения
+    исполнителей (runners) в контексте образовательных продуктов. Наследует
+    функциональность BaseRunnableResult и адаптирует её для специфики
+    образовательной системы.
+
+    Основные возможности:
+    - Хранение результатов выполнения исполнителей
+    - Доступ к данным результата и метаданным
+    - Поддержка цепочки обработки результатов
+    - Интеграция с системой логирования
+
+    Note:
+        - Является абстрактным классом
+        - Требует реализации в конкретных классах результатов
+        - Поддерживает стандартные операции с результатами
+        - Интегрируется с системой обработки ошибок
+        - Обеспечивает единообразную обработку результатов
+
+    See Also:
+        - BaseRunnableResult: базовый класс для результатов исполнителей
+        - WebEduRunner: исполнитель функций образовательных продуктов
+        - WebEduFunctionResult: результаты функций образовательных продуктов
     """
 
 
 class WebEduFunctionResult(BaseRunnableResult, metaclass=ABCMeta):
-    """
-    Базовый класс результатов функций продуктов Образования.
+    """Базовый класс результатов функций продуктов Образования.
+
+    Предоставляет базовую структуру для представления результатов выполнения
+    функций в контексте образовательных продуктов. Наследует функциональность
+    BaseRunnableResult и адаптирует её для специфики бизнес-функций
+    образовательной системы.
+
+    Основные возможности:
+    - Хранение результатов выполнения функций
+    - Структурированное представление данных
+    - Поддержка метаданных и контекста выполнения
+    - Валидация результатов бизнес-функций
+    - Интеграция с системой отчетности
+
+    Note:
+        - Является абстрактным классом
+        - Требует реализации в конкретных классах результатов
+        - Поддерживает различные типы данных результатов
+        - Учитывает бизнес-правила образовательной системы
+        - Интегрируется с системой аудита
+        - Обеспечивает прослеживаемость выполнения функций
+
+    See Also:
+        - BaseRunnableResult: базовый класс для результатов
+        - WebEduRunnerResult: результаты исполнителей
+        - WebEduResultPresenter: презентер результатов
     """

edu_rdm_integration/adapters/runners.py

@@ -1,3 +1,13 @@
+"""Исполнители (runners) для функций интеграции с продуктами Образования.
+
+Этот модуль содержит классы исполнителей, которые отвечают за запуск и управление
+выполнением функций обработки данных. Исполнители обеспечивают:
+- Подготовку и валидацию входных данных
+- Управление жизненным циклом функций
+- Логирование процесса выполнения
+- Обработку результатов и ошибок
+"""
+
 from abc import (
     ABCMeta,
 )
@@ -19,37 +29,64 @@ from edu_rdm_integration.adapters.results import (
 from edu_rdm_integration.adapters.validators import (
     WebEduRunnerValidator,
 )
-from edu_rdm_integration.consts import (
+from edu_rdm_integration.core.consts import (
     LOGS_DELIMITER,
 )
 
 
 class WebEduRunner(BaseRunner, metaclass=ABCMeta):
-    """
-    Базовый класс ранеров функций продуктов Образования.
+    """Базовый класс исполнителей функций продуктов Образования.
+    
+    Предоставляет основную функциональность для запуска и управления
+    выполнением функций обработки данных. Включает:
+    - Подготовку и валидацию входных параметров
+    - Логирование процесса выполнения
+    - Обработку результатов и ошибок
+    - Управление очередью выполнения
+    
+    Attributes:
+        helper (WebEduRunnerHelper): Помощник для вспомогательных операций
+        validator (WebEduRunnerValidator): Валидатор входных данных
+        result (WebEduRunnerResult): Объект для хранения результатов
     """
 
     def _prepare_helper_class(self) -> type[WebEduRunnerHelper]:
-        """
-        Возвращает класс помощника ранера функции.
+        """Возвращает класс помощника исполнителя.
+        
+        Returns:
+            type[WebEduRunnerHelper]: Класс помощника для вспомогательных операций
+            при выполнении функций
         """
         return WebEduRunnerHelper
 
     def _prepare_validator_class(self) -> type[WebEduRunnerValidator]:
-        """
-        Возвращает класс валидатора ранера функции.
+        """Возвращает класс валидатора исполнителя.
+        
+        Returns:
+            type[WebEduRunnerValidator]: Класс для валидации входных параметров
+            и проверки состояния исполнителя
         """
         return WebEduRunnerValidator
 
     def _prepare_result_class(self) -> type[WebEduRunnerResult]:
-        """
-        Возвращает класс результата ранера функции.
+        """Возвращает класс результата исполнителя.
+        
+        Returns:
+            type[WebEduRunnerResult]: Класс для хранения результатов выполнения
+            функций и возможных ошибок
         """
         return WebEduRunnerResult
 
     def _prepare_runnable_before_enqueue(self, runnable, *args, **kwargs):
-        """
-        Подготовка запускаемого объекта к работе перед помещением в очередь.
+        """Подготовка запускаемого объекта перед добавлением в очередь.
+        
+        Выполняет базовую подготовку объекта и добавляет логирование
+        для отслеживания процесса выполнения.
+        
+        Args:
+            runnable: Объект для выполнения
+            *args: Дополнительные позиционные аргументы
+            **kwargs: Дополнительные именованные аргументы
         """
         super()._prepare_runnable_before_enqueue(runnable, *args, **kwargs)
 
@@ -57,25 +94,47 @@ class WebEduRunner(BaseRunner, metaclass=ABCMeta):
 
 
 class WebEduGlobalHelperRunner(GlobalHelperRunner, metaclass=ABCMeta):
-    """
-    Базовый класс для создания ранеров выполнения запускаемых объектов с
-    глобальным помощником продуктов Образования.
+    """Базовый класс исполнителей с глобальным помощником.
+    
+    Расширяет функциональность WebEduRunner, добавляя поддержку
+    глобального помощника. Это позволяет:
+    - Использовать общие вспомогательные методы между разными исполнителями
+    - Кэшировать часто используемые данные
+    - Оптимизировать использование ресурсов
+    
+    Note:
+        Глобальный помощник должен быть потокобезопасным, так как может
+        использоваться одновременно несколькими исполнителями.
+    
+    Attributes:
+        helper (WebEduRunnerHelper): Глобальный помощник для всех исполнителей
+        validator (WebEduRunnerValidator): Валидатор входных данных
+        result (WebEduRunnerResult): Объект для хранения результатов
     """
 
     def _prepare_helper_class(self) -> type[WebEduRunnerHelper]:
-        """
-        Возвращает класс помощника ранера функции.
+        """Возвращает класс глобального помощника.
+        
+        Returns:
+            type[WebEduRunnerHelper]: Класс помощника, который будет использоваться
+            всеми исполнителями
         """
         return WebEduRunnerHelper
 
     def _prepare_validator_class(self) -> type[WebEduRunnerValidator]:
-        """
-        Возвращает класс валидатора ранера функции.
+        """Возвращает класс валидатора исполнителя.
+        
+        Returns:
+            type[WebEduRunnerValidator]: Класс для валидации входных параметров
+            и проверки состояния исполнителя
         """
         return WebEduRunnerValidator
 
     def _prepare_result_class(self) -> type[WebEduRunnerResult]:
-        """
-        Возвращает класс результата ранера функции.
+        """Возвращает класс результата исполнителя.
+        
+        Returns:
+            type[WebEduRunnerResult]: Класс для хранения результатов выполнения
+            функций и возможных ошибок
         """
         return WebEduRunnerResult