fastapi-refine 0.1.0__py3-none-any.whl

fastapi_refine/__init__.py

@@ -0,0 +1,22 @@
+"""fastapi-refine: FastAPI integration for Refine simple-rest data provider."""
+
+__version__ = "0.1.0"
+
+from fastapi_refine.core import FilterConfig, FilterField, PaginationConfig, SortConfig
+from fastapi_refine.dependencies import RefineQuery, RefineResponse, refine_query, refine_response
+from fastapi_refine.hooks import HookContext, RefineHooks
+from fastapi_refine.routers import RefineCRUDRouter
+
+__all__ = [
+    "FilterConfig",
+    "FilterField",
+    "SortConfig",
+    "PaginationConfig",
+    "RefineQuery",
+    "RefineResponse",
+    "refine_query",
+    "refine_response",
+    "HookContext",
+    "RefineHooks",
+    "RefineCRUDRouter",
+]

fastapi_refine/core/__init__.py

@@ -0,0 +1,27 @@
+"""Core modules for fastapi-refine."""
+
+from fastapi_refine.core.query import (
+    parse_bool,
+    parse_filters,
+    parse_sorters,
+    parse_uuid,
+    resolve_pagination,
+)
+from fastapi_refine.core.types import (
+    FilterConfig,
+    FilterField,
+    PaginationConfig,
+    SortConfig,
+)
+
+__all__ = [
+    "FilterConfig",
+    "FilterField",
+    "SortConfig",
+    "PaginationConfig",
+    "parse_bool",
+    "parse_filters",
+    "parse_sorters",
+    "parse_uuid",
+    "resolve_pagination",
+]

fastapi_refine/core/query.py

@@ -0,0 +1,187 @@
+"""Query parsing logic for Refine simple-rest conventions."""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any
+
+from sqlalchemy import ColumnElement, or_
+from starlette.datastructures import QueryParams
+
+__all__ = [
+    "parse_filters",
+    "parse_sorters",
+    "resolve_pagination",
+    "parse_bool",
+    "parse_uuid",
+]
+
+IGNORED_QUERY_KEYS = {"_start", "_end", "_sort", "_order", "id", "skip", "limit"}
+
+
+def parse_bool(value: str) -> bool:
+    """Parse boolean from string.
+
+    Supports: 1/0, true/false, t/f, yes/y, no/n (case-insensitive).
+    """
+    lowered = value.strip().lower()
+    if lowered in {"1", "true", "t", "yes", "y"}:
+        return True
+    if lowered in {"0", "false", "f", "no", "n"}:
+        return False
+    raise ValueError(f"Invalid boolean value: {value}")
+
+
+def parse_uuid(value: str) -> uuid.UUID:
+    """Parse UUID from string."""
+    return uuid.UUID(value)
+
+
+def split_filter_key(key: str) -> tuple[str, str]:
+    """Split filter key into field name and operator.
+
+    Examples:
+        "name" -> ("name", "eq")
+        "age_gte" -> ("age", "gte")
+        "title_like" -> ("title", "like")
+    """
+    for suffix in ("_ne", "_gte", "_lte", "_like"):
+        if key.endswith(suffix):
+            return key[: -len(suffix)], suffix[1:]
+    return key, "eq"
+
+
+def parse_filters(
+    query_params: QueryParams,
+    *,
+    filter_fields: dict[str, Any],
+    search_fields: list[ColumnElement[Any]] | None = None,
+) -> list[ColumnElement[Any]]:
+    """Parse Refine simple-rest filters from query parameters.
+
+    Supports json-server style operators:
+    - eq (default): field=value
+    - ne: field_ne=value
+    - gte: field_gte=value
+    - lte: field_lte=value
+    - like: field_like=value (contains match)
+
+    Also supports full-text search via q parameter.
+
+    Args:
+        query_params: FastAPI/Starlette query parameters
+        filter_fields: Mapping of field names to FilterField configs
+        search_fields: Columns to search for q parameter
+
+    Returns:
+        List of SQLAlchemy conditions
+    """
+    conditions: list[ColumnElement[Any]] = []
+
+    for key, value in query_params.multi_items():
+        if key in IGNORED_QUERY_KEYS:
+            continue
+
+        # Full-text search
+        if key == "q":
+            if search_fields:
+                pattern = f"%{value}%"
+                conditions.append(
+                    or_(*(field.ilike(pattern) for field in search_fields))
+                )
+            continue
+
+        # Field filters
+        field, op = split_filter_key(key)
+        field_spec = filter_fields.get(field)
+        if not field_spec:
+            continue
+
+        try:
+            typed_value = field_spec.cast(value)
+        except (TypeError, ValueError):
+            continue
+
+        column = field_spec.column
+        if op == "eq":
+            conditions.append(column == typed_value)
+        elif op == "ne":
+            conditions.append(column != typed_value)
+        elif op == "gte":
+            conditions.append(column >= typed_value)
+        elif op == "lte":
+            conditions.append(column <= typed_value)
+        elif op == "like":
+            if isinstance(typed_value, str):
+                conditions.append(column.ilike(f"%{value}%"))
+        else:
+            conditions.append(column == typed_value)
+
+    return conditions
+
+
+def parse_sorters(
+    _sort: str | None,
+    _order: str | None,
+    *,
+    sort_fields: dict[str, ColumnElement[Any]],
+) -> list[ColumnElement[Any]]:
+    """Parse Refine simple-rest sorters from query parameters.
+
+    Supports comma-separated fields and orders:
+    _sort=title,createdAt&_order=asc,desc
+
+    Args:
+        _sort: Comma-separated field names to sort by
+        _order: Comma-separated order directions (asc/desc)
+        sort_fields: Mapping of field names to SQLAlchemy columns
+
+    Returns:
+        List of SQLAlchemy order by clauses
+    """
+    if not _sort:
+        return []
+
+    sort_fields_list = [field.strip() for field in _sort.split(",") if field.strip()]
+    order_list = (
+        [order.strip().lower() for order in _order.split(",")] if _order else []
+    )
+
+    order_by: list[ColumnElement[Any]] = []
+    for index, field in enumerate(sort_fields_list):
+        column = sort_fields.get(field)
+        if not column:
+            continue
+
+        order = order_list[index] if index < len(order_list) else "asc"
+        order_by.append(column.desc() if order == "desc" else column.asc())
+
+    return order_by
+
+
+def resolve_pagination(
+    *,
+    _start: int | None,
+    _end: int | None,
+    skip: int,
+    limit: int,
+) -> tuple[int, int]:
+    """Resolve pagination from Refine simple-rest parameters.
+
+    Supports both range-based (_start, _end) and offset-based (skip, limit) pagination.
+
+    Args:
+        _start: Range start (0-based, inclusive)
+        _end: Range end (0-based, exclusive)
+        skip: Offset for skip/limit pagination
+        limit: Maximum number of items to return
+
+    Returns:
+        Tuple of (offset, limit) for SQLAlchemy queries
+    """
+    if _start is None and _end is None:
+        return skip, limit
+
+    start = _start or 0
+    end = _end if _end is not None else start + limit
+    return start, max(0, end - start)

