sqlmodel-object-helpers 0.0.1__py3-none-any.whl

sqlmodel_object_helpers/__init__.py

@@ -0,0 +1,97 @@
+"""sqlmodel-object-helpers — reusable query helpers for SQLModel projects."""
+
+__version__ = "0.0.1"
+
+from .constants import QueryHelperSettings, settings
+from .exceptions import (
+    DatabaseError,
+    InvalidFilterError,
+    InvalidLoadPathError,
+    MutationError,
+    ObjectNotFoundError,
+    QueryError,
+)
+from .filters import build_filter, build_flat_filter, flatten_filters
+from .loaders import build_load_chain, build_load_options
+from .operators import SPECIAL_OPERATORS, SUPPORTED_OPERATORS, Operator
+from .mutations import (
+    add_object,
+    add_objects,
+    check_for_related_records,
+    delete_object,
+    update_object,
+)
+from .query import get_object, get_objects, get_projection
+from .session import create_session_dependency
+from .types.filters import (
+    FilterBool,
+    FilterDate,
+    FilterDatetime,
+    FilterExists,
+    FilterInt,
+    FilterStr,
+    FilterTimedelta,
+    LogicalFilter,
+    OrderAsc,
+    OrderBy,
+    OrderDesc,
+)
+from .types.pagination import (
+    GetAllPagination,
+    Pagination,
+    PaginationR,
+)
+from .types.projections import ColumnSpec
+
+__all__ = [
+    # Settings
+    "settings",
+    "QueryHelperSettings",
+    # Query functions (read)
+    "get_object",
+    "get_objects",
+    "get_projection",
+    # Mutation functions (create / update / delete)
+    "add_object",
+    "add_objects",
+    "update_object",
+    "delete_object",
+    "check_for_related_records",
+    # Filters
+    "build_filter",
+    "build_flat_filter",
+    "flatten_filters",
+    "SUPPORTED_OPERATORS",
+    "SPECIAL_OPERATORS",
+    "Operator",
+    # Loaders
+    "build_load_options",
+    "build_load_chain",
+    # Exceptions
+    "QueryError",
+    "ObjectNotFoundError",
+    "InvalidFilterError",
+    "InvalidLoadPathError",
+    "DatabaseError",
+    "MutationError",
+    # Filter types
+    "FilterInt",
+    "FilterStr",
+    "FilterDate",
+    "FilterDatetime",
+    "FilterTimedelta",
+    "FilterBool",
+    "FilterExists",
+    "OrderAsc",
+    "OrderDesc",
+    "OrderBy",
+    "LogicalFilter",
+    # Pagination types
+    "Pagination",
+    "PaginationR",
+    "GetAllPagination",
+    # Projection types
+    "ColumnSpec",
+    # Session
+    "create_session_dependency",
+]

sqlmodel_object_helpers/constants.py

@@ -0,0 +1,34 @@
+"""Security and performance limits for query building.
+
+All values have sensible defaults. Override at application startup:
+
+    from sqlmodel_object_helpers import settings
+    settings.max_per_page = 300
+    settings.max_filter_depth = 50
+"""
+
+from pydantic import BaseModel
+
+
+class QueryHelperSettings(BaseModel):
+    """Mutable settings for query-helper limits.
+
+    Attributes:
+        max_filter_depth: Maximum recursion depth for build_filter (AND/OR nesting).
+            Each depth level ≈ 3 Python call frames, so 100 depth ≈ 300 frames
+            (safe under Python's default recursion limit of 1000).
+        max_and_or_items: Maximum number of sub-filters in a single AND/OR list.
+        max_load_depth: Maximum depth of eager-loading chains
+            (e.g. "application.applicant.educations" = 3).
+        max_in_list_size: Maximum number of elements in an IN(...) list.
+        max_per_page: Maximum value for per_page in pagination.
+    """
+
+    max_filter_depth: int = 100
+    max_and_or_items: int = 100
+    max_load_depth: int = 10
+    max_in_list_size: int = 1000
+    max_per_page: int = 500
+
+
+settings = QueryHelperSettings()

sqlmodel_object_helpers/exceptions.py

