explicit-python 2.2.1__py3-none-any.whl

explicit/adapters/db.py

@@ -0,0 +1,63 @@
+"""Абстракции адаптера СУБД."""
+from abc import ABCMeta
+from abc import abstractmethod
+from typing import Any
+
+
+class AbstractSpecification(metaclass=ABCMeta):
+
+    """Набор условий для проверки соответствия объекта этим условиям."""
+
+    @abstractmethod
+    def as_filter(self):
+        """Представление в виде фильтра."""
+
+    @abstractmethod
+    def is_satisfied_by(self, instance) -> bool:
+        """Соответствует ли объект условиям."""
+
+
+class AbstractRepository(metaclass=ABCMeta):
+
+    """Репозиторий - абстракция над хранилищем данных (БД).
+
+    Должен содержать методы получения объектов со всеми вариантами выборки:
+       * Все записи
+       * По идентификатору
+       * По условию (фильтрация)
+       * Стандартные наборы (администраторы, министерства,
+         виды занятий для очного обучения и т.п.)
+
+    .. note::
+       Репозиторий должен возвращать объекты модели модели предметной области,
+       но не хранилища.
+
+    """
+
+    def _to_domain(self, dbinstance: Any) -> Any:
+        """Преобразование из объекта БД в объект модели."""
+        raise NotImplementedError()
+
+    def _to_db(self, modelinstance):
+        """Преобразование из объекта модели в объект БД."""
+        raise NotImplementedError()
+
+    def add(self, obj):
+        """Добавление объекта."""
+        raise NotImplementedError()
+
+    def update(self, obj):
+        """Обновление объекта."""
+        raise NotImplementedError()
+
+    def delete(self, obj):
+        """Удаление объекта."""
+        raise NotImplementedError()
+
+    def get_all_objects(self):
+        """Возвращает все объекты."""
+        raise NotImplementedError()
+
+    def get_object_by_id(self, identifier):
+        """Возвращает объект по его идентификатору."""
+        raise NotImplementedError()

explicit/adapters/fs.py

@@ -0,0 +1,40 @@
+"""Абстракции адаптера к хранилищу файлов."""
+from abc import ABC
+
+
+class AbstractAdapter(ABC):
+
+    """Абстрактный адаптер к хранилищу файлов.
+
+    .. code-block:: python
+
+       from ..adapters.fs import adapter as fs
+
+       content = request.FILES['file_photo']
+       path = fs.save(content.name, content)
+
+    """
+
+    def open(self, name, mode='rb'):
+        raise NotImplementedError()
+
+    def save(self, name, content, max_length=None):
+        raise NotImplementedError()
+
+    def delete(self, name):
+        raise NotImplementedError()
+
+    def exists(self, name):
+        raise NotImplementedError()
+
+    def size(self, name):
+        raise NotImplementedError()
+
+    def generate_filename(self, filename):
+        raise NotImplementedError()
+
+    def path(self, name):
+        raise NotImplementedError()
+
+    def url(self, name):
+        raise NotImplementedError()

explicit/adapters/messaging.py

@@ -0,0 +1,14 @@
+"""Абстракции адаптера обмена сообщениями."""
+from abc import ABC
+from abc import abstractmethod
+
+
+class AbstractAdapter(ABC):
+
+    @abstractmethod
+    def publish(self, message, *args, **kwargs):
+        raise NotImplementedError()
+
+    @abstractmethod
+    def subscribe(self, *args, **kwargs):
+        raise NotImplementedError()

explicit/contrib/domain/model/__init__.py

@@ -0,0 +1,9 @@
+"""Дополнения для моделей предметной области."""
+from .fields import identifier
+from .fields import uuid_identifier
+
+
+__all__ = [
+    'identifier',
+    'uuid_identifier',
+]

explicit/contrib/domain/model/fields.py

@@ -0,0 +1,31 @@
+"""Поля модели предметной области."""
+from uuid import uuid4
+
+from pydantic.fields import Field
+
+
+def identifier(**kwargs):
+    return Field(
+        None,
+        title='Идентификатор',
+        description=(
+            'Идентификатор записи. '
+            'Может отсутствовать у создаваемых объектов, '
+            'но обязан присутствовать у существующих.'
+        ),
+        gt=0,
+        **kwargs
+    )
+
+
+def uuid_identifier(**kwargs):
+    return Field(
+        default_factory=uuid4,
+        title='Идентификатор UUID',
+        description=(
+            'Идентификатор записи. '
+            'Может отсутствовать у создаваемых объектов, '
+            'но обязан присутствовать у существующих.'
+        ),
+        **kwargs
+    )

