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

auto_rest/__init__.py

@@ -0,0 +1,3 @@
+from .__main__ import run_application
+
+__all__ = ["run_application"]

auto_rest/__main__.py

@@ -0,0 +1,93 @@
+"""Application entrypoint triggered by calling the packaged CLI command."""
+
+import logging
+from pathlib import Path
+
+import uvicorn
+import yaml
+from fastapi import FastAPI
+
+from .cli import *
+from .models import *
+from .routers import *
+
+__all__ = ["main", "run_application"]
+
+logger = logging.getLogger(__name__)
+
+
+def main() -> None:  # pragma: no cover
+    """Parse command-line arguments and launch an API server."""
+
+    try:
+        parser = create_cli_parser()
+        args = vars(parser.parse_args())
+        log_level = args.pop("log_level")
+
+        configure_cli_logging(log_level)
+        run_application(**args)
+
+    except KeyboardInterrupt:
+        pass
+
+    except Exception as e:
+        logger.critical(str(e), exc_info=True)
+
+
+def run_application(
+    enable_docs: bool,
+    enable_write: bool,
+    db_driver: str,
+    db_host: str,
+    db_port: int,
+    db_name: str,
+    db_user: str,
+    db_pass: str,
+    db_config: Path | None,
+    server_host: str,
+    server_port: int,
+    app_title: str,
+    app_version: str,
+) -> None:  # pragma: no cover
+    """Run an Auto-REST API server.
+
+    This function is equivalent to launching an API server from the command line
+    and accepts the same arguments as those provided in the CLI.
+
+    Args:
+        enable_docs: Whether to enable the 'docs' API endpoint.
+        enable_write: Whether to enable support for write operations.
+        db_driver: SQLAlchemy-compatible database driver.
+        db_host: Database host address.
+        db_port: Database port number.
+        db_name: Database name.
+        db_user: Database authentication username.
+        db_pass: Database authentication password.
+        db_config: Path to a database configuration file.
+        server_host: API server host address.
+        server_port: API server port number.
+        app_title: title for the generated OpenAPI schema.
+        app_version: version number for the generated OpenAPI schema.
+    """
+
+    # Connect to and map the database.
+    logger.info(f"Mapping database schema for {db_name}.")
+    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 {}
+    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.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}")
+
+    # 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")

auto_rest/cli.py

@@ -0,0 +1,127 @@
+"""
+The `cli` module manages input/output operations for the application's
+command line interface (CLI). Application inputs are parsed using the
+built-in `argparse` module while output messages are handled using the
+Python `logging` library.
+
+!!! example "Example: Parsing Arguments"
+
+    The `create_argument_parser` function returns an `ArgumentParser`
+    instance with pre-populated argument definitions.
+
+    ```python
+    from auto_rest.cli import create_argument_parser
+
+    parser = create_argument_parser()
+    args = parser.parse_args()
+    print(vars(args))
+    ```
+
+!!! example "Example: Enabling Console Logging"
+
+    The `configure_cli_logging` method overrides any existing logging
+    configurations and enables console logging according to the provided log
+    level.
+
+    ```python
+    from auto_rest.cli import configure_cli_logging
+
+    configure_cli_logging(log_level="INFO")
+    ```
+"""
+
+import importlib.metadata
+import logging
+from argparse import ArgumentParser, HelpFormatter
+from pathlib import Path
+
+from uvicorn.logging import DefaultFormatter
+
+__all__ = ["VERSION", "configure_cli_logging", "create_cli_parser"]
+
+VERSION = importlib.metadata.version("auto-rest-api")
+
+
+def configure_cli_logging(level: str) -> None:
+    """Enable console logging with the specified application log level.
+
+    Calling this method overrides and removes all previously configured
+    logging configurations.
+
+    Args:
+        level: The Python logging level.
+    """
+
+    # Normalize and validate the logging level.
+    level = level.upper()
+    if level not in ("DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"):
+        raise ValueError(f"Invalid logging level: {level}")
+
+    # Set up logging with a stream handler.
+    handler = logging.StreamHandler()
+    handler.setFormatter(DefaultFormatter(fmt="%(levelprefix)s %(message)s"))
+    logging.basicConfig(
+        force=True,
+        level=level,
+        format="%(levelprefix)s %(message)s",
+        handlers=[handler],
+    )
+
+
+def create_cli_parser(exit_on_error: bool = True) -> ArgumentParser:
+    """Create a command-line argument parser with preconfigured arguments.
+
+    Args:
+        exit_on_error: Whether to exit the program on a parsing error.
+
+    Returns:
+        An argument parser instance.
+    """
+
+    formatter = lambda prog: HelpFormatter(prog, max_help_position=29)
+    parser = ArgumentParser(
+        prog="auto-rest",
+        description="Automatically map database schemas and deploy per-table REST API endpoints.",
+        exit_on_error=exit_on_error,
+        formatter_class=formatter
+    )
+
+    parser.add_argument("--version", action="version", version=VERSION)
+    parser.add_argument(
+        "--log-level",
+        default="INFO",
+        type=lambda x: x.upper(),
+        choices=["DEBUG", "INFO", "WARNING", "ERROR"],
+        help="Set the logging level."
+    )
+
+    features = parser.add_argument_group(title="API features")
+    features.add_argument("--enable-docs", action="store_true", help="enable the 'docs' endpoint.")
+    features.add_argument("--enable-write", action="store_true", help="enable support for write operations.")
+
+    driver = parser.add_argument_group("database type")
+    db_type = driver.add_mutually_exclusive_group(required=True)
+    db_type.add_argument("--sqlite", action="store_const", dest="db_driver", const="sqlite+aiosqlite", help="use a SQLite database driver.")
+    db_type.add_argument("--psql", action="store_const", dest="db_driver", const="postgresql+asyncpg", help="use a PostgreSQL database driver.")
+    db_type.add_argument("--mysql", action="store_const", dest="db_driver", const="mysql+asyncmy", help="use a MySQL database driver.")
+    db_type.add_argument("--oracle", action="store_const", dest="db_driver", const="oracle+oracledb", help="use an Oracle database driver.")
+    db_type.add_argument("--mssql", action="store_const", dest="db_driver", const="mssql+aiomysql", help="use a Microsoft database driver.")
+    db_type.add_argument("--driver", action="store", dest="db_driver", help="use a custom database driver.")
+
+    database = parser.add_argument_group("database settings")
+    database.add_argument("--db-host", help="database address to connect to.")
+    database.add_argument("--db-port", type=int, help="database port to connect to.")
+    database.add_argument("--db-name", required=True, help="database name or file path to connect to.")
+    database.add_argument("--db-user", help="username to authenticate with.")
+    database.add_argument("--db-pass", help="password to authenticate with.")
+    database.add_argument("--db-config", action="store", type=Path, help="path to a database configuration file.")
+
+    server = parser.add_argument_group(title="server settings")
+    server.add_argument("--server-host", default="127.0.0.1", help="API server host address.")
+    server.add_argument("--server-port", type=int, default=8081, help="API server port number.")
+
+    schema = parser.add_argument_group(title="application settings")
+    schema.add_argument("--app-title", default="Auto-REST", help="application title.")
+    schema.add_argument("--app-version", default=VERSION, help="application version number.")
+
+    return parser

