qsmongo 0.3.0__py3-none-any.whl

qsmongo/__init__.py

@@ -0,0 +1,45 @@
+"""qsmongo — turn an HTTP query string into a safe MongoDB filter.
+
+from qsmongo import Field, Schema, parse
+
+schema = Schema(name=Field(str), age=Field(int))
+query = parse("age__gte=21&sort=-age&page=2", schema)
+collection.find(**query.find_kwargs())
+"""
+
+from .advisor import Index, IndexAdvice, analyze
+from .coerce import coerce
+from .cursor import Cursors
+from .errors import (
+    InvalidCursor,
+    InvalidPagination,
+    InvalidProjection,
+    InvalidValue,
+    QSMongoError,
+    UnknownField,
+    UnsupportedOperator,
+)
+from .parser import parse
+from .query import Query
+from .schema import Field, Schema
+
+__version__ = "0.3.0"
+
+__all__ = [
+    "Cursors",
+    "Field",
+    "Index",
+    "IndexAdvice",
+    "InvalidCursor",
+    "InvalidPagination",
+    "InvalidProjection",
+    "InvalidValue",
+    "QSMongoError",
+    "Query",
+    "Schema",
+    "UnknownField",
+    "UnsupportedOperator",
+    "analyze",
+    "coerce",
+    "parse",
+]

qsmongo/advisor.py