fastapi_refine/core/types.py

@@ -0,0 +1,63 @@
+"""Core type definitions for fastapi-refine."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from sqlalchemy import ColumnElement
+
+__all__ = ["FilterField", "FilterConfig", "SortConfig", "PaginationConfig"]
+
+
+@dataclass(frozen=True)
+class FilterField:
+    """Field filter configuration.
+
+    Args:
+        column: SQLAlchemy column reference
+        cast: Type converter function (str -> target type)
+    """
+
+    column: ColumnElement[Any]
+    cast: Callable[[str], Any]
+
+
+@dataclass
+class FilterConfig:
+    """Filter configuration.
+
+    Args:
+        fields: Mapping of field names to FilterField configs
+        search_fields: List of columns for full-text search (q parameter)
+    """
+
+    fields: dict[str, FilterField]
+    search_fields: list[ColumnElement[Any]] | None = None
+
+
+@dataclass
+class SortConfig:
+    """Sort configuration.
+
+    Args:
+        fields: Mapping of field names to SQLAlchemy columns
+    """
+
+    fields: dict[str, ColumnElement[Any]]
+
+
+@dataclass
+class PaginationConfig:
+    """Pagination configuration.
+
+    Args:
+        default_skip: Default offset for skip pagination
+        default_limit: Default limit for skip/limit pagination
+        max_limit: Maximum allowed limit (prevents excessive queries)
+    """
+
+    default_skip: int = 0
+    default_limit: int = 100
+    max_limit: int = 1000

fastapi_refine/dependencies/__init__.py

@@ -0,0 +1,6 @@
+"""Dependency injection modules for fastapi-refine."""
+
+from fastapi_refine.dependencies.query import RefineQuery, refine_query
+from fastapi_refine.dependencies.response import RefineResponse, refine_response
+
+__all__ = ["RefineQuery", "RefineResponse", "refine_query", "refine_response"]

fastapi_refine/dependencies/query.py

@@ -0,0 +1,156 @@
+"""Dependency injection for Refine query parsing."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import Query, Request
+from sqlalchemy import ColumnElement
+from sqlmodel import SQLModel
+
+from fastapi_refine.core import FilterConfig, PaginationConfig, SortConfig
+from fastapi_refine.core.query import (
+    parse_filters,
+    parse_sorters,
+    resolve_pagination,
+)
+
+__all__ = ["RefineQuery", "refine_query"]
+
+
+class RefineQuery:
+    """Refine query parameters parsed from request.
+
+    This class provides convenient access to parsed query parameters
+    following Refine simple-rest conventions.
+
+    Attributes:
+        model: The SQLModel class for this resource
+        conditions: List of SQLAlchemy filter conditions
+        order_by: List of SQLAlchemy order by clauses
+        offset: Query offset for pagination
+        limit: Query limit for pagination
+    """
+
+    def __init__(
+        self,
+        model: type[SQLModel],
+        filter_config: FilterConfig,
+        sort_config: SortConfig,
+        pagination_config: PaginationConfig | None = None,
+        *,
+        _start: int | None = None,
+        _end: int | None = None,
+        _sort: str | None = None,
+        _order: str | None = None,
+        skip: int = 0,
+        limit: int = 100,
+        request: Request | None = None,
+    ):
+        self.model = model
+        self.filter_config = filter_config
+        self.sort_config = sort_config
+        self.pagination_config = pagination_config or PaginationConfig()
+
+        # Parse filters
+        if request:
+            self.conditions = parse_filters(
+                request.query_params,
+                filter_fields=filter_config.fields,
+                search_fields=filter_config.search_fields,
+            )
+        else:
+            self.conditions = []
+
+        # Parse sorters
+        self.order_by = parse_sorters(_sort, _order, sort_fields=sort_config.fields)
+
+        # Parse pagination
+        self.offset, self.limit = resolve_pagination(
+            _start=_start,
+            _end=_end,
+            skip=skip,
+            limit=min(limit, self.pagination_config.max_limit),
+        )
+
+    def get_count(
+        self, session: Any, conditions: list[ColumnElement[Any]] | None = None
+    ) -> int:
+        """Get total count of records matching conditions.
+
+        Args:
+            session: SQLAlchemy/SQLModel session
+            conditions: Optional list of conditions (uses self.conditions if None)
+
+        Returns:
+            Total count of matching records
+        """
+        from sqlalchemy import func, select
+
+        conditions = conditions if conditions is not None else self.conditions
+
+        count_statement = select(func.count()).select_from(self.model)
+        if conditions:
+            count_statement = count_statement.where(*conditions)
+
+        return session.scalar(count_statement) or 0
+
+
+def refine_query(
+    model: type[SQLModel],
+    filter_config: FilterConfig,
+    sort_config: SortConfig,
+    pagination_config: PaginationConfig | None = None,
+) -> type[RefineQuery]:
+    """Create a RefineQuery dependency.
+
+    Use this function with FastAPI's Depends:
+
+    ```python
+    query_dep = refine_query(Item, filter_config, sort_config)
+
+    @router.get("/")
+    def read_items(
+        query: RefineQuery = Depends(query_dep),
+        ...
+    ):
+        conditions = query.conditions
+        order_by = query.order_by
+        offset, limit = query.offset, query.limit
+        ...
+    ```
+
+    Args:
+        model: SQLModel class
+        filter_config: Filter configuration
+        sort_config: Sort configuration
+        pagination_config: Optional pagination configuration
+
+    Returns:
+        A callable that can be used with FastAPI's Depends
+    """
+
+    def dependency(
+        request: Request,
+        _start: int | None = Query(None, alias="_start"),
+        _end: int | None = Query(None, alias="_end"),
+        _sort: str | None = Query(None, alias="_sort"),
+        _order: str | None = Query(None, alias="_order"),
+        skip: int = 0,
+        limit: int = 100,
+    ) -> RefineQuery:
+        return RefineQuery(
+            model=model,
+            filter_config=filter_config,
+            sort_config=sort_config,
+            pagination_config=pagination_config,
+            _start=_start,
+            _end=_end,
+            _sort=_sort,
+            _order=_order,
+            skip=skip,
+            limit=limit,
+            request=request,
+        )
+
+    return dependency  # type: ignore[return-value]