explicit/contrib/messagebus/event_registry.py

@@ -0,0 +1,56 @@
+"""Реестр событий по топикам."""
+from collections import defaultdict
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+from typing import Dict
+from typing import Type
+from typing import Union
+import logging
+
+
+if TYPE_CHECKING:
+    from explicit.messagebus.events import Event
+
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.INFO)
+
+
+@dataclass
+class Message:
+    topic: str
+    """Наименование топика."""
+
+    type: str
+    """Наименование типа события."""
+
+    body: dict
+    """Тело события."""
+
+
+class Registry:
+
+    """Реестр событий по топикам."""
+
+    _registry: Dict[str, list[Type['Event']]]
+
+    def __init__(self):
+        self._registry = defaultdict(list)
+
+    def register(self, topic: str, *events: Type['Event']) -> None:
+        """Регистрирует сопоставление топика с типом события."""
+        self._registry[topic].extend(events)
+
+    def resolve(self, message: Message) -> Union['Event', None]:
+        """
+        Определяет подходящий тип события и возвращает экземпляр для передачи на обработку в шину событий либо None.
+        """
+        event = None
+
+        for event_cls in self._registry[message.topic]:
+            if event_cls.__name__ == message.type:
+                event = event_cls(**message.body)
+
+        if event is None:
+            logger.warning('Событие "%s" не определено', message.type)
+
+        return event

explicit/domain/__init__.py

@@ -0,0 +1,28 @@
+"""Объекты предметной области."""
+from .factories import AbstractDomainFactory
+from .factories import DTOBase
+from .fields import Field
+from .model import HasUnsetValues
+from .model import Unset
+from .model import asdict
+from .model import is_unset
+from .model import unset
+from .model import unset_validator
+from .types import Bool
+from .types import Date
+from .types import Int
+from .types import NoneBool
+from .types import NoneDate
+from .types import NoneInt
+from .types import NoneStr
+from .types import NoneUnsetUUID
+from .types import Str
+from .types import UnsetUUID
+
+
+__all__ = [
+    'AbstractDomainFactory', 'DTOBase',
+    'Unset', 'unset', 'is_unset', 'unset_validator', 'HasUnsetValues', 'asdict',
+    'Field',
+    'UnsetUUID', 'Bool', 'Date', 'Int', 'NoneBool', 'NoneDate', 'NoneInt', 'NoneStr', 'NoneUnsetUUID', 'Str'
+]

explicit/domain/factories.py

@@ -0,0 +1,37 @@
+"""Объекты передачи данных."""
+from abc import ABCMeta
+from abc import abstractmethod
+
+from pydantic.main import BaseModel  # pylint: disable=no-name-in-module
+
+from .model import HasUnsetValues
+
+
+class DTOBase(HasUnsetValues, BaseModel):
+
+    """Базовый объект передачи данных.
+
+    .. code-block::python
+
+       dto = DeclarationDTO(last_name='Иванов', first_name='Иван')
+       declaration: Declaration = declaration_factory.create(dto)
+
+    """
+
+    class Config:
+        arbitrary_types_allowed = False
+
+
+class AbstractDomainFactory(metaclass=ABCMeta):
+
+    @abstractmethod
+    def create(self, data):
+        """Сборка объекта модели предметной области из переданных данных.
+
+        Например:
+
+        .. code-block:: python
+
+          dto = DeclarationDTO(last_name='Иванов', first_name='Иван')
+          declaration: Declaration = declaration_factory.create(dto)
+        """

explicit/domain/fields.py

@@ -0,0 +1,9 @@
+"""Набор полей объектов предметной области."""
+from functools import partial
+
+from pydantic import Field as DefaultField
+
+from .model import unset
+
+
+Field = partial(DefaultField, default=unset)

explicit/domain/model.py

