[Architecture Refactor][1] Base architecture implementation and user package refactor

app/auth/api/endpoints.py

@@ -2,7 +2,7 @@
 from fastapi import APIRouter, HTTPException, Header, status, Response, Request
 
 from app.auth.use_cases.reset_password_use_case import ResetPasswordUseCase
-from app.common.api.dependencies.get_session import SessionDependency
+from app.common.api.dependencies import SessionDependency
 from app.auth.schemas.auth_schema import PasswordResetRequest, UserLogin
 from app.auth.use_cases.auth_user_use_case import AuthUserUseCase
 from app.common.exceptions.model_not_found_exception import (

app/celery/tasks/emails.py

@@ -1,29 +1,24 @@
-from uuid import UUID
+from app.common.domain import PaginationCriteria
+from app.core.config import settings
+from app.db.session import SessionLocal
 from app.emails.exceptions.email_client_exception import EmailClientException
-from app.common.schemas.pagination_schema import ListFilter
 from app.emails.services.emails_service import EmailService
-from app.db.session import SessionLocal
 from app.main import celery
-
-
-from app.core.config import get_settings
-from app.users.schemas.user_schema import UserInDB
-from app.users.services.users_service import UsersService
-
-settings = get_settings()
+from app.users.domain import UserId
+from app.users.infrastructure import SQLAlchemyUserRepository
 
 
 @celery.task
 def send_reminder_email() -> None:
-    session = SessionLocal()
-    try:
-        users = UsersService(session).list(ListFilter(page=1, page_size=100))
-        for user in users.data:
-            EmailService().send_user_remind_email(
-                UserInDB.model_validate(user)
-            )
-    finally:
-        session.close()
+    email_service = EmailService()
+
+    with SessionLocal() as session:
+        user_repository = SQLAlchemyUserRepository(session)
+        users = user_repository.where(
+            PaginationCriteria(page=1, page_size=100)
+        )
+        for user in users:
+            email_service.send_user_remind_email(user)
 
 
 @celery.task(
@@ -32,11 +27,7 @@ def send_reminder_email() -> None:
     max_retries=settings.SEND_WELCOME_EMAIL_MAX_RETRIES,
     retry_jitter=False,
 )
-def send_welcome_email(user_id: UUID) -> None:
-    session = SessionLocal()
-    try:
-        user = UsersService(session).get_by_id(user_id)
-        if user:
-            EmailService().send_new_user_email(UserInDB.model_validate(user))
-    finally:
-        session.close()
+def send_welcome_email(user_id: UserId) -> None:
+    with SessionLocal() as session:
+        user = SQLAlchemyUserRepository(session).find_or_fail(user_id)
+        EmailService().send_new_user_email(user)

app/common/api/dependencies/__init__.py

@@ -0,0 +1 @@
+from .session_dependency import *

app/common/api/dependencies/get_session.py → app/common/api/dependencies/session_dependency.py

@@ -1,12 +1,17 @@
-from typing import Annotated, Generator
+__all__ = (
+    "get_session",
+    "SessionDependency",
+)
 
-from fastapi import Depends
+import typing as t
+
+import fastapi
 from sqlalchemy.orm import Session
 
 from app.db.session import SessionLocal
 
 
-def get_session() -> Generator:
+def get_session() -> t.Generator[Session, None, None]:
     session = SessionLocal()
     try:
         yield session
@@ -18,4 +23,7 @@ def get_session() -> Generator:
         session.close()
 
 
-SessionDependency = Annotated[Session, Depends(get_session)]
+SessionDependency = t.Annotated[
+    Session,
+    fastapi.Depends(get_session),
+]

app/common/domain/__init__.py

@@ -0,0 +1,4 @@
+from .entities import *
+from .criteria import *
+from .pagination_criteria import *
+from .repository import *

app/common/domain/criteria.py

@@ -0,0 +1,5 @@
+__all__ = ("Criteria",)
+
+
+class Criteria[TEntity]:
+    pass

app/common/domain/entities/__init__.py

@@ -0,0 +1,3 @@
+__all__ = ("Entity",)
+
+from .entity import Entity

app/common/domain/entities/_exc.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+__all__ = (
+    "EntityDefinitionError",
+    "MissingDtoError",
+    "InvalidDtoError",
+)
+
+import typing as t
+
+from app.common.exceptions import BaseApplicationError
+
+from . import _utils
+
+if t.TYPE_CHECKING:
+    from .entity import Entity
+    from .entity import _DtoConstraint
+
+
+class EntityDefinitionError(BaseApplicationError):
+    pass
+
+
+class MissingDtoError(EntityDefinitionError):
+    def __init__(
+        self,
+        entity_cls: type[Entity],
+        missing_dto_constraint: _DtoConstraint,
+    ) -> None:
+        dto_name, dto_cls = missing_dto_constraint
+        dto_bases = (dto_cls.__name__,)
+        model_name, model_bases = _utils.extract_class_info(entity_cls)
+
+        message_lines = (
+            f"Missing {dto_name} definition from {model_name} declaration.",
+            "",
+            "Example:",
+            _utils.build_nested_class_definition_example(
+                outer_class_name=model_name,
+                outer_class_bases=model_bases,
+                inner_class_name=dto_name,
+                inner_class_bases=dto_bases,
+                inner_class_statements=(
+                    "# fields required to perform operation via repository",
+                ),
+            ),
+        )
+        message = "\n".join(message_lines)
+        super().__init__(message)
+
+
+class InvalidDtoError(EntityDefinitionError):
+    def __init__(
+        self,
+        entity_cls: type[Entity],
+        invalid_dto_constraint: _DtoConstraint,
+    ) -> None:
+        dto_name, dto_cls = invalid_dto_constraint
+        dto_bases = (dto_cls.__name__,)
+        model_name, model_bases = _utils.extract_class_info(entity_cls)
+
+        message_lines = (
+            f"Invalid {dto_name} schema definition, must be child of {dto_cls.__name__}",
+            "",
+            "Example:",
+            _utils.build_nested_class_definition_example(
+                outer_class_name=model_name,
+                outer_class_bases=model_bases,
+                inner_class_name=dto_name,
+                inner_class_bases=dto_bases,
+                inner_class_statements=(
+                    "# fields required to perform operation via repository",
+                ),
+            ),
+        )
+        message = "\n".join(message_lines)
+        super().__init__(message)

app/common/domain/entities/_utils.py

@@ -0,0 +1,54 @@
+__all__ = (
+    "build_nested_class_definition_example",
+    "extract_class_info",
+)
+
+import typing as t
+
+
+def build_nested_class_definition_example(
+    *,
+    outer_class_name: str = "Outer",
+    outer_class_bases: t.Sequence[str] | None = None,
+    inner_class_name: str = "Inner",
+    inner_class_bases: t.Sequence[str] | None = None,
+    inner_class_statements: t.Sequence[str] = ("# ...",),
+) -> str:
+    output_lines = (
+        _build_class_header(outer_class_name, outer_class_bases),
+        _indent(1, _build_class_header(inner_class_name, inner_class_bases)),
+        *_indent(2, inner_class_statements),
+    )
+
+    return "\n".join(output_lines)
+
+
+def _build_class_header(name: str, bases: t.Sequence[str] | None) -> str:
+    return f"class {name}{f'({", ".join(bases)})' if bases else ''}:"
+
+
+@t.overload
+def _indent(level: int, val: str) -> str: ...
+@t.overload
+def _indent(level: int, val: t.Sequence[str]) -> t.Sequence[str]: ...
+
+
+def _indent(level: int, val: str | t.Sequence[str]) -> str | t.Sequence[str]:
+    space = "    " * level
+
+    if isinstance(val, str):
+        return f"{space}{val}"
+
+    return tuple(f"{space}{line}" for line in val)
+
+
+class _ClassInfo(t.NamedTuple):
+    class_name: str
+    class_bases: t.Sequence[str]
+
+
+def extract_class_info(cls: type) -> _ClassInfo:
+    return _ClassInfo(
+        class_name=cls.__name__,
+        class_bases=tuple(base.__name__ for base in cls.__bases__),
+    )

app/common/domain/entities/entity.py

@@ -0,0 +1,98 @@
+__all__ = ("Entity",)
+
+import typing as t
+
+import pydantic
+
+from . import _exc
+
+
+class _DtoConstraint(t.NamedTuple):
+    name: str
+    parent_cls: type
+
+
+type _DtoConstraints = t.Collection[_DtoConstraint]
+type _DtoConstraintEvaluation = _exc.EntityDefinitionError | None
+type _EntityDefinitionErrors = t.Sequence[_exc.EntityDefinitionError]
+
+
+# TODO: schema registry and automatic model rebuilding (fix circular imports for good)
+# TODO: sentinel for unloaded relationships (fix shape of data problem)
+class Entity(pydantic.BaseModel):
+    """
+    Base model of the application, representing an object in the db.
+
+    :var CreateDto: (required) Subschema for creating an object
+    :var UpdateDto: (required) Subschema for updating an object
+
+    ## Example:
+    ```
+    class User(Entity):
+        id: UserId
+        name: str
+        last_name: str
+
+        class CreateDto(pydantic.BaseModel):
+            name: str
+            last_name: str
+
+        class UpdateDto(pydantic.BaseModel):
+            name: str | None = None
+            last_name: str | None = None
+    ```
+    """
+
+    model_config = pydantic.ConfigDict(
+        from_attributes=True,
+        frozen=True,
+    )
+
+    CreateDto: t.ClassVar[type[pydantic.BaseModel]]
+    UpdateDto: t.ClassVar[type[pydantic.BaseModel]]
+
+    @classmethod
+    def __pydantic_init_subclass__(cls, **kw: t.Any) -> None:
+        super().__pydantic_init_subclass__(**kw)
+        cls._validate_entity_definition()
+
+    __required_dtos__: t.Final[_DtoConstraints] = (
+        _DtoConstraint("CreateDto", pydantic.BaseModel),
+        _DtoConstraint("UpdateDto", pydantic.BaseModel),
+    )
+
+    @classmethod
+    def _validate_entity_definition(cls) -> None:
+        errors = cls._collect_entity_definition_errors()
+
+        if errors:
+            msg = f"Can't create {cls.__name__} entity class"
+            raise ExceptionGroup(msg, errors)
+
+    @classmethod
+    def _collect_entity_definition_errors(cls) -> _EntityDefinitionErrors:
+        errors = (
+            cls._evaluate_dto_constraint(dto_constraint)
+            for dto_constraint in cls.__required_dtos__
+        )
+
+        return tuple(error for error in errors if error is not None)
+
+    @classmethod
+    def _evaluate_dto_constraint(
+        cls,
+        dto_constraint: _DtoConstraint,
+    ) -> _DtoConstraintEvaluation:
+        dto_name, dto_parent_cls = dto_constraint
+
+        if not hasattr(cls, dto_name):
+            return _exc.MissingDtoError(cls, dto_constraint)
+
+        dto = getattr(cls, dto_name)
+        is_type = isinstance(dto, type)
+        is_subclass = is_type and issubclass(dto, dto_parent_cls)
+
+        if not is_subclass:
+            return _exc.InvalidDtoError(cls, dto_constraint)
+
+        return None

app/common/domain/pagination_criteria.py

@@ -0,0 +1,23 @@
+__all__ = ("PaginationCriteria",)
+
+import typing as t
+
+import pydantic
+
+from .criteria import Criteria
+
+_PageField = t.Annotated[
+    int,
+    pydantic.Field(ge=1),
+]
+_PageSizeField = t.Annotated[
+    int,
+    pydantic.Field(ge=1, le=100),
+]
+
+
+class PaginationCriteria(pydantic.BaseModel, Criteria[t.Any]):
+    model_config = pydantic.ConfigDict(frozen=True)
+
+    page: _PageField = 1
+    page_size: _PageSizeField = 10