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

auto_rest/models.py

@@ -0,0 +1,228 @@
+"""
+The `models` module facilitates communication with relational databases
+via dynamically generated object relational mappers (ORMs). Building
+on the popular SQLAlchemy package, it natively supports multiple
+Database Management Systems (DBMS) without requiring custom configuration
+or setup.
+
+!!! example "Example: Creating ORM objects"
+
+    Utility functions are provided for connecting to the database,
+    mapping the schema, and dynamically generating ORM models based on
+    the existing database structure.
+
+    ```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
+the chosen database. If the driver supports asynchronous operations, the
+connection and session handling are configured accordingly.
+
+!!! important "Developer Note"
+
+    When working with database objects, the returned object type may vary
+    depending on whether the underlying driver is synchronous or asynchronous.
+    Of particular note are database engines (`Engine` / `AsyncEngine`) and
+    sessions (`Session` / `AsyncSession`).
+"""
+
+import asyncio
+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
+
+__all__ = [
+    "DBEngine",
+    "DBModel",
+    "DBSession",
+    "create_db_engine",
+    "create_db_interface",
+    "create_db_metadata",
+    "create_db_models",
+    "create_db_url",
+    "create_session_iterator",
+]
+
+logger = logging.getLogger(__name__)
+
+# Base classes and typing objects.
+DBModel = declarative_base()
+DBEngine = Engine | AsyncEngine
+DBSession = Session | AsyncSession
+
+
+def create_db_url(
+    driver: str,
+    database: str,
+    host: str | None = None,
+    port: int | None = None,
+    username: str | None = None,
+    password: str | None = None,
+) -> URL:
+    """Create a database URL from the provided parameters.
+
+    Args:
+        driver: The SQLAlchemy-compatible database driver.
+        database: The database name or file path (for SQLite).
+        host: The database server hostname or IP address.
+        port: The database server port number.
+        username: The username for authentication.
+        password: The password for the database user.
+
+    Returns:
+        A fully qualified database URL.
+    """
+
+    logger.debug("Resolving database URL.")
+
+    # Handle special case where SQLite uses file paths.
+    if "sqlite" in driver:
+        path = Path(database).resolve()
+        return URL.create(drivername=driver, database=str(path))
+
+    return URL.create(
+        drivername=driver,
+        username=username,
+        password=password,
+        host=host,
+        port=port,
+        database=database,
+    )
+
+
+def create_db_engine(url: URL, **kwargs: dict[str: any]) -> DBEngine:
+    """Initialize a new database engine.
+
+    Instantiates and returns an `Engine` or `AsyncEngine` instance depending
+    on whether the database URL uses a driver with support for async operations.
+
+    Args:
+        url: A fully qualified database URL.
+        **kwargs: Keyword arguments passed to `create_engine`.
+
+    Returns:
+        A SQLAlchemy `Engine` or `AsyncEngine` instance.
+    """
+
+    logger.debug(f"Building database engine for {url}.")
+
+    if url.get_dialect().is_async:
+        engine = create_async_engine(url, **kwargs)
+        logger.debug("Asynchronous connection established.")
+        return engine
+
+    else:
+        engine = create_engine(url, **kwargs)
+        logger.debug("Synchronous connection established.")
+        return engine
+
+
+async def _async_reflect_metadata(engine: AsyncEngine, metadata: MetaData) -> None:
+    """Helper function used to reflect database metadata using an async engine."""
+
+    async with engine.connect() as connection:
+        await connection.run_sync(metadata.reflect)
+
+
+def create_db_metadata(engine: DBEngine) -> MetaData:
+    """Create and reflect metadata for the database connection.
+
+    Args:
+        engine: The database engine to use for reflection.
+
+    Returns:
+        A MetaData object reflecting the database schema.
+    """
+
+    logger.debug("Loading database metadata.")
+    metadata = MetaData()
+
+    if isinstance(engine, AsyncEngine):
+        asyncio.run(_async_reflect_metadata(engine, metadata))
+
+    else:
+        metadata.reflect(bind=engine)
+
+    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.
+
+    Returns a synchronous or asynchronous function depending on whether
+    the database engine supports async operations. The type of session
+    returned also depends on the underlying database engine, and will
+    either be a `Session` or `AsyncSession` instance.
+
+    Args:
+        engine: Database engine to use when generating new sessions.
+
+    Returns:
+        A function that yields a single new database session.
+    """
+
+    if isinstance(engine, AsyncEngine):
+        async def session_iterator() -> AsyncSession:
+            async with AsyncSession(bind=engine, autocommit=False, autoflush=True) as session:
+                yield session
+
+    else:
+        def session_iterator() -> Session:
+            with Session(bind=engine, autocommit=False, autoflush=True) as session:
+                yield session
+
+    return session_iterator

auto_rest/params.py

@@ -0,0 +1,147 @@
+"""
+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'.")

auto_rest/queries.py