@@ -0,0 +1,152 @@
+"""Вспомогательные утилиты и типы предметной области."""
+from dataclasses import asdict as asdict_
+from typing import TYPE_CHECKING
+from typing import Any
+from typing import ClassVar
+from typing import Dict
+from typing import Generic
+from typing import Protocol
+from typing import TypeVar
+from typing import Union
+
+from pydantic import validator
+from pydantic.main import BaseModel
+from pydantic.validators import _VALIDATORS
+
+
+if TYPE_CHECKING:
+    from pydantic.typing import AbstractSetIntStr
+
+
+class __IsDataclass(Protocol):  # pylint: disable=invalid-name
+    """Протокол датакласса.
+
+    Лучший из известных способов сделать соответствующую подсказку.
+    """
+    __dataclass_fields__: ClassVar[Dict]
+
+
+T = TypeVar('T')
+
+
+class __SingletonMeta(type, Generic[T]):  # pylint: disable=invalid-name
+
+    _instances: 'Dict[__SingletonMeta[T], T]' = {}  # pylint: disable=invalid-sequence-index
+
+    def __call__(cls: '__SingletonMeta', *args, **kwargs):
+        if cls not in cls._instances:
+            cls._instances[cls] = super().__call__(*args, **kwargs)
+        return cls._instances[cls]
+
+
+class Unset(metaclass=__SingletonMeta):
+    """Sentinel type.
+
+    Обозначает отсутствие значения, в т.ч. None.
+    """
+
+    def __bool__(self):
+        """Проверка на истинность.
+
+        Всегда возвращает False, т.к. обозначает отсутствующее значение.
+
+        Например:
+
+            class Model:
+                some_attr = unset
+
+            if Model().some_attr:
+                print('Model has some_attr')
+
+        """
+        return False
+
+    def __repr__(self):
+        return '<unset>'
+
+
+unset = Unset()  # Sentinel value
+
+
+def is_unset(obj) -> bool:
+    return isinstance(obj, Unset)
+
+
+def unset_validator(v):
+    return v
+
+
+_VALIDATORS.append((Unset, [unset_validator]))
+
+
+class HasUnsetValues(BaseModel):
+
+    """Примесь к моделям, значения которых могут быть не заданы."""
+
+    @validator('*', pre=True)
+    def _unset_validator(cls, v):   # pylint: disable=no-self-argument
+        return v
+
+    def dict(self, *args, **kwargs):
+        """Формирует словарь из данных объекта, отбрасывая не установленные значения.
+
+        .. code-block:: python
+
+            class DocumentDTO(DTOBase):
+                series = unset
+                number = unser
+
+            DocumentDTO(number='1').dict() == {'number': '1'}
+
+        """
+        return dict(
+            (k, v)
+            for k, v in super().dict(*args, **kwargs).items()
+            if not is_unset(v)
+        )
+
+
+def filter_unset(d: Any):
+    if not isinstance(d, dict):
+        return d
+
+    return dict(
+        (k, filter_unset(v))
+        for k, v in d.items() if not is_unset(v)
+    )
+
+
+def asdict(
+    obj: Union[__IsDataclass, 'HasUnsetValues'],
+    include: Union['AbstractSetIntStr', None] = None,
+    exclude: Union['AbstractSetIntStr', None] = None,
+) -> dict:
+
+    """Формирует словарь из данных объекта, отбрасывая не установленные значения.
+
+    .. code-block:: python
+
+        @dataclass
+        class Document:
+            series = unset
+            number = unser
+
+        asdict(Document(number='1')) == {'number': '1'}
+
+    """
+
+    if isinstance(obj, BaseModel):
+        data = obj.dict(exclude=exclude, include=include)
+
+    else:
+        unfiltered_data = asdict_(obj)
+        data = dict(
+            (k, v)
+            for k, v in unfiltered_data.items()
+            if (
+                k in (include or unfiltered_data) and
+                k not in (exclude or ())
+            )
+        )
+
+    return filter_unset(data)

explicit/domain/types.py

@@ -0,0 +1,36 @@
+"""Набор типов полей объектов предметной области.
+
+Пример использования:
+
+    class SomeData(DTOBase):
+
+        global_id: Int = Field(alias='external_id')
+        first_name: Str = Field(alias='firstname')
+        second_name: NoneStr = Field(alias='patronymic')
+        birth_date: NoneStr = Field(alias='date_of_birth')
+        gender: NoneInt = Field(alias='gender_id')
+        inn_num: NoneStr = Field(alias='inn')
+        snils_num: NoneStr = Field(alias='snils')
+
+"""
+from typing import Union
+from uuid import UUID as UUID_
+import datetime
+
+from .model import Unset
+
+
+Bool = Union[bool, Unset]
+NoneBool = Union[Bool, None]
+
+Str = Union[str, Unset]
+NoneStr = Union[Str, None]
+
+Int = Union[int, Unset]
+NoneInt = Union[Int, None]
+
+Date = Union[datetime.date, Unset]
+NoneDate = Union[Date, None]
+
+UnsetUUID = Union[UUID_, Unset]  # pylint: disable=invalid-name
+NoneUnsetUUID = Union[UnsetUUID, None]  # pylint: disable=invalid-name

explicit/domain/validation/exceptions.py

