velocity-python 0.1.116__tar.gz → 0.1.118__tar.gz

{velocity_python-0.1.116/src/velocity_python.egg-info → velocity_python-0.1.118}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.1.116
+Version: 0.1.118
 Summary: A rapid application development library for interfacing with data storage
 Author-email: Velocity Team <info@codeclubs.org>
 License-Expression: MIT

{velocity_python-0.1.116 → velocity_python-0.1.118}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "velocity-python"
-version = "0.1.116"
+version = "0.1.118"
 authors = [
   { name="Velocity Team", email="info@codeclubs.org" },
 ]

{velocity_python-0.1.116 → velocity_python-0.1.118}/src/velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.1.116"
+__version__ = version = "0.1.118"
 
 import importlib as _importlib
 

velocity_python-0.1.118/src/velocity/aws/facets.py

@@ -0,0 +1,342 @@
+"""Structured grid facets: the client says WHAT it selected, this builds the SQL.
+
+A server-side grid used to filter by sending SQL it had built in the browser
+(``params.where``). Facets — the pick-lists and write-in boxes on a grid's
+toolbar — are the first filter to move off that path: the client sends the
+selection as data (``params.facets``) and :func:`build_where` turns it into a
+parameterized predicate here, with the field names whitelisted as plain
+identifiers and every value bound as a parameter. ``params.where`` keeps
+working unchanged alongside it (the toolbar search and the column filters
+still arrive that way); the two are AND'ed by :func:`apply_to_params`.
+
+The wire shape is one list under ``params.facets``::
+
+    [
+      {"field": "has_attachments", "kind": "values",   "values": ["true"]},
+      {"field": "label_ids",       "kind": "contains", "values": ["INBOX", "SENT"]},
+      {"field": "deleted_at",      "kind": "presence", "value": "present"},
+      {"field": "internal_date",   "kind": "since",    "value": "30d"},
+      {"field": "from_domain",     "kind": "text",     "value": "example.com",
+                                                        "match": "contains"},
+    ]
+
+Facets AND together; the values of one facet OR together. Kinds:
+
+``values``    ``field IN (…)`` — a pick-list over a column's own values (or a
+              lookup table's ids). The default when ``kind`` is missing.
+``contains``  membership in a JSON array column: ``field @> '["x"]'::jsonb``,
+              OR'd per value. For ``jsonb`` columns only.
+``presence``  ``value`` is ``present`` or ``absent``: NULL *or empty string*
+              counts as absent, whatever the column type
+              (``NULLIF(field::text, '')``).
+``since``     a period ending now: ``today``, ``Nd`` (``7d``, ``30d`` …, up to
+              3660 days), ``year`` (this calendar year). Evaluated in the
+              database's session time zone.
+``text``      a write-in, case-insensitive, against ``field::text``:
+              ``match`` is ``contains`` (default), ``equals`` or ``starts``.
+              The user's ``%`` and ``_`` are literal. With ``fields`` (a list
+              of columns) the term is matched against each, OR'd — one box
+              that searches subject *or* snippet.
+
+Anything malformed — an unknown kind, a field that is not a bare identifier,
+too many or too long values — raises :class:`FacetError` rather than being
+dropped: a silently ignored facet would show rows as filtered when they are
+not. Strings are bound as parameters and PostgreSQL infers their type from the
+column (a ``'3'`` parameter compares to a bigint, ``'true'`` to a boolean), so
+no column types are needed here.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Dict, List, Optional, Sequence, Tuple
+
+# The SQL emitted here is PostgreSQL's (jsonb ``@>``, ``make_interval``,
+# ``ILIKE``), and importing the postgres SQL module is what fills in
+# TableHelper's reserved-word list, so a column called ``order`` is quoted.
+import velocity.db.servers.postgres.sql  # noqa: F401
+from velocity.db.servers.tablehelper import TableHelper
+
+PARAM_KEY = "facets"
+
+KINDS = ("values", "contains", "presence", "since", "text")
+MATCHES = ("contains", "equals", "starts")
+PRESENCE = ("present", "absent")
+
+MAX_FACETS = 40
+MAX_FIELDS = 10
+MAX_VALUES = 200
+MAX_VALUE_CHARS = 500
+MAX_DAYS = 3660
+
+_IDENTIFIER = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+_DAYS = re.compile(r"^(\d{1,4})d$")
+_LIKE_SPECIAL = re.compile(r"([\\%_])")
+
+Predicate = Tuple[str, Tuple[Any, ...]]
+
+
+class FacetError(ValueError):
+    """A facet the client sent cannot be turned into SQL."""
+
+
+# ── validation ────────────────────────────────────────────────────────────────
+
+
+def _field(entry: Dict[str, Any]) -> str:
+    field = entry.get("field")
+    if not isinstance(field, str) or not _IDENTIFIER.match(field):
+        raise FacetError(f"facet field must be a column name, got {field!r}")
+    return field
+
+
+def _scalar(value: Any, field: str) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (int, float)) and not isinstance(value, bool):
+        return str(value)
+    if not isinstance(value, str):
+        raise FacetError(f"facet {field}: values must be strings, got {value!r}")
+    if len(value) > MAX_VALUE_CHARS:
+        raise FacetError(
+            f"facet {field}: a value is longer than {MAX_VALUE_CHARS} characters"
+        )
+    return value
+
+
+def _values(entry: Dict[str, Any], field: str) -> List[str]:
+    raw = entry.get("values")
+    if raw is None and "value" in entry:
+        raw = [entry["value"]]
+    if not isinstance(raw, (list, tuple)):
+        raise FacetError(f"facet {field}: 'values' must be a list")
+    if len(raw) > MAX_VALUES:
+        raise FacetError(f"facet {field}: more than {MAX_VALUES} values")
+    seen, out = set(), []
+    for item in raw:
+        value = _scalar(item, field)
+        if value == "" or value in seen:
+            continue
+        seen.add(value)
+        out.append(value)
+    return out
+
+
+def _one(entry: Dict[str, Any], field: str) -> str:
+    raw = entry.get("value")
+    if raw is None:
+        values = entry.get("values")
+        raw = values[0] if isinstance(values, (list, tuple)) and values else None
+    if raw is None:
+        return ""
+    return _scalar(raw, field).strip()
+
+
+# ── one facet -> one predicate ────────────────────────────────────────────────
+
+
+def _kind_values(column: str, entry: Dict[str, Any], field: str) -> Optional[Predicate]:
+    values = _values(entry, field)
+    if not values:
+        return None
+    if len(values) == 1:
+        return f"{column} = %s", (values[0],)
+    return f"{column} IN ({', '.join(['%s'] * len(values))})", tuple(values)
+
+
+def _kind_contains(
+    column: str, entry: Dict[str, Any], field: str
+) -> Optional[Predicate]:
+    import json
+
+    values = _values(entry, field)
+    if not values:
+        return None
+    parts = [f"{column} @> %s::jsonb" for _ in values]
+    params = tuple(json.dumps([value]) for value in values)
+    return f"({' OR '.join(parts)})", params
+
+
+def _kind_presence(
+    column: str, entry: Dict[str, Any], field: str
+) -> Optional[Predicate]:
+    value = _one(entry, field).lower()
+    if not value:
+        return None
+    if value not in PRESENCE:
+        raise FacetError(f"facet {field}: presence must be one of {PRESENCE}")
+    test = "IS NOT NULL" if value == "present" else "IS NULL"
+    return f"NULLIF({column}::text, '') {test}", ()
+
+
+def _kind_since(column: str, entry: Dict[str, Any], field: str) -> Optional[Predicate]:
+    value = _one(entry, field).lower()
+    if not value:
+        return None
+    if value == "today":
+        return f"{column} >= date_trunc('day', now())", ()
+    if value == "year":
+        return f"{column} >= date_trunc('year', now())", ()
+    match = _DAYS.match(value)
+    if not match:
+        raise FacetError(f"facet {field}: period must be today, <N>d or year")
+    days = int(match.group(1))
+    if not 1 <= days <= MAX_DAYS:
+        raise FacetError(f"facet {field}: period must be 1 to {MAX_DAYS} days")
+    return f"{column} >= now() - make_interval(days => %s)", (days,)
+
+
+def _columns(entry: Dict[str, Any], column: str, field: str) -> List[str]:
+    """The column(s) a text facet matches: ``fields`` when given, else the field."""
+    fields = entry.get("fields")
+    if fields in (None, "", []):
+        return [column]
+    if not isinstance(fields, (list, tuple)):
+        raise FacetError(f"facet {field}: 'fields' must be a list of column names")
+    if len(fields) > MAX_FIELDS:
+        raise FacetError(f"facet {field}: more than {MAX_FIELDS} fields")
+    out = []
+    for name in fields:
+        if not isinstance(name, str) or not _IDENTIFIER.match(name):
+            raise FacetError(
+                f"facet {field}: fields must be column names, got {name!r}"
+            )
+        quoted = TableHelper.quote(name)
+        if quoted not in out:
+            out.append(quoted)
+    return out
+
+
+def _kind_text(column: str, entry: Dict[str, Any], field: str) -> Optional[Predicate]:
+    value = _one(entry, field)
+    if not value:
+        return None
+    match = str(entry.get("match") or "contains").lower()
+    if match not in MATCHES:
+        raise FacetError(f"facet {field}: match must be one of {MATCHES}")
+    escaped = _LIKE_SPECIAL.sub(r"\\\1", value)
+    pattern = {
+        "contains": f"%{escaped}%",
+        "starts": f"{escaped}%",
+        "equals": escaped,
+    }[match]
+    columns = _columns(entry, column, field)
+    if len(columns) == 1:
+        return f"{columns[0]}::text ILIKE %s", (pattern,)
+    parts = " OR ".join(f"{name}::text ILIKE %s" for name in columns)
+    return f"({parts})", tuple(pattern for _ in columns)
+
+
+_BUILDERS = {
+    "values": _kind_values,
+    "contains": _kind_contains,
+    "presence": _kind_presence,
+    "since": _kind_since,
+    "text": _kind_text,
+}
+
+
+def predicate(entry: Any) -> Optional[Predicate]:
+    """``(sql, params)`` for one facet entry, or None when it selects nothing."""
+    if not isinstance(entry, dict):
+        raise FacetError(f"a facet must be an object, got {type(entry).__name__}")
+    field = _field(entry)
+    kind = str(entry.get("kind") or "values").lower()
+    if kind not in _BUILDERS:
+        raise FacetError(f"facet {field}: unknown kind {kind!r}")
+    column = TableHelper.quote(field)
+    return _BUILDERS[kind](column, entry, field)
+
+
+def build_where(facets: Any) -> Optional[Predicate]:
+    """``(sql, params)`` AND-ing every facet, or None when none selects anything."""
+    if facets in (None, "", [], ()):
+        return None
+    if not isinstance(facets, (list, tuple)):
+        raise FacetError("'facets' must be a list")
+    if len(facets) > MAX_FACETS:
+        raise FacetError(f"more than {MAX_FACETS} facets")
+    parts: List[str] = []
+    params: List[Any] = []
+    for entry in facets:
+        built = predicate(entry)
+        if built is None:
+            continue
+        sql, values = built
+        parts.append(sql)
+        params.extend(values)
+    if not parts:
+        return None
+    return " AND ".join(parts), tuple(params)
+
+
+# ── folding into a query's params ─────────────────────────────────────────────
+
+
+def _existing_predicates(tx, table: str, where: Any) -> List[Predicate]:
+    """The caller's ``where`` as ``(sql, params)`` predicates, whatever its shape."""
+    if where in (None, "", {}, [], ()):
+        return []
+    if isinstance(where, str):
+        clause = where.strip()
+        if clause.upper().startswith("WHERE "):
+            clause = clause[6:].strip()
+        if not clause:
+            return []
+        # The string travelled without parameters, so its literal ``%`` (an
+        # ``ilike '%x%'`` from the toolbar search) never met the driver's
+        # placeholder parser. Joined to a parameterized predicate it does:
+        # every literal ``%`` must become ``%%`` (found on demo, 2026-09-21).
+        return [(f"({clause.replace('%', '%%')})", ())]
+    if isinstance(where, dict):
+        helper = TableHelper(tx, table)
+        return [
+            (
+                sql,
+                (
+                    ()
+                    if value is None
+                    else (value if isinstance(value, tuple) else (value,))
+                ),
+            )
+            for sql, value in (
+                helper.make_predicate(key, val) for key, val in where.items()
+            )
+        ]
+    if isinstance(where, (list, tuple)):
+        out: List[Predicate] = []
+        for item in where:
+            if not isinstance(item, (list, tuple)) or len(item) != 2:
+                raise FacetError(f"where predicate must be (sql, params), got {item!r}")
+            sql, value = item
+            out.append(
+                (
+                    sql,
+                    (
+                        ()
+                        if value is None
+                        else (value if isinstance(value, tuple) else (value,))
+                    ),
+                )
+            )
+        return out
+    raise FacetError(f"unsupported where shape: {type(where).__name__}")
+
+
+def apply_to_params(tx, table: str, params: Optional[Dict[str, Any]]) -> Dict[str, Any]:
+    """Fold ``params['facets']`` into ``params['where']``; drop the key.
+
+    Returns a new dict. With no facets the params come back unchanged (the
+    same ``where`` object), so callers without facets see no difference.
+    """
+    if not isinstance(params, dict) or PARAM_KEY not in params:
+        return params if isinstance(params, dict) else {}
+    out = dict(params)
+    facets = out.pop(PARAM_KEY)
+    built = build_where(facets)
+    if built is None:
+        return out
+    predicates = _existing_predicates(tx, table, out.get("where"))
+    predicates.append(built)
+    out["where"] = predicates
+    return out

