fix: flake8

Author: felipementel

.github/CODEOWNERS

@@ -0,0 +1,3 @@
+pyproject.toml @felipementel
+/.github/CODEOWNERS @felipementel
+/.github/ @felipementel

src/adapters/inbound/http/dependencies.py

@@ -1,7 +1,10 @@
+"""HTTP dependency injectors for FastAPI route handlers."""
+
 from fastapi import Request
 
 from application.services.user_service import UserService
 
 
 def get_user_service(request: Request) -> UserService:
+    """Retrieve the UserService from the application state."""
     return request.app.state.user_service

src/adapters/inbound/http/routes/health.py

@@ -1,15 +1,19 @@
+"""Liveness and readiness health check routes."""
+
 from fastapi import APIRouter, HTTPException, Request, status
 
 router = APIRouter(prefix="/health", tags=["Health"])
 
 
 @router.get("/live", status_code=status.HTTP_200_OK)
 def liveness() -> dict[str, str]:
+    """Return 200 OK when the application process is running."""
     return {"status": "alive"}
 
 
 @router.get("/ready", status_code=status.HTTP_200_OK)
 def readiness(request: Request) -> dict[str, str]:
+    """Return 200 when dependencies are ready, 503 otherwise."""
     if getattr(request.app.state, "user_service", None) is None:
         raise HTTPException(
             status_code=status.HTTP_503_SERVICE_UNAVAILABLE,

src/adapters/inbound/http/routes/root.py

@@ -1,3 +1,5 @@
+"""Root, documentation, and API explorer routes."""
+
 from fastapi import APIRouter, Request
 from fastapi.openapi.docs import get_scalar_api_reference
 from fastapi.responses import HTMLResponse
@@ -14,7 +16,8 @@
   <style>
     *, *::before, *::after {{ box-sizing: border-box; margin: 0; padding: 0; }}
     body {{
-      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+      font-family:
+        -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
       background: #f5f5f5;
       display: flex;
       justify-content: center;
@@ -68,9 +71,15 @@
     <div class="section">
       <div class="section-title">Documentação</div>
       <ul>
-        <li><a href="/scalar">Scalar UI <span class="badge">interactive</span></a></li>
+        <li>
+          <a href="/scalar">Scalar UI
+          <span class="badge">interactive</span></a>
+        </li>
         <li><a href="/docs">Swagger UI</a></li>
-        <li><a href="/openapi.json">OpenAPI Spec <span class="badge">JSON</span></a></li>
+        <li>
+          <a href="/openapi.json">OpenAPI Spec
+          <span class="badge">JSON</span></a>
+        </li>
       </ul>
     </div>
 
@@ -88,12 +97,14 @@
 
 @router.get("/", response_class=HTMLResponse)
 async def root(request: Request) -> HTMLResponse:
+    """Serve the API landing page with links to docs and health probes."""
     version = getattr(request.app, "version", "0.1.0")
     return HTMLResponse(content=_ROOT_HTML_TEMPLATE.format(version=version))
 
 
 @router.get("/scalar", response_class=HTMLResponse)
 async def scalar_ui(request: Request) -> HTMLResponse:
+    """Serve the Scalar interactive API explorer."""
     return get_scalar_api_reference(
         openapi_url=str(request.app.openapi_url),
         title=request.app.title,

src/adapters/inbound/http/routes/users.py

@@ -1,3 +1,5 @@
+"""HTTP route handlers for the /usuarios resource."""
+
 from typing import Annotated
 
 from fastapi import APIRouter, Depends, HTTPException, Response, status
@@ -12,28 +14,47 @@
 UserServiceDependency = Annotated[UserService, Depends(get_user_service)]
 
 
-@router.post("", response_model=UserResponse, status_code=status.HTTP_201_CREATED)
-def create_user(payload: UserRequest, user_service: UserServiceDependency) -> UserResponse:
+@router.post(
+    "",
+    response_model=UserResponse,
+    status_code=status.HTTP_201_CREATED,
+)
+def create_user(
+    payload: UserRequest,
+    user_service: UserServiceDependency,
+) -> UserResponse:
+    """Create a new user and return the created resource."""
     try:
         user = user_service.create_user(payload.to_command())
     except UserAlreadyExistsError as error:
-        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=str(error)) from error
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail=str(error),
+        ) from error
 
     return UserResponse.from_domain(user)
 
 
 @router.get("", response_model=list[UserResponse])
 def list_users(user_service: UserServiceDependency) -> list[UserResponse]:
+    """Return all registered users."""
     users = user_service.list_users()
     return [UserResponse.from_domain(user) for user in users]
 
 
 @router.get("/{usuario_id}", response_model=UserResponse)
-def get_user(usuario_id: int, user_service: UserServiceDependency) -> UserResponse:
+def get_user(
+    usuario_id: int,
+    user_service: UserServiceDependency,
+) -> UserResponse:
+    """Return a user by ID or raise HTTP 404."""
     try:
         user = user_service.get_user(usuario_id)
     except UserNotFoundError as error:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(error)) from error
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=str(error),
+        ) from error
 
     return UserResponse.from_domain(user)
 
@@ -44,19 +65,30 @@ def update_user(
     payload: UserRequest,
     user_service: UserServiceDependency,
 ) -> UserResponse:
+    """Replace an existing user's data or raise HTTP 404."""
     try:
         user = user_service.update_user(usuario_id, payload.to_command())
     except UserNotFoundError as error:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(error)) from error
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=str(error),
+        ) from error
 
     return UserResponse.from_domain(user)
 
 
 @router.delete("/{usuario_id}", status_code=status.HTTP_204_NO_CONTENT)
