explicit-python 2.2.1__py3-none-any.whl

explicit/messagebus/commands.py

@@ -0,0 +1,100 @@
+"""Шина сообщений: обработка команд на обновление данных."""
+from abc import ABC
+from typing import Any
+from typing import Dict
+from typing import Protocol
+from typing import Tuple
+from typing import Type
+
+from pydantic.main import BaseModel
+
+from explicit.domain import HasUnsetValues
+
+
+class Command(HasUnsetValues, BaseModel):
+
+    """Объект запроса на обновление данных.
+
+    .. code-block:: python
+
+       class RegisterStudent(Command):
+           last_name: str
+           first_name: str
+
+    """
+
+    def dict_by_prefix(
+        self, prefix: str, *, removeprefix=False, exclude=None
+    ) -> dict:
+        assert prefix, f'prefix not set: "{prefix}"'
+
+        if exclude is None:
+            exclude = ()
+
+        def removeprefix_(k: str) -> str:
+            if removeprefix:
+                return k.removeprefix(prefix)
+            return k
+
+        fields = (
+            (removeprefix_(k), v)
+            for k, v in self.dict().items()
+            if k.startswith(prefix)
+        )
+
+        return dict(
+            (k, v) for k, v in fields
+            if k not in exclude
+        )
+
+
+class CommandHandler(Protocol):
+
+    """Обработчик команды.
+
+    .. code-block:: python
+
+       def register_student(command: RegisterStudent, uow: UnitOfWork) -> None::
+           assert isinstance(command, Command)
+           student = factory.create(last_name=command.last_name, first_name=command.first_name)
+           repository.add(student)
+    """
+
+    def __call__(self, command: Command, **kwargs) -> Any:
+        """Обработка запроса на обновление данных."""
+
+
+class CommandBusMixin(ABC):
+
+    """Примесь к шине сообщений, реализует обработку команд на обновление данных."""
+
+    _command_handlers_value: Dict[Type[Command], CommandHandler]
+
+    @property
+    def _command_handlers(self) -> Dict[Type[Command], CommandHandler]:
+        if not hasattr(self, '_command_handlers_value'):
+            self._command_handlers_value = {}
+        return self._command_handlers_value
+
+    def add_command_handler(self, command: Type[Command], handler: CommandHandler) -> None:
+        """Регистрация обработчика команды."""
+        assert issubclass(command, Command)
+        assert callable(handler)
+        self._command_handlers[command] = handler
+
+    def add_command_handlers(
+        self,
+        *handlers: Tuple[Type[Command], CommandHandler]
+    ) -> None:
+        """Регистрация обработчиков команд."""
+        for command, handler in handlers:
+            self.add_command_handler(command, handler)
+
+    def handle_command(self, command: Command):
+        """Передача запроса обработчику типа данного команды."""
+
+        assert isinstance(command, Command)
+        try:
+            return self._command_handlers[type(command)](command)
+        except KeyError as e:
+            raise ValueError(f'No handler for {type(command)}') from e

explicit/messagebus/dependency_injection.py

@@ -0,0 +1,48 @@
+"""Шина сообщений: внедрение зависимостей."""
+from functools import partial
+from typing import Any
+from typing import Callable
+from typing import Dict
+from typing import Optional
+import inspect
+import logging
+
+
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.INFO)
+
+
+class UnknownDependencyError(Exception):
+    """Ожидаемая обработчиком зависимость не зарегистрирована."""
+
+
+class DependencyInjectionMixin:
+
+    """Примесь к шине сообщений, реализует управление зависимостями и их внедрение."""
+
+    _dependencies: Dict[str, Callable]
+
+    def _set_dependencies(self, **dependencies: Any):
+        """Заменяет внутреннее сопоставление зависимостей."""
+        self._dependencies = dependencies
+
+    def _get_dependency(self, alias: str) -> Callable:
+        """Определяет и возвращает зависимость по имени."""
+        try:
+            return self._dependencies[alias]
+        except KeyError as e:
+            raise UnknownDependencyError(f'Зависимость для аргумента "{alias}" не найдена') from e
+
+    def _inject_dependencies(self, target: Callable, exclude: Optional[set[str]] = None) -> Callable:
+        """Внедряет зависимости в target."""
+        exclude = exclude or set()
+
+        target_signature = inspect.signature(target)
+        # определяем зависимости, которые ожидает обработчик
+        deps = {
+            name: self._get_dependency(name)
+            for name in target_signature.parameters.keys()
+            if name not in exclude
+        }
+        logger.debug('В обработчик %s внедрены зависимости %s', target, deps)
+        return partial(target, **deps)