@@ -0,0 +1,200 @@
+"""Index advice for a parsed query.
+
+This is a **lint, not a query planner**. It applies MongoDB's ESR guideline — an efficient compound
+index lists Equality fields first, then Sort fields, then Range fields — to the query qsmongo just
+built, and tells you whether one of your declared indexes can serve it. `explain()` remains the
+only ground truth; this is here to catch the obvious problems before they reach a database.
+
+    from qsmongo import Index, analyze, parse
+
+    query = parse(request.url.query, schema)
+    advice = analyze(query, INDEXES, extra_equality=["tenant_id"])
+    if not advice.ok:
+        log.warning("unindexed query: %s", advice)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from .query import Query
+
+RANGE_OPERATORS = frozenset({"$gt", "$gte", "$lt", "$lte"})
+
+
+@dataclass(frozen=True, init=False)
+class Index:
+    """A compound index, in the same key order MongoDB stores it."""
+
+    keys: tuple[tuple[str, int], ...]
+    name: str | None = None
+
+    def __init__(self, keys, name: str | None = None):
+        object.__setattr__(self, "keys", tuple((column, int(direction)) for column, direction in keys))
+        object.__setattr__(self, "name", name)
+
+    @classmethod
+    def from_index_information(cls, information: dict[str, Any]) -> list[Index]:
+        """Build the index list straight from ``collection.index_information()``."""
+        indexes = []
+        for name, spec in information.items():
+            keys = [(column, direction) for column, direction in spec["key"] if isinstance(direction, int)]
+            if keys:
+                indexes.append(cls(keys, name=name))
+        return indexes
+
+    @property
+    def columns(self) -> tuple[str, ...]:
+        return tuple(column for column, _ in self.keys)
+
+    def __str__(self) -> str:
+        body = ", ".join(f"{column}: {direction}" for column, direction in self.keys)
+        return f"{{{body}}}" + (f" ({self.name})" if self.name else "")
+
+
+@dataclass(frozen=True)
+class IndexAdvice:
+    """What the lint concluded."""
+
+    ok: bool
+    index: Index | None = None
+    covered: bool = False
+    warnings: tuple[str, ...] = ()
+    suggestion: tuple[tuple[str, int], ...] = ()
+
+    @property
+    def suggestion_spec(self) -> dict[str, int]:
+        """The suggested index in ``create_index`` form."""
+        return dict(self.suggestion)
+
+    def __str__(self) -> str:
+        if self.ok:
+            head = f"served by {self.index}" + (" (covered)" if self.covered else "")
+        else:
+            head = "no index serves this query"
+        lines = [head, *(f"  - {warning}" for warning in self.warnings)]
+        if not self.ok and self.suggestion:
+            lines.append(f"  suggested index: {Index(self.suggestion)}")
+        return "\n".join(lines)
+
+
+def _classify(filter_: dict[str, Any], equality: dict[str, None], ranges: dict[str, None], warnings: list[str]):
+    """Sort every predicate into equality, range, or 'cannot use an index'."""
+    for key, value in filter_.items():
+        if key == "$and":
+            for branch in value:
+                _classify(branch, equality, ranges, warnings)
+        elif key == "$or":
+            # The keyset clause lands here. Its fields are the sort keys, and it reads as a seek
+            # into the index, so treat them as ranges rather than warning about an index union.
+            for branch in value:
+                seen: dict[str, None] = {}
+                _classify(branch, seen, seen, warnings)
+                for column in seen:
+                    ranges.setdefault(column, None)
+        elif isinstance(value, dict):
+            operators = set(value)
+            if "$in" in operators:
+                equality.setdefault(key, None)
+            if operators & RANGE_OPERATORS:
+                ranges.setdefault(key, None)
+            if "$regex" in operators:
+                anchored = str(value["$regex"]).startswith("^") and "i" not in str(value.get("$options", ""))
+                if anchored:
+                    ranges.setdefault(key, None)
+                else:
+                    warnings.append(
+                        f"{key}: an unanchored or case-insensitive regex cannot use an index and scans "
+                        "every candidate document"
+                    )
+            if "$ne" in operators or "$nin" in operators:
+                warnings.append(f"{key}: $ne/$nin match almost everything, so an index barely narrows the scan")
+            if value.get("$exists") is False:
+                warnings.append(f"{key}: $exists=false cannot use a standard index")
+        else:
+            equality.setdefault(key, None)
+
+
+def _match(index: Index, equality: dict[str, None], sort: list[tuple[str, int]], ranges: dict[str, None]):
+    """Walk the index keys ESR-style. Returns (prefix_length, sort_is_indexed)."""
+    keys = index.keys
+    position = 0
+    while position < len(keys) and keys[position][0] in equality:
+        position += 1
+
+    # A sort on a field pinned by an equality predicate is free — every matching document shares
+    # that value — so it does not need to appear in the index after the prefix.
+    effective = [entry for entry in sort if entry[0] not in equality]
+    if not effective:
+        return position, True
+
+    window = keys[position : position + len(effective)]
+    if len(window) < len(effective):
+        return position, False
+    same = all(w == e for w, e in zip(window, effective, strict=True))
+    # Walking an index backwards is free, but only if every key is reversed.
+    reversed_ = all(w[0] == e[0] and w[1] == -e[1] for w, e in zip(window, effective, strict=True))
+    return position, same or reversed_
+
+
+def analyze(
+    query: Query,
+    indexes: list[Index] | None = None,
+    *,
+    extra_equality: list[str] = (),
+) -> IndexAdvice:
+    """Check ``query`` against ``indexes`` and suggest one when nothing fits.
+
+    Args:
+        indexes: your declared indexes, or ``Index.from_index_information(collection.index_information())``.
+        extra_equality: columns your own code pins outside the parsed filter — a tenant id, a
+            soft-delete flag. They belong at the front of the index, so the advice is wrong
+            without them.
+    """
+    equality: dict[str, None] = {column: None for column in extra_equality}
+    ranges: dict[str, None] = {}
+    warnings: list[str] = []
+    _classify(query.filter, equality, ranges, warnings)
+    for column in ranges:  # a field with both bounds is a range, not an equality
+        equality.pop(column, None)
+
+    sort = list(query.sort)
+    effective_sort = [entry for entry in sort if entry[0] not in equality]
+    suggestion = tuple(
+        [(column, 1) for column in equality]
+        + effective_sort
+        + [(column, 1) for column in ranges if column not in dict(effective_sort)]
+    )
+
+    best: tuple[int, bool] = (0, False)
+    best_index: Index | None = None
+    for index in indexes or []:
+        prefix, sort_ok = _match(index, equality, sort, ranges)
+        usable = prefix > 0 or (index.keys and index.keys[0][0] in ranges)
+        if not usable:
+            continue
+        if (sort_ok, prefix) > (best[1], best[0]):
+            best, best_index = (prefix, sort_ok), index
+
+    ok = best_index is not None and best[1]
+    if best_index is not None and not best[1]:
+        warnings.append(
+            f"{best_index} filters this query but does not provide the sort {Index(effective_sort)}, "
+            "so MongoDB sorts in memory (it aborts past its blocking-sort memory limit, 100 MB by default)"
+        )
+    elif best_index is None and (equality or ranges or effective_sort):
+        warnings.append("no index matches the leading field of this query, so it is a collection scan")
+
+    covered = False
+    if ok and query.projection and all(direction == 1 for direction in query.projection.values()):
+        wanted = set(query.projection) - {"_id"}
+        covered = wanted.issubset(set(best_index.columns))
+
+    return IndexAdvice(
+        ok=ok,
+        index=best_index,
+        covered=covered,
+        warnings=tuple(warnings),
+        suggestion=() if ok else suggestion,
+    )

qsmongo/coerce.py

@@ -0,0 +1,78 @@
+"""String -> typed value conversion.
+
+Everything arriving from a URL is a string. Mongo, however, compares by type: a document with
+``{"age": 21}`` will never match ``{"age": "21"}``. Silent type mismatch is the single most common
+cause of "the filter returns nothing and no one knows why", so coercion is strict and loud.
+"""
+
+from __future__ import annotations
+
+from datetime import date, datetime
+
+from .errors import InvalidValue
+
+try:  # pragma: no cover
+    from bson import ObjectId
+except ImportError:  # pragma: no cover
+    ObjectId = None
+
+TRUE_VALUES = frozenset({"true", "1", "yes", "on"})
+FALSE_VALUES = frozenset({"false", "0", "no", "off"})
+
+
+def _to_bool(raw: str, param: str) -> bool:
+    lowered = raw.strip().lower()
+    if lowered in TRUE_VALUES:
+        return True
+    if lowered in FALSE_VALUES:
+        return False
+    raise InvalidValue(f"{param}: expected a boolean, got {raw!r}", param=param)
+
+
+def _to_datetime(raw: str, param: str) -> datetime:
+    text = raw.strip()
+    # datetime.fromisoformat only learned to accept a trailing "Z" in 3.11; normalise for 3.10.
+    if text.endswith(("Z", "z")):
+        text = f"{text[:-1]}+00:00"
+    try:
+        return datetime.fromisoformat(text)
+    except ValueError:
+        raise InvalidValue(f"{param}: expected an ISO-8601 datetime, got {raw!r}", param=param) from None
+
+
+def _to_date(raw: str, param: str) -> datetime:
+    try:
+        parsed = date.fromisoformat(raw.strip())
+    except ValueError:
+        raise InvalidValue(f"{param}: expected an ISO-8601 date, got {raw!r}", param=param) from None
+    # Mongo has no date type: store dates as midnight datetimes so comparisons behave.
+    return datetime(parsed.year, parsed.month, parsed.day)
+
+
+def _to_object_id(raw: str, param: str):
+    if ObjectId is None:  # pragma: no cover
+        raise InvalidValue(f"{param}: ObjectId fields require pymongo to be installed", param=param)
+    try:
+        return ObjectId(raw.strip())
+    except Exception:
+        raise InvalidValue(f"{param}: expected a 24-character ObjectId, got {raw!r}", param=param) from None
+
+
+def coerce(type_: type, raw: str, param: str):
+    """Convert one raw query-string value to the field's declared type."""
+    if type_ is str:
+        return raw
+    if type_ is bool:
+        return _to_bool(raw, param)
+    if type_ is datetime:
+        return _to_datetime(raw, param)
+    if type_ is date:
+        return _to_date(raw, param)
+    if ObjectId is not None and type_ is ObjectId:
+        return _to_object_id(raw, param)
+    if type_ in (int, float):
+        try:
+            return type_(raw.strip())
+        except ValueError:
+            raise InvalidValue(f"{param}: expected {type_.__name__}, got {raw!r}", param=param) from None
+    raise InvalidValue(f"{param}: no coercion registered for {type_.__name__}", param=param)

qsmongo/cursor.py

