docs: added docstrings to classes and methods

Author: Pythonian

Makefile

@@ -39,7 +39,10 @@ install: ## Install development dependencies
 	cp .env.example .env
 	@echo "Development dependencies has been setup."
 
-migrate: ## Run the database migration
+migration: ## Create the database migration script
+	$(ALEMBIC) revision --autogenerate
+
+migrate: ## Apply the database migration
 	$(ALEMBIC) upgrade head
 
 check: ## Run all checks using tox and pre-commit

alembic/versions/e74c9e9b4d84_added_index_to_blog_model_fields.py

@@ -0,0 +1,36 @@
+"""added index to blog model fields
+
+Revision ID: e74c9e9b4d84
+Revises: 79befb39e85d
+Create Date: 2024-07-25 17:47:05.878080
+
+"""
+
+from typing import Sequence, Union
+
+from alembic import op
+
+
+# revision identifiers, used by Alembic.
+revision: str = "e74c9e9b4d84"
+down_revision: Union[str, None] = "79befb39e85d"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_constraint("blogs_title_key", "blogs", type_="unique")
+    op.create_index(op.f("ix_blogs_created_at"), "blogs", ["created_at"], unique=False)
+    op.create_index(op.f("ix_blogs_is_deleted"), "blogs", ["is_deleted"], unique=False)
+    op.create_index(op.f("ix_blogs_title"), "blogs", ["title"], unique=True)
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_index(op.f("ix_blogs_title"), table_name="blogs")
+    op.drop_index(op.f("ix_blogs_is_deleted"), table_name="blogs")
+    op.drop_index(op.f("ix_blogs_created_at"), table_name="blogs")
+    op.create_unique_constraint("blogs_title_key", "blogs", ["title"])
+    # ### end Alembic commands ###

api/v1/models/blog.py

@@ -16,37 +16,48 @@ class Blog(Base):
         primary_key=True,
         index=True,
         autoincrement=True,
+        doc="Unique identifier for the blog post.",
     )
     title = Column(
         String(255),
         nullable=False,
         unique=True,
+        index=True,
+        doc="Title of the blog post. Must be unique.",
     )
     excerpt = Column(
         String(300),
         nullable=False,
+        doc="Summary of the blog post.",
     )
     content = Column(
         Text,
         nullable=False,
+        doc="Full content of the blog post.",
     )
     image_url = Column(
         String(255),
         nullable=False,
+        doc="URL of the image associated with the blog post.",
     )
     is_deleted = Column(
         Boolean,
         default=False,
         nullable=False,
+        index=True,
+        doc="Flag to indicate if the blog post is deleted.",
     )
     created_at = Column(
         DateTime(timezone=True),
         server_default=func.now(),
         nullable=False,
+        index=True,
+        doc="Timestamp when the blog post was created.",
     )
     updated_at = Column(
         DateTime(timezone=True),
         server_default=func.now(),
         onupdate=func.now(),
         nullable=False,
+        doc="Timestamp when the blog post was last updated.",
     )

api/v1/routes/blog.py

@@ -28,6 +28,20 @@ async def create_blog(
     blog: BlogCreate,
     db: Session = Depends(get_db),
 ) -> BlogResponse:
+    """
+    Create a new blog post.
+
+    Args:
+        blog (BlogCreate): The blog post data to create.
+        db (Session): The database session dependency.
+
+    Returns:
+        BlogResponse: The created blog post response.
+
+    Raises:
+        HTTPException: If a blog post with the same title already
+                       exists or a database error occurs.
+    """
     try:
         return BlogService.create_blog(db, blog)
     except ValueError as e:
@@ -60,6 +74,20 @@ async def list_blog(
     page_size: int = Query(10, ge=1, le=100),
     db: Session = Depends(get_db),
 ) -> BlogListResponse:
+    """
+    Retrieve a list of blog posts with pagination.
+
+    Args:
+        page (int): The page number for pagination.
+        page_size (int): The number of items per page.
+        db (Session): The database session dependency.
+
+    Returns:
+        BlogListResponse: The list of blog posts with pagination info.
+
+    Raises:
+        HTTPException: If a database error occurs.
+    """
     try:
         return BlogService.list_blog(db, page, page_size)
     except SQLAlchemyError as e:
@@ -85,6 +113,19 @@ async def read_blog(
     id: int,
     db: Session = Depends(get_db),
 ) -> BlogResponse:
+    """
+    Retrieve a blog post by ID.
+
+    Args:
+        id (int): The ID of the blog post to retrieve.
+        db (Session): The database session dependency.
+
+    Returns:
+        BlogResponse: The blog post response.
+
+    Raises:
+        HTTPException: If the blog post is not found or a database error occurs.
+    """
     try:
         return BlogService.read_blog(db, id)
     except ValueError as e:
