velocity-python 0.1.117__tar.gz → 0.1.120__tar.gz

{velocity_python-0.1.117/src/velocity_python.egg-info → velocity_python-0.1.120}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.1.117
+Version: 0.1.120
 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.117 → velocity_python-0.1.120}/pyproject.toml

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

{velocity_python-0.1.117 → velocity_python-0.1.120}/src/velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.1.117"
+__version__ = version = "0.1.120"
 
 import importlib as _importlib
 

{velocity_python-0.1.117 → velocity_python-0.1.120}/src/velocity/aws/facets.py

@@ -18,6 +18,8 @@ The wire shape is one list under ``params.facets``::
       {"field": "internal_date",   "kind": "since",    "value": "30d"},
       {"field": "from_domain",     "kind": "text",     "value": "example.com",
                                                         "match": "contains"},
+      {"field": "from_domain",     "kind": "domain",   "values": ["example.com"],
+                                                        "exclude": true},
     ]
 
 Facets AND together; the values of one facet OR together. Kinds:
@@ -34,7 +36,17 @@ Facets AND together; the values of one facet OR together. Kinds:
               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.
+              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.
+``domain``    a domain and every subdomain of it: each value (``example.com``)
+              matches ``field`` equal to it or ending in ``.example.com``,
+              case-insensitively; values OR together. "This top-level
+              domain", from a cell that reads ``em1.mail.example.com``.
+
+Any facet may carry ``"exclude": true``: its predicate is negated, NULL-safe
+— ``NOT COALESCE((…), false)`` — so a row the predicate cannot judge (the
+column is NULL) is kept, not hidden. "Hide everything from this domain."
 
 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
@@ -47,7 +59,7 @@ no column types are needed here.
 from __future__ import annotations
 
 import re
-from typing import Any, Dict, List, Optional, Sequence, Tuple
+from typing import Any, Dict, List, Optional, Tuple
 
 # The SQL emitted here is PostgreSQL's (jsonb ``@>``, ``make_interval``,
 # ``ILIKE``), and importing the postgres SQL module is what fills in
@@ -57,11 +69,12 @@ from velocity.db.servers.tablehelper import TableHelper
 
 PARAM_KEY = "facets"
 
-KINDS = ("values", "contains", "presence", "since", "text")
+KINDS = ("values", "contains", "presence", "since", "text", "domain")
 MATCHES = ("contains", "equals", "starts")
 PRESENCE = ("present", "absent")
 
 MAX_FACETS = 40
+MAX_FIELDS = 10
 MAX_VALUES = 200
 MAX_VALUE_CHARS = 500
 MAX_DAYS = 3660
