Merge pull request #148 from nanotaboada/feature/docstring

chore: add missing class and function docstring

Author: nanotaboada

.pylintrc

@@ -1,9 +1,7 @@
 [MASTER]
 disable=
-    C0111, # missing-docstring
     C0114, # missing-module-docstring
-    C0115, # missing-class-docstring
-    C0116, # missing-function-docstring
     C0301, # line-too-long
+    R0902, # too-many-instance-attributes
     R0903, # too-few-public-methods
-    W0718, # broad-exception-caught
+    R0913, # too-many-arguments

data/players-sqlite3.db

@@ -8,10 +8,38 @@
 
 
 class MainModel(BaseModel):
+    """
+    Base model configuration for all Pydantic models in the application.
+
+    This class sets a common configuration for alias generation and name population
+    for any model that inherits from it. It uses camelCase for JSON field names.
+
+    Attributes:
+        model_config (ConfigDict): Configuration for Pydantic models, including:
+            alias_generator (function): A function to generate field aliases.
+                Here, it uses `to_camel` to convert field names to camelCase.
+            populate_by_name (bool): Allows population of fields by name when using Pydantic models.
+    """
     model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
 
 
 class PlayerModel(MainModel):
+    """
+    Pydantic model representing a football Player.
+
+    Attributes:
+        id (int): The unique identifier for the player.
+        first_name (str): The first name of the player.
+        middle_name (Optional[str]): The middle name of the player, if any.
+        last_name (str): The last name of the player.
+        date_of_birth (Optional[str]): The date of birth of the player, if provided.
+        squad_number (int): The unique squad number assigned to the player.
+        position (str): The playing position of the player.
+        abbr_position (Optional[str]): The abbreviated form of the player's position, if any.
+        team (Optional[str]): The team to which the player belongs, if any.
+        league (Optional[str]): The league where the team plays, if any.
+        starting11 (Optional[bool]): Indicates if the player is in the starting 11, if provided.
+    """
     id: int
     first_name: str
     middle_name: Optional[str]

models/player_model.py

@@ -19,6 +19,12 @@
 
 
 def get_orm_session():
+    """
+    Dependency function to yield a scoped SQLAlchemy ORM session.
+
+    Yields:
+        OrmSession: An instance of a scoped SQLAlchemy ORM session.
+    """
     orm_session = OrmSession()
     try:
         yield orm_session
@@ -31,12 +37,22 @@ def get_orm_session():
 @api_router.post(
     "/players/",
     status_code=status.HTTP_201_CREATED,
-    summary="Creates a new Player",
+    summary="Creates a new Player"
 )
 def post(
     player_model: PlayerModel = Body(...),
-    orm_session: Session = Depends(get_orm_session),
+    orm_session: Session = Depends(get_orm_session)
 ):
+    """
+    Endpoint to create a new player.
+
+    Args:
+        player_model (PlayerModel): The data model representing a Player.
+        orm_session (Session): The SQLAlchemy ORM session.
+
+    Raises:
+        HTTPException: HTTP 409 Conflict error if the Player already exists.
+    """
     player = player_service.retrieve_by_id(orm_session, player_model.id)
 
     if player:
