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

auto_rest/handlers.py

@@ -51,16 +51,15 @@ This makes it easy to incorporate handlers into 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 .interfaces import *
 from .models import *
-from .params import *
 from .queries import *
 
 __all__ = [
@@ -192,21 +191,30 @@ def create_list_records_handler(engine: DBEngine, table: Table) -> Callable[...,
     """
 
     interface = create_interface(table)
+    interface_opt = create_interface(table, mode="optional")
+    columns = 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),
+        _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[*columns]] = 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.
 
         URL query parameters are used to enable filtering, ordering, and paginating returned values.
         """
 
+        response.headers["X-Pagination-Limit"] = str(_limit_)
+        response.headers["X-Pagination-Offset"] = str(_offset_)
+        response.headers["X-Order-By"] = str(_order_by_)
+        response.headers["X-Order-Direction"] = str(_direction_)
+
         query = select(table)
-        query = apply_pagination_params(query, pagination_params, response)
-        query = apply_ordering_params(query, ordering_params, response)
+        query = apply_pagination_params(query, _limit_, _offset_)
+        query = apply_ordering_params(query, _order_by_, _direction_)
 
         result = await execute_session_query(session, query)
         return [row._mapping for row in result.all()]

auto_rest/interfaces.py

@@ -10,21 +10,20 @@ which force interface fields to be optional or read only.
     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")
+    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 Iterator, Literal
+
+from typing import Any, 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"]
+MODE_TYPE = Literal["default", "required", "optional"]
 
 
 def iter_columns(table: Table, pk_only: bool = False) -> Iterator[Column]:
@@ -38,69 +37,62 @@ def iter_columns(table: Table, pk_only: bool = False) -> Iterator[Column]:
         A column of the SQLAlchemy model.
     """
 
-    for column in table.columns:
+    for column in table.columns.values():
         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.
+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.
 
-    Returns:
-        The equivalent Python type for the column data.
-    """
-
-    try:
-        return col.type.python_type
+    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.
 
-    # 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.
+    Modes:
+        default: Values are marked as (not)required based on the column schema.
+        required: Values are always marked required.
+        required: Values are always marked optional.
 
     Args:
-        col: The column to determine a default value for.
+        col: The column to return values 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
+    try:
+        col_type = col.type.python_type
+
+    except NotImplementedError:
+        col_type = Any
+
+    col_default = getattr(col.default, "arg", col.default)
 
     if mode == "required":
-        return ...
+        return col_type, ...
 
     elif mode == "optional":
-        return default
+        return col_type | None, col_default
 
-    elif mode == "default":
-        if col.nullable or (col.default is not None):
-            return default
+    elif mode == "default" and (col.nullable or col.default):
+        return col_type | None, col_default
 
-        return ...
+    elif mode == "default":
+        return col_type, ...
 
     raise RuntimeError(f"Unknown mode: {mode}")
 
 
-def create_interface(
-    table: Table,
-    pk_only: bool = False,
-    mode: MODES = "default"
-) -> type[PydanticModel]:
+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.
+        required: Values are always marked optional.
+
     Args:
         table: The SQLAlchemy table to create an interface for.
         pk_only: If True, only include primary key columns.
@@ -111,16 +103,13 @@ def create_interface(
     """
 
     # 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
+        col.name: create_field_definition(col, mode) for col in iter_columns(table, pk_only)
     }
 
-    # Dynamically create a unique name for the interface
-    name_parts = [table.name, mode.title()]
+    # Create a unique name for the interface
+    name = f"{table.name}-{mode.title()}"
     if pk_only:
-        name_parts.insert(1, 'PK')
+        name += '-PK'
 
-    interface_name = '-'.join(name_parts)
-    return create_model(interface_name, **fields)
+    return create_model(name, __config__={'arbitrary_types_allowed': True}, **fields)

auto_rest/queries.py

@@ -19,15 +19,18 @@ handling and provides a streamlined interface for database interactions.
         result = await execute_session_query(async_session, query)
     ```
 """
+from typing import Literal
 
 from fastapi import HTTPException
-from sqlalchemy import Executable, Result
+from sqlalchemy import asc, desc, Executable, Result, Select
 from sqlalchemy.ext.asyncio import AsyncSession
 from starlette import status
 
 from auto_rest.models import DBSession
 
 __all__ = [
+    "apply_ordering_params",
+    "apply_pagination_params",
     "commit_session",
     "delete_session_record",
     "execute_session_query",
@@ -35,6 +38,64 @@ __all__ = [
 ]
 
 
+def apply_ordering_params(
+    query: Select,
+    order_by: str | None = None,
+    direction: Literal["desc", "asc"] = "asc"
+) -> Select:
+    """Apply ordering to a database query.
+
+    Returns a copy of the provided query with ordering parameters applied.
+
+    Args:
+        query: The database query to apply parameters to.
+        order_by: The name of the column to order by.
+        direction: The direction to order by (defaults to "asc").
+
+    Returns:
+        A copy of the query modified to return ordered values.
+    """
+
+    if order_by is None:
+        return query
+
+    if order_by not in query.columns:
+        raise ValueError(f"Invalid column name: {order_by}")
+
+    # Default to ascending order for an invalid ordering direction
+    if direction == "desc":
+        return query.order_by(desc(order_by))
+
+    elif direction == "asc":
+        return query.order_by(asc(order_by))
+
+    raise ValueError(f"Invalid direction, use 'asc' or 'desc': {direction}")
+
+
+def apply_pagination_params(query: Select, limit: int = 0, offset: int = 0) -> Select:
+    """Apply pagination to a database query.
+
+    Returns a copy of the provided query with offset and limit parameters applied.
+
+    Args:
+        query: The database query to apply parameters to.
+        limit: The number of results to return.
+        offset: The offset to start with.
+
+    Returns:
+        A copy of the query modified to only return the paginated values.
+    """
+
+    if offset < 0 or limit < 0:
+        raise ValueError("Pagination parameters cannot be negative")
+
+    # Do not apply pagination if not requested
+    if limit == 0:
+        return query
+
+    return query.offset(offset or 0).limit(limit)
+
+
 async def commit_session(session: DBSession) -> None:
     """Commit a SQLAlchemy session.
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: auto-rest-api
-Version: 0.1.2
+Version: 0.1.3
 Summary: Automatically map database schemas and deploy per-table REST API endpoints.
 License: GPL-3.0-only
 Keywords: Better,HPC,automatic,rest,api

auto_rest_api-0.1.3.dist-info/RECORD

@@ -0,0 +1,14 @@
+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=Z8DMv3KRYLBXlUKoE4e-2qE9YvG-IPgS57C0RpUDWv4,12603
+auto_rest/interfaces.py,sha256=WB_0eMDjGF8DpnDN9INHqo7u4x3aklvzAYK4t3JwC7s,3779
+auto_rest/models.py,sha256=HCJUQPBmkkfVFv9CRcPzMP66pQk_UIb3j3cdwHqodwE,5388
+auto_rest/queries.py,sha256=Z2ATkcSYldV6BkcrmLogmBoDkPEkyFzFqI7qPcq86uc,4705
+auto_rest/routers.py,sha256=RqBwLqVFU1OIFSCUuwOtTis8mT_zyWTaB_8SyIXjfe0,5727
+auto_rest_api-0.1.3.dist-info/LICENSE.md,sha256=zFRw_u1mGSOH8GrpOu0L1P765aX9fB5UpKz06mTxAos,34893
+auto_rest_api-0.1.3.dist-info/METADATA,sha256=Cs7u-2jZGTTlvBprPzdLVWl1uSAAjjLgeh5PuHo3tUk,2951
+auto_rest_api-0.1.3.dist-info/WHEEL,sha256=IYZQI976HJqqOpQU6PHkJ8fb3tMNBFjg-Cn-pwAbaFM,88
+auto_rest_api-0.1.3.dist-info/entry_points.txt,sha256=zFynmBrHyYo3Ds0Uo4-bTFe1Tdr5mIXV4dPQOFb-W1w,53
+auto_rest_api-0.1.3.dist-info/RECORD,,

auto_rest/params.py

@@ -1,174 +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 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, Optional
-
-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",
-    "create_ordering_dependency",
-    "create_pagination_dependency",
-]
-
-
-def create_ordering_dependency(table: Table) -> Callable[..., dict]:
-    """Create an injectable dependency for fetching ordering arguments from query parameters.
-
-    Args:
-        table: The database table to create the dependency for.
-
-    Returns:
-        An injectable FastAPI dependency.
-    """
-
-    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.
-
-        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(table: Table) -> Callable[..., dict]:
-    """Create an injectable dependency for fetching pagination arguments from query parameters.
-
-    Args:
-        table: The database table to create the dependency for.
-
-    Returns:
-        An injectable FastAPI dependency.
-    """
-
-    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.
-
-        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.2.dist-info/RECORD

@@ -1,15 +0,0 @@
-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,,