auto-rest-api 0.1.2__tar.gz → 0.1.11__tar.gz

{auto_rest_api-0.1.2 → auto_rest_api-0.1.11}/LICENSE.md

@@ -617,59 +617,3 @@ Program, unless a warranty or assumption of liability accompanies a
 copy of the Program in return for a fee.
 
 END OF TERMS AND CONDITIONS
-
-## How to Apply These Terms to Your New Programs
-
-If you develop a new program, and you want it to be of the greatest
-possible use to the public, the best way to achieve this is to make it
-free software which everyone can redistribute and change under these
-terms.
-
-To do so, attach the following notices to the program. It is safest to
-attach them to the start of each source file to most effectively state
-the exclusion of warranty; and each file should have at least the
-"copyright" line and a pointer to where the full notice is found.
-
-        <one line to give the program's name and a brief idea of what it does.>
-        Copyright (C) <year>  <name of author>
-
-        This program is free software: you can redistribute it and/or modify
-        it under the terms of the GNU General Public License as published by
-        the Free Software Foundation, either version 3 of the License, or
-        (at your option) any later version.
-
-        This program is distributed in the hope that it will be useful,
-        but WITHOUT ANY WARRANTY; without even the implied warranty of
-        MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-        GNU General Public License for more details.
-
-        You should have received a copy of the GNU General Public License
-        along with this program.  If not, see <https://www.gnu.org/licenses/>.
-
-Also add information on how to contact you by electronic and paper
-mail.
-
-If the program does terminal interaction, make it output a short
-notice like this when it starts in an interactive mode:
-
-        <program>  Copyright (C) <year>  <name of author>
-        This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
-        This is free software, and you are welcome to redistribute it
-        under certain conditions; type `show c' for details.
-
-The hypothetical commands \`show w' and \`show c' should show the
-appropriate parts of the General Public License. Of course, your
-program's commands might be different; for a GUI interface, you would
-use an "about box".
-
-You should also get your employer (if you work as a programmer) or
-school, if any, to sign a "copyright disclaimer" for the program, if
-necessary. For more information on this, and how to apply and follow
-the GNU GPL, see <https://www.gnu.org/licenses/>.
-
-The GNU General Public License does not permit incorporating your
-program into proprietary programs. If your program is a subroutine
-library, you may consider it more useful to permit linking proprietary
-applications with the library. If this is what you want to do, use the
-GNU Lesser General Public License instead of this License. But first,
-please read <https://www.gnu.org/licenses/why-not-lgpl.html>.

{auto_rest_api-0.1.2 → auto_rest_api-0.1.11}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.3
 Name: auto-rest-api
-Version: 0.1.2
+Version: 0.1.11
 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.11
+Requires-Python: >=3.11,<4
 Classifier: Environment :: Web Environment
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Information Technology
@@ -18,23 +18,25 @@ Classifier: Topic :: Internet :: WWW/HTTP
 Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
 Classifier: Topic :: Software Development
 Classifier: Typing :: Typed
-Requires-Dist: aiomysql (>=0.2,<1.0)
-Requires-Dist: aioodbc (>=0.5,<1.0)
-Requires-Dist: aiosqlite (>=0.20,<1.0)
-Requires-Dist: asyncpg (>=0.30,<1.0)
-Requires-Dist: fastapi (>=0.115,<1.0)
-Requires-Dist: greenlet (>=3.1,<4.0)
-Requires-Dist: httpx (>=0.28,<1.0)
-Requires-Dist: oracledb (>=2.5,<3.0)
-Requires-Dist: pydantic (>=2.10,<3.0)
-Requires-Dist: pyyaml (>=6.0.2,<7.0.0)
-Requires-Dist: sqlalchemy (>=2.0,<3.0)
-Requires-Dist: uvicorn (>=0.34,<1.0)
+Requires-Dist: aiomysql (==0.3.2)
+Requires-Dist: aioodbc (==0.5.0)
+Requires-Dist: aiosqlite (==0.20.0)
+Requires-Dist: asgi-correlation-id (==4.3.4)
+Requires-Dist: asyncpg (==0.30.0)
+Requires-Dist: colorlog (>=6.9.0,<7.0.0)
+Requires-Dist: fastapi (==0.120.1)
+Requires-Dist: greenlet (==3.2.4)
+Requires-Dist: httpx (==0.28.1)
+Requires-Dist: oracledb (==2.5.1)
+Requires-Dist: pydantic (==2.12.3)
+Requires-Dist: pyyaml (==6.0.3)
+Requires-Dist: sqlalchemy (==2.0.44)
+Requires-Dist: uvicorn (==0.38.0)
 Description-Content-Type: text/markdown
 
 # Auto-REST
 
-A command line tool for deploying dynamically generated REST APIs against relational databases.
+A light-weight CLI tool for deploying dynamically generated REST APIs against relational databases.
 See the [project documentation](https://better-hpc.github.io/auto-rest/) for detailed usage instructions.
 
 ## Supported Databases
@@ -70,10 +72,6 @@ Launch an API by providing connection arguments to a database of your choice.
 
 ```shell
 auto-rest \