@@ -0,0 +1,171 @@
+"""Keyset (cursor) pagination.
+
+``skip``/``limit`` degrades linearly: to serve page 2000 the server walks 100,000 documents it will
+never return. Keyset pagination replaces the skip with a range clause built from the last document
+of the previous page, so every page costs the same as the first — provided the sort is backed by an
+index.
+
+The cursor is opaque to clients and, when a secret is supplied, HMAC-signed so it cannot be forged
+into a filter of the client's choosing.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+from datetime import datetime
+from typing import Any
+
+from .errors import InvalidCursor
+
+try:  # pragma: no cover
+    from bson import ObjectId
+except ImportError:  # pragma: no cover
+    ObjectId = None
+
+_MISSING = object()
+
+
+def _b64encode(raw: bytes) -> str:
+    return base64.urlsafe_b64encode(raw).decode().rstrip("=")
+
+
+def _b64decode(text: str) -> bytes:
+    padding = "=" * (-len(text) % 4)
+    try:
+        return base64.urlsafe_b64decode(text + padding)
+    except Exception:
+        raise InvalidCursor("cursor is not valid base64", param="after") from None
+
+
+def _pack(value: Any) -> list[Any]:
+    """Tag a value with its type so decoding does not need the schema."""
+    if isinstance(value, bool):
+        return ["b", value]
+    if isinstance(value, datetime):
+        return ["d", value.isoformat()]
+    if ObjectId is not None and isinstance(value, ObjectId):
+        return ["o", str(value)]
+    if isinstance(value, (int, float, str)) or value is None:
+        return ["j", value]
+    raise InvalidCursor(f"cannot put {type(value).__name__} in a cursor", param="after")
+
+
+def _unpack(item: Any) -> Any:
+    if not isinstance(item, list) or len(item) != 2:
+        raise InvalidCursor("malformed cursor value", param="after")
+    tag, value = item
+    if tag == "j" or tag == "b":
+        return value
+    if tag == "d":
+        try:
+            return datetime.fromisoformat(value)
+        except (TypeError, ValueError):
+            raise InvalidCursor("malformed datetime in cursor", param="after") from None
+    if tag == "o":
+        if ObjectId is None:  # pragma: no cover
+            raise InvalidCursor("cursor contains an ObjectId but pymongo is not installed", param="after")
+        try:
+            return ObjectId(value)
+        except Exception:
+            raise InvalidCursor("malformed ObjectId in cursor", param="after") from None
+    raise InvalidCursor(f"unknown cursor value type {tag!r}", param="after")
+
+
+def _dig(document: dict, path: str) -> Any:
+    """Read a possibly dotted path out of a document."""
+    current: Any = document
+    for part in path.split("."):
+        if not isinstance(current, dict) or part not in current:
+            return _MISSING
+        current = current[part]
+    return current
+
+
+class Cursors:
+    """Encodes and decodes pagination cursors.
+
+    Args:
+        secret: signing key. Strongly recommended — without it a client can hand-craft a cursor
+            and page from an arbitrary position. Signing does not hide the contents; it only
+            proves the server issued them.
+        id_field: the tiebreaker field appended to every sort so the order is total. Two documents
+            sharing a ``created_at`` would otherwise be able to straddle a page boundary, and one
+            of them would be skipped or repeated.
+    """
+
+    __slots__ = ("_secret", "id_field")
+
+    def __init__(self, secret: bytes | str | None = None, *, id_field: str = "_id"):
+        if isinstance(secret, str):
+            secret = secret.encode()
+        self._secret = secret
+        self.id_field = id_field
+
+    @property
+    def signed(self) -> bool:
+        return self._secret is not None
+
+    def _signature(self, payload: bytes) -> str:
+        return _b64encode(hmac.new(self._secret, payload, hashlib.sha256).digest())
+
+    def encode(self, document: dict, sort: list[tuple[str, int]]) -> str:
+        """Build the cursor that resumes *after* ``document``, given the sort used to fetch it."""
+        values = []
+        for column, _ in sort:
+            value = _dig(document, column)
+            if value is _MISSING:
+                raise InvalidCursor(f"document has no {column!r} to build a cursor from", param="after")
+            values.append(_pack(value))
+        payload = json.dumps(values, separators=(",", ":"), sort_keys=True).encode()
+        token = _b64encode(payload)
+        if self._secret is None:
+            return token
+        return f"{token}.{self._signature(payload)}"
+
+    def decode(self, token: str) -> list[Any]:
+        signature = None
+        if "." in token:
+            token, _, signature = token.partition(".")
+        if self._secret is None:
+            if signature is not None:
+                raise InvalidCursor("cursor is signed but no secret is configured", param="after")
+        else:
+            if signature is None:
+                raise InvalidCursor("cursor is not signed", param="after")
+            if not hmac.compare_digest(self._signature(_b64decode(token)), signature):
+                raise InvalidCursor("cursor signature does not match", param="after")
+        try:
+            values = json.loads(_b64decode(token))
+        except ValueError:
+            raise InvalidCursor("cursor is not valid JSON", param="after") from None
+        if not isinstance(values, list):
+            raise InvalidCursor("cursor payload must be a list", param="after")
+        return [_unpack(item) for item in values]
+
+    def __repr__(self) -> str:  # never leak the secret into a log line
+        return f"Cursors(signed={self.signed}, id_field={self.id_field!r})"
+
+
+def keyset_filter(sort: list[tuple[str, int]], values: list[Any]) -> dict[str, Any]:
+    """Range clause selecting everything strictly after ``values`` in ``sort`` order.
+
+    For ``sort=[("created_at", -1), ("_id", 1)]`` this produces the lexicographic comparison::
+
+        {"$or": [{"created_at": {"$lt": t}},
+                 {"created_at": t, "_id": {"$gt": i}}]}
+    """
+    if len(values) != len(sort):
+        raise InvalidCursor(
+            f"cursor has {len(values)} value(s) but the sort has {len(sort)} field(s); "
+            "the sort must match the one that produced the cursor",
+            param="after",
+        )
+    branches: list[dict[str, Any]] = []
+    for index, (column, direction) in enumerate(sort):
+        clause: dict[str, Any] = {sort[j][0]: values[j] for j in range(index)}
+        clause[column] = {"$gt" if direction == 1 else "$lt": values[index]}
+        branches.append(clause)
+    return branches[0] if len(branches) == 1 else {"$or": branches}

qsmongo/errors.py

@@ -0,0 +1,37 @@
+"""Exceptions raised while parsing a query string.
+
+Every error carries the offending parameter so an API layer can turn it into a useful 400
+response instead of a generic "bad request".
+"""
+
+
+class QSMongoError(ValueError):
+    """Base class for every parse failure."""
+
+    def __init__(self, message: str, *, param: str | None = None):
+        super().__init__(message)
+        self.param = param
+
+
+class UnknownField(QSMongoError):
+    """The query string referenced a field that is not declared in the schema."""
+
+
+class UnsupportedOperator(QSMongoError):
+    """The field exists but does not allow this operator."""
+
+
+class InvalidValue(QSMongoError):
+    """A value could not be coerced to the field's declared type, or conflicts with another clause."""
+
+
+class InvalidPagination(QSMongoError):
+    """page / per_page was not a usable positive integer, or two paging modes were mixed."""
+
+
+class InvalidCursor(QSMongoError):
+    """A keyset cursor was malformed, unsigned, forged, or does not match the requested sort."""
+
+
+class InvalidProjection(QSMongoError):
+    """The requested field selection cannot be turned into a MongoDB projection."""

