auto-rest-api 0.1.0__py3-none-any.whl → 0.1.2__py3-none-any.whl

auto_rest/__main__.py

@@ -3,10 +3,9 @@
 import logging
 from pathlib import Path
 
-import uvicorn
 import yaml
-from fastapi import FastAPI
 
+from .app import *
 from .cli import *
 from .models import *
 from .routers import *
@@ -70,24 +69,26 @@ def run_application(
         app_version: version number for the generated OpenAPI schema.
     """
 
-    # Connect to and map the database.
     logger.info(f"Mapping database schema for {db_name}.")
+
+    # Resolve database connection settings
     db_url = create_db_url(driver=db_driver, host=db_host, port=db_port, database=db_name, username=db_user, password=db_pass)
     db_kwargs = yaml.safe_load(db_config.read_text()) if db_config else {}
+
+    # Connect to and map the database.
     db_conn = create_db_engine(db_url, **db_kwargs)
     db_meta = create_db_metadata(db_conn)
-    db_models = create_db_models(db_meta)
 
     # Build an empty application and dynamically add the requested functionality.
     logger.info("Creating API application.")
-    app = FastAPI(title=app_title, version=app_version, docs_url="/docs/" if enable_docs else None, redoc_url=None)
+    app = create_app(app_title, app_version, enable_docs)
     app.include_router(create_welcome_router(), prefix="")
     app.include_router(create_meta_router(db_conn, db_meta, app_title, app_version), prefix="/meta")
 
-    for model_name, model in db_models.items():
-        logger.info(f"Adding `/db/{model_name}` endpoint.")
-        app.include_router(create_model_router(db_conn, model, enable_write), prefix=f"/db/{model_name}")
+    for table_name, table in db_meta.tables.items():
+        logger.info(f"Adding `/db/{table_name}` endpoint.")
+        app.include_router(create_table_router(db_conn, table, enable_write), prefix=f"/db/{table_name}")
 
     # Launch the API server.
     logger.info(f"Launching API server on http://{server_host}:{server_port}.")
-    uvicorn.run(app, host=server_host, port=server_port, log_level="error")
+    run_server(app, server_host, server_port)

auto_rest/app.py

@@ -0,0 +1,67 @@
+"""
+The `app` module provides factory functions and utilities for building and
+deploying Fast-API applications.
+
+
+!!! example "Example: Build and Deploy an API"
+
+    ```python
+    from auto_rest.app import create_app, run_server
+
+    app = create_app(app_title="My Application", app_version="1.2.3", enable_docs=True)
+    ... # Add endpoints to the application here
+    run_server(app, host="127.0.0.1", port=8081)
+    ```
+"""
+
+import uvicorn
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+__all__ = ["create_app", "run_server"]
+
+
+def create_app(app_title: str, app_version: str, enable_docs: bool) -> FastAPI:
+    """Create and configure a FastAPI application instance.
+
+    This function initializes a FastAPI app with a customizable title, version,
+    and optional documentation routes. It also configures application middleware
+    for CORS policies.
+
+    Args:
+        app_title: The title of the FastAPI application.
+        app_version: The version of the FastAPI application.
+        enable_docs: Whether to enable the `/docs/` endpoint.
+
+    Returns:
+        FastAPI: A configured FastAPI application instance.
+    """
+
+    app = FastAPI(
+        title=app_title,
+        version=app_version,
+        docs_url="/docs/" if enable_docs else None,
+        redoc_url=None,
+    )
+
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["*"],
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    return app
+
+
+def run_server(app: FastAPI, host: str, port: int) -> None: # pragma: no cover
+    """Deploy a FastAPI application server.
+
+    Args:
+        app: The FastAPI application to run.
+        host: The hostname or IP address for the server to bind to.
+        port: The port number for the server to listen on.
+    """
+
+    uvicorn.run(app, host=host, port=port, log_level="error")

auto_rest/handlers.py

@@ -55,10 +55,10 @@ from typing import Awaitable, Callable
 
 from fastapi import Depends, Response
 from pydantic import create_model
-from pydantic.main import ModelT
-from sqlalchemy import insert, MetaData, select
-from starlette.requests import Request
+from pydantic.main import BaseModel as PydanticModel
+from sqlalchemy import insert, MetaData, select, Table
 
+from .interfaces import *
 from .models import *
 from .params import *
 from .queries import *
@@ -79,7 +79,7 @@ __all__ = [
 logger = logging.getLogger(__name__)
 
 
-def create_welcome_handler() -> Callable[[], Awaitable[ModelT]]:
+def create_welcome_handler() -> Callable[[], Awaitable[PydanticModel]]:
     """Create an endpoint handler that returns an application welcome message.
 
     Returns:
@@ -96,7 +96,7 @@ def create_welcome_handler() -> Callable[[], Awaitable[ModelT]]:
     return welcome_handler
 
 
-def create_about_handler(name: str, version: str) -> Callable[[], Awaitable[ModelT]]:
+def create_about_handler(name: str, version: str) -> Callable[[], Awaitable[PydanticModel]]:
     """Create an endpoint handler that returns the application name and version number.
 
     Args:
@@ -104,7 +104,7 @@ def create_about_handler(name: str, version: str) -> Callable[[], Awaitable[Mode
         version: The returned version identifier.
 
     Returns:
-        An async function that returns aplication info.
+        An async function that returns application info.
     """
 
     interface = create_model("Version", version=(str, version), name=(str, name))
@@ -117,7 +117,7 @@ def create_about_handler(name: str, version: str) -> Callable[[], Awaitable[Mode
     return about_handler
 
 
-def create_engine_handler(engine: DBEngine) -> Callable[[], Awaitable[ModelT]]:
+def create_engine_handler(engine: DBEngine) -> Callable[[], Awaitable[PydanticModel]]:
     """Create an endpoint handler that returns configuration details for a database engine.
 
     Args:
@@ -141,7 +141,7 @@ def create_engine_handler(engine: DBEngine) -> Callable[[], Awaitable[ModelT]]:
     return meta_handler
 
 
-def create_schema_handler(metadata: MetaData) -> Callable[[], Awaitable[ModelT]]:
+def create_schema_handler(metadata: MetaData) -> Callable[[], Awaitable[PydanticModel]]:
     """Create an endpoint handler that returns the database schema.
 
     Args:
@@ -180,120 +180,121 @@ def create_schema_handler(metadata: MetaData) -> Callable[[], Awaitable[ModelT]]
     return schema_handler
 
 
-def create_list_records_handler(engine: DBEngine, model: DBModel) -> Callable[..., Awaitable[list[ModelT]]]:
+def create_list_records_handler(engine: DBEngine, table: Table) -> Callable[..., Awaitable[list[PydanticModel]]]:
     """Create an endpoint handler that returns a list of records from a database table.
 
     Args:
         engine: Database engine to use when executing queries.
-        model: The ORM object to use for database manipulations.
+        table: The database table to query against.
 
     Returns:
         An async function that returns a list of records from the given database model.
     """
 
-    interface = create_db_interface(model)
+    interface = create_interface(table)
 
     async def list_records_handler(
         response: Response,
         session: DBSession = Depends(create_session_iterator(engine)),
-        pagination_params: dict[str, int] = Depends(get_pagination_params),
-        ordering_params: dict[str, int] = Depends(get_ordering_params),
+        pagination_params: dict[str, int] = create_pagination_dependency(table),
+        ordering_params: dict[str, int] = create_ordering_dependency(table),
     ) -> list[interface]:
         """Fetch a list of records from the database.
 
         URL query parameters are used to enable filtering, ordering, and paginating returned values.
         """
 
-        query = select(model)
+        query = select(table)
         query = apply_pagination_params(query, pagination_params, response)
         query = apply_ordering_params(query, ordering_params, response)
+
         result = await execute_session_query(session, query)
-        return [interface.model_validate(record.__dict__) for record in result.scalars().all()]
+        return [row._mapping for row in result.all()]
 
     return list_records_handler
 
 
-def create_get_record_handler(engine: DBEngine, model: DBModel) -> Callable[..., Awaitable[ModelT]]:
+def create_get_record_handler(engine: DBEngine, table: Table) -> Callable[..., Awaitable[PydanticModel]]:
     """Create a function for handling GET requests against a single record in the database.
 
     Args:
         engine: Database engine to use when executing queries.
-        model: The ORM object to use for database manipulations.
+        table: The database table to query against.
 
     Returns:
-        An async function that returns a single record from the given database model.
+        An async function that returns a single record from the given database table.
     """
 
-    interface = create_db_interface(model)
+    interface = create_interface(table)
+    pk_interface = create_interface(table, pk_only=True, mode='required')
 
     async def get_record_handler(
-        request: Request,
+        pk: pk_interface = Depends(),
         session: DBSession = Depends(create_session_iterator(engine)),
     ) -> interface:
         """Fetch a single record from the database."""
 
-        query = select(model).filter_by(**request.path_params)
+        query = select(table).filter_by(**pk.model_dump())
         result = await execute_session_query(session, query)
         record = get_record_or_404(result)
-        return interface.model_validate(record.__dict__)
+        return record
 
     return get_record_handler
 
 
-def create_post_record_handler(engine: DBEngine, model: DBModel) -> Callable[..., Awaitable[ModelT]]:
+def create_post_record_handler(engine: DBEngine, table: Table) -> Callable[..., Awaitable[PydanticModel]]:
     """Create a function for handling POST requests against a record in the database.
 
     Args:
         engine: Database engine to use when executing queries.
-        model: The ORM object to use for database manipulations.
+        table: The database table to query against.
 
     Returns:
         An async function that handles record creation.
     """
 
-    interface = create_db_interface(model)
+    interface = create_interface(table)
 
     async def post_record_handler(
         data: interface,
         session: DBSession = Depends(create_session_iterator(engine)),
-    ) -> interface:
+    ) -> None:
         """Create a new record in the database."""
 
-        query = insert(model).values(**data.dict())
-        result = await execute_session_query(session, query)
-        record = get_record_or_404(result)
-
+        query = insert(table).values(**data.dict())
+        await execute_session_query(session, query)
         await commit_session(session)
-        return interface.model_validate(record.__dict__)
 
     return post_record_handler
 
 
-def create_put_record_handler(engine: DBEngine, model: DBModel) -> Callable[..., Awaitable[ModelT]]:
+def create_put_record_handler(engine: DBEngine, table: Table) -> Callable[..., Awaitable[PydanticModel]]:
     """Create a function for handling PUT requests against a record in the database.
 
     Args:
         engine: Database engine to use when executing queries.
-        model: The ORM object to use for database manipulations.
+        table: The database table to query against.
 
     Returns:
         An async function that handles record updates.
     """
 
-    interface = create_db_interface(model)
+    interface = create_interface(table)
+    opt_interface = create_interface(table, mode='optional')
+    pk_interface = create_interface(table, pk_only=True, mode='required')
 
     async def put_record_handler(
-        request: Request,
-        data: interface,
+        data: opt_interface,
+        pk: pk_interface = Depends(),
         session: DBSession = Depends(create_session_iterator(engine)),
     ) -> interface:
         """Replace record values in the database with the provided data."""
 
-        query = select(model).filter_by(**request.path_params)
+        query = select(table).filter_by(**pk.model_dump())
         result = await execute_session_query(session, query)
         record = get_record_or_404(result)
 
-        for key, value in data.dict().items():
+        for key, value in data.model_dump().items():
             setattr(record, key, value)
 
         await commit_session(session)
@@ -302,57 +303,60 @@ def create_put_record_handler(engine: DBEngine, model: DBModel) -> Callable[...,
     return put_record_handler
 
 
-def create_patch_record_handler(engine: DBEngine, model: DBModel) -> Callable[..., Awaitable[ModelT]]:
+def create_patch_record_handler(engine: DBEngine, table: Table) -> Callable[..., Awaitable[PydanticModel]]:
     """Create a function for handling PATCH requests against a record in the database.
 
     Args:
         engine: Database engine to use when executing queries.
-        model: The ORM object to use for database manipulations.
+        table: The database table to query against.
 
     Returns:
         An async function that handles record updates.
     """
 
-    interface = create_db_interface(model)
+    interface = create_interface(table)
+    pk_interface = create_interface(table, pk_only=True, mode='required')
 
     async def patch_record_handler(
-        request: Request,
         data: interface,
+        pk: pk_interface = Depends(),
         session: DBSession = Depends(create_session_iterator(engine)),
     ) -> interface:
         """Update record values in the database with the provided data."""
 
-        query = select(model).filter_by(**request.path_params)
+        query = select(table).filter_by(**pk.model_dump())
         result = await execute_session_query(session, query)
         record = get_record_or_404(result)
 
-        for key, value in data.dict(exclude_unset=True).items():
+        for key, value in data.model_dump(exclude_unset=True).items():
             setattr(record, key, value)
 
         await commit_session(session)
-        return interface(record.__dict__)
+        return record
 
     return patch_record_handler
 
 
-def create_delete_record_handler(engine: DBEngine, model: DBModel) -> Callable[..., Awaitable[None]]:
+def create_delete_record_handler(engine: DBEngine, table: Table) -> Callable[..., Awaitable[None]]:
     """Create a function for handling DELETE requests against a record in the database.
 
     Args:
         engine: Database engine to use when executing queries.
-        model: The ORM object to use for database manipulations.
+        table: The database table to query against.
 
     Returns:
         An async function that handles record deletion.
     """
 
+    pk_interface = create_interface(table, pk_only=True, mode='required')
+
     async def delete_record_handler(
-        request: Request,
+        pk: pk_interface = Depends(),
         session: DBSession = Depends(create_session_iterator(engine)),
     ) -> None:
         """Delete a record from the database."""
 
-        query = select(model).filter_by(**request.path_params)
+        query = select(table).filter_by(**pk.model_dump())
         result = await execute_session_query(session, query)
         record = get_record_or_404(result)
 

auto_rest/interfaces.py

@@ -0,0 +1,126 @@
+"""Pydantic models are used to facilitate data validation and to define
+interfaces for FastAPI endpoint handlers. The `interfaces` module
+provides utility functions for converting SQLAlchemy models into
+Pydantic interfaces. Interfaces can be created using different modes
+which force interface fields to be optional or read only.
+
+!!! example "Example: Creating an Interface"
+
+    The `create_interface_default` method creates an interface class
+    based on a SQLAlchemy table.
+
+    ```python
+    default_interface = create_interface_default(database_model)
+    required_interface = create_interface_required(database_model, mode="required")
+    optional_interface = create_interface_optional(database_model, mode="optional")
+    ```
+"""
+from typing import Iterator, Literal
+
+from pydantic import BaseModel as PydanticModel, create_model
+from sqlalchemy import Column, Table
+
+__all__ = ["create_interface"]
+
+from sqlalchemy.sql.schema import ScalarElementColumnDefault
+
+MODES = Literal["default", "required", "optional"]
+
+
+def iter_columns(table: Table, pk_only: bool = False) -> Iterator[Column]:
+    """Iterate over the columns of a SQLAlchemy model.
+
+    Args:
+        table: The table to iterate columns over.
+        pk_only: If True, only iterate over primary key columns.
+
+    Yields:
+        A column of the SQLAlchemy model.
+    """
+
+    for column in table.columns:
+        if column.primary_key or not pk_only:
+            yield column
+
+
+def get_column_type(col: Column) -> type[any]:
+    """Return the Python type corresponding to a column's DB datatype.
+
+    Returns the `any` type for DBMS drivers that do not support mapping DB
+    types to Python primitives,
+
+    Args:
+        col: The column to determine a type for.
+
+    Returns:
+        The equivalent Python type for the column data.
+    """
+
+    try:
+        return col.type.python_type
+
+    # Catch any error, but list the expected ones explicitly
+    except (NotImplementedError, Exception):
+        return any
+
+
+def get_column_default(col: Column, mode: MODES) -> any:
+    """Return the default value for a column.
+
+    Args:
+        col: The column to determine a default value for.
+        mode: The mode to use when determining the default value.
+
+    Returns:
+        The default value for the column.
+    """
+
+    # Extract the default value from the SQLAlchemy wrapper class
+    sqla_default = col.default
+    default = getattr(sqla_default, "arg", None) or sqla_default
+
+    if mode == "required":
+        return ...
+
+    elif mode == "optional":
+        return default
+
+    elif mode == "default":
+        if col.nullable or (col.default is not None):
+            return default
+
+        return ...
+
+    raise RuntimeError(f"Unknown mode: {mode}")
+
+
+def create_interface(
+    table: Table,
+    pk_only: bool = False,
+    mode: MODES = "default"
+) -> type[PydanticModel]:
+    """Create a Pydantic interface for a SQLAlchemy model where all fields are required.
+
+    Args:
+        table: The SQLAlchemy table to create an interface for.
+        pk_only: If True, only include primary key columns.
+        mode: Whether to force fields to all be optional or required.
+
+    Returns:
+        A dynamically generated Pydantic model with all fields required.
+    """
+
+    # Map field names to the column type and default value.
+    columns = iter_columns(table, pk_only)
+    fields = {
+        col.name: (get_column_type(col), get_column_default(col, mode))
+        for col in columns
+    }
+
+    # Dynamically create a unique name for the interface
+    name_parts = [table.name, mode.title()]
+    if pk_only:
+        name_parts.insert(1, 'PK')
+
+    interface_name = '-'.join(name_parts)
+    return create_model(interface_name, **fields)

auto_rest/models.py

@@ -5,18 +5,16 @@ on the popular SQLAlchemy package, it natively supports multiple
 Database Management Systems (DBMS) without requiring custom configuration
 or setup.
 
-!!! example "Example: Creating ORM objects"
+!!! example "Example: Mapping Database Metadata"
 
-    Utility functions are provided for connecting to the database,
-    mapping the schema, and dynamically generating ORM models based on
-    the existing database structure.
+    Utility functions are provided for connecting to the database
+    and mapping the underlying schema.
 
     ```python
     connection_args = dict(...)
     db_url = create_db_url(**connection_args)
     db_conn = create_db_engine(db_url)
     db_meta = create_db_metadata(db_conn)
-    db_models = create_db_models(db_meta)
     ```
 
 Support for asynchronous operations is automatically determined based on
@@ -36,19 +34,15 @@ import logging
 from pathlib import Path
 from typing import Callable
 
-from pydantic.main import create_model, ModelT
 from sqlalchemy import create_engine, Engine, MetaData, URL
 from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession, create_async_engine
-from sqlalchemy.orm import declarative_base, Session
+from sqlalchemy.orm import Session
 
 __all__ = [
     "DBEngine",
-    "DBModel",
     "DBSession",
     "create_db_engine",
-    "create_db_interface",
     "create_db_metadata",
-    "create_db_models",
     "create_db_url",
     "create_session_iterator",
 ]
@@ -56,7 +50,6 @@ __all__ = [
 logger = logging.getLogger(__name__)
 
 # Base classes and typing objects.
-DBModel = declarative_base()
 DBEngine = Engine | AsyncEngine
 DBSession = Session | AsyncSession
 
@@ -131,7 +124,7 @@ async def _async_reflect_metadata(engine: AsyncEngine, metadata: MetaData) -> No
     """Helper function used to reflect database metadata using an async engine."""
 
     async with engine.connect() as connection:
-        await connection.run_sync(metadata.reflect)
+        await connection.run_sync(metadata.reflect, views=True)
 
 
 def create_db_metadata(engine: DBEngine) -> MetaData:
@@ -151,55 +144,11 @@ def create_db_metadata(engine: DBEngine) -> MetaData:
         asyncio.run(_async_reflect_metadata(engine, metadata))
 
     else:
-        metadata.reflect(bind=engine)
+        metadata.reflect(bind=engine, views=True)
 
     return metadata
 
 
-def create_db_models(metadata: MetaData) -> dict[str, DBModel]:
-    """Dynamically generate database models from a metadata instance.
-
-    Args:
-        metadata: A reflection of database metadata.
-
-    Returns:
-        A dictionary mapping table names to database models.
-    """
-
-    logger.debug("Building database models...")
-    models = {}
-
-    # Dynamically create a class for each table.
-    for table_name, table in metadata.tables.items():
-        logger.debug(f"> Creating model for table {table_name}.")
-        models[table_name] = type(
-            table_name.capitalize(),
-            (DBModel,),
-            {"__table__": table},
-        )
-
-    logger.debug(f"Successfully generated {len(models)} models.")
-    return models
-
-
-def create_db_interface(model: DBModel) -> type[ModelT]:
-    """Create a Pydantic interface for a SQLAlchemy model.
-
-    Args:
-        model: A SQLAlchemy model to create an interface for.
-
-    Returns:
-        A Pydantic model class with the same structure as the provided SQLAlchemy model.
-    """
-
-    fields = {
-        col.name: (col.type.python_type, col.default if col.default is not None else ...)
-        for col in model.__table__.columns
-    }
-
-    return create_model(model.__name__, **fields)
-
-
 def create_session_iterator(engine: DBEngine) -> Callable[[], DBSession]:
     """Create a generator for database sessions.
 

auto_rest/params.py

@@ -4,71 +4,85 @@ parameters from incoming HTTP requests. These utilities ensure the consistent
 parsing, validation, and application of query parameters, and automatically
 update HTTP response headers to reflect applied query options.
 
-Parameter functions are designed in pairs. A *get* function is used to parse
-parameters from a FastAPI request and an *apply* function is used to apply
-the arguments onto a SQLAlchemy query.
+Parameter functions are designed in pairs of two. The first function is a
+factory for creating an injectable FastAPI dependency. The dependency
+is used to parse parameters from incoming requests and applies high level
+validation against the parsed values. The second function to applies the
+validated arguments onto a SQLAlchemy query and returns the updated query.
 
 !!! example "Example: Parameter Parsing and Application"
 
-    When handling URL parameters, a *get* function is injected as a dependency
-    into the signature of the request handler. The parsed parameter dictionary
-    is then passed to an *apply* function.
-
     ```python
-    from fastapi import FastAPI, Response, Depends
+    from fastapi import FastAPI, Response
     from sqlalchemy import select
-    from auto_rest.query_params import get_pagination_params, apply_pagination_params
+    from auto_rest.query_params import create_pagination_dependency, apply_pagination_params
 
     app = FastAPI()
 
     @app.get("/items/")
     async def list_items(
-        pagination_params: dict = Depends(get_pagination_params),
+        pagination_params: dict = create_pagination_dependency(model),
         response: Response
     ):
-        query = select(SomeModel)
+        query = select(model)
         query = apply_pagination_params(query, pagination_params, response)
         return ...  # Logic to further process and execute the query goes here
     ```
 """
 
-from typing import Literal
+from collections.abc import Callable
+from typing import Literal, Optional
 
-from fastapi import Query
-from sqlalchemy import asc, desc
+from fastapi import Depends, Query
+from sqlalchemy import asc, desc, Table
 from sqlalchemy.sql.selectable import Select
 from starlette.responses import Response
 
 __all__ = [
     "apply_ordering_params",
     "apply_pagination_params",
-    "get_ordering_params",
-    "get_pagination_params",
+    "create_ordering_dependency",
+    "create_pagination_dependency",
 ]
 
 
-def get_pagination_params(
-    _limit_: int = Query(10, ge=0, description="The maximum number of records to return."),
-    _offset_: int = Query(0, ge=0, description="The starting index of the returned records."),
-) -> dict[str, int]:
-    """Extract pagination parameters from request query parameters.
+def create_ordering_dependency(table: Table) -> Callable[..., dict]:
+    """Create an injectable dependency for fetching ordering arguments from query parameters.
 
     Args:
-        _limit_: The maximum number of records to return.
-        _offset_: The starting index of the returned records.
+        table: The database table to create the dependency for.
 
     Returns:
-        dict: A dictionary containing the `limit` and `offset` values.
+        An injectable FastAPI dependency.
     """
 
-    return {"limit": _limit_, "offset": _offset_}
+    columns = tuple(table.columns.keys())
 
+    def get_ordering_params(
+        _order_by_: Optional[Literal[*columns]] = Query(None, description="The field name to sort by."),
+        _direction_: Optional[Literal["asc", "desc"]] = Query(None, description="Sort results in 'asc' or 'desc' order.")
+    ) -> dict:
+        """Extract ordering parameters from request query parameters.
 
-def apply_pagination_params(query: Select, params: dict[str, int], response: Response) -> Select:
-    """Apply pagination to a database query.
+        Args:
+            _order_by_: The field to order by.
+            _direction_: The direction to order by.
+
+        Returns:
+            dict: A dictionary containing the `order_by` and `direction` values.
+        """
+
+        return {"order_by": _order_by_, "direction": _direction_}
+
+    return Depends(get_ordering_params)
 
-    Returns a copy of the provided query with offset and limit parameters applied.
-    Compatible with parameters returned by the `get_pagination_params` method.
+
+def apply_ordering_params(query: Select, params: dict, response: Response) -> Select:
+    """Apply ordering to a database query.
+
+    Returns a copy of the provided query with ordering parameters applied.
+    This method is compatible with parameters returned by the `get_ordering_params` method.
+    Ordering is not applied for invalid params, but response headers are still set.
 
     Args:
         query: The database query to apply parameters to.
@@ -76,47 +90,64 @@ def apply_pagination_params(query: Select, params: dict[str, int], response: Res
         response: The outgoing HTTP response object.
 
     Returns:
-        A copy of the query modified to only return the paginated values.
+        A copy of the query modified to return ordered values.
     """
 
-    limit = params.get("limit", 0)
-    offset = params.get("offset", 0)
+    order_by = params.get("order_by")
+    direction = params.get("direction")
 
-    if limit < 0 or offset < 0:
-        raise ValueError("Pagination parameters must be greater than or equal to zero.")
+    # Set common response headers
+    response.headers["X-Order-By"] = str(order_by)
+    response.headers["X-Order-Direction"] = str(direction)
 
-    if limit == 0:
-        response.headers["X-Pagination-Applied"] = "false"
+    if order_by is None:
+        response.headers["X-Order-Applied"] = "false"
         return query
 
-    response.headers["X-Pagination-Applied"] = "true"
-    response.headers["X-Pagination-Limit"] = str(limit)
-    response.headers["X-Pagination-Offset"] = str(offset)
-    return query.offset(offset).limit(limit)
+    # Default to ascending order for an invalid ordering direction
+    response.headers["X-Order-Applied"] = "true"
+    if direction == "desc":
+        return query.order_by(desc(order_by))
+
+    else:
+        return query.order_by(asc(order_by))
 
 
-def get_ordering_params(
-    _order_by_: str | None = Query(None, description="The field name to sort by."),
-    _direction_: Literal["asc", "desc"] = Query("asc", description="Sort results in 'asc' or 'desc' order.")
-) -> dict:
-    """Extract ordering parameters from request query parameters.
+def create_pagination_dependency(table: Table) -> Callable[..., dict]:
+    """Create an injectable dependency for fetching pagination arguments from query parameters.
 
     Args:
-        _order_by_: The field to order by.
-        _direction_: The direction to order by.
+        table: The database table to create the dependency for.
 
     Returns:
-        dict: A dictionary containing the `order_by` and `direction` values.
+        An injectable FastAPI dependency.
     """
 
-    return {"order_by": _order_by_, "direction": _direction_}
+    def get_pagination_params(
+        _limit_: Optional[int] = Query(None, ge=0, description="The maximum number of records to return."),
+        _offset_: Optional[int] = Query(None, ge=0, description="The starting index of the returned records."),
+    ) -> dict[str, int]:
+        """Extract pagination parameters from request query parameters.
 
+        Args:
+            _limit_: The maximum number of records to return.
+            _offset_: The starting index of the returned records.
 
-def apply_ordering_params(query: Select, params: dict, response: Response) -> Select:
-    """Apply ordering to a database query.
+        Returns:
+            dict: A dictionary containing the `limit` and `offset` values.
+        """
 
-    Returns a copy of the provided query with ordering parameters applied.
-    Compatible with parameters returned by the `get_ordering_params` method.
+        return {"limit": _limit_, "offset": _offset_}
+
+    return Depends(get_pagination_params)
+
+
+def apply_pagination_params(query: Select, params: dict[str, int], response: Response) -> Select:
+    """Apply pagination to a database query.
+
+    Returns a copy of the provided query with offset and limit parameters applied.
+    This method is compatible with parameters returned by the `get_pagination_params` method.
+    Pagination is not applied for invalid params, but response headers are still set.
 
     Args:
         query: The database query to apply parameters to.
@@ -124,24 +155,20 @@ def apply_ordering_params(query: Select, params: dict, response: Response) -> Se
         response: The outgoing HTTP response object.
 
     Returns:
-        A copy of the query modified to return ordered values.
+        A copy of the query modified to only return the paginated values.
     """
 
-    order_by = params.get("order_by")
-    direction = params.get("direction", "asc")
+    limit = params.get("limit")
+    offset = params.get("offset")
 
-    if not order_by:
-        response.headers["X-Order-Applied"] = "false"
-        return query
-
-    response.headers["X-Order-Applied"] = "true"
-    response.headers["X-Order-By"] = order_by
-    response.headers["X-Order-Direction"] = direction
-
-    if direction == "asc":
-        return query.order_by(asc(order_by))
+    # Set common response headers
+    response.headers["X-Pagination-Limit"] = str(limit)
+    response.headers["X-Pagination-Offset"] = str(offset)
 
-    if direction == "desc":
-        return query.order_by(desc(order_by))
+    # Do not apply pagination if not requested
+    if limit in (0, None):
+        response.headers["X-Pagination-Applied"] = "false"
+        return query
 
-    raise ValueError("Ordering direction must be 'asc' or 'desc'.")
+    response.headers["X-Pagination-Applied"] = "true"
+    return query.offset(offset or 0).limit(limit)

auto_rest/queries.py

@@ -10,7 +10,7 @@ handling and provides a streamlined interface for database interactions.
     Query utilities seamlessly support synchronous and asynchronous session types.
 
     ```python
-    query = select(SomeModel).where(SomeModel.id == item_id)
+    query = select(SomeTable).where(SomeTable.id == item_id)
 
     with Session(...) as sync_session:
         result = await execute_session_query(sync_session, query)
@@ -101,7 +101,7 @@ def get_record_or_404(result: Result) -> any:
         HTTPException: If the record is not found.
     """
 
-    if not (record := result.scalar_one_or_none()):
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Record not found")
+    if record := result.fetchone():
+        return record
 
-    return record
+    raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Record not found")

auto_rest/routers.py

@@ -24,15 +24,15 @@ routers to be added directly to an API application instance.
 """
 
 from fastapi import APIRouter
-from sqlalchemy import MetaData
+from sqlalchemy import MetaData, Table
 from starlette import status
 
 from auto_rest.handlers import *
-from auto_rest.models import DBEngine, DBModel
+from auto_rest.models import DBEngine
 
 __all__ = [
     "create_meta_router",
-    "create_model_router",
+    "create_table_router",
     "create_welcome_router",
 ]
 
@@ -45,7 +45,13 @@ def create_welcome_router() -> APIRouter:
     """
 
     router = APIRouter()
-    router.add_api_route("/", create_welcome_handler(), methods=["GET"], include_in_schema=False)
+    router.add_api_route(
+        path="/",
+        methods=["GET"],
+        endpoint=create_welcome_handler(),
+        include_in_schema=False
+    )
+
     return router
 
 
@@ -58,7 +64,7 @@ def create_meta_router(engine: DBEngine, metadata: MetaData, name: str, version:
     Args:
         engine: The database engine used to facilitate database interactions.
         metadata: The metadata object containing the database schema.
-        version: The application name.
+        name: The application name.
         version: The application versionnumber.
 
     Returns:
@@ -68,101 +74,110 @@ def create_meta_router(engine: DBEngine, metadata: MetaData, name: str, version:
     router = APIRouter()
     tags = ["Application Metadata"]
 
-    router.add_api_route("/app", create_about_handler(name, version), methods=["GET"], tags=tags)
-    router.add_api_route("/engine", create_engine_handler(engine), methods=["GET"], tags=tags)
-    router.add_api_route("/schema", create_schema_handler(metadata), methods=["GET"], tags=tags)
+    router.add_api_route(
+        path="/app",
+        methods=["GET"],
+        endpoint=create_about_handler(name, version),
+        summary="Fetch application metadata.",
+        tags=tags
+    )
+
+    router.add_api_route(
+        path="/engine",
+        methods=["GET"],
+        endpoint=create_engine_handler(engine),
+        summary="Fetch database metadata.",
+        tags=tags
+    )
+
+    router.add_api_route(
+        path="/schema",
+        methods=["GET"],
+        endpoint=create_schema_handler(metadata),
+        summary="Fetch the database schema.",
+        tags=tags
+    )
+
     return router
 
 
-def create_model_router(engine: DBEngine, model: DBModel, writeable: bool = False) -> APIRouter:
-    """Create an API router with endpoint handlers for the given database model.
+def create_table_router(engine: DBEngine, table: Table, writeable: bool = False) -> APIRouter:
+    """Create an API router with endpoint handlers for a given database table.
 
     Args:
         engine: The SQLAlchemy engine connected to the database.
-        model: The ORM model class representing a database table.
+        table: The database table to create API endpoints for.
         writeable: Whether the router should include support for write operations.
 
     Returns:
-        An APIRouter instance with routes for database operations on the model.
+        An APIRouter instance with routes for database operations on the table.
     """
 
     router = APIRouter()
 
     # Construct path parameters from primary key columns
-    pk_columns = model.__table__.primary_key.columns
-    path_params_url = "/".join(f"{{{col.name}}}" for col in pk_columns)
-    path_params_openapi = {
-        "parameters": [
-            {
-                "name": col.name,
-                "in": "path",
-                "required": True
-            } for col in pk_columns
-        ]
-    }
-
-    # Raise an error if no primary key columns are found
-    # (SQLAlchemy should ensure this never happens)
-    if not pk_columns:  # pragma: no cover
-        raise RuntimeError(f"No primary key columns found for table {model.__tablename__}.")
-
-    # Define routes for read operations
-    router.add_api_route(
-        path="/",
-        methods=["GET"],
-        endpoint=create_list_records_handler(engine, model),
-        status_code=status.HTTP_200_OK,
-        tags=[model.__name__],
-        openapi_extra=path_params_openapi
-    )
-
-    router.add_api_route(
-        path=f"/{path_params_url}/",
-        methods=["GET"],
-        endpoint=create_get_record_handler(engine, model),
-        status_code=status.HTTP_200_OK,
-        tags=[model.__name__],
-        openapi_extra=path_params_openapi
-    )
-
-    if not writeable:
-        return router
+    pk_columns = sorted(column.name for column in table.primary_key.columns)
+    path_params_url = "/".join(f"{{{col_name}}}" for col_name in pk_columns)
 
-    # Define routes for write operations
+    # Add route for read operations against the table
     router.add_api_route(
         path="/",
-        methods=["POST"],
-        endpoint=create_post_record_handler(engine, model),
-        status_code=status.HTTP_201_CREATED,
-        tags=[model.__name__],
-        openapi_extra=path_params_openapi
-    )
-
-    router.add_api_route(
-        path=f"/{path_params_url}/",
-        methods=["PUT"],
-        endpoint=create_put_record_handler(engine, model),
-        status_code=status.HTTP_200_OK,
-        tags=[model.__name__],
-        openapi_extra=path_params_openapi
-    )
-
-    router.add_api_route(
-        path=f"/{path_params_url}/",
-        methods=["PATCH"],
-        endpoint=create_patch_record_handler(engine, model),
+        methods=["GET"],
+        endpoint=create_list_records_handler(engine, table),
         status_code=status.HTTP_200_OK,
-        tags=[model.__name__],
-        openapi_extra=path_params_openapi
+        summary="Fetch multiple records from the table.",
+        tags=[table.name],
     )
 
-    router.add_api_route(
-        path=f"/{path_params_url}/",
-        methods=["DELETE"],
-        endpoint=create_delete_record_handler(engine, model),
-        status_code=status.HTTP_200_OK,
-        tags=[model.__name__],
-        openapi_extra=path_params_openapi
-    )
+    # Add route for write operations against the table
+    if writeable:
+        router.add_api_route(
+            path="/",
+            methods=["POST"],
+            endpoint=create_post_record_handler(engine, table),
+            status_code=status.HTTP_201_CREATED,
+            summary="Create a new record.",
+            tags=[table.name],
+        )
+
+    # Add route for read operations against individual records
+    if pk_columns:
+        router.add_api_route(
+            path=f"/{path_params_url}/",
+            methods=["GET"],
+            endpoint=create_get_record_handler(engine, table),
+            status_code=status.HTTP_200_OK,
+            summary="Fetch a single record from the table.",
+            tags=[table.name],
+        )
+
+    # Add routes for write operations against individual records
+    if pk_columns and writeable:
+        router.add_api_route(
+            path=f"/{path_params_url}/",
+            methods=["PUT"],
+            endpoint=create_put_record_handler(engine, table),
+            status_code=status.HTTP_200_OK,
+            summary="Replace a single record in the table.",
+            tags=[table.name],
+        )
+
+        router.add_api_route(
+            path=f"/{path_params_url}/",
+            methods=["PATCH"],
+            endpoint=create_patch_record_handler(engine, table),
+            status_code=status.HTTP_200_OK,
+            summary="Update a single record in the table.",
+            tags=[table.name],
+        )
+
+        router.add_api_route(
+            path=f"/{path_params_url}/",
+            methods=["DELETE"],
+            endpoint=create_delete_record_handler(engine, table),
+            status_code=status.HTTP_200_OK,
+            summary="Delete a single record from the table.",
+            tags=[table.name],
+        )
 
     return router

{auto_rest_api-0.1.0.dist-info → auto_rest_api-0.1.2.dist-info}/METADATA

@@ -1,11 +1,11 @@
 Metadata-Version: 2.3
 Name: auto-rest-api
-Version: 0.1.0
+Version: 0.1.2
 Summary: Automatically map database schemas and deploy per-table REST API endpoints.
 License: GPL-3.0-only
 Keywords: Better,HPC,automatic,rest,api
 Author: Better HPC LLC
-Requires-Python: >=3.10
+Requires-Python: >=3.11
 Classifier: Environment :: Web Environment
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Information Technology

auto_rest_api-0.1.2.dist-info/RECORD

@@ -0,0 +1,15 @@
+auto_rest/__init__.py,sha256=9ICmv2urSoAo856FJylKdorF19UsUGc4eyORYLptf1Q,69
+auto_rest/__main__.py,sha256=lz6-LEpbu51Ah3QCzUzZhevjWhK5kmOxhuuqhX5t-io,3093
+auto_rest/app.py,sha256=I6ZeHzKuhPTS1svLhMTvefjzTkMJgGpwVz1kdJ_9mtE,1887
+auto_rest/cli.py,sha256=A7-kMTNNzqZB7jTUJBAVqfYm9RyYjENr0g_vK9JE0N4,5199
+auto_rest/handlers.py,sha256=84P7mEXzwpEgSOg6ZIBMT_q0ZTfiESpd-IXUmekMqJo,12005
+auto_rest/interfaces.py,sha256=U2-e3fy_ROmNrIAvkXG7dACMJi3akFEldXrbIacMbIc,3714
+auto_rest/models.py,sha256=HCJUQPBmkkfVFv9CRcPzMP66pQk_UIb3j3cdwHqodwE,5388
+auto_rest/params.py,sha256=t1YK9Q-dwh7N99myYH2RZCO6XheWcgLJl_Stpi65PKQ,6075
+auto_rest/queries.py,sha256=nws0J1XnCzB3Y0DN1dDccsgK91z7dzza1VyC_qCitG0,2910
+auto_rest/routers.py,sha256=RqBwLqVFU1OIFSCUuwOtTis8mT_zyWTaB_8SyIXjfe0,5727
+auto_rest_api-0.1.2.dist-info/LICENSE.md,sha256=zFRw_u1mGSOH8GrpOu0L1P765aX9fB5UpKz06mTxAos,34893
+auto_rest_api-0.1.2.dist-info/METADATA,sha256=xQY6_P1nDZbq6PfcDp5EGjEhRxCwJql_g8V0NcRpxVM,2951
+auto_rest_api-0.1.2.dist-info/WHEEL,sha256=IYZQI976HJqqOpQU6PHkJ8fb3tMNBFjg-Cn-pwAbaFM,88
+auto_rest_api-0.1.2.dist-info/entry_points.txt,sha256=zFynmBrHyYo3Ds0Uo4-bTFe1Tdr5mIXV4dPQOFb-W1w,53
+auto_rest_api-0.1.2.dist-info/RECORD,,

auto_rest_api-0.1.0.dist-info/RECORD

@@ -1,13 +0,0 @@
-auto_rest/__init__.py,sha256=9ICmv2urSoAo856FJylKdorF19UsUGc4eyORYLptf1Q,69
-auto_rest/__main__.py,sha256=RK3SuyGrWmXAjWZfZZJs-FP9srqjgdzhm86MuBucOok,3197
-auto_rest/cli.py,sha256=A7-kMTNNzqZB7jTUJBAVqfYm9RyYjENr0g_vK9JE0N4,5199
-auto_rest/handlers.py,sha256=0nj3radoT0V2bCSmb5gBuWyu1CtUgSQ_NU0typ8zKBA,11827
-auto_rest/models.py,sha256=XfzBdfnjQCXmcQBOYsC7OsZ69EBCKlANrcPnO5Tj8fQ,6882
-auto_rest/params.py,sha256=f5gIeCIlzvy70IgtfJ96Krohf44AySwR5k-b1DYeIXw,4953
-auto_rest/queries.py,sha256=GzoCtxRPn9UJ7cnhYuPc8wZFppbqe7ykSlnesfWSr94,2926
-auto_rest/routers.py,sha256=VzGPEwJe8GqLly751EWIru_LwjB7R9t1z9OPoYitc9I,5431
-auto_rest_api-0.1.0.dist-info/LICENSE.md,sha256=zFRw_u1mGSOH8GrpOu0L1P765aX9fB5UpKz06mTxAos,34893
-auto_rest_api-0.1.0.dist-info/METADATA,sha256=tvb1bdogwjEIf8e6XQYuvRY65ZCfrKNInbQBKmkR8cc,2951
-auto_rest_api-0.1.0.dist-info/WHEEL,sha256=IYZQI976HJqqOpQU6PHkJ8fb3tMNBFjg-Cn-pwAbaFM,88
-auto_rest_api-0.1.0.dist-info/entry_points.txt,sha256=zFynmBrHyYo3Ds0Uo4-bTFe1Tdr5mIXV4dPQOFb-W1w,53
-auto_rest_api-0.1.0.dist-info/RECORD,,