-  # Enable optional endpoints / functionality
-  --enable-docs \
-  --enable-write \
-  # Define the database type and connection arguments
   --psql 
   --db-host localhost
   --db-port 5432

{auto_rest_api-0.1.2 → auto_rest_api-0.1.11}/README.md

@@ -1,6 +1,6 @@
 # Auto-REST
 
-A command line tool for deploying dynamically generated REST APIs against relational databases.
+A light-weight CLI tool for deploying dynamically generated REST APIs against relational databases.
 See the [project documentation](https://better-hpc.github.io/auto-rest/) for detailed usage instructions.
 
 ## Supported Databases
@@ -36,10 +36,6 @@ Launch an API by providing connection arguments to a database of your choice.
 
 ```shell
 auto-rest \
-  # Enable optional endpoints / functionality
-  --enable-docs \
-  --enable-write \
-  # Define the database type and connection arguments
   --psql 
   --db-host localhost
   --db-port 5432

auto_rest_api-0.1.11/auto_rest/__main__.py

@@ -0,0 +1,70 @@
+"""Application entrypoint triggered by calling the packaged CLI command."""
+
+import logging
+
+from .app import *
+from .cli import *
+from .models import *
+from .routers import *
+
+__all__ = ["main", "run_application"]
+
+logger = logging.getLogger("auto_rest")
+
+
+def main() -> None:  # pragma: no cover
+    """Application entry point called when executing the command line interface.
+
+    This is a wrapper around the `run_application` function used to provide
+    graceful error handling.
+    """
+
+    try:
+        run_application()
+
+    except KeyboardInterrupt:
+        pass
+
+    except Exception as e:
+        logger.critical(str(e), exc_info=True)
+
+
+def run_application(cli_args: list[str] = None, /) -> 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. Arguments are
+    parsed from STDIN by default, unless specified in the function call.
+
+    Args:
+        A list of commandline arguments used to run the application.
+    """
+
+    # Parse application arguments
+    args = create_cli_parser().parse_args(cli_args)
+    configure_cli_logging(args.log_level)
+
+    logger.info(f"Resolving database connection settings.")
+    db_kwargs = parse_db_settings(args.db_config)
+    db_url = create_db_url(
+        driver=args.db_driver,
+        host=args.db_host,
+        port=args.db_port,
+        database=args.db_name,
+        username=args.db_user,
+        password=args.db_pass
+    )
+
+    logger.info("Mapping database schema.")
+    db_conn = create_db_engine(db_url, **db_kwargs)
+    db_meta = create_db_metadata(db_conn)
+
+    logger.info("Creating application.")
+    app = create_app(args.app_title, args.app_version)
+    app.include_router(create_welcome_router(), prefix="")
+    app.include_router(create_meta_router(db_conn, db_meta, args.app_title, args.app_version), prefix="/meta")
+    for table_name, table in db_meta.tables.items():
+        app.include_router(create_table_router(db_conn, table), prefix=f"/db/{table_name}")
+
+    logger.info(f"Launching server on http://{args.server_host}:{args.server_port}.")
+    run_server(app, args.server_host, args.server_port)

auto_rest_api-0.1.11/auto_rest/app.py

@@ -0,0 +1,114 @@
+"""
+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")
+    ... # Add endpoints to the application here
+    run_server(app, host="127.0.0.1", port=8081)
+    ```
+"""
+
+import logging
+from http import HTTPStatus
+
+import uvicorn
+from asgi_correlation_id import CorrelationIdMiddleware
+from fastapi import FastAPI, Request
+from fastapi.middleware.cors import CORSMiddleware
+from starlette.responses import Response
+
+__all__ = ["create_app", "run_server"]
+
+logger = logging.getLogger("auto_rest.access")
+
+
+async def logging_middleware(request: Request, call_next: callable) -> Response:
+    """FastAPI middleware for logging response status codes.
+
+    Args:
+        request: The incoming HTTP request.
+        call_next: The next middleware in the middleware chain.
+
+    Returns:
+        The outgoing HTTP response.
+    """
+
+    # Extract metadata from the request
+    request_meta = {
+        "ip": request.client.host,
+        "port": request.client.port,
+        "method": request.method,
+        "endpoint": request.url.path,
+    }
+
+    if request.url.query:
+        request_meta["endpoint"] += "?" + request.url.query
+
+    # Execute handling logic
+    try:
+        response = await call_next(request)
+
+    except Exception as exc:
+        logger.error(str(exc), exc_info=exc, extra=request_meta)
+        raise
+
+    # Log the outgoing response
+    status = HTTPStatus(response.status_code)
+    level = logging.INFO if status < 400 else logging.ERROR
+    logger.log(level, f"{status} {status.phrase}", extra=request_meta)
+
+    return response
+
+
+def create_app(app_title: str, app_version: str) -> 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.
+
+    Returns:
+        FastAPI: A configured FastAPI application instance.
+    """
+
+    app = FastAPI(
+        title=app_title,
+        version=app_version,
+        docs_url="/docs/",
+        redoc_url=None,
+    )
+
+    app.middleware("http")(logging_middleware)
+    app.add_middleware(CorrelationIdMiddleware)
+    app.add_middleware(
+        CORSMiddleware,
+        allow_credentials=True,
+        allow_origins=["*"],
+        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 overwrites its logging level when run and needs to be manually disabled here.
+    uvicorn.run(app, host=host, port=port, log_level=1000)

{auto_rest_api-0.1.2 → auto_rest_api-0.1.11}/auto_rest/cli.py

@@ -31,13 +31,11 @@ Python `logging` library.
 """
 
 import importlib.metadata
-import logging
+import logging.config
 from argparse import ArgumentParser, HelpFormatter
 from pathlib import Path
 
-from uvicorn.logging import DefaultFormatter
-
-__all__ = ["VERSION", "configure_cli_logging", "create_cli_parser"]
+__all__ = ["configure_cli_logging", "create_cli_parser", "VERSION"]
 
 VERSION = importlib.metadata.version("auto-rest-api")
 
@@ -49,7 +47,7 @@ def configure_cli_logging(level: str) -> None:
     logging configurations.
 
     Args:
-        level: The Python logging level.
+        level: The Python logging level (e.g., "DEBUG", "INFO", etc.).
     """
 
     # Normalize and validate the logging level.
@@ -57,15 +55,57 @@ def configure_cli_logging(level: str) -> None:
     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],
-    )
+    msg_prefix = "%(log_color)s%(levelname)-8s%(reset)s (%(asctime)s) [%(correlation_id)s] "
+    logging.config.dictConfig({
+        "version": 1,
+        "disable_existing_loggers": True,
+        "filters": {
+            "correlation_id": {
+                "()": "asgi_correlation_id.CorrelationIdFilter",
+                "uuid_length": 8,
+                "default_value": "-" * 8
+            },
+        },
+        "formatters": {
+            "app": {
+                "()": "colorlog.ColoredFormatter",
+                "format": msg_prefix + "%(message)s",
+            },
+            "access": {
+                "()": "colorlog.ColoredFormatter",
+                "format": msg_prefix + "%(ip)s:%(port)s - %(method)s %(endpoint)s - %(message)s",
+            }
+        },
+        "handlers": {
+            "app": {
+                "class": "colorlog.StreamHandler",
+                "formatter": "app",
+                "filters": ["correlation_id"],
+            },
+            "access": {
+                "class": "colorlog.StreamHandler",
+                "formatter": "access",
+                "filters": ["correlation_id"],
+            }
+        },
+        "loggers": {
+            "auto_rest": {
+                "handlers": ["app"],
+                "level": level,
+                "propagate": False
+            },
+            "auto_rest.access": {
+                "handlers": ["access"],
+                "level": level,
+                "propagate": False
+            },
+            "auto_rest.query": {
+                "handlers": ["app"],
+                "level": level,
+                "propagate": False
+            }
+        }
+    })
 
 
 def create_cli_parser(exit_on_error: bool = True) -> ArgumentParser:
