Vishesh 'ironeagle' Bangotra
a3c063b569
- Add comprehensive module and function docstrings to crud_app and model_app templates - Document OpenAPI-first guarantees, non-goals, and usage patterns in templates - Add template-level __init__.py files with CLI and client usage examples - Update mkdocs.yml to include CRUD and model-based CRUD template documentation - Ensure template documentation follows strict package-bound mkdocstrings rules
157 lines
3.4 KiB
Python
157 lines
3.4 KiB
Python
"""
|
|
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
|