@@ -0,0 +1,52 @@
+from http import HTTPStatus
+
+
+class QueryError(Exception):
+    """Base exception for all library errors."""
+
+    def __init__(self, message: str, status_code: int = HTTPStatus.BAD_REQUEST):
+        self.message = message
+        self.status_code = status_code
+        super().__init__(message)
+
+
+class ObjectNotFoundError(QueryError):
+    """Raised when a requested object does not exist."""
+
+    def __init__(self, model_name: str):
+        super().__init__(f"Resource not found: {model_name}", status_code=HTTPStatus.NOT_FOUND)
+
+
+class InvalidFilterError(QueryError):
+    """Raised when filter parameters are invalid."""
+
+    def __init__(self, detail: str):
+        super().__init__(detail, status_code=HTTPStatus.BAD_REQUEST)
+
+
+class InvalidLoadPathError(QueryError):
+    """Raised when a load_path references a non-existent field or relationship."""
+
+    def __init__(self, model_name: str, field_name: str):
+        super().__init__(
+            f"Model {model_name} has no field {field_name}",
+            status_code=HTTPStatus.BAD_REQUEST,
+        )
+
+
+class DatabaseError(QueryError):
+    """Raised for unexpected database errors (connection, timeout, etc.)."""
+
+    def __init__(self, detail: str):
+        super().__init__(detail, status_code=HTTPStatus.INTERNAL_SERVER_ERROR)
+
+
+class MutationError(QueryError):
+    """Raised when a create/update/delete operation fails.
+
+    Covers constraint violations, invalid field names in update data,
+    and other mutation-specific errors.
+    """
+
+    def __init__(self, detail: str):
+        super().__init__(detail, status_code=HTTPStatus.BAD_REQUEST)

sqlmodel_object_helpers/filters.py