qsmongo/parser.py

@@ -0,0 +1,279 @@
+"""Query string -> :class:`~qsmongo.query.Query`.
+
+Grammar::
+
+    field=value               equality
+    field__<op>=value         ne gt gte lt lte in nin exists contains startswith endswith regex
+    field__in=a,b,c           comma separated list, "\\," escapes a literal comma
+    fields=name,price         projection (or fields=-secret to exclude)
+    sort=-created_at,name     "-" prefix means descending
+    page=2&per_page=50        offset paging, clamped to max_per_page
+    after=<cursor>&per_page=50  keyset paging, mutually exclusive with page
+
+Field names are matched against a :class:`~qsmongo.schema.Schema`; anything undeclared raises.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+from urllib.parse import parse_qsl
+
+from .coerce import coerce
+from .cursor import Cursors, keyset_filter
+from .errors import (
+    InvalidCursor,
+    InvalidPagination,
+    InvalidProjection,
+    InvalidValue,
+    UnsupportedOperator,
+)
+from .query import Query
+from .schema import Schema
+
+OP_SUFFIXES = {
+    "ne": "$ne",
+    "gt": "$gt",
+    "gte": "$gte",
+    "lt": "$lt",
+    "lte": "$lte",
+    "in": "$in",
+    "nin": "$nin",
+    "regex": "$regex",
+    "exists": "$exists",
+    "contains": "$regex",
+    "startswith": "$regex",
+    "endswith": "$regex",
+}
+LIST_OPS = frozenset({"in", "nin"})
+MAX_REGEX_LENGTH = 200
+
+
+def _split_list(raw: str) -> list[str]:
+    """Split on commas, honouring a backslash escape so values may contain a literal comma."""
+    parts: list[str] = []
+    current: list[str] = []
+    escaped = False
+    for char in raw:
+        if escaped:
+            current.append(char)
+            escaped = False
+        elif char == "\\":
+            escaped = True
+        elif char == ",":
+            parts.append("".join(current))
+            current = []
+        else:
+            current.append(char)
+    if escaped:  # trailing backslash is a literal backslash
+        current.append("\\")
+    parts.append("".join(current))
+    return [p for p in parts if p != ""]
+
+
+def _split_key(key: str) -> tuple[str, str]:
+    """``"age__gte"`` -> ``("age", "gte")``. A field with no known suffix is an equality match."""
+    if "__" in key:
+        field, _, suffix = key.rpartition("__")
+        if field and suffix in OP_SUFFIXES:
+            return field, suffix
+    return key, "eq"
+
+
+def _positive_int(raw: str, param: str) -> int:
+    try:
+        value = int(raw.strip())
+    except ValueError:
+        raise InvalidPagination(f"{param}: expected a positive integer, got {raw!r}", param=param) from None
+    if value < 1:
+        raise InvalidPagination(f"{param}: must be 1 or greater, got {value}", param=param)
+    return value
+
+
+def _parse_sort(raw: str, schema: Schema) -> list[tuple[str, int]]:
+    order: list[tuple[str, int]] = []
+    for token in raw.split(","):
+        token = token.strip()
+        if not token:
+            continue
+        direction = 1
+        if token.startswith("-"):
+            direction = -1
+            token = token[1:]
+        field_def = schema.get(token)  # raises UnknownField
+        if not field_def.sortable:
+            raise UnsupportedOperator(f"field {token!r} is not sortable", param=token)
+        order.append((schema.column(token), direction))
+    return order
+
+
+def _parse_projection(raw: str, schema: Schema) -> dict[str, int]:
+    """``"name,price"`` -> ``{"name": 1, "price": 1}``; ``"-secret"`` -> ``{"secret": 0}``."""
+    include: dict[str, int] = {}
+    exclude: dict[str, int] = {}
+    for token in raw.split(","):
+        token = token.strip()
+        if not token:
+            continue
+        excluded = token.startswith("-")
+        if excluded:
+            token = token[1:]
+        field_def = schema.get(token)  # raises UnknownField
+        if not field_def.projectable:
+            raise UnsupportedOperator(f"field {token!r} cannot be selected", param=token)
+        (exclude if excluded else include)[schema.column(token)] = 0 if excluded else 1
+    if include and exclude:
+        # Mongo rejects mixed projections (only _id may be excluded alongside inclusions), so
+        # catching it here gives a 400 instead of an OperationFailure from the driver.
+        raise InvalidProjection("fields cannot mix included and excluded names; use one or the other", param="fields")
+    return include or exclude
+
+
+def _text_clause(field_def, op: str, raw: str, param: str) -> dict[str, Any]:
+    """contains/startswith/endswith as an escaped pattern — user input is never a pattern."""
+    if not raw:
+        raise InvalidValue(f"{param}: expected a non-empty value", param=param)
+    escaped = re.escape(raw)
+    pattern = {"contains": escaped, "startswith": f"^{escaped}", "endswith": f"{escaped}$"}[op]
+    clause: dict[str, Any] = {"$regex": pattern}
+    if not field_def.case_sensitive:
+        clause["$options"] = "i"
+    return clause
+
+
+def _build_clause(field_def, op: str, raw: str, param: str) -> dict[str, Any]:
+    """Everything except equality, as the operator document Mongo expects."""
+    if op == "exists":
+        return {"$exists": coerce(bool, raw, param)}
+    if op in LIST_OPS:
+        values = [coerce(field_def.type, item, param) for item in _split_list(raw)]
+        if not values:
+            raise InvalidValue(f"{param}: expected at least one value", param=param)
+        return {OP_SUFFIXES[op]: values}
+    if op in ("contains", "startswith", "endswith"):
+        return _text_clause(field_def, op, raw, param)
+    if op == "regex":
+        if len(raw) > MAX_REGEX_LENGTH:
+            raise InvalidValue(f"{param}: pattern exceeds {MAX_REGEX_LENGTH} characters", param=param)
+        return {"$regex": raw}
+    return {OP_SUFFIXES[op]: coerce(field_def.type, raw, param)}
+
+
+def parse(
+    query_string: str,
+    schema: Schema,
+    *,
+    default_per_page: int = 25,
+    max_per_page: int = 100,
+    cursors: Cursors | None = None,
+    page_param: str = "page",
+    per_page_param: str = "per_page",
+    sort_param: str = "sort",
+    fields_param: str = "fields",
+    after_param: str = "after",
+    ignore_unknown: bool = False,
+) -> Query:
+    """Parse ``query_string`` into a :class:`Query` validated against ``schema``.
+
+    Pass ``cursors`` to enable keyset pagination via ``?after=``; without it the parameter is
+    rejected. Set ``ignore_unknown`` to skip undeclared parameters instead of raising — useful when
+    the same URL carries parameters your view consumes (``?include=...``, cache busters).
+    """
+    pairs = parse_qsl(query_string.lstrip("?"), keep_blank_values=True)
+
+    equality: dict[str, tuple[str, list[Any]]] = {}
+    operators: dict[str, dict[str, Any]] = {}
+    sort: list[tuple[str, int]] = []
+    projection: dict[str, int] = {}
+    page: int | None = None
+    per_page = default_per_page
+    after: str | None = None
+
+    for raw_key, raw_value in pairs:
+        key = raw_key.strip()
+        if key == page_param:
+            page = _positive_int(raw_value, page_param)
+            continue
+        if key == per_page_param:
+            per_page = min(_positive_int(raw_value, per_page_param), max_per_page)
+            continue
+        if key == sort_param:
+            sort.extend(_parse_sort(raw_value, schema))
+            continue
+        if key == fields_param:
+            projection.update(_parse_projection(raw_value, schema))
+            continue
+        if key == after_param:
+            after = raw_value
+            continue
+
+        field_name, op = _split_key(key)
+        if ignore_unknown and field_name not in schema:
+            continue
+        field_def = schema.get(field_name)  # raises UnknownField
+        if op not in field_def.ops:
+            raise UnsupportedOperator(
+                f"field {field_name!r} does not support {op!r} (allowed: {sorted(field_def.ops)})", param=key
+            )
+
+        column = schema.column(field_name)
+        if op == "eq":
+            equality.setdefault(column, (field_name, []))[1].append(coerce(field_def.type, raw_value, key))
+            continue
+        clause = _build_clause(field_def, op, raw_value, key)
+        existing = operators.setdefault(column, {})
+        duplicate = set(existing) & set(clause) - {"$options"}
+        if duplicate:
+            raise InvalidValue(
+                f"{field_name!r} was given two {sorted(duplicate)[0]} clauses; combine them into one", param=key
+            )
+        existing.update(clause)
+
+    filter_: dict[str, Any] = {}
+    for column, (field_name, values) in equality.items():
+        if len(values) == 1:
+            filter_[column] = values[0]
+        else:
+            if not schema.get(field_name).multi:
+                raise InvalidValue(
+                    f"{field_name!r} was given {len(values)} values; declare it as Field(..., multi=True) "
+                    "to combine them into an $in",
+                    param=field_name,
+                )
+            filter_[column] = {"$in": values}
+
+    for column, clauses in operators.items():
+        if column in filter_:
+            raise InvalidValue(
+                f"{column!r} has both an equality match and {sorted(clauses)}; use one or the other", param=column
+            )
+        filter_[column] = clauses
+
+    # Every page, not just the ones reached by a cursor, needs a total order: two documents
+    # sharing a sort value could otherwise straddle the boundary and be skipped or repeated.
+    if cursors is not None and not any(column == cursors.id_field for column, _ in sort):
+        sort = [*sort, (cursors.id_field, 1)]
+
+    if after is not None:
+        if page is not None:
+            raise InvalidPagination(
+                f"{after_param} and {page_param} are different pagination modes; send only one", param=after_param
+            )
+        if cursors is None:
+            raise InvalidCursor(
+                f"{after_param} is not enabled; pass cursors=Cursors(...) to parse()", param=after_param
+            )
+        keyset = keyset_filter(sort, cursors.decode(after))
+        filter_ = {"$and": [filter_, keyset]} if filter_ else keyset
+
+    resolved_page = page or 1
+    return Query(
+        filter=filter_,
+        sort=sort,
+        projection=projection or None,
+        skip=0 if after is not None else (resolved_page - 1) * per_page,
+        limit=per_page,
+        page=resolved_page,
+        per_page=per_page,
+        cursors=cursors,
+    )

qsmongo/query.py

@@ -0,0 +1,62 @@
+"""The parse result: a filter, a projection, a sort, and a page window."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from .cursor import Cursors
+from .errors import InvalidCursor
+
+
+@dataclass(frozen=True)
+class Query:
+    """Everything needed to run the request against a collection.
+
+    ``filter`` is a plain Mongo query document, so it composes with anything you already have::
+
+        collection.find({"$and": [tenant_scope, query.filter]})
+    """
+
+    filter: dict[str, Any] = field(default_factory=dict)
+    sort: list[tuple[str, int]] = field(default_factory=list)
+    projection: dict[str, int] | None = None
+    skip: int = 0
+    limit: int = 25
+    page: int = 1
+    per_page: int = 25
+    cursors: Cursors | None = None
+
+    def find_kwargs(self) -> dict[str, Any]:
+        """Keyword arguments for ``collection.find(**query.find_kwargs())``."""
+        kwargs: dict[str, Any] = {"filter": self.filter, "skip": self.skip, "limit": self.limit}
+        if self.sort:
+            kwargs["sort"] = self.sort
+        if self.projection:
+            kwargs["projection"] = self.projection
+        return kwargs
+
+    def pipeline(self) -> list[dict[str, Any]]:
+        """The same query as aggregation stages, for when you need to $lookup afterwards."""
+        stages: list[dict[str, Any]] = [{"$match": self.filter}]
+        if self.sort:
+            stages.append({"$sort": dict(self.sort)})
+        if self.skip:
+            stages.append({"$skip": self.skip})
+        stages.append({"$limit": self.limit})
+        if self.projection:
+            stages.append({"$project": self.projection})
+        return stages
+
+    def next_cursor(self, last_document: dict | None) -> str | None:
+        """Cursor that resumes after ``last_document`` — the final document of this page.
+
+        Returns None for an empty page, which is also how a client knows it has reached the end.
+        Note that the cursor encodes the sort fields, so the next request must repeat the same
+        ``sort``; sending a different one is rejected rather than silently paginating nonsense.
+        """
+        if self.cursors is None:
+            raise InvalidCursor("cursor support is not enabled; pass cursors=Cursors(...) to parse()")
+        if not last_document:
+            return None
+        return self.cursors.encode(last_document, self.sort)