auto_rest/handlers.py

@@ -0,0 +1,362 @@
+"""
+An **endpoint handler** is a function designed to process incoming HTTP
+requests for single API endpoint. In `auto_rest`, handlers are
+created dynamically using a factory pattern. This approach allows
+handler logic to be customized and reused across multiple endpoints.
+
+!!! example "Example: Creating a Handler"
+
+    New endpoint handlers are created dynamically using factory methods.
+
+    ```python
+    welcome_handler = create_welcome_handler()
+    ```
+
+Handler functions are defined as asynchronous coroutines.
+This provides improved performance when handling large numbers of
+incoming requests.
+
+!!! example "Example: Async Handlers"
+
+    Python requires asynchronous coroutines to be run from an asynchronous
+    context. In the following example, this is achieved using `asyncio.run`.
+
+    ```python
+    import asyncio
+
+    return_value = asyncio.run(welcome_handler())
+    ```
+
+Handlers are specifically designed to integrate with the FastAPI framework,
+including support for FastAPI's type hinting and data validation capabilities.
+This makes it easy to incorporate handlers into a FastAPI application.
+
+!!! example "Example: Adding a Handler to an Application"
+
+    Use the `add_api_route` method to dynamically add handler functions to
+    an existing application instance.
+
+    ```python
+    app = FastAPI(...)
+
+    handler = create_welcome_handler()
+    app.add_api_route("/", handler, methods=["GET"], ...)
+    ```
+
+!!! info "Developer Note"
+
+    FastAPI internally performs post-processing on values returned by endpoint
+    handlers before sending them in an HTTP response. For this reason, handlers
+    should always be tested within the context of a FastAPI application.
+"""
+
+import logging
+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 .models import *
+from .params import *
+from .queries import *
+
+__all__ = [
+    "create_about_handler",
+    "create_delete_record_handler",
+    "create_engine_handler",
+    "create_get_record_handler",
+    "create_list_records_handler",
+    "create_patch_record_handler",
+    "create_post_record_handler",
+    "create_put_record_handler",
+    "create_schema_handler",
+    "create_welcome_handler",
+]
+
+logger = logging.getLogger(__name__)
+
+
+def create_welcome_handler() -> Callable[[], Awaitable[ModelT]]:
+    """Create an endpoint handler that returns an application welcome message.
+
+    Returns:
+        An async function that returns a welcome message.
+    """
+
+    interface = create_model("Welcome", message=(str, "Welcome to Auto-Rest!"))
+
+    async def welcome_handler() -> interface:
+        """Return an application welcome message."""
+
+        return interface()
+
+    return welcome_handler
+
+
+def create_about_handler(name: str, version: str) -> Callable[[], Awaitable[ModelT]]:
+    """Create an endpoint handler that returns the application name and version number.
+
+    Args:
+        name: The application name.
+        version: The returned version identifier.
+
+    Returns:
+        An async function that returns aplication info.
+    """
+
+    interface = create_model("Version", version=(str, version), name=(str, name))
+
+    async def about_handler() -> interface:
+        """Return the application name and version number."""
+
+        return interface()
+
+    return about_handler
+
+
+def create_engine_handler(engine: DBEngine) -> Callable[[], Awaitable[ModelT]]:
+    """Create an endpoint handler that returns configuration details for a database engine.
+
+    Args:
+        engine: Database engine to return the configuration for.
+
+    Returns:
+        An async function that returns database metadata.
+    """
+
+    interface = create_model("Meta",
+        dialect=(str, engine.dialect.name),
+        driver=(str, engine.dialect.driver),
+        database=(str, engine.url.database),
+    )
+
+    async def meta_handler() -> interface:
+        """Return metadata concerning the underlying application database."""
+
+        return interface()
+
+    return meta_handler
+
+
+def create_schema_handler(metadata: MetaData) -> Callable[[], Awaitable[ModelT]]:
+    """Create an endpoint handler that returns the database schema.
+
+    Args:
+        metadata: Metadata object containing the database schema.
+
+    Returns:
+        An async function that returns the database schema.
+    """
+
+    # Define Pydantic models for column, table, and schema level data
+    column_interface = create_model("Column",
+        type=(str, ...),
+        nullable=(bool, ...),
+        default=(str | None, None),
+        primary_key=(bool, ...),
+    )
+
+    table_interface = create_model("Table", columns=(dict[str, column_interface], ...))
+    schema_interface = create_model("Schema", tables=(dict[str, table_interface], ...))
+
+    async def schema_handler() -> schema_interface:
+        """Return metadata concerning the underlying application database."""
+
+        return schema_interface(
+            tables={table_name: table_interface(columns={
+                column.name: column_interface(
+                    type=str(column.type),
+                    nullable=column.nullable,
+                    default=str(column.default.arg) if column.default else None,
+                    primary_key=column.primary_key
+                )
+                for column in table.columns
+            }) for table_name, table in metadata.tables.items()}
+        )
+
+    return schema_handler
+
+
+def create_list_records_handler(engine: DBEngine, model: DBModel) -> Callable[..., Awaitable[list[ModelT]]]:
+    """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.
+
+    Returns:
+        An async function that returns a list of records from the given database model.
+    """
+
+    interface = create_db_interface(model)
+
+    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),
+    ) -> 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 = 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 list_records_handler
+
+
+def create_get_record_handler(engine: DBEngine, model: DBModel) -> Callable[..., Awaitable[ModelT]]:
+    """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.
+
+    Returns:
+        An async function that returns a single record from the given database model.
+    """
+
+    interface = create_db_interface(model)
+
+    async def get_record_handler(
+        request: Request,
+        session: DBSession = Depends(create_session_iterator(engine)),
+    ) -> interface:
+        """Fetch a single record from the database."""
+
+        query = select(model).filter_by(**request.path_params)
+        result = await execute_session_query(session, query)
+        record = get_record_or_404(result)
+        return interface.model_validate(record.__dict__)
+
+    return get_record_handler
+
+
+def create_post_record_handler(engine: DBEngine, model: DBModel) -> Callable[..., Awaitable[ModelT]]:
+    """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.
+
+    Returns:
+        An async function that handles record creation.
+    """
+
+    interface = create_db_interface(model)
+
+    async def post_record_handler(
+        data: interface,
+        session: DBSession = Depends(create_session_iterator(engine)),
+    ) -> interface:
+        """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)
+
+        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]]:
+    """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.
+
+    Returns:
+        An async function that handles record updates.
+    """
+
+    interface = create_db_interface(model)
+
+    async def put_record_handler(
+        request: Request,
+        data: interface,
+        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)
+        result = await execute_session_query(session, query)
+        record = get_record_or_404(result)
+
+        for key, value in data.dict().items():
+            setattr(record, key, value)
+
+        await commit_session(session)
+        return interface.model_validate(record.__dict__)
+
+    return put_record_handler
+
+
+def create_patch_record_handler(engine: DBEngine, model: DBModel) -> Callable[..., Awaitable[ModelT]]:
+    """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.
+
+    Returns:
+        An async function that handles record updates.
+    """
+
+    interface = create_db_interface(model)
+
+    async def patch_record_handler(
+        request: Request,
+        data: interface,
+        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)
+        result = await execute_session_query(session, query)
+        record = get_record_or_404(result)
+
+        for key, value in data.dict(exclude_unset=True).items():
+            setattr(record, key, value)
+
+        await commit_session(session)
+        return interface(record.__dict__)
+
+    return patch_record_handler
+
+
+def create_delete_record_handler(engine: DBEngine, model: DBModel) -> 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.
+
+    Returns:
+        An async function that handles record deletion.
+    """
+
+    async def delete_record_handler(
+        request: Request,
+        session: DBSession = Depends(create_session_iterator(engine)),
+    ) -> None:
+        """Delete a record from the database."""
+
+        query = select(model).filter_by(**request.path_params)
+        result = await execute_session_query(session, query)
+        record = get_record_or_404(result)
+
+        await delete_session_record(session, record)
+        await commit_session(session)
+
+    return delete_record_handler