explicit/messagebus/events.py

@@ -0,0 +1,121 @@
+"""Шина сообщений: обработка событий."""
+from abc import ABC
+from typing import TYPE_CHECKING
+from typing import Any
+from typing import Callable
+from typing import Dict
+from typing import List
+from typing import Optional
+from typing import Type
+from uuid import uuid4
+import json
+
+from more_itertools.recipes import consume
+from pydantic.fields import Field
+from pydantic.json import pydantic_encoder
+
+from explicit.domain.model import asdict
+
+
+if TYPE_CHECKING:
+    from dataclasses import dataclass  # noqa
+
+    from explicit.unit_of_work import AbstractUnitOfWork  # noqa
+else:
+    from pydantic.dataclasses import dataclass  # noqa
+
+
+@dataclass
+class EventMeta:
+    id: str = Field(default_factory=lambda: str(uuid4()))
+    transaction_id: Optional[str] = None
+    payload: Dict = Field(default_factory=dict)
+
+
+@dataclass
+class Event:
+    """Событие."""
+    meta: EventMeta = Field(default_factory=EventMeta)
+
+    def set_transaction_id(self, transaction_id: str):
+        self.meta.transaction_id = transaction_id
+
+    def get_transaction_id(self) -> Optional[str]:
+        return self.meta.transaction_id
+
+    def set_payload(self, payload: Dict):
+        assert isinstance(payload, dict)
+        self.meta.payload = payload
+
+    def get_payload(self):
+        return self.meta.payload
+
+    @classmethod
+    def from_event(cls, event: 'Event', **kwargs) -> 'Event':
+        return cls(
+            meta=EventMeta(transaction_id=event.meta.transaction_id, payload=event.meta.payload),
+            **kwargs
+        )
+
+    def configure_meta(
+        self, transaction_id: Optional[str] = None, payload: Optional[Dict] = None
+    ) -> None:
+        self.meta.transaction_id = transaction_id
+        if payload:
+            assert isinstance(payload, dict)
+            self.meta.payload = payload
+
+    def dump(self) -> str:
+        return json.dumps(
+            {
+                'type': type(self).__name__,
+                'body': asdict(self)
+            },
+            default=pydantic_encoder
+        )
+
+
+EventHandler = Callable[[Event], Any]
+"""Обработчик события.
+
+.. code-block:: python
+
+   def student_registered(event: StudentRegistered, uow: UnitOfWork) -> None:
+       assert isinstance(event, Event)
+       ...
+"""
+
+
+class EventBusMixin(ABC):
+
+    """Примесь к шине сообщений, реализует обработку событий."""
+
+    _event_handlers_value: Dict[Type[Event], List[EventHandler]]
+
+    @property
+    def _event_handlers(self) -> Dict[Type[Event], List[EventHandler]]:
+        if not hasattr(self, '_event_handlers_value'):
+            self._event_handlers_value = {}
+        return self._event_handlers_value
+
+    def add_event_handler(
+        self, event: Type[Event], handler: EventHandler
+    ) -> None:
+        """Регистрация обработчика события."""
+
+        assert issubclass(event, Event)
+        assert callable(handler)
+        self._event_handlers.setdefault(event, []).append(handler)
+
+    def handle_event(self, event: Event):
+        """Передача события списку обработчиков типа данного события."""
+
+        assert isinstance(event, Event)
+
+        try:
+            consume(
+                handler(event)
+                for handler in self._event_handlers[type(event)]
+            )
+        except KeyError as e:
+            raise ValueError(f'No handler for {type(event)}') from e

explicit/messagebus/messagebus.py

