async-orm-kit 1.0.0__py3-none-any.whl

async_orm_kit/query/mixins/orderable.py

@@ -0,0 +1,208 @@
+from typing import Any
+
+from async_orm_kit.query.lookups.resolver import ResolverContext
+
+
+class OrderedExpression:
+    """Wrapper that adds sort direction to ORM expressions for use in ``order_by()``.
+
+    Encapsulates any ORM expression (field reference, computed expression, aggregate,
+    or conditional) with an ascending or descending sort direction. Created by
+    calling ``.asc()`` or ``.desc()`` on any :class:`OrderableMixin` subclass.
+
+    During query compilation, the wrapped expression is resolved to a SQLAlchemy
+    column/expression, then the appropriate ``.asc()`` or ``.desc()`` method is
+    applied to generate the final ORDER BY clause element.
+
+    Args:
+        expression: Any ORM expression with a ``resolve(field_resolver, context)``
+            method. Typically a :class:`F`, :class:`FExpression`, :class:`Aggregate`,
+            or :class:`Case` instance.
+        ascending: If ``True``, sort in ascending order (smallest to largest).
+            If ``False``, sort in descending order (largest to smallest).Defaults to ``True``.Attributes:
+        expression: The wrapped ORM expression to be sorted.
+        ascending (bool): Sort direction flag.
+
+    Example:
+        >>> from async_orm_kit.query.expressions.f import F
+        >>> from async_orm_kit.query.aggregations import Sum
+        >>> from async_orm_kit.query.expressions.case import Case, When
+        >>> from async_orm_kit.query.expressions.value import Value
+        >>>
+        >>> # Simple field ordering
+        >>> Product.objects.order_by(F("price").desc())
+        >>> # SQL: ORDER BY "price" DESC
+        >>>
+        >>> # Computed expression ordering
+        >>> Product.objects.order_by((F("price") * F("quantity")).asc())
+        >>> # SQL: ORDER BY ("price" * "quantity") ASC
+        >>>
+        >>> # Aggregate ordering (requires annotation)
+        >>> Product.objects.annotate(
+        ...     total_sales=Sum("order_items__quantity")
+        ... ).order_by(F("total_sales").desc())
+        >>> # SQL: ORDER BY SUM("order_items"."quantity") DESC
+        >>>
+        >>> # Conditional ordering
+        >>> priority = Case(
+        ...     When(status="urgent", then=Value(0)),
+        ...     When(status="high", then=Value(1)),
+        ...     default=Value(2)
+        ... )
+        >>> Task.objects.order_by(priority.asc(), F("created_at").desc())
+        >>> # SQL: ORDER BY CASE ... END ASC, "created_at" DESC
+
+    Note:
+        - The wrapped expression is **not resolved** until query compilation time,
+          allowing the same ``OrderedExpression`` instance to be reused across
+          multiple queries.
+        - Multiple ``OrderedExpression`` instances can be passed to ``order_by()``
+          to create multi-column sorts with mixed directions.
+        - Database NULL handling varies by backend and can be controlled with
+          ``NULLS FIRST`` / ``NULLS LAST`` (not currently supported by this class,
+          but available via raw SQLAlchemy if needed).
+
+    See Also:
+        - :class:`OrderableMixin` for the ``.asc()`` / ``.desc()`` factory methods.
+        - :meth:`QuerySet.order_by` for usage in query construction.
+    """
+
+    def __init__(self, expression: Any, ascending: bool = True):
+        self.expression = expression
+        self.ascending = ascending
+
+    def resolve(self, field_resolver, context: ResolverContext = ResolverContext()):
+        """Resolve the wrapped expression and apply sort direction.Delegates resolution to the wrapped expression's ``resolve()`` method,
+        then applies SQLAlchemy's ``.asc()`` or ``.desc()`` method to the
+        resulting column/expression to produce the final ORDER BY element.
+
+        Args:
+            field_resolver: FieldResolver instance for resolving field paths
+                and managing JOIN registration.
+            context: Resolution context for JOIN optimization. Defaults to
+                empty context (no special flags).
+
+        Returns:
+            SQLAlchemy column expression with ``.asc()`` or ``.desc()`` applied,
+            ready for inclusion in an ORDER BY clause.
+
+        Example:
+            >>> resolver = FieldResolver(Product, join_graph)
+            >>> ordered = F("price").desc()
+            >>> sql_expr = ordered.resolve(resolver)
+            >>> # Returns: Product.price.desc() (SQLAlchemy UnaryExpression)
+
+        Note:
+            The ``context`` parameter is propagated to the wrapped expression's
+            resolution, ensuring consistent JOIN strategy if the expression
+            references relationships.
+        """
+        resolved = self.expression.resolve(field_resolver, context)
+        if self.ascending:
+            return resolved.asc()
+        return resolved.desc()
+
+    def __repr__(self) -> str:
+        """Return developer-friendly string representation.
+
+        Returns:
+            String showing the wrapped expression and sort direction.
+
+        Example:
+            >>> repr(F("price").desc())
+            >>> # Returns: "OrderedExpression(F('price'), DESC)"
+        """
+        direction = "ASC" if self.ascending else "DESC"
+        return f"OrderedExpression({self.expression!r}, {direction})"
+
+
+class OrderableMixin:
+    """Mixin that adds ``.asc()`` and ``.desc()`` methods for sort direction control.
+
+    Enables any ORM expression class to produce :class:`OrderedExpression` instances
+    for use in ``order_by()`` clauses. Classes inheriting this mixin can be sorted
+    in ascending or descending order by calling the provided methods.
+
+    Classes Using This Mixin:
+        - :class:`F` — field references (``F("created_at").desc()``)
+        - :class:`FExpression` — computed expressions (``(F("a") + F("b")).asc()``)
+        - :class:`Aggregate` — aggregate results (``Sum("amount").desc()``)
+        - :class:`Case` — conditional expressions (``Case(...).asc()``)
+        - :class:`Value` — literal values (``Value(1).desc()`` — rare but valid)
+
+    Example:
+        >>> from async_orm_kit.query.expressions.f import F
+        >>> from async_orm_kit.query.aggregations import Count
+        >>> # Ascending sort (default direction)
+        >>> Product.objects.order_by(F("name").asc())
+        >>> # SQL: ORDER BY "name" ASC
+        >>>
+        >>> # Descending sort
+        >>> Product.objects.order_by(F("price").desc())
+        >>> # SQL: ORDER BY "price" DESC
+        >>>
+        >>> # Multi-column sort with mixed directions
+        >>> Product.objects.order_by(
+        ...     F("category").asc(),
+        ...     F("price").desc(),
+        ...     F("name").asc()
+        ... )
+        >>> # SQL: ORDER BY "category" ASC, "price" DESC, "name" ASC
+        >>>
+        >>> # Sorting by computed expression
+        >>> Product.objects.order_by((F("price") * F("quantity")).desc())
+        >>> # SQL: ORDER BY ("price" * "quantity") DESC
+        >>>
+        >>> # Sorting by aggregate (requires annotation)
+        >>> Category.objects.annotate(
+        ...     product_count=Count("products")
+        ... ).order_by(F("product_count").desc())
+        >>> # SQL: ORDER BY COUNT("products"."id") DESC
+
+    Note:
+        - Both methods return new :class:`OrderedExpression` instances; the
+          original expression object is **never mutated** (immutable pattern).
+        - The ``__slots__ = ()`` declaration prevents instance attribute creation,
+          ensuring this mixin adds no memory overhead to inheriting classes.
+        - Calling ``.asc()`` or ``.desc()`` multiple times on the same expression
+          creates independent ``OrderedExpression`` wrappers — the last one used
+          in ``order_by()`` determines the actual sort direction.
+
+    See Also:
+        - :class:`OrderedExpression` for the wrapper class structure.
+        - :meth:`QuerySet.order_by` for usage in query construction.
+    """
+
+    __slots__ = ()
+
+    def asc(self) -> OrderedExpression:
+        """Create an ascending sort wrapper for this expression.
+
+        Returns:
+            OrderedExpression with ``ascending=True``, suitable for passing
+            to ``order_by()``.
+
+        Example:
+            >>> F("price").asc()
+            >>> # Returns: OrderedExpression(F('price'), ASC)
+            >>>
+            >>> Product.objects.order_by(F("created_at").asc())
+            >>> # SQL: ORDER BY "created_at" ASC
+        """
+        return OrderedExpression(self, True)
+
+    def desc(self) -> OrderedExpression:
+        """Create a descending sort wrapper for this expression.
+
+        Returns:
+            OrderedExpression with ``ascending=False``, suitable for passing
+            to ``order_by()``.
+
+        Example:
+            >>> F("price").desc()
+            >>> # Returns: OrderedExpression(F('price'), DESC)
+            >>>
+            >>> Product.objects.order_by(F("price").desc())
+            >>> # SQL: ORDER BY "price" DESC
+        """
+        return OrderedExpression(self, False)