qsmongo/schema.py

@@ -0,0 +1,116 @@
+"""Field declarations — the whitelist that makes parsing safe.
+
+Nothing reaches MongoDB unless it was declared here first. That is the whole security model:
+an undeclared field is an error, never a pass-through.
+"""
+
+from __future__ import annotations
+
+from datetime import date, datetime
+
+from .errors import UnknownField
+
+try:  # pragma: no cover - exercised only when pymongo is installed
+    from bson import ObjectId
+except ImportError:  # pragma: no cover
+    ObjectId = None
+
+COMPARISON_OPS = frozenset({"eq", "ne", "gt", "gte", "lt", "lte", "in", "nin", "exists"})
+EQUALITY_OPS = frozenset({"eq", "ne", "in", "nin", "exists"})
+# Substring matching is offered as three escaped, anchored operators rather than raw regex.
+TEXT_MATCH_OPS = frozenset({"contains", "startswith", "endswith"})
+# "regex" hands the pattern straight to Mongo, so it stays opt-in per field.
+TEXT_OPS = EQUALITY_OPS | TEXT_MATCH_OPS
+ALL_OPS = COMPARISON_OPS | TEXT_MATCH_OPS | {"regex"}
+
+_DEFAULT_OPS: dict[type, frozenset[str]] = {
+    str: TEXT_OPS,
+    int: COMPARISON_OPS,
+    float: COMPARISON_OPS,
+    bool: frozenset({"eq", "ne", "exists"}),
+    datetime: COMPARISON_OPS,
+    date: COMPARISON_OPS,
+}
+
+
+class Field:
+    """One queryable field.
+
+    Args:
+        type_: python type used to coerce incoming strings (str, int, float, bool, datetime, date, ObjectId).
+        ops: operators this field accepts. Defaults to a sensible set for the type.
+        sortable: whether the field may appear in the sort parameter.
+        multi: when True, a repeated key (``tag=a&tag=b``) collapses to ``$in`` instead of erroring.
+        alias: the document field name, when it differs from the name exposed in the API.
+        projectable: whether the field may be requested in the ``fields`` parameter.
+        case_sensitive: applies to contains/startswith/endswith. Case-insensitive matching cannot
+            use an ordinary index, so a case-sensitive ``startswith`` is the only substring
+            operator that stays fast on a large collection.
+
+    A field declared with ``ops=set()`` is not queryable at all — useful when you only want it to
+    be selectable via ``fields``.
+    """
+
+    __slots__ = ("type", "ops", "sortable", "multi", "alias", "projectable", "case_sensitive")
+
+    def __init__(
+        self,
+        type_: type,
+        *,
+        ops: set[str] | frozenset[str] | None = None,
+        sortable: bool = True,
+        multi: bool = False,
+        alias: str | None = None,
+        projectable: bool = True,
+        case_sensitive: bool = False,
+    ):
+        if ops is None:
+            ops = _DEFAULT_OPS.get(type_)
+            if ops is None:
+                ops = EQUALITY_OPS  # ObjectId and anything custom
+        unknown = set(ops) - ALL_OPS
+        if unknown:
+            raise ValueError(f"unknown operator(s) for field: {sorted(unknown)}")
+        if type_ is not str and (set(ops) & (TEXT_MATCH_OPS | {"regex"})):
+            raise ValueError(f"text operators require a str field, got {type_.__name__}")
+        self.type = type_
+        self.ops = frozenset(ops)
+        self.sortable = sortable
+        self.multi = multi
+        self.alias = alias
+        self.projectable = projectable
+        self.case_sensitive = case_sensitive
+
+    def __repr__(self) -> str:
+        return f"Field({self.type.__name__}, ops={sorted(self.ops)}, multi={self.multi})"
+
+
+class Schema:
+    """A whitelist of queryable fields.
+
+    >>> Schema(name=Field(str), age=Field(int))
+    """
+
+    __slots__ = ("fields",)
+
+    def __init__(self, **fields: Field):
+        for name, field in fields.items():
+            if not isinstance(field, Field):
+                raise TypeError(f"{name!r} must be a Field, got {type(field).__name__}")
+        self.fields = fields
+
+    def get(self, name: str) -> Field:
+        try:
+            return self.fields[name]
+        except KeyError:
+            raise UnknownField(f"unknown field {name!r}", param=name) from None
+
+    def column(self, name: str) -> str:
+        """Document field name for an API-facing field name."""
+        return self.get(name).alias or name
+
+    def __contains__(self, name: object) -> bool:
+        return name in self.fields
+
+    def __repr__(self) -> str:
+        return f"Schema({', '.join(self.fields)})"