@@ -95,10 +135,6 @@ def create_cli_parser(exit_on_error: bool = True) -> ArgumentParser:
         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.")

{auto_rest_api-0.1.2 → auto_rest_api-0.1.11}/auto_rest/handlers.py

@@ -50,17 +50,15 @@ This makes it easy to incorporate handlers into a FastAPI application.
     should always be tested within the context of a FastAPI application.
 """
 
-import logging
-from typing import Awaitable, Callable
+from typing import Awaitable, Callable, Literal, Optional
 
-from fastapi import Depends, Response
+from fastapi import Depends, Query, Response
 from pydantic import create_model
 from pydantic.main import BaseModel as PydanticModel
-from sqlalchemy import insert, MetaData, select, Table
+from sqlalchemy import asc, desc, func, insert, MetaData, select, Table
 
 from .interfaces import *
 from .models import *
-from .params import *
 from .queries import *
 
 __all__ = [
@@ -76,8 +74,6 @@ __all__ = [
     "create_welcome_handler",
 ]
 
-logger = logging.getLogger(__name__)
-
 
 def create_welcome_handler() -> Callable[[], Awaitable[PydanticModel]]:
     """Create an endpoint handler that returns an application welcome message.
@@ -192,12 +188,17 @@ def create_list_records_handler(engine: DBEngine, table: Table) -> Callable[...,
     """
 
     interface = create_interface(table)
+    interface_opt = create_interface(table, mode="optional")
+    col_names = tuple(table.columns.keys())
 
     async def list_records_handler(
         response: Response,
         session: DBSession = Depends(create_session_iterator(engine)),
-        pagination_params: dict[str, int] = create_pagination_dependency(table),
-        ordering_params: dict[str, int] = create_ordering_dependency(table),
+        filters: interface_opt = Depends(),
+        _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."),
+        _order_by_: Optional[Literal[*col_names]] = Query(None, description="The field name to sort by."),
+        _direction_: Literal["asc", "desc"] = Query("asc", description="Sort results in 'asc' or 'desc' order."),
     ) -> list[interface]:
         """Fetch a list of records from the database.
 
@@ -205,11 +206,39 @@ def create_list_records_handler(engine: DBEngine, table: Table) -> Callable[...,
         """
 
         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 [row._mapping for row in result.all()]
+        # Fetch data per the request parameters
+        for param, value in filters:
+            if value is not None:
+                column = getattr(table.c, param)
+
+                # Use a "_null_" parameter value to represent a `None` database value
+                if isinstance(value, str) and value.lower() == "_null_":
+                    query = query.filter(column.is_(None))
+
+                else:
+                    query = query.filter(column.ilike(f"%{value}%"))
+
+        if _limit_ > 0:
+            query = query.offset(_offset_).limit(_limit_)
+
+        if _order_by_ is not None:
+            direction = {'desc': desc, 'asc': asc}[_direction_]
+            query = query.order_by(direction(_order_by_))
+
+        # Determine total record count
+        total_count_query = select(func.count()).select_from(table)
+        total_count = await execute_session_query(session, total_count_query)
+
+        # Set headers
+        response.headers["x-pagination-limit"] = str(_limit_)
+        response.headers["x-pagination-offset"] = str(_offset_)
+        response.headers["x-pagination-total"] = str(total_count.first()[0])
+        response.headers["x-order-by"] = str(_order_by_)
+        response.headers["x-order-direction"] = str(_direction_)
+
+        # noinspection PyTypeChecker
+        return await execute_session_query(session, query)
 
     return list_records_handler
 
@@ -242,7 +271,7 @@ def create_get_record_handler(engine: DBEngine, table: Table) -> Callable[..., A
     return get_record_handler
 
 
-def create_post_record_handler(engine: DBEngine, table: Table) -> Callable[..., Awaitable[PydanticModel]]:
+def create_post_record_handler(engine: DBEngine, table: Table) -> Callable[..., Awaitable[None]]:
     """Create a function for handling POST requests against a record in the database.
 
     Args:
@@ -261,7 +290,7 @@ def create_post_record_handler(engine: DBEngine, table: Table) -> Callable[...,
     ) -> None:
         """Create a new record in the database."""
 
-        query = insert(table).values(**data.dict())
+        query = insert(table).values(**data.model_dump())
         await execute_session_query(session, query)
         await commit_session(session)
 
@@ -298,7 +327,7 @@ def create_put_record_handler(engine: DBEngine, table: Table) -> Callable[..., A
             setattr(record, key, value)
 
         await commit_session(session)
-        return interface.model_validate(record.__dict__)
+        return record
 
     return put_record_handler
 

auto_rest_api-0.1.11/auto_rest/interfaces.py

@@ -0,0 +1,118 @@
+"""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` method creates a Pydantic interface class derived
+    from a SQLAlchemy table. By default, interface fields are marked as
+    required based on the underlying schema. The `mode` argument is used to
+    override field definitions and make all fields in the interface either
+    `optional` or `required` regardless of the schema definition.
+
+    ```python
+    default_interface = create_interface(database_model)
+    required_interface = create_interface(database_model, mode="required")
+    optional_interface = create_interface(database_model, mode="optional")
+    ```
+"""
+
+from typing import Any, Iterator, Literal
+
+from pydantic import BaseModel as PydanticModel, create_model
+from sqlalchemy import Column, Table
+
+__all__ = ["create_interface"]
+
+MODE_TYPE = 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.values():
+        if column.primary_key or not pk_only:
+            yield column
+
+
+def create_field_definition(col: Column, mode: MODE_TYPE = "default") -> tuple[type[any], any]:
+    """Return a tuple with the type and default value for a database table column.
+
+    The returned tuple is compatible for use with Pydantic as a field definition
+    during dynamic model generation. The `mode` argument modifies returned
+    values to enforce different behavior in the generated Pydantic interface.
+
+    Modes:
+        default: Values are marked as (not)required based on the column schema.
+        required: Values are always marked required.
+        optional: Values are always marked optional.
+
+    Args:
+        col: The column to return values for.
+        mode: The mode to use when determining the default value.
+
+    Returns:
+        The default value for the column.
+    """
+
+    try:
+        col_type = col.type.python_type
+
+    except NotImplementedError:
+        col_type = Any
+
+    col_default = getattr(col.default, "arg", col.default)
+
+    if mode == "required":
+        return col_type, ...
+
+    elif mode == "optional":
+        return col_type | None, col_default
+
+    elif mode == "default" and (col.nullable or col.default):
+        return col_type | None, col_default
+
+    elif mode == "default":
+        return col_type, ...
+
+    raise RuntimeError(f"Unknown mode: {mode}")
+
+
+def create_interface(table: Table, pk_only: bool = False, mode: MODE_TYPE = "default") -> type[PydanticModel]:
+    """Create a Pydantic interface for a SQLAlchemy model where all fields are required.
+
+    Modes:
+        default: Values are marked as (not)required based on the column schema.
+        required: Values are always marked required.
+        optional: Values are always marked optional.
+
+    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.
+    fields = {
+        col.name: create_field_definition(col, mode) for col in iter_columns(table, pk_only)
+    }
+
+    # Create a unique name for the interface
+    name = f"{table.name}-{mode.title()}"
+    if pk_only:
+        name += '-PK'
+
+    return create_model(name, __config__={'arbitrary_types_allowed': True}, **fields)