@@ -117,6 +158,21 @@ async def update_blog(
     blog_update: BlogUpdate,
     db: Session = Depends(get_db),
 ) -> BlogResponse:
+    """
+    Update an existing blog post by ID.
+
+    Args:
+        id (int): The ID of the blog post to update.
+        blog_update (BlogUpdate): The updated blog post data.
+        db (Session): The database session dependency.
+
+    Returns:
+        BlogResponse: The updated blog post response.
+
+    Raises:
+        HTTPException: If the blog post is not found, a conflict occurs,
+                       or a database error occurs.
+    """
     try:
         return BlogService.update_blog(db, id, blog_update)
     except RequestValidationError as e:
@@ -155,6 +211,16 @@ async def delete_blog(
     id: int,
     db: Session = Depends(get_db),
 ) -> None:
+    """
+    Delete a blog post by ID (soft delete).
+
+    Args:
+        id (int): The ID of the blog post to delete.
+        db (Session): The database session dependency.
+
+    Raises:
+        HTTPException: If the blog post is not found or a database error occurs.
+    """
     try:
         BlogService.delete_blog(db, id)
     except ValueError as e:

api/v1/schemas/blog.py

@@ -13,24 +13,27 @@ class BlogBase(BaseModel):
         ...,
         min_length=10,
         max_length=255,
-        description="Title of the blog post",
+        description="Title of the blog post. Must be between 10 and 255 characters.",
     )
     excerpt: str = Field(
         ...,
         min_length=20,
         max_length=300,
-        description="Short excerpt of the blog post",
+        description="Short excerpt of the blog post. Must be between 20 and 300 characters.",
     )
     content: str = Field(
         ...,
-        description="Content of the blog post",
+        description="Full content of the blog post.",
     )
     image_url: str = Field(
         ...,
         max_length=255,
-        description="URL of the blog post image",
+        description="URL of the blog post image.",
+    )
+    is_deleted: Optional[bool] = Field(
+        False,
+        description="Flag to indicate if the blog post is deleted. Defaults to False.",
     )
-    is_deleted: Optional[bool] = False
 
 
 class BlogCreate(BlogBase):
@@ -46,41 +49,87 @@ class BlogUpdate(BaseModel):
         None,
         min_length=10,
         max_length=255,
-        description="Title of the blog post",
+        description="Title of the blog post. Must be between 10 and 255 characters.",
     )
     excerpt: Optional[str] = Field(
         None,
         min_length=20,
         max_length=300,
-        description="Short excerpt of the blog post",
+        description="Short excerpt of the blog post. Must be between 20 and 300 characters.",
+    )
+    content: Optional[str] = Field(
+        None,
+        description="Full content of the blog post.",
+    )
+    image_url: Optional[str] = Field(
+        None,
+        max_length=255,
+        description="URL of the blog post image.",
+    )
+    is_deleted: Optional[bool] = Field(
+        False,
+        description="Flag to indicate if the blog post is deleted. Defaults to False.",
     )
-    content: Optional[str]
-    image_url: Optional[str]
-    is_deleted: Optional[bool] = False
 
 
 class BlogResponse(BlogBase):
     """Schema for returning blog post data."""
 
-    id: int
-    created_at: datetime
-    updated_at: datetime
+    id: int = Field(
+        ...,
+        description="Unique identifier for the blog post.",
+    )
+    created_at: datetime = Field(
+        ...,
+        description="Timestamp when the blog post was created.",
+    )
+    updated_at: datetime = Field(
+        ...,
+        description="Timestamp when the blog post was last updated.",
+    )
 
 
 class BlogListItemResponse(BaseModel):
     """Schema for representing a blog post item in the list response."""
 
-    id: int
-    title: str
-    excerpt: str
-    image_url: str
-    created_at: datetime
+    id: int = Field(
+        ...,
+        description="Unique identifier for the blog post.",
+    )
+    title: str = Field(
+        ...,
+        description="Title of the blog post.",
+    )
+    excerpt: str = Field(
+        ...,
+        description="Short excerpt of the blog post.",
+    )
+    image_url: str = Field(
+        ...,
+        description="URL of the blog post image.",
+    )
+    created_at: datetime = Field(
+        ...,
+        description="Timestamp when the blog post was created.",
+    )
 
 
 class BlogListResponse(BaseModel):
     """Schema for representing a blog post listing in the API response."""
 
-    count: int
-    next: Optional[str]
-    previous: Optional[str]
-    results: List[BlogListItemResponse]
+    count: int = Field(
+        ...,
+        description="Total number of blog posts.",
+    )
+    next: Optional[str] = Field(
+        None,
+        description="URL to the next page of results, if available.",
+    )
+    previous: Optional[str] = Field(
+        None,
+        description="URL to the previous page of results, if available.",
+    )
+    results: List[BlogListItemResponse] = Field(
+        ...,
+        description="List of blog post items.",
+    )