qsmongo-0.3.0.dist-info/METADATA

@@ -0,0 +1,299 @@
+Metadata-Version: 2.4
+Name: qsmongo
+Version: 0.3.0
+Summary: Turn an HTTP query string into a safe, typed MongoDB filter.
+Project-URL: Homepage, https://github.com/boskodjokic/qsmongo
+Project-URL: Issues, https://github.com/boskodjokic/qsmongo/issues
+Author: Bosko Djokic
+License: MIT License
+        
+        Copyright (c) 2026 Bosko Djokic
+        
+        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.
+License-File: LICENSE
+Keywords: fastapi,filtering,mongodb,pagination,query string
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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 :: Database
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# qsmongo
+
+[![CI](https://github.com/boskodjokic/qsmongo/actions/workflows/ci.yml/badge.svg)](https://github.com/boskodjokic/qsmongo/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+Turn an HTTP query string into a MongoDB query that is **safe by construction** — nothing is
+queryable until you declare it — and **fast by construction**: keyset pagination that costs the
+same on page 10,000 as on page 1.
+
+```
+GET /users?age__gte=21&status__in=active,trial&fields=name,age&sort=-created_at&per_page=50
+```
+
+```python
+from qsmongo import Field, Schema, parse
+
+schema = Schema(
+    name=Field(str),
+    age=Field(int),
+    status=Field(str),
+    created_at=Field(datetime, alias="audit.created"),
+)
+
+query = parse(request.url.query, schema)
+
+query.filter  # {'age': {'$gte': 21}, 'status': {'$in': ['active', 'trial']}}
+query.projection  # {'name': 1, 'age': 1}
+query.sort  # [('audit.created', -1)]
+
+collection.find(**query.find_kwargs())
+```
+
+No dependencies. Python 3.10+.
+
+## Why
+
+Every REST API over MongoDB grows the same ad-hoc filter parser, and it goes wrong in the same
+five ways:
+
+1. **Type mismatch.** `?age=21` gives you the string `"21"`. Mongo does not match `21` against
+   `"21"`, so the endpoint returns an empty list and nobody can tell whether the data is missing or
+   the filter is broken.
+2. **Operator injection.** Passing user input into a query document unfiltered means a crafted
+   parameter can inject `$where` or `$ne` and walk straight past your access checks.
+3. **Separator collisions.** A product genuinely named `Dolce & Gabbana`, a colour called
+   `black and white`, a tag containing a comma — each one quietly truncates the filter.
+4. **Unbounded pages.** `?per_page=100000` is a denial-of-service vector you shipped yourself.
+5. **Offset pagination.** `skip=100000` makes the server walk 100,000 documents it will never
+   return, and when the sort key has ties, documents shift between pages and are skipped or served
+   twice.
+
+## Install
+
+```bash
+pip install qsmongo
+```
+
+## The grammar
+
+| Query string | Result |
+| --- | --- |
+| `name=Ada` | `{"name": "Ada"}` |
+| `age__gte=21` | `{"age": {"$gte": 21}}` |
+| `age__gte=21&age__lt=65` | `{"age": {"$gte": 21, "$lt": 65}}` |
+| `status__in=active,trial` | `{"status": {"$in": ["active", "trial"]}}` |
+| `name__contains=ada` | `{"name": {"$regex": "ada", "$options": "i"}}` |
+| `name__startswith=Ad` | `{"name": {"$regex": "^Ad", "$options": "i"}}` |
+| `deleted_at__exists=false` | `{"deleted_at": {"$exists": False}}` |
+| `fields=name,price` | `{"name": 1, "price": 1}` |
+| `fields=-internal_note` | `{"internal_note": 0}` |
+| `sort=-created_at,name` | `[("created_at", -1), ("name", 1)]` |
+| `page=2&per_page=50` | `skip=50, limit=50` |
+| `after=<cursor>&per_page=50` | keyset range clause, `skip=0` |
+
+Operators: `ne` `gt` `gte` `lt` `lte` `in` `nin` `contains` `startswith` `endswith` `exists`
+`regex`. No suffix means equality.
+
+## Declaring fields
+
+```python
+Schema(
+    name=Field(str),  # eq/ne/in/nin/exists + contains/startswith/endswith
+    age=Field(int),  # numbers also get gt/gte/lt/lte
+    email=Field(str, alias="contact.email"),  # public name differs from the document field
+    tag=Field(str, multi=True),  # ?tag=red&tag=blue -> $in
+    sku=Field(str, case_sensitive=True),  # index-friendly startswith
+    internal_cost=Field(float, projectable=False),  # never selectable via ?fields
+    description=Field(str, ops=set()),  # selectable, never queryable
+    pattern=Field(str, ops={"eq", "regex"}),  # raw regex is opt-in
+)
+```
+
+A field that is not declared cannot be queried, sorted on, projected, or smuggled in as an
+operator — `parse` raises `UnknownField` instead. That whitelist *is* the security model.
+
+## Keyset pagination
+
+Offset paging is fine until it isn't. Pass a `Cursors` codec and clients can page by cursor:
+
+```python
+from qsmongo import Cursors, parse
+
+cursors = Cursors(secret=settings.CURSOR_SECRET)  # HMAC-signed, so clients cannot forge one
+
+query = parse(request.url.query, schema, cursors=cursors)
+items = list(collection.find(**query.find_kwargs()))
+
+return {"items": items, "next": query.next_cursor(items[-1] if items else None)}
+```
+
+The client sends that token back as `?after=<cursor>`, and the skip becomes a range clause:
+
+```python
+{"$or": [{"score": {"$lt": 42}}, {"score": 42, "_id": {"$gt": "abc"}}]}
+```
+
+Details that matter:
+
+- **An `_id` tiebreaker is appended to every sort** when cursors are enabled, so the ordering is
+  total. Without it, two documents sharing a `created_at` can straddle a page boundary and one of
+  them is lost.
+- **Cursors are signed** when you supply a secret, and the secret never appears in a `repr`.
+  Unsigned, tampered, or truncated tokens raise `InvalidCursor`.
+- **The sort must stay the same between pages.** Changing it raises rather than silently
+  paginating nonsense.
+- `after` and `page` are different modes; sending both is an error.
+- Forward-only. Backward paging is not implemented.
+
+[`tests/test_keyset_property.py`](tests/test_keyset_property.py) walks a dataset engineered so that
+every page boundary lands in the middle of a tie, and asserts the pages reconstruct the full
+ordering exactly — no document skipped, none repeated.
+
+## Index advice
+
+A query that parses cleanly can still be a collection scan. `analyze` checks the query against your
+declared indexes using MongoDB's ESR ordering — **E**quality keys first, then **S**ort keys, then
+**R**ange keys — and suggests one when nothing fits:
+
+```python
+from qsmongo import Index, analyze
+
+INDEXES = Index.from_index_information(collection.index_information())
+
+advice = analyze(query, INDEXES, extra_equality=["tenant_id"])
+if not advice.ok:
+    log.warning("unindexed query\n%s", advice)
+```
+
+```
+no index serves this query
+  - {status: 1, price: 1, audit.created: -1} filters this query but does not provide the sort
+    {audit.created: -1}, so MongoDB sorts in memory (it aborts past its blocking-sort memory
+    limit, 100 MB by default)
+  suggested index: {status: 1, audit.created: -1, price: 1}
+```
+
+That example is the classic mistake: `{status, price, created_at}` looks sensible, but the range on
+`price` sits between the equality key and the sort key, so the index stops providing the ordering.
+Swapping the last two fixes it, and nothing about the query itself changes.
+
+It also flags the predicates that cannot use an index at all — case-insensitive or unanchored
+regex, `$ne`/`$nin`, `$exists: false` — reports covered queries, and understands that a sort on a
+field pinned by an equality match is free. `extra_equality` is for the clauses your own code adds
+(a tenant id, a soft-delete flag): they belong at the front of the index, and the advice is wrong
+without them.
+
+**This is a lint, not a query planner.** It reasons about the query shape, not your data
+distribution or the real plan cache. `explain()` remains the only ground truth; this is here to
+catch the obvious problems in CI or a dev-mode log, before they reach a database.
+
+## Safety
+
+- **Keys** are matched against the schema, so `$where=...` or `age__$gt=...` never reach the driver.
+- **Values** are only ever coerced to the declared scalar type. Nothing is `eval`'d or parsed as
+  JSON, so a value of `{"$ne": null}` stays the harmless nine-character string it is.
+- **Substring search is escaped.** `contains` / `startswith` / `endswith` run the value through
+  `re.escape` and anchor it, so `?name__contains=.*` looks for a literal `.*`. Raw `regex` is
+  opt-in per field and length-capped.
+- **`per_page`** is clamped to `max_per_page` (default 100), so a client cannot ask for the
+  collection.
+- **Projection is whitelisted**, so a field marked `projectable=False` cannot be selected even
+  when it is filterable.
+
+Case-insensitive matching cannot use an ordinary index. `case_sensitive=True` drops the `i` option,
+which is what makes `startswith` an index-friendly prefix scan on a large collection.
+
+## Errors
+
+All inherit `QSMongoError` (a `ValueError`) and carry the offending `.param`:
+
+`UnknownField` · `UnsupportedOperator` · `InvalidValue` · `InvalidPagination` · `InvalidCursor` ·
+`InvalidProjection`
+
+```python
+try:
+    query = parse(request.url.query, schema, cursors=cursors)
+except QSMongoError as exc:
+    raise HTTPException(status_code=400, detail={"parameter": exc.param, "error": str(exc)})
+```
+
+See [`examples/fastapi_app.py`](examples/fastapi_app.py) for a complete endpoint.
+
+## Edge cases, on purpose
+
+Covered in [`tests/test_edge_cases.py`](tests/test_edge_cases.py):
+
+- `title=black and white` — the word `and` is a value, not a keyword.
+- `title=Dolce%20%26%20Gabbana` — an encoded `&` stays inside the value.
+- `title=Dolce & Gabbana` — an *unencoded* `&` cannot be recovered by any parser, so it raises
+  rather than silently searching for `Dolce`.
+- `tag__in=red\,blue,green` — a backslash escapes a comma inside a list.
+- `title=black+white` — `+` decodes to a space, per form encoding.
+- `age=` — a blank value on a typed field is an error, not `0`.
+
+## Composing with your own scope
+
+`query.filter` is a plain dict, so multi-tenant scoping stays yours — the library never invents
+clauses on your behalf:
+
+```python
+collection.find({"$and": [{"tenant_id": user.tenant_id}, query.filter]})
+```
+
+Or use the aggregation form when you need `$lookup` afterwards:
+
+```python
+collection.aggregate([*query.pipeline(), {"$lookup": {...}}])
+```
+
+## Prior art
+
+[`mongo-queries-manager`](https://pypi.org/project/mongo-queries-manager/) solves the same problem
+and has more features — projection with `$elemMatch`, `$text`, custom casters. It takes the
+opposite default: every field is queryable unless blacklisted, and types are inferred from the
+value (`5.6` becomes a float, `true` becomes a bool).
+
+Use it if you want breadth, or don't want to declare a schema.
+
+Use `qsmongo` if you want an undeclared field to be an error rather than a silent leak, a numeric
+SKU like `01234` to stay the string it is in your documents, and cursor pagination.
+[`fastapi-filter`](https://pypi.org/project/fastapi-filter/) is also whitelist-based via pydantic
+models, but is coupled to FastAPI and an ODM; `qsmongo` takes a string and returns a dict.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check .
+```
+
+## License
+
+MIT

qsmongo-0.3.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+qsmongo/__init__.py,sha256=PO7w0wG2Wf3cXOMFk9YjjM6xHwzV2TGfBr6YTTCk_yg,941
+qsmongo/advisor.py,sha256=ZJR0agn6bEI2-AgvvOm7VNwgiiJpXRXvzob_acVLzlI,8180
+qsmongo/coerce.py,sha256=w2Ouvy9U9G0NNqmSNJV6gBW3wZRPbamFuTKrPru7bGQ,2837
+qsmongo/cursor.py,sha256=TwGLI01trz_jHH5dZr1tAF0XOk5XgFxKxGTr3y9WC-o,6654
+qsmongo/errors.py,sha256=etwbbsUCLycCJ01rIrCXlZUt7vUTcK7F7i2UCp9A6-U,1154
+qsmongo/parser.py,sha256=UMOD2XHOTQevVmcSkhbkDAVrdNc6GgGnpBF6l5RT2kI,10355
+qsmongo/query.py,sha256=3nqdQ6CKZyGTPy2P3AIJabYS0knukn2eJP0Uzhd9OFs,2398
+qsmongo/schema.py,sha256=LCKvWXhxaZD8ilH3OrLdBwpUc1xj_nDITZ4LTFayjrg,4284
+qsmongo-0.3.0.dist-info/METADATA,sha256=oCS1PjFkJcO-v9uItC1ZsWkPDhEzITmSdU0zmTKQfv8,12597
+qsmongo-0.3.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+qsmongo-0.3.0.dist-info/licenses/LICENSE,sha256=bIQgMfVLAHq7LdY5FIYUi1I5XlO77i01JnXhYq5esso,1069
+qsmongo-0.3.0.dist-info/RECORD,,

qsmongo-0.3.0.dist-info/WHEEL

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

qsmongo-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bosko Djokic
+
+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.