@@ -59,6 +75,15 @@ def post(
 def get_all(
     orm_session: Session = Depends(get_orm_session)
 ):
+    """
+    Endpoint to retrieve all players.
+
+    Args:
+        orm_session (Session): The SQLAlchemy ORM session.
+
+    Returns:
+        List[PlayerModel]: A list of data models representing all players.
+    """
     players = player_service.retrieve_all(orm_session)
 
     return players
@@ -72,9 +97,22 @@ def get_all(
 )
 @cache(expire=CACHING_TIME_IN_SECONDS)
 def get_by_id(
-    player_id: int = Path(..., title="The Id of the Player"),
+    player_id: int = Path(..., title="The ID of the Player"),
     orm_session: Session = Depends(get_orm_session)
 ):
+    """
+    Endpoint to retrieve a Player by its ID.
+
+    Args:
+        player_id (int): The ID of the Player to retrieve.
+        orm_session (Session): The SQLAlchemy ORM session.
+
+    Returns:
+        PlayerModel: A data model representing the Player.
+
+    Raises:
+        HTTPException: Not found error if the Player with the specified ID does not exist.
+    """
     player = player_service.retrieve_by_id(orm_session, player_id)
 
     if not player:
@@ -94,6 +132,19 @@ def get_by_squad_number(
     squad_number: int = Path(..., title="The Squad Number of the Player"),
     orm_session: Session = Depends(get_orm_session)
 ):
+    """
+    Endpoint to retrieve a Player by its Squad Number.
+
+    Args:
+        squad_number (int): The Squad Number of the Player to retrieve.
+        orm_session (Session): SQLAlchemy ORM session.
+
+    Returns:
+        PlayerModel: A data model representing the Player.
+
+    Raises:
+        HTTPException: HTTP 404 Not Found error if the Player with the specified Squad Number does not exist.
+    """
     player = player_service.retrieve_by_squad_number(orm_session, squad_number)
 
     if not player:
@@ -110,11 +161,21 @@ def get_by_squad_number(
     summary="Updates an existing Player"
 )
 def put(
-    player_id: int = Path(..., title="The Id of the Player"),
+    player_id: int = Path(..., title="The ID of the Player"),
     player_model: PlayerModel = Body(...),
-    orm_session: Session = Depends(get_orm_session),
-
+    orm_session: Session = Depends(get_orm_session)
 ):
+    """
+    Endpoint to entirely update an existing Player.
+
+    Args:
+        player_id (int): The ID of the Player to update.
+        player_model (PlayerModel): The data model representing the Player to update.
+        orm_session (Session): The SQLAlchemy ORM session.
+
+    Raises:
+        HTTPException: HTTP 404 Not Found error if the player with the specified ID does not exist.
+    """
     player = player_service.retrieve_by_id(orm_session, player_id)
 
     if not player:
@@ -133,13 +194,23 @@ def put(
     summary="Deletes an existing Player"
 )
 def delete(
-    player_id: int = Path(..., title="The Id of the Player"),
+    player_id: int = Path(..., title="The ID of the Player"),
     orm_session: Session = Depends(get_orm_session)
 ):
+    """
+    Endpoint to delete an existing Player.
+
+    Args:
+        player_id (int): The ID of the Player to delete.
+        orm_session (Session): The SQLAlchemy ORM session.
+
+    Raises:
+        HTTPException: HTTP 404 Not Found error if the Player with the specified ID does not exist.
+    """
     player = player_service.retrieve_by_id(orm_session, player_id)
 
     if not player:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Player not found")
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND)
 
     player_service.delete(orm_session, player_id)
 

routes/player_route.py

@@ -7,14 +7,31 @@
 
 
 class Player(Base):
+    """
+    SQLAlchemy schema describing a database table of football players.
+
+    Attributes:
+        id (Integer): The primary key for the player record.
+        first_name (String): The first name of the player (not nullable).
+        middle_name (String): The middle name of the player.
+        last_name (String): The last name of the player (not nullable).
+        date_of_birth (String): The date of birth of the player.
+        squad_number (Integer): The squad number of the player (not nullable, unique).
+        position (String): The playing position of the player (not nullable).
+        abbr_position (String): The abbreviated form of the player's position.
+        team (String): The team to which the player belongs.
+        league (String): The league where the team plays.
+        starting11 (Boolean): Indicates if the player is in the starting 11.
+    """
+
     __tablename__ = "players"
 
-    id = Column(Integer, primary_key=True, index=True)
+    id = Column(Integer, primary_key=True)
     first_name = Column(String, name='firstName', nullable=False)
     middle_name = Column(String, name='middleName')
     last_name = Column(String, name='lastName', nullable=False)
     date_of_birth = Column(String, name="dateOfBirth")
-    squad_number = Column(Integer, name='squadNumber', index=True, nullable=False)
+    squad_number = Column(Integer, name='squadNumber', unique=True, nullable=False)
     position = Column(String, nullable=False)
     abbr_position = Column(String, name='abbrPosition')
     team = Column(String)

schemas/player_schema.py

@@ -82,7 +82,7 @@ def retrieve_by_squad_number(orm_session: Session, squad_number: int):
 
 
 def update(orm_session: Session, player_model: PlayerModel):
-    """Updates an existing Player in the database.
+    """Updates (entirely) an existing Player in the database.
 
     Args:
         orm_session: The SQLAlchemy ORM session instance.
@@ -115,7 +115,7 @@ def update(orm_session: Session, player_model: PlayerModel):
 
 
 def delete(orm_session: Session, player_id: int):
-    """Deletes a Player from the database.
+    """Deletes an existing Player from the database.
 
     Args:
         orm_session: The SQLAlchemy ORM session instance.