@@ -183,6 +196,27 @@ def _kind_since(column: str, entry: Dict[str, Any], field: str) -> Optional[Pred
     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:
@@ -196,7 +230,30 @@ def _kind_text(column: str, entry: Dict[str, Any], field: str) -> Optional[Predi
         "starts": f"{escaped}%",
         "equals": escaped,
     }[match]
-    return f"{column}::text ILIKE %s", (pattern,)
+    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)
+
+
+def _kind_domain(column: str, entry: Dict[str, Any], field: str) -> Optional[Predicate]:
+    parts: List[str] = []
+    params: List[str] = []
+    for value in _values(entry, field):
+        domain = value.strip().lower().strip(".")
+        if not domain:
+            continue
+        if "@" in domain or any(ch.isspace() for ch in domain):
+            raise FacetError(f"facet {field}: {value!r} is not a domain")
+        escaped = _LIKE_SPECIAL.sub(r"\\\1", domain)
+        parts.append(f"({column}::text ILIKE %s OR {column}::text ILIKE %s)")
+        params.extend((escaped, f"%.{escaped}"))
+    if not parts:
+        return None
+    if len(parts) == 1:
+        return parts[0], tuple(params)
+    return f"({' OR '.join(parts)})", tuple(params)
 
 
 _BUILDERS = {
@@ -205,6 +262,7 @@ _BUILDERS = {
     "presence": _kind_presence,
     "since": _kind_since,
     "text": _kind_text,
+    "domain": _kind_domain,
 }
 
 
@@ -216,8 +274,17 @@ def predicate(entry: Any) -> Optional[Predicate]:
     kind = str(entry.get("kind") or "values").lower()
     if kind not in _BUILDERS:
         raise FacetError(f"facet {field}: unknown kind {kind!r}")
+    exclude = entry.get("exclude", False)
+    if not isinstance(exclude, bool):
+        raise FacetError(f"facet {field}: 'exclude' must be true or false")
     column = TableHelper.quote(field)
-    return _BUILDERS[kind](column, entry, field)
+    built = _BUILDERS[kind](column, entry, field)
+    if built is None or not exclude:
+        return built
+    sql, params = built
+    # NULL-safe negation: a NULL column makes the inner predicate NULL, and
+    # plain NOT would drop the row; COALESCE keeps it.
+    return f"NOT COALESCE(({sql}), false)", params
 
 
 def build_where(facets: Any) -> Optional[Predicate]:

{velocity_python-0.1.117 → velocity_python-0.1.120/src/velocity_python.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.1.117
+Version: 0.1.120
 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.117 → velocity_python-0.1.120}/tests/test_facets.py

@@ -81,6 +81,91 @@ def test_text_matches_are_case_insensitive_and_escape_like_wildcards():
         facets.predicate({"field": "x", "kind": "text", "value": "a", "match": "regex"})
 
 
+def test_text_over_several_fields_ors_one_term_across_them():
+    sql, params = facets.predicate(
+        {
+            "field": "subject",
+            "kind": "text",
+            "value": "invoice",
+            "fields": ["subject", "snippet"],
+        }
+    )
+    assert sql == "(subject::text ILIKE %s OR snippet::text ILIKE %s)"
+    assert params == ("%invoice%", "%invoice%")
+    # one field, or the facet's own field, is the plain form
+    assert facets.predicate(
+        {"field": "subject", "kind": "text", "value": "x", "fields": ["snippet"]}
+    ) == ("snippet::text ILIKE %s", ("%x%",))
+    assert facets.predicate(
+        {"field": "subject", "kind": "text", "value": "x", "fields": []}
+    ) == (
+        "subject::text ILIKE %s",
+        ("%x%",),
+    )
+    # duplicates collapse, reserved words are quoted, junk is refused
+    sql, _params = facets.predicate(
+        {"field": "a", "kind": "text", "value": "x", "fields": ["order", "order", "b"]}
+    )
+    assert sql == '("order"::text ILIKE %s OR b::text ILIKE %s)'
+    for fields in ("subject", ["subject; drop"], [1], ["a"] * (facets.MAX_FIELDS + 1)):
+        with pytest.raises(facets.FacetError):
+            facets.predicate(
+                {"field": "a", "kind": "text", "value": "x", "fields": fields}
+            )
+
+
+def test_domain_matches_the_domain_and_every_subdomain_case_insensitively():
+    assert facets.predicate(
+        {"field": "from_domain", "kind": "domain", "values": ["Example.com"]}
+    ) == (
+        "(from_domain::text ILIKE %s OR from_domain::text ILIKE %s)",
+        ("example.com", "%.example.com"),
+    )
+    sql, params = facets.predicate(
+        {"field": "from_domain", "kind": "domain", "values": ["a.com", ".b.org."]}
+    )
+    assert sql == (
+        "((from_domain::text ILIKE %s OR from_domain::text ILIKE %s) OR "
+        "(from_domain::text ILIKE %s OR from_domain::text ILIKE %s))"
+    )
+    assert params == ("a.com", "%.a.com", "b.org", "%.b.org")
+    # LIKE wildcards in a value are literal characters
+    _sql, params = facets.predicate(
+        {"field": "d", "kind": "domain", "values": ["100%_x.com"]}
+    )
+    assert params == ("100\\%\\_x.com", "%.100\\%\\_x.com")
+
+
+def test_domain_refuses_an_address_or_whitespace_and_ignores_blanks():
+    for bad in ("user@example.com", "two words.com", "a\tb.com"):
+        with pytest.raises(facets.FacetError):
+            facets.predicate({"field": "d", "kind": "domain", "values": [bad]})
+    assert facets.predicate({"field": "d", "kind": "domain", "values": ["", ".", "  "]}) is None
+
+
+def test_exclude_negates_null_safely_for_any_kind():
+    assert facets.predicate(
+        {"field": "from_address", "values": ["test@example.com"], "exclude": True}
+    ) == ("NOT COALESCE((from_address = %s), false)", ("test@example.com",))
+    assert facets.predicate(
+        {"field": "from_domain", "kind": "domain", "values": ["y.com"], "exclude": True}
+    ) == (
+        "NOT COALESCE(((from_domain::text ILIKE %s OR from_domain::text ILIKE %s)), false)",
+        ("y.com", "%.y.com"),
+    )
+    assert facets.predicate(
+        {"field": "subject", "kind": "text", "value": "spam", "exclude": True}
+    ) == ("NOT COALESCE((subject::text ILIKE %s), false)", ("%spam%",))
+    # the flag is explicit: false and absent are the plain predicate
+    plain = facets.predicate({"field": "a", "values": ["1"]})
+    assert facets.predicate({"field": "a", "values": ["1"], "exclude": False}) == plain
+    # nothing selected excludes nothing
+    assert facets.predicate({"field": "a", "values": [], "exclude": True}) is None
+    for bad in ("true", 1, None):
+        with pytest.raises(facets.FacetError):
+            facets.predicate({"field": "a", "values": ["1"], "exclude": bad})
+
+
 def test_an_empty_selection_is_no_predicate_not_an_error():
     for entry in (
         {"field": "a", "values": []},
@@ -89,6 +174,7 @@ def test_an_empty_selection_is_no_predicate_not_an_error():
         {"field": "a", "kind": "presence", "value": ""},
         {"field": "a", "kind": "since", "value": None},
         {"field": "a", "kind": "text", "value": "   "},
+        {"field": "a", "kind": "domain", "values": []},
     ):
         assert facets.predicate(entry) is None
     assert facets.build_where([{"field": "a", "values": []}]) is None