player.py

"""
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 src.databases.player import generate_async_session
from src.models.player import PlayerModel
from src.services import player

router = APIRouter()
simple_memory_cache = SimpleMemoryCache()

CACHE_KEY = "players"
CACHE_TTL = 600  # 10 minutes

PLAYER_TITLE = "The ID of the Player"

# POST -------------------------------------------------------------------------


@router.post(
    "/players/",
    status_code=status.HTTP_201_CREATED,
    summary="Creates a new Player",
    tags=["Players"],
)
async def post_async(
    player_model: PlayerModel = Body(...),
    async_session: AsyncSession = Depends(generate_async_session),
):
    """
    Endpoint to create a new player.

    Args:
        player_model (PlayerModel): The Pydantic model representing the Player to
        create.
        async_session (AsyncSession): The async version of a SQLAlchemy ORM session.

    Raises:
        HTTPException: HTTP 409 Conflict error if the Player already exists.
    """
    player_res = await player.retrieve_by_id_async(async_session, player_model.id)
    if player_res:
        raise HTTPException(status_code=status.HTTP_409_CONFLICT)
    await player.create_async(async_session, player_model)
    await simple_memory_cache.clear(CACHE_KEY)


# GET --------------------------------------------------------------------------


@router.get(
    "/players/",
    response_model=List[PlayerModel],
    status_code=status.HTTP_200_OK,
    summary="Retrieves a collection of Players",
    tags=["Players"],
)
async def get_all_async(
    response: Response, async_session: AsyncSession = Depends(generate_async_session)
):
    """
    Endpoint to retrieve all players.

    Args:
        async_session (AsyncSession): The async version of a SQLAlchemy ORM session.

    Returns:
        List[PlayerModel]: A list of Pydantic models representing all players.
    """
    players = await simple_memory_cache.get(CACHE_KEY)
    response.headers["X-Cache"] = "HIT"
    if not players:
        players = await player.retrieve_all_async(async_session)
        await simple_memory_cache.set(CACHE_KEY, players, ttl=CACHE_TTL)
        response.headers["X-Cache"] = "MISS"
    return players


@router.get(
    "/players/{player_id}",
    response_model=PlayerModel,
    status_code=status.HTTP_200_OK,
    summary="Retrieves a Player by its Id",
    tags=["Players"],
)
async def get_by_id_async(
    player_id: int = Path(..., title=PLAYER_TITLE),
    async_session: AsyncSession = Depends(generate_async_session),
):
    """
    Endpoint to retrieve a Player by its ID.

    Args:
        player_id (int): The ID of the Player to retrieve.
        async_session (AsyncSession): The async version of a SQLAlchemy ORM session.

    Returns:
        PlayerModel: The Pydantic model representing the matching Player.

    Raises:
        HTTPException: Not found error if the Player with the specified ID does not
        exist.
    """
    player_res = await player.retrieve_by_id_async(async_session, player_id)
    if not player_res:
        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND)
    return player_res


@router.get(
    "/players/squadnumber/{squad_number}",
    response_model=PlayerModel,
    status_code=status.HTTP_200_OK,
    summary="Retrieves a Player by its Squad Number",
    tags=["Players"],
)
async def get_by_squad_number_async(
    squad_number: int = Path(..., title="The Squad Number of the Player"),
    async_session: AsyncSession = Depends(generate_async_session),
):
    """
    Endpoint to retrieve a Player by its Squad Number.

    Args:
        squad_number (int): The Squad Number of the Player to retrieve.
        async_session (AsyncSession): The async version of a SQLAlchemy ORM session.

    Returns:
        PlayerModel: The Pydantic model representing the matching Player.

    Raises:
        HTTPException: HTTP 404 Not Found error if the Player with the specified
        Squad Number does not exist.
    """
    player_res = await player.retrieve_by_squad_number_async(
        async_session, squad_number
    )
    if not player_res:
        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND)
    return player_res


# PUT --------------------------------------------------------------------------


@router.put(
    "/players/{player_id}",
    status_code=status.HTTP_204_NO_CONTENT,
    summary="Updates an existing Player",
    tags=["Players"],
)
async def put_async(
    player_id: int = Path(..., title=PLAYER_TITLE),
    player_model: PlayerModel = Body(...),
    async_session: AsyncSession = Depends(generate_async_session),
):
    """
    Endpoint to entirely update an existing Player.

    Args:
        player_id (int): The ID of the Player to update.
        player_model (PlayerModel): The Pydantic model representing the Player to
        update.
        async_session (AsyncSession): The async version of a SQLAlchemy ORM session.

    Raises:
        HTTPException: HTTP 404 Not Found error if the Player with the specified ID
        does not exist.
    """
    player_res = await player.retrieve_by_id_async(async_session, player_id)
    if not player_res:
        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND)
    await player.update_async(async_session, player_model)
    await simple_memory_cache.clear(CACHE_KEY)


# DELETE -----------------------------------------------------------------------


@router.delete(
    "/players/{player_id}",
    status_code=status.HTTP_204_NO_CONTENT,
    summary="Deletes an existing Player",
    tags=["Players"],
)
async def delete_async(
    player_id: int = Path(..., title=PLAYER_TITLE),
    async_session: AsyncSession = Depends(generate_async_session),
):
    """
    Endpoint to delete an existing Player.

    Args:
        player_id (int): The ID of the Player to delete.
        async_session (AsyncSession): The async version of a SQLAlchemy ORM session.

    Raises:
        HTTPException: HTTP 404 Not Found error if the Player with the specified ID
        does not exist.
    """
    player_res = await player.retrieve_by_id_async(async_session, player_id)
    if not player_res:
        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND)
    await player.delete_async(async_session, player_id)
    await simple_memory_cache.clear(CACHE_KEY)