@@ -0,0 +1,440 @@
+from typing import Any
+
+from sqlalchemy.orm import RelationshipProperty, aliased
+from sqlmodel import SQLModel, and_, or_
+
+from .constants import settings
+from .exceptions import InvalidFilterError
+from .operators import SPECIAL_OPERATORS, SUPPORTED_OPERATORS
+
+
+def _validate_field_name(field: str) -> None:
+    """Reject field names starting with '_' to prevent access to dunder attributes."""
+    if field.startswith("_"):
+        msg = f"Invalid field name: {field}"
+        raise InvalidFilterError(msg)
+
+
+def flatten_filters(filters: dict[str, Any], parent_key: str = "") -> dict[str, Any]:
+    """Convert nested filter dicts into flat dot-notation dicts.
+
+    Example:
+      {"attempt": {"application": {"applicant": {"last_name": {"eq": "test"}}}}}
+      becomes
+      {"attempt.application.applicant.last_name": {"eq": "test"}}
+    """
+    flat: dict[str, Any] = {}
+    for key, value in filters.items():
+        current_key = f"{parent_key}.{key}" if parent_key else key
+        if isinstance(value, dict):
+            if _is_operator_dict(value):
+                flat[current_key] = value
+            else:
+                nested = flatten_filters(value, current_key)
+                flat.update(nested)
+        else:
+            flat[current_key] = {"eq": value}
+    return flat
+
+
+def _is_operator_dict(value: dict[str, Any]) -> bool:
+    """Check if a dict contains operator keys (supported or special like 'exists')."""
+    return any(k in SUPPORTED_OPERATORS or k in SPECIAL_OPERATORS for k in value)
+
+
+# ---------------------------------------------------------------------------
+# build_filter — for LogicalFilter (AND/OR/condition) used by get_object
+# ---------------------------------------------------------------------------
+
+
+def _add_join(
+    joins: list[Any],
+    seen_joins: set[tuple[Any, ...]],
+    join_tuple: tuple[Any, ...],
+) -> None:
+    """Register a join if not already seen."""
+    if join_tuple not in seen_joins:
+        joins.append(join_tuple)
+        seen_joins.add(join_tuple)
+
+
+def _apply_field_operator(attr: Any, value: dict[str, Any]) -> Any:
+    """Apply all operators from value dict to attr. Returns SQLAlchemy expression."""
+    expressions: list[Any] = []
+    for operator, val in value.items():
+        if operator not in SUPPORTED_OPERATORS:
+            msg = f"Unsupported operator: '{operator}'"
+            raise InvalidFilterError(msg)
+        expressions.append(SUPPORTED_OPERATORS[operator](attr, val))
+    if len(expressions) == 1:
+        return expressions[0]
+    return and_(*expressions)
+
+
+def _handle_and_or(
+    combiner: Any,
+    sub_filters: list[dict[str, Any]],
+    model: type[SQLModel],
+    joins: list[Any],
+    parent_model: type[SQLModel],
+    seen_joins: set[tuple[Any, ...]],
+    _depth: int = 0,
+) -> tuple[Any, list[Any]]:
+    """Process AND/OR list of sub-filters recursively."""
+    if len(sub_filters) > settings.max_and_or_items:
+        msg = f"AND/OR cannot contain more than {settings.max_and_or_items} conditions"
+        raise InvalidFilterError(msg)
+    expressions: list[Any] = []
+    for sub_filter in sub_filters:
+        expr, sub_joins = build_filter(
+            model, sub_filter, joins, parent_model, seen_joins, _depth=_depth + 1
+        )
+        expressions.append(expr)
+        for j in sub_joins:
+            _add_join(joins, seen_joins, j)
+    return combiner(*expressions), joins
+
+
+def _handle_condition(
+    condition: dict[str, Any],
+    model: type[SQLModel],
+    joins: list[Any],
+    parent_model: type[SQLModel],
+    seen_joins: set[tuple[Any, ...]],
+    _depth: int = 0,
+) -> tuple[Any, list[Any]]:
+    """Process a condition block — field-level filters with possible relationships."""
+    expressions: list[Any] = []
+
+    for field, value in condition.items():
+        if field in model.__mapper__.relationships:  # type: ignore[attr-defined]  # SQLAlchemy metaclass
+            _process_relationship_field(
+                field, value, model, joins, parent_model, seen_joins, expressions,
+                _depth=_depth,
+            )
+        else:
+            _process_simple_field(field, value, model, expressions)
+
+    return and_(*expressions), joins
+
+
+def _process_relationship_field(
+    field: str,
+    value: Any,
+    model: type[SQLModel],
+    joins: list[Any],
+    parent_model: type[SQLModel],
+    seen_joins: set[tuple[Any, ...]],
+    expressions: list[Any],
+    _depth: int = 0,
+) -> None:
+    """Process a field that maps to a relationship."""
+    rel_prop = model.__mapper__.relationships[field]  # type: ignore[attr-defined]  # SQLAlchemy metaclass
+    rel_model = rel_prop.mapper.class_
+    _add_join(joins, seen_joins, (model, rel_prop))
+
+    if not isinstance(value, dict):
+        msg = f"Invalid condition for field '{field}': {value}"
+        raise InvalidFilterError(msg)
+
+    if _is_operator_dict(value):
+        try:
+            attr = getattr(rel_model, field)
+        except AttributeError:
+            msg = f"Field '{field}' not found in model {rel_model.__name__}"
+            raise InvalidFilterError(msg) from None
+        expressions.append(_apply_field_operator(attr, value))
+    else:
+        sub_expr, sub_joins = build_filter(
+            rel_model, {"condition": value}, joins, parent_model, seen_joins,
+            _depth=_depth + 1,
+        )
+        expressions.append(sub_expr)
+        for j in sub_joins:
+            _add_join(joins, seen_joins, j)
+
+
+def _process_simple_field(
+    field: str,
+    value: Any,
+    model: type[SQLModel],
+    expressions: list[Any],
+) -> None:
+    """Process a simple (non-relationship) field."""
+    _validate_field_name(field)
+    try:
+        attr = getattr(model, field)
+    except AttributeError:
+        msg = f"Field or relationship '{field}' not found in model {model.__name__}"
+        raise InvalidFilterError(msg) from None
+
+    if isinstance(value, dict) and _is_operator_dict(value):
+        expressions.append(_apply_field_operator(attr, value))
+    else:
+        msg = f"Invalid condition for field '{field}': {value}"
+        raise InvalidFilterError(msg)
+
+
+def _resolve_relationship_chain(
+    path_parts: list[str],
+    model: type[SQLModel],
+    joins: list[Any],
+    seen_joins: set[tuple[Any, ...]],
+) -> tuple[type[SQLModel], Any]:
+    """Walk a dot-notation path, registering joins along the way.
+
+    Returns (final_model, final_attr) for the terminal field.
+    """
+    current_model = model
+
+    for i, part in enumerate(path_parts[:-1]):
+        _validate_field_name(part)
+        if part not in current_model.__mapper__.relationships:  # type: ignore[attr-defined]  # SQLAlchemy metaclass
+            msg = f"Relationship '{part}' not found in model {current_model.__name__}"
+            raise InvalidFilterError(msg)
+        rel_prop = current_model.__mapper__.relationships[part]  # type: ignore[attr-defined]  # SQLAlchemy metaclass
+        _add_join(joins, seen_joins, (current_model, rel_prop))
+        current_model = rel_prop.mapper.class_
+
+    return current_model, path_parts[-1]
+
+
+def _handle_dot_notation(
+    field: str,
+    condition: dict[str, Any],
+    model: type[SQLModel],
+    joins: list[Any],
+    parent_model: type[SQLModel],
+    seen_joins: set[tuple[Any, ...]],
+    expressions: list[Any],
+    _depth: int = 0,
+) -> None:
+    """Process a dot-notation field path with optional relationship traversal."""
+    path_parts = field.split(".")
+    current_model, terminal_part = _resolve_relationship_chain(
+        path_parts, model, joins, seen_joins
+    )
+
+    if terminal_part in current_model.__mapper__.relationships:  # type: ignore[attr-defined]  # SQLAlchemy metaclass
+        rel_prop = current_model.__mapper__.relationships[terminal_part]  # type: ignore[attr-defined]
+        rel_model = rel_prop.mapper.class_
+        _add_join(joins, seen_joins, (current_model, rel_prop))
+
+        if _is_operator_dict(condition):
+            try:
+                attr = getattr(rel_model, terminal_part)
+            except AttributeError:
+                msg = f"Field '{terminal_part}' not found in model {rel_model.__name__}"
+                raise InvalidFilterError(msg) from None
+            expressions.append(_apply_field_operator(attr, condition))
+        else:
+            sub_expr, sub_joins = build_filter(
+                rel_model, {"condition": condition}, joins, parent_model, seen_joins,
+                _depth=_depth + 1,
+            )
+            expressions.append(sub_expr)
+            for j in sub_joins:
+                _add_join(joins, seen_joins, j)
+    else:
+        _validate_field_name(terminal_part)
+        try:
+            attr = getattr(current_model, terminal_part)
+        except AttributeError:
+            msg = f"Field '{terminal_part}' not found in model {current_model.__name__}"
+            raise InvalidFilterError(msg) from None
+
+        if _is_operator_dict(condition):
+            expressions.append(_apply_field_operator(attr, condition))
+        else:
+            msg = f"Invalid condition for field '{field}': {condition}"
+            raise InvalidFilterError(msg)
+
+
+def build_filter(
+    model: type[SQLModel],
+    filters: dict[str, Any],
+    joins: list[Any] | None = None,
+    parent_model: type[SQLModel] | None = None,
+    seen_joins: set[tuple[Any, ...]] | None = None,
+    _depth: int = 0,
+) -> tuple[Any, list[Any]]:
+    """Build a SQLAlchemy filter expression from a filter dict.
+
+    Supports:
+    - AND/OR/condition recursive structure (LogicalFilter)
+    - Dot-notation field paths with automatic joins
+    - Flat dict filters with operators
+    """
+    if _depth > settings.max_filter_depth:
+        msg = f"Filter nesting depth exceeds {settings.max_filter_depth}"
+        raise InvalidFilterError(msg)
+
+    if joins is None:
+        joins = []
+    if seen_joins is None:
+        seen_joins = set()
+    if parent_model is None:
+        parent_model = model
+
+    if "AND" in filters and filters["AND"] is not None:
+        return _handle_and_or(
+            and_, filters["AND"], model, joins, parent_model, seen_joins, _depth=_depth
+        )
+
+    if "OR" in filters and filters["OR"] is not None:
+        return _handle_and_or(
+            or_, filters["OR"], model, joins, parent_model, seen_joins, _depth=_depth
+        )
+
+    if "condition" in filters:
+        return _handle_condition(
+            filters["condition"], model, joins, parent_model, seen_joins, _depth=_depth
+        )
+
+    # Dot-notation / flat dict filters
+    expressions: list[Any] = []
+    for field, condition in filters.items():
+        if not isinstance(condition, dict):
+            msg = f"Invalid condition for field '{field}': {condition}"
+            raise InvalidFilterError(msg)
+        _handle_dot_notation(
+            field, condition, model, joins, parent_model, seen_joins, expressions,
+            _depth=_depth,
+        )
+
+    if not expressions:
+        return None, joins
+    return and_(*expressions), joins
+
+
+# ---------------------------------------------------------------------------
+# build_flat_filter — for flattened dict filters used by get_objects
+# Uses aliased() models for join handling (different from build_filter)
+# ---------------------------------------------------------------------------
+
+
+def _resolve_aliased_path(
+    field_parts: list[str],
+    model: type[SQLModel],
+    model_aliases: dict[str, Any],
+    join_entities: list[tuple[Any, Any]],
+    suspend_error: bool,
+) -> Any | None:
+    """Resolve a dot-notation path using aliased models.
+
+    Returns the final attribute, or None if suspend_error=True and path is invalid.
+    """
+    alias_path = field_parts[:-1]
+    related_field = field_parts[-1]
+    related_model = model
+
+    for i, related_name in enumerate(alias_path):
+        try:
+            _validate_field_name(related_name)
+        except InvalidFilterError:
+            if not suspend_error:
+                raise
+            return None
+        try:
+            relationship_attr = getattr(related_model, related_name)
+        except AttributeError:
+            if not suspend_error:
+                msg = f"Model {model.__name__} has no relationship {related_name}"
+                raise InvalidFilterError(msg)
+            return None
+
+        related_model = relationship_attr.property.mapper.class_
+
+        alias_key = ".".join(alias_path[: i + 1])
+        if alias_key not in model_aliases:
+            alias = aliased(related_model)
+            model_aliases[alias_key] = alias
+            join_entities.append((alias, relationship_attr))
+
+    try:
+        _validate_field_name(related_field)
+    except InvalidFilterError:
+        if not suspend_error:
+            raise
+        return None
+    final_key = ".".join(alias_path)
+    return getattr(model_aliases[final_key], related_field)
+
+
+def _apply_filter_value(
+    attr: Any,
+    value: Any,
+    conditions: list[Any],
+) -> None:
+    """Process a filter value (dict with operators, exists, or list) and append conditions."""
+    if isinstance(value, dict):
+        if "exists" in value:
+            if hasattr(attr, "prop") and isinstance(attr.prop, RelationshipProperty):
+                cond = attr.any() if value["exists"] else ~attr.any()
+            else:
+                cond = attr.is_not(None) if value["exists"] else attr.is_(None)
+            conditions.append(cond)
+        else:
+            field_conditions = [
+                SUPPORTED_OPERATORS[op](attr, op_val)
+                for op, op_val in value.items()
+                if op in SUPPORTED_OPERATORS and op_val is not None
+            ]
+            if field_conditions:
+                conditions.append(and_(*field_conditions))
+    elif isinstance(value, list):
+        field_conditions = [
+            SUPPORTED_OPERATORS[cond[0]](attr, cond[1])
+            if isinstance(cond, (list, tuple)) and len(cond) == 2 and cond[0] in SUPPORTED_OPERATORS
+            else attr == cond
+            for cond in value
+        ]
+        conditions.append(and_(*field_conditions))
+
+
+def build_flat_filter(
+    model: type[SQLModel],
+    filters: dict[str, Any],
+    suspend_error: bool = False,
+) -> tuple[list[Any], list[tuple[Any, Any]]]:
+    """Build filter conditions from a flattened dict (dot-notation keys).
+
+    Uses aliased() models for join handling.
+    Returns (conditions, join_entities).
+    """
+    conditions: list[Any] = []
+    model_aliases: dict[str, Any] = {}
+    join_entities: list[tuple[Any, Any]] = []
+
+    for field, value in filters.items():
+        field_parts = field.split(".")
+
+        if any(not part for part in field_parts):
+            if not suspend_error:
+                raise InvalidFilterError(f"Empty segment in filter path: {field!r}")
+            continue
+
+        if len(field_parts) > 1:
+            attr = _resolve_aliased_path(
+                field_parts, model, model_aliases, join_entities, suspend_error
+            )
+            if attr is None:
+                continue
+        else:
+            try:
+                _validate_field_name(field_parts[0])
+            except InvalidFilterError:
+                if not suspend_error:
+                    raise
+                continue
+            try:
+                attr = getattr(model, field_parts[0])
+            except AttributeError:
+                if not suspend_error:
+                    msg = f"Model {model.__name__} has no field {field_parts[0]}"
+                    raise InvalidFilterError(msg)
+                continue
+
+        _apply_filter_value(attr, value, conditions)
+
+    return conditions, join_entities