auto-rest-api 0.1.0__tar.gz → 0.1.1__tar.gz

{auto_rest_api-0.1.0 → auto_rest_api-0.1.1}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.3
 Name: auto-rest-api
-Version: 0.1.0
+Version: 0.1.1
 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.0 → auto_rest_api-0.1.1}/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 *
@@ -80,7 +79,7 @@ def run_application(
 
     # 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")
 
@@ -90,4 +89,4 @@ def run_application(
 
     # 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_api-0.1.1/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_api-0.1.0 → auto_rest_api-0.1.1}/auto_rest/handlers.py

@@ -55,7 +55,7 @@ from typing import Awaitable, Callable
 
 from fastapi import Depends, Response
 from pydantic import create_model
-from pydantic.main import ModelT
+from pydantic.main import BaseModel as PydanticModel
 from sqlalchemy import insert, MetaData, select
 from starlette.requests import Request
 
@@ -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,7 +180,7 @@ 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, model: DBModel) -> Callable[..., Awaitable[list[PydanticModel]]]:
     """Create an endpoint handler that returns a list of records from a database table.
 
     Args:
@@ -196,8 +196,8 @@ def create_list_records_handler(engine: DBEngine, model: DBModel) -> Callable[..
     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(model),
+        ordering_params: dict[str, int] = create_ordering_dependency(model),
     ) -> list[interface]:
         """Fetch a list of records from the database.
 
@@ -213,7 +213,7 @@ def create_list_records_handler(engine: DBEngine, model: DBModel) -> Callable[..
     return list_records_handler
 
 
-def create_get_record_handler(engine: DBEngine, model: DBModel) -> Callable[..., Awaitable[ModelT]]:
+def create_get_record_handler(engine: DBEngine, model: DBModel) -> Callable[..., Awaitable[PydanticModel]]:
     """Create a function for handling GET requests against a single record in the database.
 
     Args:
@@ -240,7 +240,7 @@ def create_get_record_handler(engine: DBEngine, model: DBModel) -> Callable[...,
     return get_record_handler
 
 
-def create_post_record_handler(engine: DBEngine, model: DBModel) -> Callable[..., Awaitable[ModelT]]:
+def create_post_record_handler(engine: DBEngine, model: DBModel) -> Callable[..., Awaitable[PydanticModel]]:
     """Create a function for handling POST requests against a record in the database.
 
     Args:
@@ -269,7 +269,7 @@ def create_post_record_handler(engine: DBEngine, model: DBModel) -> Callable[...
     return post_record_handler
 
 
-def create_put_record_handler(engine: DBEngine, model: DBModel) -> Callable[..., Awaitable[ModelT]]:
+def create_put_record_handler(engine: DBEngine, model: DBModel) -> Callable[..., Awaitable[PydanticModel]]:
     """Create a function for handling PUT requests against a record in the database.
 
     Args:
@@ -302,7 +302,7 @@ 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, model: DBModel) -> Callable[..., Awaitable[PydanticModel]]:
     """Create a function for handling PATCH requests against a record in the database.
 
     Args:

{auto_rest_api-0.1.0 → auto_rest_api-0.1.1}/auto_rest/models.py

@@ -36,7 +36,7 @@ import logging
 from pathlib import Path
 from typing import Callable
 
-from pydantic.main import create_model, ModelT
+from pydantic.main import create_model, BaseModel as PydanticModel
 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
@@ -55,8 +55,10 @@ __all__ = [
 
 logger = logging.getLogger(__name__)
 
+Base = declarative_base()
+
 # Base classes and typing objects.
-DBModel = declarative_base()
+DBModel = type[Base]
 DBEngine = Engine | AsyncEngine
 DBSession = Session | AsyncSession
 
@@ -174,7 +176,7 @@ def create_db_models(metadata: MetaData) -> dict[str, DBModel]:
         logger.debug(f"> Creating model for table {table_name}.")
         models[table_name] = type(
             table_name.capitalize(),
-            (DBModel,),
+            (Base,),
             {"__table__": table},
         )
 
@@ -182,7 +184,7 @@ def create_db_models(metadata: MetaData) -> dict[str, DBModel]:
     return models
 
 
-def create_db_interface(model: DBModel) -> type[ModelT]:
+def create_db_interface(model: DBModel) -> type[PydanticModel]:
     """Create a Pydantic interface for a SQLAlchemy model.
 
     Args:

auto_rest_api-0.1.1/auto_rest/params.py

@@ -0,0 +1,175 @@
+"""
+The `params` module provides utilities for extracting and applying query
+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 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"
+
+    ```python
+    from fastapi import FastAPI, Response
+    from sqlalchemy import select
+    from auto_rest.query_params import create_pagination_dependency, apply_pagination_params
+
+    app = FastAPI()
+
+    @app.get("/items/")
+    async def list_items(
+        pagination_params: dict = create_pagination_dependency(model),
+        response: Response
+    ):
+        query = select(model)
+        query = apply_pagination_params(query, pagination_params, response)
+        return ...  # Logic to further process and execute the query goes here
+    ```
+"""
+from collections.abc import Callable
+from typing import Literal
+
+from fastapi import Depends, Query
+from sqlalchemy import asc, desc
+from sqlalchemy.sql.selectable import Select
+from starlette.responses import Response
+
+from .models import DBModel
+
+__all__ = [
+    "apply_ordering_params",
+    "apply_pagination_params",
+    "create_ordering_dependency",
+    "create_pagination_dependency",
+]
+
+
+def create_ordering_dependency(model: type[DBModel]) -> Callable[..., dict]:
+    """Create an injectable dependency for fetching ordering arguments from query parameters.
+
+    Args:
+        model: The database model to create the dependency for.
+
+    Returns:
+        An injectable FastAPI dependency.
+    """
+
+    columns = tuple(model.__table__.columns.keys())
+
+    def get_ordering_params(
+        _order_by_: Literal[*columns] = 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.
+
+        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)
+
+
+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.
+        params: A dictionary containing parsed URL parameters.
+        response: The outgoing HTTP response object.
+
+    Returns:
+        A copy of the query modified to return ordered values.
+    """
+
+    order_by = params.get("order_by")
+    direction = params.get("direction")
+
+    # Set common response headers
+    response.headers["X-Order-By"] = str(order_by)
+    response.headers["X-Order-Direction"] = str(direction)
+
+    if order_by is None:
+        response.headers["X-Order-Applied"] = "false"
+        return query
+
+    # 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 create_pagination_dependency(model: type[DBModel]) -> Callable[..., dict]:
+    """Create an injectable dependency for fetching pagination arguments from query parameters.
+
+    Args:
+        model: The database model to create the dependency for.
+
+    Returns:
+        An injectable FastAPI dependency.
+    """
+
+    def get_pagination_params(
+        _limit_: int = Query(0, 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.
+
+        Args:
+            _limit_: The maximum number of records to return.
+            _offset_: The starting index of the returned records.
+
+        Returns:
+            dict: A dictionary containing the `limit` and `offset` values.
+        """
+
+        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.
+        params: A dictionary containing parsed URL parameters.
+        response: The outgoing HTTP response object.
+
+    Returns:
+        A copy of the query modified to only return the paginated values.
+    """
+
+    limit = params.get("limit")
+    offset = params.get("offset")
+
+    # Set common response headers
+    response.headers["X-Pagination-Limit"] = str(limit)
+    response.headers["X-Pagination-Offset"] = str(offset)
+
+    # Do not apply pagination if not requested
+    if limit in (0, None):
+        response.headers["X-Pagination-Applied"] = "false"
+        return query
+
+    response.headers["X-Pagination-Applied"] = "true"
+    return query.offset(offset or 0).limit(limit)

{auto_rest_api-0.1.0 → auto_rest_api-0.1.1}/auto_rest/routers.py

@@ -58,7 +58,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:
@@ -89,15 +89,11 @@ def create_model_router(engine: DBEngine, model: DBModel, writeable: bool = Fals
     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)
+    pk_columns = sorted(column.name for column in model.__table__.primary_key.columns)
+    path_params_url = "/".join(f"{{{col_name}}}" for col_name in pk_columns)
     path_params_openapi = {
         "parameters": [
-            {
-                "name": col.name,
-                "in": "path",
-                "required": True
-            } for col in pk_columns
+            {"name": col_name, "in": "path", "required": True} for col_name in pk_columns
         ]
     }
 
@@ -113,7 +109,6 @@ def create_model_router(engine: DBEngine, model: DBModel, writeable: bool = Fals
         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(
@@ -135,7 +130,6 @@ def create_model_router(engine: DBEngine, model: DBModel, writeable: bool = Fals
         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(

{auto_rest_api-0.1.0 → auto_rest_api-0.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [project]
 name = "auto-rest-api"
-version = "0.1.0"
+version = "0.1.1"
 readme = "README.md"
 description = "Automatically map database schemas and deploy per-table REST API endpoints."
 authors = [{ name = "Better HPC LLC" }]
@@ -24,7 +24,7 @@ classifiers = [
     "Topic :: Software Development",
     "Typing :: Typed"
 ]
-requires-python = ">=3.10"
+requires-python = ">=3.11"
 dependencies = [
     "aiomysql~=0.2",
     "aioodbc~=0.5",

auto_rest_api-0.1.0/auto_rest/params.py

@@ -1,147 +0,0 @@
-"""
-The `params` module provides utilities for extracting and applying query
-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.
-
-!!! 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 sqlalchemy import select
-    from auto_rest.query_params import get_pagination_params, apply_pagination_params
-
-    app = FastAPI()
-
-    @app.get("/items/")
-    async def list_items(
-        pagination_params: dict = Depends(get_pagination_params),
-        response: Response
-    ):
-        query = select(SomeModel)
-        query = apply_pagination_params(query, pagination_params, response)
-        return ...  # Logic to further process and execute the query goes here
-    ```
-"""
-
-from typing import Literal
-
-from fastapi import Query
-from sqlalchemy import asc, desc
-from sqlalchemy.sql.selectable import Select
-from starlette.responses import Response
-
-__all__ = [
-    "apply_ordering_params",
-    "apply_pagination_params",
-    "get_ordering_params",
-    "get_pagination_params",
-]
-
-
-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.
-
-    Args:
-        _limit_: The maximum number of records to return.
-        _offset_: The starting index of the returned records.
-
-    Returns:
-        dict: A dictionary containing the `limit` and `offset` values.
-    """
-
-    return {"limit": _limit_, "offset": _offset_}
-
-
-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.
-    Compatible with parameters returned by the `get_pagination_params` method.
-
-    Args:
-        query: The database query to apply parameters to.
-        params: A dictionary containing parsed URL parameters.
-        response: The outgoing HTTP response object.
-
-    Returns:
-        A copy of the query modified to only return the paginated values.
-    """
-
-    limit = params.get("limit", 0)
-    offset = params.get("offset", 0)
-
-    if limit < 0 or offset < 0:
-        raise ValueError("Pagination parameters must be greater than or equal to zero.")
-
-    if limit == 0:
-        response.headers["X-Pagination-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)
-
-
-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.
-
-    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_}
-
-
-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.
-    Compatible with parameters returned by the `get_ordering_params` method.
-
-    Args:
-        query: The database query to apply parameters to.
-        params: A dictionary containing parsed URL parameters.
-        response: The outgoing HTTP response object.
-
-    Returns:
-        A copy of the query modified to return ordered values.
-    """
-
-    order_by = params.get("order_by")
-    direction = params.get("direction", "asc")
-
-    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))
-
-    if direction == "desc":
-        return query.order_by(desc(order_by))
-
-    raise ValueError("Ordering direction must be 'asc' or 'desc'.")