@@ -0,0 +1,90 @@
+"""Шина сообщений."""
+from typing import Type
+import threading
+
+from explicit.unit_of_work import AbstractUnitOfWork
+
+from .commands import Command
+from .commands import CommandBusMixin
+from .commands import CommandHandler
+from .dependency_injection import DependencyInjectionMixin
+from .events import Event
+from .events import EventBusMixin
+from .events import EventHandler
+from .queries import Query
+from .queries import QueryBusMixin
+
+
+class MessageBus(DependencyInjectionMixin, QueryBusMixin, CommandBusMixin, EventBusMixin):
+
+    """Шина.
+
+    Обеспечивает доставку команды соответствующему обработчику.
+
+    .. code-block:: python
+
+       from core import bus
+
+       bus.handle(Command(...))
+
+    """
+
+    def __init__(
+        self,
+        uow: AbstractUnitOfWork,
+        **dependencies,
+    ):
+        self._thread_local = threading.local()
+        self._uow = uow
+        self._set_dependencies(uow=uow, **dependencies)
+
+    def add_command_handler(self, command: Type[Command], handler: CommandHandler) -> None:
+        """Внедрение зависимостей в обработчик и регистрация его обычным образом."""
+        super().add_command_handler(
+            command=command, handler=self._inject_dependencies(target=handler, exclude={'command'})
+        )
+
+    def add_event_handler(self, event: Type[Event], handler: EventHandler) -> None:
+        """Внедрение зависимостей в обработчик и регистрация его обычным образом."""
+        super().add_event_handler(event=event, handler=self._inject_dependencies(target=handler, exclude={'event'}))
+
+    def get_uow(self) -> AbstractUnitOfWork:
+        """Возвращает используемый UnitOfWork.
+
+        Может использоваться, например, для динамической регистрации репозиториев.
+        """
+        return self._uow
+
+    @property
+    def _message_queue(self):
+        if not hasattr(self._thread_local, 'message_bus_queue'):
+            self._thread_local.message_bus_queue = []
+        return self._thread_local.message_bus_queue
+
+    def _collect_events(self):
+        self._message_queue.extend(self._uow.collect_events())
+
+    def handle(self, message):
+        result = None
+
+        self._message_queue[:] = [message]
+
+        while self._message_queue:
+            message = self._message_queue.pop(0)
+
+            if isinstance(message, Query):
+                result = self.handle_query(message)
+
+            elif isinstance(message, Command):
+                result = self.handle_command(message)
+
+            elif isinstance(message, Event):
+                # результат обработки события нас не интересует.
+                self.handle_event(message)
+
+            else:
+                raise ValueError(f'Unknown message type: {message}')
+
+            self._collect_events()
+
+        return result

explicit/messagebus/queries.py

@@ -0,0 +1,51 @@
+"""Шина сообщений: обработка запросов на чтение данных."""
+from abc import ABC
+from abc import abstractmethod
+from dataclasses import dataclass
+from typing import Any
+from typing import Dict
+from typing import Type
+
+
+@dataclass
+class Query(ABC):
+    """Объект запроса на чтение данных."""
+
+
+class QueryHandler(ABC):
+
+    @abstractmethod
+    def handle(self, query: Query) -> Any:
+        """Обработка запроса на чтение данных."""
+        assert isinstance(query, Query)
+
+
+class QueryBusMixin(ABC):
+
+    """Примесь к шине сообщений, реализует обработку запросов на чтение данных."""
+
+    _query_handlers_value: Dict[Type[Query], QueryHandler]
+
+    @property
+    def _query_handlers(self) -> Dict[Type[Query], QueryHandler]:
+        if not hasattr(self, "_query_handlers_value"):
+            self._query_handlers_value = {}
+        return self._query_handlers_value
+
+    def add_query_handler(
+        self, query: Type[Query], handler: QueryHandler
+    ) -> None:
+        """Регистрация обработчика запроса."""
+
+        assert issubclass(query, Query)
+        assert isinstance(handler, QueryHandler)
+        self._query_handlers[query] = handler
+
+    def handle_query(
+        self,
+        query: Query,
+    ):
+        """Передача запроса обработчику типа данного запроса."""
+
+        assert isinstance(query, Query)
+        return self._query_handlers[type(query)].handle(query)

explicit/unit_of_work.py