fastapi_refine/dependencies/response.py

@@ -0,0 +1,51 @@
+"""Response handling for Refine simple-rest conventions."""
+
+from __future__ import annotations
+
+from fastapi import Response
+
+__all__ = ["RefineResponse", "refine_response"]
+
+
+class _RefineResponseHelper:
+    """Helper for setting Refine-specific response headers.
+
+    Refine's simple-rest data provider expects an x-total-count header
+    for list responses to support server-side pagination.
+    """
+
+    def __init__(self, response: Response):
+        self._response = response
+
+    def set_total_count(self, count: int) -> None:
+        """Set the x-total-count header.
+
+        Args:
+            count: Total number of records (for pagination)
+        """
+        self._response.headers["x-total-count"] = str(count)
+
+
+# Type alias for backwards compatibility
+RefineResponse = _RefineResponseHelper
+
+
+def refine_response() -> _RefineResponseHelper:
+    """Dependency that creates a RefineResponse helper.
+
+    Usage:
+        ```python
+        @router.get("/")
+        def read_items(
+            response: RefineResponse = Depends(refine_response),
+            ...
+        ):
+            response.set_total_count(100)
+            return items
+        ```
+    """
+
+    def dependency(resp: Response) -> _RefineResponseHelper:
+        return _RefineResponseHelper(resp)
+
+    return dependency  # type: ignore[return-value]

fastapi_refine/hooks/__init__.py

@@ -0,0 +1,6 @@
+"""Hook system for customizing CRUD behavior."""
+
+from fastapi_refine.hooks.base import HookContext, RefineHooks
+from fastapi_refine.hooks.builtin import OwnerBasedHooks
+
+__all__ = ["HookContext", "RefineHooks", "OwnerBasedHooks"]

fastapi_refine/hooks/base.py