-def delete_user(usuario_id: int, user_service: UserServiceDependency) -> Response:
+def delete_user(
+    usuario_id: int,
+    user_service: UserServiceDependency,
+) -> Response:
+    """Delete a user by ID or raise HTTP 404."""
     try:
         user_service.delete_user(usuario_id)
     except UserNotFoundError as error:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(error)) from error
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=str(error),
+        ) from error
 
     return Response(status_code=status.HTTP_204_NO_CONTENT)

src/adapters/inbound/http/schemas.py

@@ -1,3 +1,5 @@
+"""Pydantic request and response schemas for the Usuarios API."""
+
 from datetime import date
 
 from pydantic import BaseModel, ConfigDict, Field
@@ -7,6 +9,8 @@
 
 
 class UserRequest(BaseModel):
+    """Schema for creating or updating a user."""
+
     model_config = ConfigDict(populate_by_name=True, str_strip_whitespace=True)
 
     id: int = Field(gt=0)
@@ -16,6 +20,7 @@ class UserRequest(BaseModel):
     telefones: list[str] = Field(default_factory=list)
 
     def to_command(self) -> SaveUserCommand:
+        """Convert this request schema to a SaveUserCommand."""
         return SaveUserCommand(
             id=self.id,
             nome=self.nome,
@@ -26,6 +31,8 @@ def to_command(self) -> SaveUserCommand:
 
 
 class UserResponse(BaseModel):
+    """Schema for returning user data in API responses."""
+
     model_config = ConfigDict(populate_by_name=True)
 
     id: int
@@ -36,6 +43,7 @@ class UserResponse(BaseModel):
 
     @classmethod
     def from_domain(cls, user: User) -> "UserResponse":
+        """Build a UserResponse from a domain User entity."""
         return cls(
             id=user.id,
             nome=user.nome,

src/adapters/outbound/repositories/in_memory_user_repository.py

@@ -1,25 +1,34 @@
+"""In-memory implementation of the UserRepository port."""
+
 from domain.user import User
 
 
 class InMemoryUserRepository:
+    """Thread-unsafe in-memory store for User entities."""
+
     def __init__(self) -> None:
+        """Initialise an empty in-memory user store."""
         self._storage: dict[int, User] = {}
 
     def save(self, user: User) -> User:
+        """Persist a user and return the stored copy."""
         stored_user = self._clone(user)
         self._storage[user.id] = stored_user
         return self._clone(stored_user)
 
     def list_all(self) -> list[User]:
+        """Return copies of all stored users."""
         return [self._clone(user) for user in self._storage.values()]
 
     def get_by_id(self, user_id: int) -> User | None:
+        """Return a user by ID, or None if not found."""
         user = self._storage.get(user_id)
         if user is None:
             return None
         return self._clone(user)
 
     def delete(self, user_id: int) -> None:
+        """Remove a user by ID (no-op if not found)."""
         self._storage.pop(user_id, None)
 
     @staticmethod

src/application/commands.py

@@ -1,9 +1,13 @@
+"""Command objects for the application use-case layer."""
+
 from dataclasses import dataclass
 from datetime import date
 
 
 @dataclass(frozen=True, slots=True)
 class SaveUserCommand:
+    """Immutable command carrying the data needed to save a user."""
+
     id: int
     nome: str
     dt_nascimento: date

src/application/services/user_service.py

@@ -1,35 +1,45 @@
+"""Application service orchestrating user use-cases."""
+
 from application.commands import SaveUserCommand
 from domain.errors import UserAlreadyExistsError, UserNotFoundError
 from domain.ports.user_repository import UserRepository
 from domain.user import User
 
 
 class UserService:
+    """Coordinate domain logic and repository access for users."""
+
     def __init__(self, repository: UserRepository) -> None:
+        """Inject the UserRepository dependency."""
         self._repository = repository
 
     def create_user(self, command: SaveUserCommand) -> User:
+        """Create and persist a new user from the given command."""
         if self._repository.get_by_id(command.id) is not None:
             raise UserAlreadyExistsError(command.id)
 
         user = self._to_user(command)
         return self._repository.save(user)
 
     def list_users(self) -> list[User]:
+        """Return all persisted users."""
         return self._repository.list_all()
 
     def get_user(self, user_id: int) -> User:
+        """Return a user by ID or raise UserNotFoundError."""
         user = self._repository.get_by_id(user_id)
         if user is None:
             raise UserNotFoundError(user_id)
         return user
 
     def update_user(self, user_id: int, command: SaveUserCommand) -> User:
+        """Replace an existing user's data or raise UserNotFoundError."""
         self.get_user(user_id)
         user = self._to_user(command, user_id=user_id)
         return self._repository.save(user)
 
     def delete_user(self, user_id: int) -> None:
+        """Delete a user by ID or raise UserNotFoundError."""
         self.get_user(user_id)
         self._repository.delete(user_id)
 

src/domain/errors.py

@@ -1,8 +1,17 @@
+"""Domain exceptions for the Usuarios bounded context."""
+
+
 class UserAlreadyExistsError(Exception):
+    """Raised when attempting to create a user with a duplicate ID."""
+
     def __init__(self, user_id: int) -> None:
+        """Initialise with the duplicate user ID."""
         super().__init__(f"Usuario com id {user_id} ja existe.")
 
 
 class UserNotFoundError(Exception):
+    """Raised when a requested user does not exist."""
+
     def __init__(self, user_id: int) -> None:
+        """Initialise with the missing user ID."""
         super().__init__(f"Usuario com id {user_id} nao foi encontrado.")