@@ -0,0 +1,148 @@
+"""Исключения предметной области."""
+from collections import defaultdict
+from functools import wraps
+from typing import List
+from typing import Mapping
+
+from pydantic import ValidationError as PydanticValidationError
+
+
+NON_FIELD_ERRORS = '__all__'
+
+
+def init_messages_dict() -> Mapping[str, List[str]]:
+    return defaultdict(list)
+
+
+class DomainValidationError(Exception):
+
+    """Ошибка валидации данных модели предметной области.
+
+    .. code-block:: python
+
+       def handler(...):
+            errors = init_messages_dict()
+            if not password:
+                errors['Пароль'].append('Обязательное поле')
+            if password != confirm:
+                errors['Пароль'].append('Пароль и подтверждение не совпадают')
+            if errors:
+                raise DomainValidationError(errors)
+
+    """
+
+    def __init__(self, message, code=None, params=None):
+        """
+        The `message` argument can be a single error, a list of errors, or a
+        dictionary that maps field names to lists of errors.
+
+        What we define as an "error" can be either a simple string or an
+        instance of DomainValidationError with its message attribute set, and
+        what we define as list or dictionary can be an actual `list` or `dict`
+        or an instance of DomainValidationError with its `error_list` or
+        `error_dict` attribute set.
+        """
+        super().__init__(message, code, params)
+
+        if isinstance(message, DomainValidationError):
+            if hasattr(message, 'error_dict'):
+                message = message.error_dict
+            elif not hasattr(message, 'message'):
+                message = message.error_list
+            else:
+                message, code, params = (
+                    message.message, message.code, message.params
+                )
+
+        if isinstance(message, dict):
+            self.error_dict = {}
+            for field, messages in message.items():
+                if not isinstance(messages, DomainValidationError):
+                    messages = DomainValidationError(messages)
+                self.error_dict[field] = messages.error_list
+
+        elif isinstance(message, list):
+            self.error_list = []
+            for sub_message in message:
+                # Normalize plain strings to instances of
+                # DomainValidationError.
+                if not isinstance(sub_message, DomainValidationError):
+                    sub_message = DomainValidationError(sub_message)
+                if hasattr(sub_message, 'error_dict'):
+                    self.error_list.extend(
+                        sum(sub_message.error_dict.values(), []))
+                else:
+                    self.error_list.extend(sub_message.error_list)
+
+        else:
+            self.message = message
+            self.code = code
+            self.params = params
+            self.error_list = [self]
+
+    @property
+    def message_dict(self):
+        # Trigger an AttributeError if this DomainValidationError
+        # doesn't have an error_dict.
+        getattr(self, 'error_dict')
+
+        return dict(self)
+
+    @property
+    def messages(self):
+        if hasattr(self, 'error_dict'):
+            return sum(dict(self).values(), [])
+        return list(self)
+
+    def update_error_dict(self, error_dict):
+        if hasattr(self, 'error_dict'):
+            for field, error_list in self.error_dict.items():
+                error_dict.setdefault(field, []).extend(error_list)
+        else:
+            error_dict.setdefault(NON_FIELD_ERRORS, []).extend(self.error_list)
+        return error_dict
+
+    def __iter__(self):
+        if hasattr(self, 'error_dict'):
+            for field, errors in self.error_dict.items():
+                yield field, list(DomainValidationError(errors))
+        else:
+            for error in self.error_list:
+                message = error.message
+                if error.params:
+                    message %= error.params
+                yield str(message)
+
+    def __str__(self):
+        if hasattr(self, 'error_dict'):
+            return repr(dict(self))
+        return repr(list(self))
+
+    def __repr__(self):
+        return f'DomainValidationError({self})'
+
+
+def handle_pydantic_validation_error(fn):
+
+    """Конвертирует PydanticValidationError в DomainValidationError.
+
+    .. code-block:: python
+
+    @handle_domain_validation_error
+    def create_object(uow: 'UnitOfWork', data: 'SessionOrderDTO',):
+        ...
+    """
+
+    @wraps(fn)
+    def wrapper(*args, **kwargs):
+        try:
+            return fn(*args, **kwargs)
+        except PydanticValidationError as error:
+            errors_dict = defaultdict(list)
+            for i in error.errors():
+                for field in i['loc']:
+                    errors_dict[field].append(i['msg'])
+            if errors_dict:
+                raise DomainValidationError(errors_dict) from error
+        return fn
+    return wrapper

explicit/messagebus/__init__.py

@@ -0,0 +1,8 @@
+"""Абстракции шины сообщений."""
+
+from .messagebus import MessageBus
+
+
+__all__ = [
+    'MessageBus',
+]