@@ -0,0 +1,78 @@
+"""Hook system for customizing CRUD behavior."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Any
+
+from sqlalchemy import ColumnElement
+from sqlmodel import SQLModel
+
+__all__ = ["RefineHooks", "HookContext"]
+
+
+# Hook type aliases
+BeforeQueryHook = Callable[
+    ["HookContext", list[ColumnElement[Any]]],
+    list[ColumnElement[Any]] | Awaitable[list[ColumnElement[Any]]],
+]
+
+AfterQueryHook = Callable[
+    ["HookContext", list[Any]],
+    list[Any] | Awaitable[list[Any]],
+]
+
+BeforeMutationHook = Callable[
+    ["HookContext", Any],
+    None | Awaitable[None],
+]
+
+AfterMutationHook = Callable[
+    ["HookContext", Any, Any],
+    Any | Awaitable[Any],
+]
+
+
+@dataclass
+class HookContext:
+    """Context passed to hooks during execution.
+
+    Attributes:
+        model: The SQLModel class being operated on
+        session: Database session
+        current_user: Currently authenticated user (if available)
+        request: Current FastAPI request (if available)
+    """
+
+    model: type[SQLModel]
+    session: Any
+    current_user: Any | None = None
+    request: Any | None = None
+
+
+@dataclass
+class RefineHooks:
+    """Collection of lifecycle hooks for CRUD operations.
+
+    All hooks are optional. Define only the ones you need.
+
+    Attributes:
+        before_query: Called before query execution, can modify conditions
+        after_query: Called after query execution, can modify results
+        before_create: Called before creating a record, can raise for permission check
+        after_create: Called after creating a record, can modify the result
+        before_update: Called before updating a record, can raise for permission check
+        after_update: Called after updating a record, can modify the result
+        before_delete: Called before deleting a record, can raise for permission check
+        after_delete: Called after deleting a record
+    """
+
+    before_query: BeforeQueryHook | None = None
+    after_query: AfterQueryHook | None = None
+    before_create: BeforeMutationHook | None = None
+    after_create: AfterMutationHook | None = None
+    before_update: BeforeMutationHook | None = None
+    after_update: AfterMutationHook | None = None
+    before_delete: BeforeMutationHook | None = None
+    after_delete: AfterMutationHook | None = None

fastapi_refine/hooks/builtin.py

@@ -0,0 +1,93 @@
+"""Built-in hook implementations for common use cases."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import HTTPException, status
+from sqlalchemy import ColumnElement
+
+from fastapi_refine.hooks.base import HookContext, RefineHooks
+
+__all__ = ["OwnerBasedHooks"]
+
+
+class OwnerBasedHooks(RefineHooks):
+    """Hooks for owner-based permission control.
+
+    Ensures users can only access records they own, unless they are superusers.
+
+    Example:
+        ```python
+        hooks = OwnerBasedHooks(
+            owner_field="owner_id",
+            allow_superuser=True,
+        )
+        ```
+    """
+
+    def __init__(
+        self,
+        owner_field: str = "owner_id",
+        allow_superuser: bool = True,
+    ):
+        """Initialize owner-based hooks.
+
+        Args:
+            owner_field: Name of the field containing the owner's user ID
+            allow_superuser: Whether to allow superusers to access all records
+        """
+        self.owner_field = owner_field
+        self.allow_superuser = allow_superuser
+        super().__init__(
+            before_query=self._before_query,
+            before_update=self._before_mutation,
+            before_delete=self._before_mutation,
+        )
+
+    def _before_query(
+        self,
+        context: HookContext,
+        conditions: list[ColumnElement[Any]],
+    ) -> list[ColumnElement[Any]]:
+        """Add owner filter to query conditions."""
+        if not context.current_user:
+            return conditions
+
+        if self.allow_superuser and getattr(
+            context.current_user, "is_superuser", False
+        ):
+            return conditions
+
+        user_id = getattr(context.current_user, "id", None)
+        if not user_id:
+            return conditions
+
+        # Add owner_id filter
+        model_class = context.model
+        owner_column = getattr(model_class, self.owner_field)
+        conditions.append(owner_column == user_id)
+
+        return conditions
+
+    def _before_mutation(self, context: HookContext, item: Any) -> None:
+        """Check if user has permission to modify/delete this item."""
+        if not context.current_user:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Authentication required",
+            )
+
+        if self.allow_superuser and getattr(
+            context.current_user, "is_superuser", False
+        ):
+            return
+
+        user_id = getattr(context.current_user, "id", None)
+        owner_id = getattr(item, self.owner_field, None)
+
+        if owner_id != user_id:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="Not enough permissions",
+            )

fastapi_refine/routers/__init__.py

@@ -0,0 +1,5 @@
+"""Router factory for generating Refine-compatible CRUD endpoints."""
+
+from fastapi_refine.routers.factory import RefineCRUDRouter
+
+__all__ = ["RefineCRUDRouter"]

fastapi_refine/routers/factory.py