async_orm_kit/query/observability.py

@@ -0,0 +1,346 @@
+"""Opt-in SQLAlchemy execution diagnostics, scoped to the current async task.
+
+The profiler measures DBAPI cursor-execution time, not complete QuerySet
+materialization, network connection acquisition, or request latency. It works
+with SQLAlchemy ``Engine`` and ``AsyncEngine`` without wrapping/monkey-patching
+SQLAlchemy internals and introduces no new mandatory dependencies.
+"""
+
+from __future__ import annotations
+
+import re
+import threading
+import time
+from collections import Counter
+from collections.abc import AsyncIterator, Callable, Iterator
+from contextlib import asynccontextmanager, contextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass, field
+from typing import Any
+
+from sqlalchemy import event
+from sqlalchemy.engine import Engine
+from sqlalchemy.ext.asyncio import AsyncEngine
+
+from async_orm_kit._logging import get_logger
+
+logger = get_logger(__name__)
+
+# Only SQL templates are retained. Redact SQL literals and comments even when
+# raw SQL is executed through exec_driver_sql(). Parameter values are never read.
+_SQL_LITERAL = re.compile(r"'(?:''|[^'])*'", re.DOTALL)
+_SQL_BLOCK_COMMENT = re.compile(r"/\*.*?\*/", re.DOTALL)
+_SQL_LINE_COMMENT = re.compile(r"--[^\n]*")
+_SQL_NUMBER = re.compile(r"(?<![\w:$])\b\d+(?:\.\d+)?\b(?![\w])")
+_SQL_WHITESPACE = re.compile(r"\s+")
+
+
+def sanitized_sql(sql: str, *, max_length: int = 2048) -> str:
+    """Return a bounded, best-effort redacted statement (never bind values).
+
+    For absolute secrecy in production, do not enable SQL recording: arbitrary
+    driver SQL and SQL identifiers may contain confidential information.
+    """
+    text = _SQL_LITERAL.sub("'?'", sql)
+    text = _SQL_BLOCK_COMMENT.sub(" ", text)
+    text = _SQL_LINE_COMMENT.sub(" ", text)
+    text = _SQL_NUMBER.sub("?", text)
+    text = _SQL_WHITESPACE.sub(" ", text).strip()
+    return text[:max_length]
+
+
+def sql_fingerprint(sql: str) -> str:
+    """Normalize a statement for *heuristic* repetition detection."""
+    return sanitized_sql(sql, max_length=4096)
+
+
+@dataclass(frozen=True, slots=True)
+class QueryRecord:
+    """One database cursor execution, without SQL bind parameters."""
+
+    sql: str
+    duration_ms: float
+    timestamp: float
+    row_count: int | None
+    success: bool
+    error_type: str | None = None
+
+
+@dataclass(slots=True)
+class QueryProfile:
+    """A bounded task-local capture, including totals for evicted records."""
+
+    max_entries: int
+    slow_threshold_ms: float
+    records: list[QueryRecord] = field(default_factory=list)
+    total_queries: int = 0
+    total_duration_ms: float = 0.0
+    slow_queries: int = 0
+    failed_queries: int = 0
+    dropped_entries: int = 0
+    untracked_patterns: int = 0
+    patterns: Counter[str] = field(default_factory=Counter)
+    active: bool = True
+    _slowest: QueryRecord | None = field(default=None, repr=False)
+
+    def _record(self, record: QueryRecord) -> None:
+        if not self.active:
+            return
+        self.total_queries += 1
+        self.total_duration_ms += record.duration_ms
+        self.slow_queries += record.duration_ms >= self.slow_threshold_ms
+        self.failed_queries += not record.success
+        if self._slowest is None or record.duration_ms > self._slowest.duration_ms:
+            self._slowest = record
+        if record.success:
+            fingerprint = sql_fingerprint(record.sql)
+            if fingerprint in self.patterns or len(self.patterns) < self.max_entries:
+                self.patterns[fingerprint] += 1
+            else:
+                # Query patterns are bounded too; distinct raw SQL must not
+                # grow the profile indefinitely in a long-running request.
+                self.untracked_patterns += 1
+        if len(self.records) >= self.max_entries:
+            self.records.pop(0)
+            self.dropped_entries += 1
+        self.records.append(record)
+
+    def stats(self) -> dict[str, Any]:
+        """Return full execution totals, even if older records were evicted."""
+        return {
+            "total_queries": self.total_queries,
+            "total_duration_ms": round(self.total_duration_ms, 3),
+            "avg_duration_ms": round(self.total_duration_ms / self.total_queries, 3)
+            if self.total_queries
+            else 0.0,
+            "slow_queries": self.slow_queries,
+            "failed_queries": self.failed_queries,
+            "dropped_entries": self.dropped_entries,
+            "untracked_patterns": self.untracked_patterns,
+            "slowest_query": (
+                {"sql": self._slowest.sql, "duration_ms": self._slowest.duration_ms}
+                if self._slowest is not None
+                else None
+            ),
+        }
+
+    def n_plus_one_report(self, *, threshold: int = 10) -> dict[str, Any]:
+        """Report suspected repeated SELECT-by-key patterns, not guaranteed N+1.
+
+        Repeated WHERE queries are only a heuristic; deliberate polling and
+        bulk jobs may also match. This does not trace object relationships.
+        """
+        if (
+            isinstance(threshold, bool)
+            or not isinstance(threshold, int)
+            or threshold < 2
+        ):
+            raise ValueError("threshold must be an integer >= 2")
+        suspects: list[dict[str, Any]] = [
+            {
+                "pattern": sql[:200],
+                "count": count,
+                "severity": "high" if count > 100 else "medium",
+            }
+            for sql, count in self.patterns.items()
+            if count >= threshold
+            and sql.lstrip().upper().startswith("SELECT ")
+            and " WHERE " in f" {sql.upper()} "
+        ]
+        suspects.sort(key=lambda entry: (-entry["count"], entry["pattern"]))
+        return {
+            "total_queries": self.total_queries,
+            "unique_patterns": len(self.patterns),
+            "untracked_patterns": self.untracked_patterns,
+            "potential_n_plus_one": suspects,
+        }
+
+
+class QueryProfiler:
+    """Capture cursor executions from a SQLAlchemy Engine or AsyncEngine.
+
+    A profiler's ``capture()`` is scoped via ``ContextVar`` to the current
+    execution context; captures in concurrent async tasks do not mix. Nested
+    captures both receive the query. Lifecycle registration is reference-counted
+    so one exiting request cannot detach another active request's listener.
+
+    Example::
+
+        profiler = QueryProfiler(async_engine)
+        with profiler.capture() as profile:
+            results = await session.execute(statement)
+        print(profile.stats(), profile.n_plus_one_report(threshold=3))
+
+    ``capture()`` automatically registers and removes listeners. Use ``attach``
+    and ``detach`` for persistent monitoring, though uncaptured executions are
+    ignored unless an ``on_query`` callback is configured.
+    """
+
+    def __init__(
+        self,
+        engine: Engine | AsyncEngine,
+        *,
+        max_entries: int = 1000,
+        slow_threshold_ms: float = 100.0,
+        on_query: Callable[[QueryRecord], None] | None = None,
+    ) -> None:
+        sync_engine = engine.sync_engine if isinstance(engine, AsyncEngine) else engine
+        if not isinstance(sync_engine, Engine):
+            raise TypeError("engine must be a SQLAlchemy Engine or AsyncEngine")
+        if (
+            isinstance(max_entries, bool)
+            or not isinstance(max_entries, int)
+            or max_entries < 1
+        ):
+            raise ValueError("max_entries must be an integer >= 1")
+        if slow_threshold_ms < 0:
+            raise ValueError("slow_threshold_ms must be nonnegative")
+        if on_query is not None and not callable(on_query):
+            raise TypeError("on_query must be callable")
+        self._engine = sync_engine
+        self._max_entries = max_entries
+        self._slow_threshold_ms = float(slow_threshold_ms)
+        self._on_query = on_query
+        self._captures: ContextVar[tuple[QueryProfile, ...]] = ContextVar(
+            f"ormkit_query_profiles_{id(self)}", default=()
+        )
+        self._registered = False
+        self._permanent = False
+        self._capture_count = 0
+        self._lock = threading.RLock()
+        self._clock_key = f"_ormkit_query_start_{id(self)}"
+        # Hold exact callback objects for event.remove(), including on Python
+        # versions that create a fresh bound method object on attribute access.
+        self._before_cb = self._before_cursor_execute
+        self._after_cb = self._after_cursor_execute
+        self._error_cb = self._handle_error
+
+    def _install(self) -> None:
+        if self._registered:
+            return
+        event.listen(self._engine, "before_cursor_execute", self._before_cb)
+        event.listen(self._engine, "after_cursor_execute", self._after_cb)
+        event.listen(self._engine, "handle_error", self._error_cb)
+        self._registered = True
+
+    def _uninstall(self) -> None:
+        if not self._registered:
+            return
+        event.remove(self._engine, "before_cursor_execute", self._before_cb)
+        event.remove(self._engine, "after_cursor_execute", self._after_cb)
+        event.remove(self._engine, "handle_error", self._error_cb)
+        self._registered = False
+
+    def attach(self) -> None:
+        """Keep listeners installed until ``detach()`` is called."""
+        with self._lock:
+            self._permanent = True
+            self._install()
+
+    def detach(self) -> None:
+        """Remove persistent monitoring without disrupting active captures."""
+        with self._lock:
+            self._permanent = False
+            if not self._capture_count:
+                self._uninstall()
+
+    @contextmanager
+    def capture(self) -> Iterator[QueryProfile]:
+        """Capture queries in this task; usable across ``await`` boundaries."""
+        profile = QueryProfile(
+            max_entries=self._max_entries,
+            slow_threshold_ms=self._slow_threshold_ms,
+        )
+        with self._lock:
+            self._install()
+            self._capture_count += 1
+        token = self._captures.set((*self._captures.get(), profile))
+        try:
+            yield profile
+        finally:
+            profile.active = False
+            self._captures.reset(token)
+            with self._lock:
+                self._capture_count -= 1
+                if not self._permanent and not self._capture_count:
+                    self._uninstall()
+
+    @asynccontextmanager
+    async def acapture(self) -> AsyncIterator[QueryProfile]:
+        """``async with`` equivalent of ``capture()``."""
+        with self.capture() as profile:
+            yield profile
+
+    def _before_cursor_execute(
+        self,
+        connection: Any,
+        cursor: Any,
+        statement: str,
+        parameters: Any,
+        context: Any,
+        executemany: bool,
+    ) -> None:
+        if self._captures.get() or self._on_query is not None:
+            setattr(context, self._clock_key, time.perf_counter_ns())
+
+    def _finish(
+        self,
+        statement: str,
+        context: Any,
+        *,
+        row_count: int | None = None,
+        error_type: str | None = None,
+    ) -> None:
+        start = getattr(context, self._clock_key, None)
+        if start is None:
+            return
+        # Avoid double counting if an adapter emits more than one callback.
+        delattr(context, self._clock_key)
+        duration_ms = max(0.0, (time.perf_counter_ns() - start) / 1_000_000)
+        record = QueryRecord(
+            sql=sanitized_sql(statement),
+            duration_ms=duration_ms,
+            timestamp=time.time(),
+            row_count=row_count if row_count is not None and row_count >= 0 else None,
+            success=error_type is None,
+            error_type=error_type,
+        )
+        for profile in self._captures.get():
+            profile._record(record)
+        if self._on_query is not None:
+            try:
+                self._on_query(record)
+            except Exception:
+                # Diagnostics must never change the result of a DB operation.
+                logger.exception("Query monitoring callback failed")
+
+    def _after_cursor_execute(
+        self,
+        connection: Any,
+        cursor: Any,
+        statement: str,
+        parameters: Any,
+        context: Any,
+        executemany: bool,
+    ) -> None:
+        self._finish(statement, context, row_count=getattr(cursor, "rowcount", None))
+
+    def _handle_error(self, exception_context: Any) -> None:
+        context = getattr(exception_context, "execution_context", None)
+        if context is None:
+            return  # failure before cursor execution is outside this profiler
+        error = getattr(exception_context, "original_exception", None)
+        self._finish(
+            getattr(exception_context, "statement", "") or "",
+            context,
+            error_type=type(error).__name__ if error is not None else "UnknownError",
+        )
+
+
+__all__ = [
+    "QueryProfiler",
+    "QueryProfile",
+    "QueryRecord",
+    "sanitized_sql",
+    "sql_fingerprint",
+]

