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
159 lines
3.4 KiB
Python
159 lines
3.4 KiB
Python
"""
|
|
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
|