{velocity_python-0.1.116 → velocity_python-0.1.118}/src/velocity/aws/handlers/mixins/data_service.py

@@ -16,6 +16,7 @@ import xml.etree.ElementTree as ET
 from io import BytesIO, StringIO
 
 from velocity.aws import dirty_pipeline, ssm_config
+from velocity.aws import facets
 from velocity.aws.handlers.exceptions import AlertError
 from velocity.db.exceptions import DbDataIntegrityError
 from velocity.misc import export
@@ -409,7 +410,10 @@ class DataServiceMixin:
     def query_hook(self, tx, table, payload, context):
         self._call_rwx_hook("before_query", "common", tx, table, payload, context)
         self._call_rwx_hook("before_query", table, tx, table, payload, context)
-        params = payload.get("params", {})
+        # Structured facet selections (params.facets) become a parameterized
+        # predicate AND'ed onto params.where — here, once, so the rows, the
+        # count and every later use of ``params`` see the same filter.
+        params = facets.apply_to_params(tx, table, payload.get("params", {}))
         result_format = payload.get("result_format")
 
         # Clear any previous swallowed-error details so we only report errors

{velocity_python-0.1.116 → velocity_python-0.1.118/src/velocity_python.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.1.116
+Version: 0.1.118
 Summary: A rapid application development library for interfacing with data storage
 Author-email: Velocity Team <info@codeclubs.org>
 License-Expression: MIT

{velocity_python-0.1.116 → velocity_python-0.1.118}/src/velocity_python.egg-info/SOURCES.txt

@@ -10,6 +10,7 @@ src/velocity/aws/amplify_build.py
 src/velocity/aws/blobs.py
 src/velocity/aws/dirty_pipeline.py
 src/velocity/aws/email.py
+src/velocity/aws/facets.py
 src/velocity/aws/feature_flags.py
 src/velocity/aws/job_lifecycle.py
 src/velocity/aws/job_results.py
@@ -233,6 +234,7 @@ tests/test_delete_hook_fk_blocked.py
 tests/test_dirty_pipeline_fast_path.py
 tests/test_email_processing.py
 tests/test_enqueue_send_failures.py
+tests/test_facets.py
 tests/test_feature_flags.py
 tests/test_get_cognito_user_provider.py
 tests/test_http_handler_rollback.py