@@ -0,0 +1,331 @@
+"""CRUD Router factory for generating standard Refine-compatible endpoints."""
+
+from __future__ import annotations
+
+from typing import Any, Generic, TypeVar
+
+from fastapi import APIRouter, HTTPException, Query, Response, status
+from sqlmodel import Session, SQLModel, select
+
+from fastapi_refine.core import FilterConfig, PaginationConfig, SortConfig
+from fastapi_refine.dependencies import RefineQuery, RefineResponse
+from fastapi_refine.hooks import HookContext, RefineHooks
+
+__all__ = ["RefineCRUDRouter"]
+
+ModelT = TypeVar("ModelT", bound=SQLModel)
+CreateSchemaT = TypeVar("CreateSchemaT", bound=SQLModel)
+UpdateSchemaT = TypeVar("UpdateSchemaT", bound=SQLModel)
+PublicSchemaT = TypeVar("PublicSchemaT", bound=SQLModel)
+
+
+class RefineCRUDRouter(Generic[ModelT, CreateSchemaT, UpdateSchemaT, PublicSchemaT]):
+    """Factory for generating Refine-compatible CRUD routers.
+
+    Automatically creates standard CRUD endpoints that follow Refine simple-rest conventions:
+    - GET /{resource}/ - List with pagination, sorting, filtering
+    - GET /{resource}/{id} - Get single item
+    - POST /{resource}/ - Create new item
+    - PATCH /{resource}/{id} - Update item
+    - DELETE /{resource}/{id} - Delete item
+
+    Example:
+        ```python
+        router = RefineCRUDRouter(
+            model=Item,
+            prefix="/items",
+            create_schema=ItemCreate,
+            update_schema=ItemUpdate,
+            public_schema=ItemPublic,
+            session_dep=SessionDep,
+            filter_config=filter_config,
+            sort_config=sort_config,
+            current_user_dep=CurrentUser,
+            hooks=OwnerBasedHooks(owner_field="owner_id"),
+        ).router
+        ```
+    """
+
+    def __init__(
+        self,
+        model: type[ModelT],
+        prefix: str,
+        create_schema: type[CreateSchemaT],
+        update_schema: type[UpdateSchemaT],
+        public_schema: type[PublicSchemaT],
+        session_dep: Any,
+        filter_config: FilterConfig,
+        sort_config: SortConfig,
+        pagination_config: PaginationConfig | None = None,
+        hooks: RefineHooks | None = None,
+        current_user_dep: Any | None = None,
+        tags: list[str] | None = None,
+    ):
+        """Initialize the CRUD router.
+
+        Args:
+            model: SQLModel database class
+            prefix: URL prefix for routes (e.g., "/items")
+            create_schema: Pydantic schema for creating items
+            update_schema: Pydantic schema for updating items
+            public_schema: Pydantic schema for API responses
+            session_dep: FastAPI dependency for database session
+            filter_config: Filter configuration
+            sort_config: Sort configuration
+            pagination_config: Optional pagination configuration
+            hooks: Optional lifecycle hooks
+            current_user_dep: Optional FastAPI dependency for current user
+            tags: OpenAPI tags for documentation
+        """
+        self.model = model
+        self.create_schema = create_schema
+        self.update_schema = update_schema
+        self.public_schema = public_schema
+        self.session_dep = session_dep
+        self.filter_config = filter_config
+        self.sort_config = sort_config
+        self.pagination_config = pagination_config or PaginationConfig()
+        self.hooks = hooks or RefineHooks()
+        self.current_user_dep = current_user_dep
+
+        self.router = APIRouter(prefix=prefix, tags=tags or [prefix.strip("/")])  # type: ignore[arg-type]
+        self._setup_routes()
+
+    def _setup_routes(self) -> None:
+        """Setup all CRUD routes."""
+        self.router.add_api_route(
+            "/",
+            self.get_list,
+            methods=["GET"],
+            response_model=list[self.public_schema],  # type: ignore[name-defined]
+        )
+        self.router.add_api_route(
+            "/{id}",
+            self.get_one,
+            methods=["GET"],
+            response_model=self.public_schema,
+        )
+        self.router.add_api_route(
+            "/",
+            self.create,
+            methods=["POST"],
+            response_model=self.public_schema,
+        )
+        self.router.add_api_route(
+            "/{id}",
+            self.update,
+            methods=["PATCH"],
+            response_model=self.public_schema,
+        )
+        self.router.add_api_route(
+            "/{id}",
+            self.delete,
+            methods=["DELETE"],
+        )
+
+    def get_list(
+        self,
+        request: Any,  # Request
+        response: Response,
+        session: Session,
+        skip: int = 0,
+        limit: int = 100,
+        _start: int | None = Query(None, alias="_start"),
+        _end: int | None = Query(None, alias="_end"),
+        _sort: str | None = Query(None, alias="_sort"),
+        _order: str | None = Query(None, alias="_order"),
+        id: list[Any] | None = Query(None),
+    ) -> list[Any]:
+        """Get list of items (Refine getList)."""
+        # Parse query
+        query = RefineQuery(
+            model=self.model,
+            filter_config=self.filter_config,
+            sort_config=self.sort_config,
+            pagination_config=self.pagination_config,
+            _start=_start,
+            _end=_end,
+            _sort=_sort,
+            _order=_order,
+            skip=skip,
+            limit=limit,
+            request=request,
+        )
+
+        conditions = query.conditions
+        if id:
+            conditions.append(self.model.id.in_(id))  # type: ignore[attr-defined]
+
+        # Execute before_query hook
+        if self.hooks.before_query:
+            current_user = self.current_user() if self.current_user_dep else None  # type: ignore[attr-defined]
+            context = HookContext(
+                model=self.model,
+                session=session,
+                current_user=current_user,
+                request=request,
+            )
+            conditions = self._run_hook(self.hooks.before_query, context, conditions)
+
+        # Get count
+        count = query.get_count(session, conditions)
+        refine_response = RefineResponse(response)
+        refine_response.set_total_count(count)
+
+        # Execute query
+        statement = select(self.model)
+        if conditions:
+            statement = statement.where(*conditions)
+        if query.order_by:
+            statement = statement.order_by(*query.order_by)
+
+        items = list(
+            session.exec(statement.offset(query.offset).limit(query.limit)).all()
+        )
+
+        # Execute after_query hook
+        if self.hooks.after_query:
+            current_user = self.current_user() if self.current_user_dep else None  # type: ignore[attr-defined]
+            context = HookContext(
+                model=self.model,
+                session=session,
+                current_user=current_user,
+                request=request,
+            )
+            items = self._run_hook(self.hooks.after_query, context, items)
+
+        return items
+
+    def get_one(self, id: Any, session: Session) -> Any:
+        """Get single item by ID (Refine getOne)."""
+        item = session.get(self.model, id)
+        if not item:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"{self.model.__name__} not found",
+            )
+        return item
+
+    def create(
+        self,
+        item_in: CreateSchemaT,
+        session: Session,
+    ) -> Any:
+        """Create new item (Refine create)."""
+        current_user = self.current_user_dep() if self.current_user_dep else None
+
+        # Execute before_create hook
+        if self.hooks.before_create:
+            context = HookContext(
+                model=self.model,
+                session=session,
+                current_user=current_user,
+            )
+            self._run_hook(self.hooks.before_create, context, item_in)
+
+        # Create item
+        item = self.model.model_validate(item_in)
+        session.add(item)
+        session.commit()
+        session.refresh(item)
+
+        # Execute after_create hook
+        if self.hooks.after_create:
+            context = HookContext(
+                model=self.model,
+                session=session,
+                current_user=current_user,
+            )
+            item = self._run_hook(self.hooks.after_create, context, item_in, item)
+
+        return item
+
+    def update(
+        self,
+        id: Any,
+        item_in: UpdateSchemaT,
+        session: Session,
+    ) -> Any:
+        """Update item (Refine update)."""
+        item = session.get(self.model, id)
+        if not item:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"{self.model.__name__} not found",
+            )
+
+        current_user = self.current_user_dep() if self.current_user_dep else None
+
+        # Execute before_update hook
+        if self.hooks.before_update:
+            context = HookContext(
+                model=self.model,
+                session=session,
+                current_user=current_user,
+            )
+            self._run_hook(self.hooks.before_update, context, item)
+
+        # Update item
+        update_data = item_in.model_dump(exclude_unset=True)
+        item.sqlmodel_update(update_data)
+        session.add(item)
+        session.commit()
+        session.refresh(item)
+
+        # Execute after_update hook
+        if self.hooks.after_update:
+            context = HookContext(
+                model=self.model,
+                session=session,
+                current_user=current_user,
+            )
+            item = self._run_hook(self.hooks.after_update, context, item, item)
+
+        return item
+
+    def delete(self, id: Any, session: Session) -> dict[str, str]:
+        """Delete item (Refine delete)."""
+        item = session.get(self.model, id)
+        if not item:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"{self.model.__name__} not found",
+            )
+
+        current_user = self.current_user_dep() if self.current_user_dep else None
+
+        # Execute before_delete hook
+        if self.hooks.before_delete:
+            context = HookContext(
+                model=self.model,
+                session=session,
+                current_user=current_user,
+            )
+            self._run_hook(self.hooks.before_delete, context, item)
+
+        # Delete item
+        session.delete(item)
+        session.commit()
+
+        # Execute after_delete hook
+        if self.hooks.after_delete:
+            context = HookContext(
+                model=self.model,
+                session=session,
+                current_user=current_user,
+            )
+            self._run_hook(self.hooks.after_delete, context, item)
+
+        return {"message": f"{self.model.__name__} deleted successfully"}
+
+    def _run_hook(self, hook: Any, *args: Any) -> Any:
+        """Run a hook, handling both sync and async hooks."""
+        import inspect
+
+        result = hook(*args)
+
+        if inspect.isawaitable(result):
+            # For now, we'll just return the awaitable as-is
+            # In a full async implementation, we'd await it here
+            return result
+        return result

