"""
CRUD route handlers bound via OpenAPI operationId.

These handlers explicitly control HTTP status codes to ensure
runtime behavior matches the OpenAPI contract.

This module defines OpenAPI-bound operation handlers for a simple CRUD
service. Functions in this module are bound to HTTP routes exclusively
via OpenAPI ``operationId`` values.

Handlers explicitly control HTTP response status codes to ensure runtime
behavior matches the OpenAPI contract. Error conditions are translated
into explicit HTTP responses rather than relying on implicit framework
behavior.

No routing decorators or path definitions appear in this module. All
routing, HTTP methods, and schemas are defined in the OpenAPI
specification.
"""

from fastapi import Response, HTTPException

from data import (
    list_items as _list_items,
    get_item as _get_item,
    create_item as _create_item,
    update_item as _update_item,
    delete_item as _delete_item,
)


def list_items():
    """
    List all items.

    Implements the OpenAPI operation identified by
    ``operationId: list_items``.

    Returns
    -------
    list[dict]
        A list of item representations.
    """
    return _list_items()


def get_item(item_id: int):
    """
    Retrieve a single item by ID.

    Implements the OpenAPI operation identified by
    ``operationId: get_item``.

    Parameters
    ----------
    item_id : int
        Identifier of the item to retrieve.

    Returns
    -------
    dict
        The requested item.

    Raises
    ------
    HTTPException
        404 if the item does not exist.
    """
    try:
        return _get_item(item_id)
    except KeyError:
        raise HTTPException(status_code=404, detail="Item not found")


def create_item(payload: dict, response: Response):
    """
    Create a new item.

    Implements the OpenAPI operation identified by
    ``operationId: create_item``.

    Parameters
    ----------
    payload : dict
        Item attributes excluding the ``id`` field.
    response : fastapi.Response
        Response object used to set the HTTP status code.

    Returns
    -------
    dict
        The newly created item.
    """
    item = _create_item(payload)
    response.status_code = 201
    return item


def update_item(item_id: int, payload: dict):
    """
    Update an existing item.

    Implements the OpenAPI operation identified by
    ``operationId: update_item``.

    Parameters
    ----------
    item_id : int
        Identifier of the item to update.
    payload : dict
        Item attributes excluding the ``id`` field.

    Returns
    -------
    dict
        The updated item.

    Raises
    ------
    HTTPException
        404 if the item does not exist.
    """
    try:
        return _update_item(item_id, payload)
    except KeyError:
        raise HTTPException(status_code=404, detail="Item not found")


def delete_item(item_id: int, response: Response):
    """
    Delete an existing item.

    Implements the OpenAPI operation identified by
    ``operationId: delete_item``.

    Parameters
    ----------
    item_id : int
        Identifier of the item to delete.
    response : fastapi.Response
        Response object used to set the HTTP status code.

    Returns
    -------
    None
        No content.

    Raises
    ------
    HTTPException
        404 if the item does not exist.
    """
    try:
        _delete_item(item_id)
    except KeyError:
        raise HTTPException(status_code=404, detail="Item not found")

    response.status_code = 204