docs(projects): Documentation of code

Adding documentation of code
for projects routes.

Author: matheusAFONSECA

src/models/project_model.py

@@ -1,12 +1,28 @@
-from sqlalchemy import Column, Integer, String, Text, ForeignKey, TIMESTAMP, func
 from sqlalchemy.orm import relationship
 from src.modules.database_conection import Base
+from sqlalchemy import Column, Integer, String, Text, ForeignKey, TIMESTAMP, func
+
 
 class Project(Base):
+    """
+    Represents a project entity in the to-do list application.
+
+    Attributes:
+        id (int): Primary key identifier for the project.
+        user_id (int): Foreign key referencing the user who owns the project.
+        title (str): Title of the project.
+        description (str): Detailed description of the project.
+        created_at (datetime): Timestamp when the project was created.
+        updated_at (datetime): Timestamp when the project was last updated.
+        user (User): Relationship to the User model, representing the owner of the project.
+    """
+
     __tablename__ = "projects"
 
     id = Column(Integer, primary_key=True, index=True)
-    user_id = Column(Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False)
+    user_id = Column(
+        Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False
+    )
     title = Column(String(255), nullable=False)
     description = Column(Text)
     created_at = Column(TIMESTAMP, server_default=func.now())

src/models/user_model.py

@@ -27,4 +27,5 @@ class User(Base):
     created_at = Column(TIMESTAMP, server_default=func.now(), nullable=False)
     updated_at = Column(TIMESTAMP, server_default=func.now(), onupdate=func.now(), nullable=False)
 
+    # Relationship to projects
     projects = relationship("Project", back_populates="user", cascade="all, delete-orphan")

src/routes/project_routes.py

@@ -1,11 +1,12 @@
-from fastapi import APIRouter, Depends, HTTPException, status
-from sqlalchemy.orm import Session
 from typing import List
 
-from src.utils.security import get_current_user
+from sqlalchemy.orm import Session
+from fastapi import APIRouter, Depends, HTTPException, status
+
+from src.utils.utils import get_db
 from src.models.user_model import User
 from src.models.project_model import Project
-from src.utils.utils import get_db
+from src.utils.security import get_current_user
 from src.schemas.projects.projects_schema import ProjectCreate, ProjectResponse
 
 project_router = APIRouter(prefix="/projects", tags=["projects"])
@@ -19,6 +20,27 @@ def create_project(
     db: Session = Depends(get_db),
     current_user: User = Depends(get_current_user),
 ):
+    """
+    Create a new project for the authenticated user.
+
+    This endpoint allows the current authenticated user to create a new project
+    by providing the required project data. The project will be associated with
+    the user who is currently authenticated.
+
+    Args:
+        project (ProjectCreate): The project data to be created, including title and description.
+        db (Session): SQLAlchemy database session dependency.
+        current_user (User): The currently authenticated user, injected by dependency.
+
+    Returns:
+        ProjectResponse: The newly created project data.
+
+    Raises:
+        HTTPException: If the user is not authenticated or if there is a database error.
+
+    Status Codes:
+        201 CREATED: Project was successfully created.
+    """
     new_project = Project(
         user_id=current_user.id, title=project.title, description=project.description
     )
@@ -32,6 +54,25 @@ def create_project(
 def list_projects(
     db: Session = Depends(get_db), current_user: User = Depends(get_current_user)
 ):
+    """
+    List all projects for the authenticated user.
+
+    This endpoint allows the current authenticated user to retrieve a list of all
+    projects associated with their account.
+
+    Args:
+        db (Session): SQLAlchemy database session dependency.
+        current_user (User): The currently authenticated user, injected by dependency.
+
+    Returns:
+        List[ProjectResponse]: A list of projects associated with the authenticated user.
+
+    Raises:
+        HTTPException: If the user is not authenticated.
+    
+    Status Codes:
+        200 OK: Projects were successfully retrieved.
+    """
     return db.query(Project).filter(Project.user_id == current_user.id).all()
 
 
@@ -41,6 +82,27 @@ def get_project(
     db: Session = Depends(get_db),
     current_user: User = Depends(get_current_user),
 ):
+    """
+    Get a specific project for the authenticated user.
+
+    This endpoint allows the current authenticated user to retrieve a specific
+    project associated with their account by providing the project ID.
+
+    Args:
+        project_id (int): The ID of the project to retrieve.
+        db (Session): SQLAlchemy database session dependency.
+        current_user (User): The currently authenticated user, injected by dependency.
+
+    Returns:
+        ProjectResponse: The project data for the specified project ID.
+
+    Raises:
+        HTTPException: If the user is not authenticated or if the project is not found.
+
+    Status Codes:
+        200 OK: Project was successfully retrieved.
+        404 NOT FOUND: Project was not found.
+    """
     project = (
         db.query(Project)
         .filter(Project.id == project_id, Project.user_id == current_user.id)
@@ -58,6 +120,29 @@ def update_project(
     db: Session = Depends(get_db),
     current_user: User = Depends(get_current_user),
 ):
+    """
+    Update a specific project for the authenticated user.
+
+    This endpoint allows the current authenticated user to update a specific
+    project associated with their account by providing the project ID and the
+    updated project data.
+
+    Args:
+        project_id (int): The ID of the project to update.
+        updated (ProjectCreate): The updated project data, including title and description.
+        db (Session): SQLAlchemy database session dependency.
+        current_user (User): The currently authenticated user, injected by dependency.
+
+    Returns:
+        ProjectResponse: The updated project data.
+
+    Raises:
+        HTTPException: If the user is not authenticated or if the project is not found.
+
+    Status Codes:
+        200 OK: Project was successfully updated.
+        404 NOT FOUND: Project was not found.
+    """
     project = (
         db.query(Project)
         .filter(Project.id == project_id, Project.user_id == current_user.id)
@@ -78,6 +163,22 @@ def delete_project(
     db: Session = Depends(get_db),
     current_user: User = Depends(get_current_user),
 ):
+    """
+    Delete a specific project for the authenticated user.
+    This endpoint allows the current authenticated user to delete a specific
+    project associated with their account by providing the project ID.
+
+    Args:
+        project_id (int): The ID of the project to delete.
+        db (Session): SQLAlchemy database session dependency.
+        current_user (User): The currently authenticated user, injected by dependency.
+
+    Raises:
+        HTTPException: If the user is not authenticated or if the project is not found.
+
+    Status Codes:
+        204 NO CONTENT: Project was successfully deleted.
+    """
     project = (
         db.query(Project)
         .filter(Project.id == project_id, Project.user_id == current_user.id)

src/schemas/projects/projects_schema.py

@@ -1,12 +1,33 @@
-from pydantic import BaseModel
 from typing import Optional
 from datetime import datetime
+from pydantic import BaseModel
 
 class ProjectCreate(BaseModel):
+    """
+    ProjectCreate schema for creating new projects.
+    
+    Attributes:
+        title (str): Title of the project.
+        description (Optional[str]): Description of the project.
+    """
     title: str
     description: Optional[str] = None
 
 class ProjectResponse(ProjectCreate):
+    """
+    ProjectResponse schema for API responses.
+
+    Inherits from ProjectCreate and adds additional fields for the project ID,
+    creation timestamp, and last update timestamp.
+
+    Attributes:
+        id (int): Unique identifier for the project.
+        created_at (datetime): Timestamp when the project was created.
+        updated_at (datetime): Timestamp when the project was last updated.
+
+    Config:
+        from_attributes (bool): Enables population of the model from ORM objects.
+    """
     id: int
     created_at: datetime
     updated_at: datetime