Refactor base domain declarations and fix things around

.github/workflows/ci.yaml

@@ -12,7 +12,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: "3.12"
+          python-version: "3.13"
 
       - name: Install uv
         uses: astral-sh/setup-uv@v6

README.md

@@ -472,7 +472,7 @@ natural.
 
 ## Technology Stack
 
-- **Python**: `3.12`
+- **Python**: `3.13`
 - **Core**: `alembic`, `alembic-postgresql-enum`, `bcrypt`, `dishka`, `fastapi-error-map`, `fastapi`, `orjson`,
   `psycopg3[binary]`, `pydantic[email]`, `pyjwt[crypto]`, `rtoml`, `sqlalchemy[mypy]`, `uuid6`, `uvicorn`, `uvloop`
 - **Development**: `mypy`, `pre-commit`, `ruff`, `slotscheck`
@@ -596,7 +596,7 @@ export APP_ENV=local
 3. Check it and generate `.env`
 
 ```shell
-# Probably you'll need Python 3.12 installed on your system to run these commands. 
+# Probably you'll need Python 3.13 installed on your system to run these commands. 
 # The next code section provides commands for its fast installation.
 make env  # should print APP_ENV=local
 make dotenv  # should tell you where .env.local was generated
@@ -609,7 +609,7 @@ make dotenv  # should tell you where .env.local was generated
 # sudo apt install pipx
 # pipx ensurepath
 # pipx install uv
-# uv python install 3.12
+# uv python install 3.13
 uv v
 source .venv/bin/activate
 # .venv\Scripts\activate  # Windows

config/local/Dockerfile

@@ -1,4 +1,4 @@
-FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim AS builder
+FROM ghcr.io/astral-sh/uv:python3.13-bookworm-slim AS builder
 WORKDIR /app
 ENV UV_COMPILE_BYTECODE=1 \
     UV_LINK_MODE=copy
@@ -8,7 +8,7 @@ RUN --mount=type=cache,target=/root/.cache/uv \
     uv pip install --system --target /app/dependencies .
 COPY . ./
 
-FROM python:3.12-slim-bookworm AS final
+FROM python:3.13-slim-bookworm AS final
 ARG APP_UID=10001
 ARG APP_GID=10001
 RUN groupadd -g ${APP_GID} appgroup && \

pyproject.toml

@@ -17,7 +17,7 @@ license = "MIT"
 authors = [
     { name = "Ivan Borovets", email = "[email protected]" },
 ]
-requires-python = "==3.12.*"
+requires-python = "==3.13.*"
 dependencies = [
     "alembic==1.16.4",
     "alembic-postgresql-enum==1.8.0",
@@ -174,7 +174,6 @@ split-on-trailing-comma = true
     "S107", # hardcoded-password-default
 ]
 #
-"src/app/domain/value_objects/base.py" = ["B024", ]                       # abstract-base-class-without-abstract-method
 "src/app/infrastructure/adapters/password_hasher_bcrypt.py" = ["E501", ]  # line-too-long
 "src/app/infrastructure/auth/session/constants.py" = ["S105", ]           # hardcoded-password-string
 "src/app/presentation/http/auth/constants.py" = ["S105", ]                # hardcoded-password-string

src/app/application/commands/activate_user.py

@@ -19,7 +19,7 @@
 from app.domain.enums.user_role import UserRole
 from app.domain.exceptions.user import UserNotFoundByUsernameError
 from app.domain.services.user import UserService
-from app.domain.value_objects.username.username import Username
+from app.domain.value_objects.username import Username
 
 log = logging.getLogger(__name__)
 

src/app/application/commands/change_password.py

@@ -18,8 +18,8 @@
 from app.domain.entities.user import User
 from app.domain.exceptions.user import UserNotFoundByUsernameError
 from app.domain.services.user import UserService
-from app.domain.value_objects.raw_password.raw_password import RawPassword
-from app.domain.value_objects.username.username import Username
+from app.domain.value_objects.raw_password import RawPassword
+from app.domain.value_objects.username import Username
 
 log = logging.getLogger(__name__)
 

src/app/application/commands/create_user.py

@@ -19,8 +19,8 @@
 from app.domain.enums.user_role import UserRole
 from app.domain.exceptions.user import UsernameAlreadyExistsError
 from app.domain.services.user import UserService
-from app.domain.value_objects.raw_password.raw_password import RawPassword
-from app.domain.value_objects.username.username import Username
+from app.domain.value_objects.raw_password import RawPassword
+from app.domain.value_objects.username import Username
 
 log = logging.getLogger(__name__)
 

src/app/application/commands/deactivate_user.py

@@ -20,7 +20,7 @@
 from app.domain.enums.user_role import UserRole
 from app.domain.exceptions.user import UserNotFoundByUsernameError
 from app.domain.services.user import UserService
-from app.domain.value_objects.username.username import Username
+from app.domain.value_objects.username import Username
 
 log = logging.getLogger(__name__)
 

src/app/application/commands/grant_admin.py

@@ -17,7 +17,7 @@
 from app.domain.enums.user_role import UserRole
 from app.domain.exceptions.user import UserNotFoundByUsernameError
 from app.domain.services.user import UserService
-from app.domain.value_objects.username.username import Username
+from app.domain.value_objects.username import Username
 
 log = logging.getLogger(__name__)
 

src/app/application/commands/revoke_admin.py

@@ -15,7 +15,7 @@
 from app.domain.enums.user_role import UserRole
 from app.domain.exceptions.user import UserNotFoundByUsernameError
 from app.domain.services.user import UserService
-from app.domain.value_objects.username.username import Username
+from app.domain.value_objects.username import Username
 
 log = logging.getLogger(__name__)
 

src/app/application/common/ports/access_revoker.py

@@ -7,6 +7,4 @@
 class AccessRevoker(Protocol):
     @abstractmethod
     async def remove_all_user_access(self, user_id: UserId) -> None:
-        """
-        :raises DataMapperError:
-        """
+        """:raises DataMapperError:"""

src/app/application/common/ports/flusher.py

@@ -10,8 +10,8 @@ class Flusher(Protocol):
     @abstractmethod
     async def flush(self) -> None:
         """
-        Flush pending changes to validate constraints or trigger side effects.
-
         :raises DataMapperError:
         :raises UsernameAlreadyExists:
+
+        Flush pending changes to validate constraints or trigger side effects.
         """

src/app/application/common/ports/identity_provider.py

@@ -7,6 +7,4 @@
 class IdentityProvider(Protocol):
     @abstractmethod
     async def get_current_user_id(self) -> UserId:
-        """
-        :raises AuthenticationError:
-        """
+        """:raises AuthenticationError:"""

src/app/application/common/ports/transaction_manager.py

@@ -12,7 +12,7 @@ class TransactionManager(Protocol):
     @abstractmethod
     async def commit(self) -> None:
         """
-        Commit the successful outcome of a business transaction.
-
         :raises DataMapperError:
+
+        Commit the successful outcome of a business transaction.
         """

src/app/application/common/ports/user_command_gateway.py

@@ -3,28 +3,22 @@
 
 from app.domain.entities.user import User
 from app.domain.value_objects.user_id import UserId
-from app.domain.value_objects.username.username import Username
+from app.domain.value_objects.username import Username
 
 
 class UserCommandGateway(Protocol):
     @abstractmethod
     def add(self, user: User) -> None:
-        """
-        :raises DataMapperError:
-        """
+        """:raises DataMapperError:"""
 
     @abstractmethod
     async def read_by_id(self, user_id: UserId) -> User | None:
-        """
-        :raises DataMapperError:
-        """
+        """:raises DataMapperError:"""
 
     @abstractmethod
     async def read_by_username(
         self,
         username: Username,
         for_update: bool = False,
     ) -> User | None:
-        """
-        :raises DataMapperError:
-        """
+        """:raises DataMapperError:"""

src/app/application/common/ports/user_query_gateway.py

@@ -11,6 +11,4 @@ async def read_all(
         self,
         user_read_all_params: UserListParams,
     ) -> list[UserQueryModel] | None:
-        """
-        :raises ReaderError:
-        """
+        """:raises ReaderError:"""

src/app/application/common/query_params/pagination.py

@@ -13,6 +13,7 @@ class Pagination:
     offset: int
 
     def __post_init__(self):
+        """:raises PaginationError:"""
         if self.limit <= 0:
             raise PaginationError(f"Limit must be greater than 0, got {self.limit}")
         if self.offset < 0:

src/app/application/common/services/authorization/authorize.py

@@ -11,8 +11,6 @@ def authorize[PC: PermissionContext](
     *,
     context: PC,
 ) -> None:
-    """
-    :raises AuthorizationError:
-    """
+    """:raises AuthorizationError:"""
     if not permission.is_satisfied_by(context):
         raise AuthorizationError(AUTHZ_NOT_AUTHORIZED)

src/app/domain/entities/base.py

@@ -1,4 +1,3 @@
-from abc import ABC
 from dataclasses import dataclass
 from typing import Any, TypeVar
 
@@ -9,8 +8,10 @@
 
 
 @dataclass(eq=False)
-class Entity[T: ValueObject](ABC):
+class Entity[T: ValueObject]:
     """
+    raises DomainError
+
     Base class for domain entities, defined by a unique identity (`id`).
     - `id`: Identity that remains constant throughout the entity's lifecycle.
     - Entities are mutable, but are compared solely by their `id`.
@@ -20,8 +21,25 @@ class Entity[T: ValueObject](ABC):
 
     id_: T
 
+    def __post_init__(self) -> None:
+        """
+        :raises DomainError:
+
+        Hook for additional initialization and ensuring invariants.
+        Subclasses can override this method to implement custom logic, while
+        still calling `super().__post_init__()` to preserve base checks.
+        """
+        self.__forbid_base_class_instantiation()
+
+    def __forbid_base_class_instantiation(self) -> None:
+        """:raises DomainError:"""
+        if type(self) is Entity:
+            raise DomainError("Base Entity cannot be instantiated directly.")
+
     def __setattr__(self, name: str, value: Any) -> None:
         """
+        :raises DomainError:
+
         Prevents modifying the `id` after it's set.
         Other attributes can be changed as usual.
         """

src/app/domain/entities/user.py

@@ -4,7 +4,7 @@
 from app.domain.enums.user_role import UserRole
 from app.domain.value_objects.user_id import UserId
 from app.domain.value_objects.user_password_hash import UserPasswordHash
-from app.domain.value_objects.username.username import Username
+from app.domain.value_objects.username import Username
 
 
 @dataclass(eq=False, kw_only=True)

src/app/domain/exceptions/user.py

@@ -2,7 +2,7 @@
 
 from app.domain.enums.user_role import UserRole
 from app.domain.exceptions.base import DomainError
-from app.domain.value_objects.username.username import Username
+from app.domain.value_objects.username import Username
 
 
 class UsernameAlreadyExistsError(DomainError):

src/app/domain/ports/password_hasher.py

@@ -1,7 +1,7 @@
 from abc import abstractmethod
 from typing import Protocol
 
-from app.domain.value_objects.raw_password.raw_password import RawPassword
+from app.domain.value_objects.raw_password import RawPassword
 
 
 class PasswordHasher(Protocol):

src/app/domain/services/user.py

@@ -7,10 +7,10 @@
 )
 from app.domain.ports.password_hasher import PasswordHasher
 from app.domain.ports.user_id_generator import UserIdGenerator
-from app.domain.value_objects.raw_password.raw_password import RawPassword
+from app.domain.value_objects.raw_password import RawPassword
 from app.domain.value_objects.user_id import UserId
 from app.domain.value_objects.user_password_hash import UserPasswordHash
-from app.domain.value_objects.username.username import Username
+from app.domain.value_objects.username import Username
 
 
 class UserService:
@@ -57,17 +57,13 @@ def change_password(self, user: User, raw_password: RawPassword) -> None:
         user.password_hash = hashed_password
 
     def toggle_user_activation(self, user: User, *, is_active: bool) -> None:
-        """
-        :raises ActivationChangeNotPermittedError:
-        """
+        """:raises ActivationChangeNotPermittedError:"""
         if not user.role.is_changeable:
             raise ActivationChangeNotPermittedError(user.username, user.role)
         user.is_active = is_active
 
     def toggle_user_admin_role(self, user: User, *, is_admin: bool) -> None:
-        """
-        :raises RoleChangeNotPermittedError:
-        """
+        """:raises RoleChangeNotPermittedError:"""
         if not user.role.is_changeable:
             raise RoleChangeNotPermittedError(user.username, user.role)
         user.role = UserRole.ADMIN if is_admin else UserRole.USER