fastapi_refine-0.1.0.dist-info/METADATA

@@ -0,0 +1,282 @@
+Metadata-Version: 2.4
+Name: fastapi-refine
+Version: 0.1.0
+Summary: FastAPI integration for Refine simple-rest data provider
+Project-URL: Homepage, https://github.com/koch3092/fastapi-refine
+Project-URL: Documentation, https://github.com/koch3092/fastapi-refine#readme
+Project-URL: Repository, https://github.com/koch3092/fastapi-refine
+Project-URL: Bug Tracker, https://github.com/koch3092/fastapi-refine/issues
+Author-email: koko <developer@dorakoch.com>
+License: MIT
+License-File: LICENSE
+Keywords: crud,fastapi,refine,rest,sqlalchemy,sqlmodel
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.114.2
+Requires-Dist: sqlmodel>=0.0.21
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8.0; extra == 'dev'
+Requires-Dist: pytest>=7.4.3; extra == 'dev'
+Requires-Dist: ruff>=0.2.2; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# fastapi-refine
+
+[![PyPI version](https://badge.fury.io/py/fastapi-refine.svg)](https://badge.fury.io/py/fastapi-refine)
+[![Python Versions](https://img.shields.io/pypi/pyversions/fastapi-refine.svg)](https://pypi.org/project/fastapi-refine/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+FastAPI integration for [Refine](https://refine.dev/) simple-rest data provider. Build type-safe, production-ready REST APIs that work seamlessly with Refine's data provider conventions.
+
+## Features
+
+- **Automatic Query Parsing**: Parse Refine's filter, sort, and pagination parameters out-of-the-box
+- **Type-Safe**: Full type hints and mypy strict mode compliance
+- **SQLModel Integration**: First-class support for SQLModel/SQLAlchemy ORM
+- **CRUD Router Factory**: Generate complete CRUD endpoints with one class
+- **Flexible Filtering**: Support for `eq`, `ne`, `gte`, `lte`, `like` operators and full-text search
+- **Hook System**: Inject custom logic before/after operations (permissions, validation, etc.)
+- **Production Ready**: Built with FastAPI best practices
+
+## Installation
+
+```bash
+pip install fastapi-refine
+```
+
+## Quick Start
+
+### Basic Usage with Manual Endpoints
+
+```python
+from typing import Annotated
+
+from fastapi import APIRouter, Depends
+from sqlmodel import Session, select
+from fastapi_refine import (
+    FilterConfig,
+    FilterField,
+    SortConfig,
+    RefineQuery,
+    RefineResponse,
+    refine_query,
+    refine_response,
+)
+from fastapi_refine.core import parse_bool
+
+from .models import Item, ItemPublic
+from .database import get_session
+
+router = APIRouter(prefix="/items", tags=["items"])
+
+SessionDep = Annotated[Session, Depends(get_session)]
+
+# Configure which fields can be filtered and sorted
+filter_config = FilterConfig(
+    fields={
+        "id": FilterField(Item.id, str),
+        "title": FilterField(Item.title, str),
+        "is_active": FilterField(Item.is_active, parse_bool),
+    },
+    search_fields=[Item.title, Item.description],  # Full-text search fields
+)
+
+sort_config = SortConfig(
+    fields={
+        "id": Item.id,
+        "title": Item.title,
+        "created_at": Item.created_at,
+    }
+)
+
+@router.get("/", response_model=list[ItemPublic])
+def read_items(
+    session: SessionDep,
+    refine_resp: Annotated[RefineResponse, Depends(refine_response())],
+    query: Annotated[RefineQuery, Depends(refine_query(Item, filter_config, sort_config))],
+) -> list[ItemPublic]:
+    # query.conditions contains parsed WHERE clauses
+    # query.order_by contains ORDER BY clauses
+    # query.offset and query.limit are ready for pagination
+
+    items = session.exec(
+        select(Item)
+        .where(*query.conditions)
+        .order_by(*query.order_by)
+        .offset(query.offset)
+        .limit(query.limit)
+    ).all()
+
+    # Set x-total-count header for Refine pagination
+    total = query.get_count(session, query.conditions)
+    refine_resp.set_total_count(total)
+
+    return items
+```
+
+### Automatic CRUD Router (Recommended)
+
+Generate all CRUD endpoints automatically:
+
+```python
+from fastapi import FastAPI
+from fastapi_refine import RefineCRUDRouter, FilterConfig, FilterField, SortConfig
+from fastapi_refine.core import parse_bool
+from .models import Item, ItemCreate, ItemUpdate, ItemPublic
+from .database import get_session
+
+app = FastAPI()
+
+# Create router with full CRUD operations
+crud_router = RefineCRUDRouter(
+    model=Item,
+    prefix="/items",
+    create_schema=ItemCreate,
+    update_schema=ItemUpdate,
+    public_schema=ItemPublic,
+    session_dep=get_session,
+    filter_config=FilterConfig(
+        fields={
+            "title": FilterField(Item.title, str),
+            "is_active": FilterField(Item.is_active, parse_bool),
+        },
+        search_fields=[Item.title],
+    ),
+    sort_config=SortConfig(
+        fields={"title": Item.title, "created_at": Item.created_at}
+    ),
+    tags=["items"],
+)
+
+app.include_router(crud_router.router)
+```
+
+This automatically creates:
+- `GET /items/` - List with filtering, sorting, pagination
+- `GET /items/{id}` - Get single item
+- `POST /items/` - Create item
+- `PATCH /items/{id}` - Update item
+- `DELETE /items/{id}` - Delete item
+
+## Advanced Usage
+
+### Custom Hooks for Permissions
+
+```python
+from fastapi import Depends, HTTPException
+from fastapi_refine import RefineHooks, HookContext, RefineCRUDRouter
+
+def before_query(context: HookContext, conditions: list) -> list:
+    """Filter items to only show user's own items"""
+    if context.current_user:
+        conditions.append(context.model.owner_id == context.current_user.id)
+    return conditions
+
+def before_delete(context: HookContext, item) -> None:
+    """Only allow deleting own items"""
+    if item.owner_id != context.current_user.id:
+        raise HTTPException(status_code=403, detail="Not authorized")
+
+hooks = RefineHooks(
+    before_query=before_query,
+    before_delete=before_delete,
+)
+
+crud_router = RefineCRUDRouter(
+    model=Item,
+    hooks=hooks,
+    current_user_dep=get_current_user,
+    # ... other config
+)
+```
+
+### Pagination Configuration
+
+```python
+from fastapi_refine import PaginationConfig, RefineCRUDRouter
+
+pagination_config = PaginationConfig(
+    default_skip=0,
+    default_limit=50,
+    max_limit=500,  # Prevent excessive queries
+)
+
+crud_router = RefineCRUDRouter(
+    pagination_config=pagination_config,
+    # ... other config
+)
+```
+
+## Supported Query Parameters
+
+The library parses Refine simple-rest query parameters:
+
+### Filtering
+- `field=value` - Exact match (eq)
+- `field_ne=value` - Not equal
+- `field_gte=value` - Greater than or equal
+- `field_lte=value` - Less than or equal
+- `field_like=value` - Contains (case-insensitive)
+- `q=search` - Full-text search across configured fields
+
+### Sorting
+- `_sort=field1,field2` - Sort by multiple fields
+- `_order=asc,desc` - Sort order for each field
+
+### Pagination
+- Range-based: `_start=0&_end=20`
+- Offset-based: `skip=0&limit=20`
+
+### Example Query
+```
+GET /items?title_like=hello&is_active=true&_sort=created_at&_order=desc&_start=0&_end=10
+```
+
+## Type Converters
+
+Built-in converters for common types:
+
+```python
+from fastapi_refine import FilterConfig, FilterField
+from fastapi_refine.core import parse_bool, parse_uuid
+
+filter_config = FilterConfig(
+    fields={
+        "id": FilterField(Item.id, parse_uuid),
+        "is_active": FilterField(Item.is_active, parse_bool),
+        "price": FilterField(Item.price, float),
+        "quantity": FilterField(Item.quantity, int),
+    }
+)
+```
+
+## Requirements
+
+- Python 3.10+
+- FastAPI 0.114.2+
+- SQLModel 0.0.21+
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Links
+
+- [Refine Documentation](https://refine.dev/docs/)
+- [FastAPI Documentation](https://fastapi.tiangolo.com/)
+- [SQLModel Documentation](https://sqlmodel.tiangolo.com/)

fastapi_refine-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+fastapi_refine/__init__.py,sha256=jB3ePqiyivSvboP6Oiwyu-Y0DJzfTe_Pkz48pnFwBfI,643
+fastapi_refine/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fastapi_refine/core/__init__.py,sha256=4WeRIBcgUjNDjtO6UCiA5pD6wu1o-X1RokfOqahlrw0,491
+fastapi_refine/core/query.py,sha256=x0poTtwpiT06a2aHqHLjM3BPpgK_QNafb4HxdEWG6gA,5242
+fastapi_refine/core/types.py,sha256=hO_x5rRIs5FQt3LaQcvWLezyzNTXHOMDFGUxEzEIaEY,1412
+fastapi_refine/dependencies/__init__.py,sha256=G0Ls3DmmqmOW-gcruNdskP1uZHsj_8c-aXQrazA1Zqk,289
+fastapi_refine/dependencies/query.py,sha256=mAGCICC2sxMXwX7vtzRT05nrPq4tenEoWGRZ2PHd7Qs,4528
+fastapi_refine/dependencies/response.py,sha256=1r_DgSSHK8FqKe0vB8OTUqST1m8k3YV35YTkRZzQbY0,1328
+fastapi_refine/hooks/__init__.py,sha256=NMw5nZ2rTZeantO51rbIHhHBcmo3zuhyRnSoic1BtV4,231
+fastapi_refine/hooks/base.py,sha256=mv_OaRIUYSq-wu5vcNeayb-51yGomRQSowayrEdTGf0,2358
+fastapi_refine/hooks/builtin.py,sha256=NsNnITbg_qQN9-vuLpcvXPCLY9yFrb3rGZ-uuhRMG30,2733
+fastapi_refine/routers/__init__.py,sha256=N4bnZXJjpJRpP-sS-aBXV-EwOBod3rStoMhycZ_HvLg,163
+fastapi_refine/routers/factory.py,sha256=RUiP_MkZbv6vo8q3xDUlpH_9eNq55Nsplfu60kCFMsU,11182
+fastapi_refine/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fastapi_refine-0.1.0.dist-info/METADATA,sha256=60CpkMAOG1qgo1wULyHbvSYyum1ha15JmcKZBfgrl8g,8320
+fastapi_refine-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+fastapi_refine-0.1.0.dist-info/licenses/LICENSE,sha256=fmW7UZeYMMP-iK31FXjWS3ZXQMpIlAYIdtohot23Fqo,1061
+fastapi_refine-0.1.0.dist-info/RECORD,,

fastapi_refine-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

fastapi_refine-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 koko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.