@@ -0,0 +1,184 @@
+"""Абстракции "Единицы работы"."""
+from abc import ABC
+from abc import abstractmethod
+from queue import Queue
+from typing import Dict
+from typing import Optional
+from typing import Tuple
+from typing import Type
+import threading
+
+from explicit.adapters.db import AbstractRepository
+
+
+class RepositoryRegistry:
+
+    """Реестр репозиториев."""
+
+    __repositories: Dict[str, AbstractRepository]  # pylint: disable=invalid-name
+
+    def __init__(self, uow: 'AbstractUnitOfWork'):
+        self.__repositories = {}
+        self.__uow = uow
+
+    def register(
+        self, *repositories: Tuple[str, AbstractRepository]
+    ):
+        for name, repository in repositories:
+            self.__repositories[name] = repository
+            setattr(self.__uow, name, repository)
+
+    def get(self, name: str) -> AbstractRepository:
+        return self.__repositories[name]
+
+    def __iter__(self):
+        yield from self.__repositories.values()
+
+
+# данные уровня модуля, локальные для текущего потока
+_thread_local = threading.local()
+
+
+class AbstractUnitOfWork(ABC):
+
+    """Единица работы, логическая бизнес-транзакция.
+
+    Обеспечивает атомарность выполняемых операций.
+
+    .. code-block:: python
+
+       class UnitOfWork(AbstractUnitOfWork):
+
+           units: UnitsRepository
+           users: UsersRepository
+           persons: PersonsRepository
+           students: StudentsRepository
+
+       def handler(...):
+            with UnitOfWork().wraps():
+                ...
+
+    """
+
+    _registry: RepositoryRegistry
+
+    strategy: 'AbstractTransactionStrategy'
+
+    def __init__(self, *args, **kwargs) -> None:  # pylint: disable=unused-argument
+        self._registry = RepositoryRegistry(self)
+        # данные уровня экземпляра, локальные для текущего потока
+        self._thread_local = threading.local()
+
+    def register_repositories(
+        self, *repositories: Tuple[str, AbstractRepository]
+    ):
+        """Регистрация репозиториев.
+
+        Пример:
+
+            .. code-block::python
+
+            class AppConfig(AppConfigBase):
+              def ready(self):
+                  self._register_repositories()
+
+              def _register_repositories(self):
+                  from app.core import bus
+                  from .adapters.db import repository
+
+                  bus.get_uow().register_repositories(('persons', repository))
+
+        """
+        self._registry.register(*repositories)
+
+    @property
+    def _wrapping(self) -> bool:
+        self._init_per_thread_state()
+        return self._thread_local.uow_wrapping
+
+    @_wrapping.setter
+    def _wrapping(self, value):
+        self._init_per_thread_state()
+        self._thread_local.uow_wrapping = value
+
+    @property
+    def _event_queue(self):
+        if not hasattr(_thread_local, 'event_queue'):
+            _thread_local.event_queue = Queue()
+        return _thread_local.event_queue
+
+    def _init_per_thread_state(self):
+        """Инициализирует локальные для потока атрибуты значениями по-умолчанию."""
+        if not hasattr(self._thread_local, 'uow_init'):
+            self._thread_local.uow_init = True
+            self._thread_local.uow_wrapping = False
+
+    @abstractmethod
+    def _get_new_self(self) -> 'AbstractUnitOfWork':
+        """Возвращает экземпляр UnitOfWork для вложенных транзакций."""
+
+    def commit(self):
+        """Зафиксировать транзакцию."""
+        self.strategy.commit()
+
+    def rollback(self):
+        """Откатить транзакцию."""
+        self.strategy.rollback()
+
+    def wrap(self) -> 'AbstractUnitOfWork':
+        """Обернуть логику в бизнес-транзакцию."""
+        if not self._wrapping:
+            self._wrapping = True
+            return self
+
+        return self._get_new_self()
+
+    def add_event(self, event):
+        self._event_queue.put(event)
+
+    def collect_events(self):
+        while not self._event_queue.empty():
+            yield self._event_queue.get_nowait()
+
+    def __enter__(self) -> 'AbstractUnitOfWork':
+        """Начало транзакции."""
+
+        self.strategy.__enter__()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: Optional[Type[Exception]],
+        *args: Tuple
+    ) -> None:
+        """Окончание транзакции."""
+
+        try:
+            if exc_type is not None:
+                self.rollback()
+            else:
+                self.commit()
+        except Exception as e:
+            raise e
+        finally:
+            self._wrapping = False
+            self.strategy.__exit__()
+
+
+class AbstractTransactionStrategy(ABC):
+
+    """Абстрактная транзакционная стратегия."""
+
+    def __enter__(self):
+        """Действия при входе в транзакцию."""
+
+    def __exit__(self, *_):
+        """Действия при выходе из транзакции."""
+
+    @abstractmethod
+    def commit(self):
+        """Зафиксировать транзакцию."""
+
+    @abstractmethod
+    def rollback(self):
+        """Откатить транзакцию."""