async_orm_kit/query/planning/directives.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum, auto
+
+
+class LoadStrategy(Enum):
+    JOINEDLOAD = auto()
+    SELECTINLOAD = auto()
+    SUBQUERYLOAD = auto()
+    SKIP = auto()
+
+
+@dataclass(frozen=True, slots=True)
+class LoadDirective:
+    """
+    Immutable output of the planning process.
+
+    One directive per loading path, carrying the chosen strategy
+    and a human-readable reason for debugging / EXPLAIN output.
+    """
+
+    path: str
+    strategy: LoadStrategy
+    reason: str
+    original_strategy: LoadStrategy | None = None  # before any demotion
+    segment_strategies: tuple[LoadStrategy, ...] = ()
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.path, str) or not self.path:
+            raise ValueError("LoadDirective.path must be a non-empty string.")
+        path_parts = self.path.split("__")
+        if any(not part or part.strip() != part for part in path_parts):
+            raise ValueError("LoadDirective.path contains an invalid segment.")
+        if not isinstance(self.strategy, LoadStrategy):
+            raise TypeError("LoadDirective.strategy must be a LoadStrategy.")
+        if not isinstance(self.reason, str) or not self.reason:
+            raise ValueError("LoadDirective.reason must be a non-empty string.")
+        if self.original_strategy is not None and not isinstance(
+            self.original_strategy, LoadStrategy
+        ):
+            raise TypeError("original_strategy must be a LoadStrategy or None.")
+        try:
+            segment_strategies = tuple(self.segment_strategies)
+        except TypeError as exc:
+            raise TypeError(
+                "segment_strategies must be an iterable of strategies."
+            ) from exc
+        object.__setattr__(self, "segment_strategies", segment_strategies)
+        if segment_strategies:
+            if len(segment_strategies) != len(path_parts):
+                raise ValueError(
+                    "segment_strategies must contain one strategy per path segment."
+                )
+            if any(
+                not isinstance(strategy, LoadStrategy)
+                for strategy in segment_strategies
+            ):
+                raise TypeError("segment_strategies must contain LoadStrategy values.")
+
+    @property
+    def was_demoted(self) -> bool:
+        return (
+            self.original_strategy is not None
+            and self.original_strategy != self.strategy
+        )
+
+    def __repr__(self) -> str:
+        demoted = " (demoted)" if self.was_demoted else ""
+        return (
+            f"LoadDirective({self.path!r}, "
+            f"{self.strategy.name}{demoted}, "
+            f"{self.reason!r})"
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class JoinPromotion:
+    """Record of a LEFT → INNER promotion for audit trail."""
+
+    path: str
+    old_type: str
+    new_type: str
+    reason: str
+
+
+@dataclass(frozen=True, slots=True)
+class QueryContext:
+    """
+    Immutable snapshot of query-level facts that planning
+    passes need to make decisions.
+
+    Built ONCE by the QuerySet compiler, then passed through
+    read-only. No pass mutates this.
+    """
+
+    has_aggregates: bool = False
+    is_distinct: bool = False
+    limit: int | None = None
+
+    # Paths the user explicitly requested
+    select_related_paths: frozenset[str] = field(default_factory=frozenset)
+    prefetch_paths: frozenset[str] = field(default_factory=frozenset)
+
+    def __post_init__(self) -> None:
+        if type(self.has_aggregates) is not bool or type(self.is_distinct) is not bool:
+            raise TypeError("QueryContext flags must be bool values.")
+        if self.limit is not None and (type(self.limit) is not int or self.limit < 0):
+            raise ValueError(
+                "QueryContext.limit must be a non-negative integer or None."
+            )
+
+        for attribute in ("select_related_paths", "prefetch_paths"):
+            paths = frozenset(getattr(self, attribute))
+            if any(not isinstance(path, str) or not path for path in paths):
+                raise ValueError(f"{attribute} must contain non-empty strings.")
+            object.__setattr__(self, attribute, paths)