"""
CRUD route handlers bound via OpenAPI operationId.

This module defines OpenAPI-bound operation handlers for a model-based
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. Domain models defined using
Pydantic are used for request and response payloads.

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

from fastapi import Response, HTTPException

from models import ItemCreate
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[Item]
        A list of item domain objects.
    """
    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
    -------
    Item
        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: ItemCreate, response: Response):
    """
    Create a new item.

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

    Parameters
    ----------
    payload : ItemCreate
        Request body describing the item to create.
    response : fastapi.Response
        Response object used to set the HTTP status code.

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


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

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

    Parameters
    ----------
    item_id : int
        Identifier of the item to update.
    payload : ItemCreate
        New item data.

    Returns
    -------
    Item
        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
    return None