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

{velocity_python-0.1.118 → velocity_python-0.1.121}/PKG-INFO

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

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

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

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

{velocity_python-0.1.118 → velocity_python-0.1.121}/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:
@@ -33,10 +35,21 @@ Facets AND together; the values of one facet OR together. Kinds:
               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``.
+              ``match`` is ``contains`` (default), ``equals``, ``starts`` or
+              ``words`` — every whitespace-separated word of the term must
+              appear, in any order ("school rock" finds "School of Rock").
               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.
+              that searches subject *or* snippet; for ``words`` each word may
+              be in either column.
+``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
@@ -49,7 +62,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
@@ -59,8 +72,8 @@ from velocity.db.servers.tablehelper import TableHelper
 
 PARAM_KEY = "facets"
 
-KINDS = ("values", "contains", "presence", "since", "text")
-MATCHES = ("contains", "equals", "starts")
+KINDS = ("values", "contains", "presence", "since", "text", "domain")
+MATCHES = ("contains", "equals", "starts", "words")
 PRESENCE = ("present", "absent")
 
 MAX_FACETS = 40
@@ -214,17 +227,54 @@ def _kind_text(column: str, entry: Dict[str, Any], field: str) -> Optional[Predi
     match = str(entry.get("match") or "contains").lower()
     if match not in MATCHES:
         raise FacetError(f"facet {field}: match must be one of {MATCHES}")
+    columns = _columns(entry, column, field)
+
+    def like_any(pattern: str) -> Predicate:
+        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)
+
+    if match == "words":
+        words: List[str] = []
+        for word in value.split():
+            if word not in words:
+                words.append(word)
+        built = []
+        for word in words:
+            escaped_word = _LIKE_SPECIAL.sub(r"\\\1", word)
+            built.append(like_any(f"%{escaped_word}%"))
+        if len(built) == 1:
+            return built[0]
+        sql = " AND ".join(part for part, _ in built)
+        return f"({sql})", tuple(p for _, params in built for p in params)
+
     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)
+    return like_any(pattern)
+
+
+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 = {
@@ -233,6 +283,7 @@ _BUILDERS = {
     "presence": _kind_presence,
     "since": _kind_since,
     "text": _kind_text,
+    "domain": _kind_domain,
 }
 
 
@@ -244,8 +295,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.118 → velocity_python-0.1.121}/src/velocity_python.egg-info/PKG-INFO

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

@@ -81,6 +81,39 @@ def test_text_matches_are_case_insensitive_and_escape_like_wildcards():
         facets.predicate({"field": "x", "kind": "text", "value": "a", "match": "regex"})
 
 
+def test_words_match_requires_every_word_in_any_order():
+    assert facets.predicate(
+        {"field": "subject", "kind": "text", "value": "school rock", "match": "words"}
+    ) == (
+        "(subject::text ILIKE %s AND subject::text ILIKE %s)",
+        ("%school%", "%rock%"),
+    )
+    # one word is the plain contains form; repeats and extra whitespace collapse
+    assert facets.predicate(
+        {"field": "subject", "kind": "text", "value": "  rock  rock ", "match": "words"}
+    ) == ("subject::text ILIKE %s", ("%rock%",))
+    # over several columns each word may sit in either one
+    sql, params = facets.predicate(
+        {
+            "field": "subject",
+            "kind": "text",
+            "value": "school rock",
+            "match": "words",
+            "fields": ["subject", "snippet"],
+        }
+    )
+    assert sql == (
+        "((subject::text ILIKE %s OR snippet::text ILIKE %s) AND "
+        "(subject::text ILIKE %s OR snippet::text ILIKE %s))"
+    )
+    assert params == ("%school%", "%school%", "%rock%", "%rock%")
+    # the user's wildcards stay literal per word
+    _sql, params = facets.predicate(
+        {"field": "s", "kind": "text", "value": "50%_off now", "match": "words"}
+    )
+    assert params == ("%50\\%\\_off%", "%now%")
+
+
 def test_text_over_several_fields_ors_one_term_across_them():
     sql, params = facets.predicate(
         {
@@ -114,6 +147,58 @@ def test_text_over_several_fields_ors_one_term_across_them():
             )
 
 
+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": []},
@@ -122,6 +207,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