refactor: replace module comments with docstrings

Author: nanotaboada

.codacy.yml

@@ -2,7 +2,7 @@
 
 exclude_paths:
   - "assets/**/*"
-  - "database/**/*"
+  - "databases/**/*"
   - "models/**/*"
   - "postman_collections/**/*"
   - "schemas/**/*"

Dockerfile

@@ -38,7 +38,7 @@ COPY README.md          ./
 COPY assets             ./assets
 
 # Copy pre-built wheels from builder
-COPY --from=builder     /app/wheelhouse    /app/wheelhouse
+COPY --from=builder     /app/wheelhouse     /app/wheelhouse
 
 # Install dependencies
 COPY requirements.txt   .
@@ -53,9 +53,12 @@ COPY routes             ./routes
 COPY schemas            ./schemas
 COPY services           ./services
 
-# Copy entrypoint script and image-bundled, pre-seeded SQLite database
+# https://rules.sonarsource.com/docker/RSPEC-6504/
+
+# Copy entrypoint and healthcheck scripts
 COPY --chmod=755        scripts/entrypoint.sh       ./entrypoint.sh
 COPY --chmod=755        scripts/healthcheck.sh      ./healthcheck.sh
+# Copy pre-seeded SQLite database as init bundle
 COPY --chmod=755        storage                     ./docker-compose
 
 # Add non-root user and make volume mount point writable

codecov.yml

@@ -40,7 +40,7 @@ comment:
 # https://docs.codecov.com/docs/ignoring-paths
 ignore:
   - "^assets/.*"
-  - "^database/.*"
+  - "^databases/.*"
   - "^models/.*"
   - "^postman_collections/.*"
   - "^schemas/.*"

databases/__init__.py

@@ -1,7 +1,13 @@
-# ------------------------------------------------------------------------------
-# Database
-# ------------------------------------------------------------------------------
+"""
+Database setup and session management for async SQLAlchemy with SQLite.
 
+- Configures the async database engine using `aiosqlite` driver.
+- Creates an async sessionmaker for ORM operations.
+- Defines the declarative base class for model definitions.
+- Provides an async generator dependency to yield database sessions.
+
+The `STORAGE_PATH` environment variable controls the SQLite file location.
+"""
 import logging
 import os
 from typing import AsyncGenerator

database/player_database.py databases/player_database.pydatabase/player_database.py renamed to databases/player_database.py

@@ -1,7 +1,12 @@
-# ------------------------------------------------------------------------------
-# Main
-# ------------------------------------------------------------------------------
+"""
+Main application module for the FastAPI RESTful API.
 
+- Sets up the FastAPI app with metadata (title, description, version).
+- Defines the lifespan event handler for app startup/shutdown logging.
+- Includes API routers for player and health endpoints.
+
+This serves as the entry point for running the API server.
+"""
 from contextlib import asynccontextmanager
 import logging
 from typing import AsyncIterator

main.py

@@ -1,7 +1,11 @@
-# ------------------------------------------------------------------------------
-# Model
-# ------------------------------------------------------------------------------
+"""
+Pydantic models defining the data schema for football players.
 
+- `MainModel`: Base model with common config for camelCase aliasing.
+- `PlayerModel`: Represents a football player with personal and team details.
+
+These models are used for data validation and serialization in the API.
+"""
 from typing import Optional
 from pydantic import BaseModel, ConfigDict
 from pydantic.alias_generators import to_camel

models/player_model.py

@@ -1,10 +1,11 @@
-# ------------------------------------------------------------------------------
-# Route
-# ------------------------------------------------------------------------------
+"""
+Health check API route.
 
+Defines a simple endpoint to verify that the service is up and running.
+Returns a JSON response with a "status" key set to "ok".
+"""
 from fastapi import APIRouter
 
-
 api_router = APIRouter()
 
 @api_router.get("/health", tags=["Health"])

routes/health_route.py

@@ -1,13 +1,27 @@
-# ------------------------------------------------------------------------------
-# Route
-# ------------------------------------------------------------------------------
-
+"""
+API routes for managing Player resources.
+
+Provides CRUD endpoints to create, read, update, and delete Player entities.
+
+Features:
+- Caching with in-memory cache to optimize retrieval performance.
+- Async database session dependency injection.
+- Standard HTTP status codes and error handling.
+
+Endpoints:
+- POST /players/                          : Create a new Player.
+- GET /players/                           : Retrieve all Players.
+- GET /players/{player_id}                : Retrieve Player by ID.
+- GET /players/squadnumber/{squad_number} : Retrieve Player by Squad Number.
+- PUT /players/{player_id}                : Update an existing Player.
+- DELETE /players/{player_id}             : Delete an existing Player.
+"""
 from typing import List
 from fastapi import APIRouter, Body, Depends, HTTPException, status, Path, Response
 from sqlalchemy.ext.asyncio import AsyncSession
 from aiocache import SimpleMemoryCache
 
-from database.player_database import generate_async_session
+from databases.player_database import generate_async_session
 from models.player_model import PlayerModel
 from services import player_service
 

routes/player_route.py

@@ -1,9 +1,12 @@
-# ------------------------------------------------------------------------------
-# Schema
-# ------------------------------------------------------------------------------
+"""
+SQLAlchemy ORM model for the Player database table.
 
+Defines the schema and columns corresponding to football player attributes.
+
+Used for async database CRUD operations in the application.
+"""
 from sqlalchemy import Column, String, Integer, Boolean
-from database.player_database import Base
+from databases.player_database import Base
 
 
 class Player(Base):