@@ -0,0 +1,107 @@
+"""
+The `queries` module provides asynchronous wrapper functions around operations
+involving SQLAlchemy sessions. These utilities automatically account for
+variations in behavior between synchronous and asynchronous session types
+(i.e., `Session` and `AsyncSession` instances). This ensures consistent query
+handling and provides a streamlined interface for database interactions.
+
+!!! example "Example: Query Execution"
+
+    Query utilities seamlessly support synchronous and asynchronous session types.
+
+    ```python
+    query = select(SomeModel).where(SomeModel.id == item_id)
+
+    with Session(...) as sync_session:
+        result = await execute_session_query(sync_session, query)
+
+    with AsyncSession(...) as async_session:
+        result = await execute_session_query(async_session, query)
+    ```
+"""
+
+from fastapi import HTTPException
+from sqlalchemy import Executable, Result
+from sqlalchemy.ext.asyncio import AsyncSession
+from starlette import status
+
+from auto_rest.models import DBSession
+
+__all__ = [
+    "commit_session",
+    "delete_session_record",
+    "execute_session_query",
+    "get_record_or_404"
+]
+
+
+async def commit_session(session: DBSession) -> None:
+    """Commit a SQLAlchemy session.
+
+    Supports synchronous and asynchronous sessions.
+
+    Args:
+        session: The session to commit.
+    """
+
+    if isinstance(session, AsyncSession):
+        await session.commit()
+
+    else:
+        session.commit()
+
+
+async def delete_session_record(session: DBSession, record: Result) -> None:
+    """Delete a record from the database using an existing session.
+
+    Does not automatically commit the session.
+    Supports synchronous and asynchronous sessions.
+
+    Args:
+        session: The session to use for deletion.
+        record: The record to be deleted.
+    """
+
+    if isinstance(session, AsyncSession):
+        await session.delete(record)
+
+    else:
+        session.delete(record)
+
+
+async def execute_session_query(session: DBSession, query: Executable) -> Result:
+    """Execute a query in the given session and return the result.
+
+    Supports synchronous and asynchronous sessions.
+
+    Args:
+        session: The SQLAlchemy session to use for executing the query.
+        query: The query to be executed.
+
+    Returns:
+        The result of the executed query.
+    """
+
+    if isinstance(session, AsyncSession):
+        return await session.execute(query)
+
+    return session.execute(query)
+
+
+def get_record_or_404(result: Result) -> any:
+    """Retrieve a scalar record from a query result or raise a 404 error.
+
+    Args:
+        result: The query result to extract the scalar record from.
+
+    Returns:
+        The scalar record if it exists.
+
+    Raises:
+        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")
+
+    return record

auto_rest/routers.py

@@ -0,0 +1,168 @@
+"""
+API routers are responsible for redirecting incoming HTTP requests to the
+appropriate handling logic. Router objects are created using a factory
+pattern, with each router being responsible for a single application
+resource. Each factory returns an `APIRouter` instance preconfigured
+with request handling logic for the relevant resource. This allows
+routers to be added directly to an API application instance.
+
+!!! example "Example: Creating and Adding a Router"
+
+    Care should be taken to avoid path conflicts when adding routers
+    to an API application instance. Using a unique `prefix` value
+    ensures that each router's endpoints are properly namespaced and
+    unique.
+
+    ```python
+    from fastapi import FastAPI
+    from auto_rest.routers import create_welcome_router
+
+    app = FastAPI()
+    welcome_router = create_welcome_router()
+    app.include_router(welcome_router, prefix="/welcome")
+    ```
+"""
+
+from fastapi import APIRouter
+from sqlalchemy import MetaData
+from starlette import status
+
+from auto_rest.handlers import *
+from auto_rest.models import DBEngine, DBModel
+
+__all__ = [
+    "create_meta_router",
+    "create_model_router",
+    "create_welcome_router",
+]
+
+
+def create_welcome_router() -> APIRouter:
+    """Create an API router for returning a welcome message.
+
+    Returns:
+        An `APIRouter` with a single route for retrieving a welcome message.
+    """
+
+    router = APIRouter()
+    router.add_api_route("/", create_welcome_handler(), methods=["GET"], include_in_schema=False)
+    return router
+
+
+def create_meta_router(engine: DBEngine, metadata: MetaData, name: str, version: str) -> APIRouter:
+    """Create an API router for returning database metadata.
+
+    Includes routes for retrieving the database driver, database schema,
+    and application/schema version.
+
+    Args:
+        engine: The database engine used to facilitate database interactions.
+        metadata: The metadata object containing the database schema.
+        version: The application name.
+        version: The application versionnumber.
+
+    Returns:
+        An `APIRouter` with a routes for retrieving application metadata.
+    """
+
+    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)
+    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.
+
+    Args:
+        engine: The SQLAlchemy engine connected to the database.
+        model: The ORM model class representing a database table.
+        writeable: Whether the router should include support for write operations.
+
+    Returns:
+        An APIRouter instance with routes for database operations on the model.
+    """
+
+    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
+
+    # Define routes for write operations
+    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),
+        status_code=status.HTTP_200_OK,
+        tags=[model.__name__],
+        openapi_extra=path_params_openapi
+    )
+
+    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
+    )
+
+    return router