velocity-python 0.2.5__tar.gz → 0.2.7__tar.gz

{velocity_python-0.2.5/src/velocity_python.egg-info → velocity_python-0.2.7}/PKG-INFO

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

{velocity_python-0.2.5 → velocity_python-0.2.7}/pyproject.toml

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

{velocity_python-0.2.5 → velocity_python-0.2.7}/src/velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.2.5"
+__version__ = version = "0.2.7"
 
 import importlib as _importlib
 

{velocity_python-0.2.5 → velocity_python-0.2.7}/src/velocity/aws/failures.py

@@ -61,6 +61,13 @@ logger = logging.getLogger(__name__)
 EVENT_TYPE = "velocity.failure"
 EVENT_VERSION = 1
 TOPIC_CONFIG_KEY = "FailureTopicArn"
+# Where a person reads failures (a failure inbox screen); the email links it.
+INBOX_CONFIG_KEY = "FailureInboxUrl"
+# The site's IANA zone; the email shows when it happened there.
+TIMEZONE_CONFIG_KEY = "SiteTimezone"
+# SNS caps an email subject at 100 characters of plain ASCII.
+EMAIL_SUBJECT_LIMIT = 100
+SUMMARY_LIMIT = 300
 SOURCES = frozenset({"queue", "scheduler", "web", "webhook", "job"})
 
 MESSAGE_LIMIT = 1000
@@ -541,10 +548,17 @@ def build_event(
         "log_group": f"/aws/lambda/{function}" if function else None,
         "log_stream": os.environ.get("AWS_LAMBDA_LOG_STREAM_NAME") or None,
         "classification": None,
+        # for people (render_text / the alert email): where it failed, a
+        # one-line summary and what to do, from the exception's `summary` /
+        # `hint` attributes or `extra`
+        "where": frame or None,
+        "summary": _person_text(exc, extra, "summary", keys),
+        "hint": _person_text(exc, extra, "hint", keys),
     }
     if extra:
         event["extra"] = payload_excerpt(
-            {k: v for k, v in extra.items() if k != "message"}, keys
+            {k: v for k, v in extra.items() if k not in ("message", "summary", "hint")},
+            keys,
         )
     event["classification"] = _run_classify(
         classify if classify is not None else _classify, exc, event
@@ -552,55 +566,162 @@ def build_event(
     return event
 
 
+def _person_text(exc, extra, name, keys):
+    """An exception's ``summary``/``hint`` attribute, else ``extra[name]``;
+    scrubbed and trimmed, or None."""
+    value = getattr(exc, name, None) if exc is not None else None
+    if not value and extra:
+        value = extra.get(name)
+    if not value:
+        return None
+    return _truncate(scrub_text(" ".join(str(value).split()), keys), SUMMARY_LIMIT)
+
+
+def _local_time(occurred_at: Optional[str]) -> str:
+    """``Oct 20, 2026, 11:18 AM MDT`` in the site's zone (``SiteTimezone``),
+    else UTC; the raw value when it is not a timestamp."""
+    if not occurred_at:
+        return ""
+    try:
+        when = datetime.datetime.fromisoformat(str(occurred_at).replace("Z", "+00:00"))
+    except ValueError:
+        return str(occurred_at)
+    zone_name = None
+    try:
+        zone_name = _config(TIMEZONE_CONFIG_KEY)
+    except Exception:
+        zone_name = None
+    if zone_name:
+        try:
+            from zoneinfo import ZoneInfo
+
+            when = when.astimezone(ZoneInfo(str(zone_name)))
+        except Exception:
+            when = when.astimezone(datetime.timezone.utc)
+    hour = when.strftime("%I").lstrip("0") or "12"
+    return f"{when.strftime('%b')} {when.day}, {when.year}, {hour}:{when.strftime('%M %p %Z')}"
+
+
+def _cloudwatch_escape(value: str) -> str:
+    from urllib.parse import quote
+
+    return quote(quote(value, safe=""), safe="").replace("%", "$")
+
+
+def log_link(event: Optional[Dict[str, Any]]) -> str:
+    """The CloudWatch console page of the event's log stream, or ""."""
+    if not event or not event.get("log_group"):
+        return ""
+    region = os.environ.get("AWS_REGION")  # set in every Lambda
+    if not region:
+        return ""
+    url = (
+        f"https://{region}.console.aws.amazon.com/cloudwatch/home?region={region}"
+        f"#logsV2:log-groups/log-group/{_cloudwatch_escape(event['log_group'])}"
+    )
+    if event.get("log_stream"):
+        url += f"/log-events/{_cloudwatch_escape(event['log_stream'])}"
+    return url
+
+
+def _handled(event: Dict[str, Any]) -> Optional[bool]:
+    extra = event.get("extra")
+    if isinstance(extra, dict) and "handled" in extra:
+        return bool(extra["handled"])
+    return None
+
+
+_SOURCE_WORDS = {
+    "job": "a background job",
+    "queue": "a queued message",
+    "scheduler": "a scheduled task",
+    "request": "a request",
+}
+
+
 def render_text(event: Optional[Dict[str, Any]]) -> str:
-    """A plain-text rendering of an (already scrubbed) event, for email or
-    chat fallbacks. Contains nothing the event does not."""
+    """The failure for a person (the alert email, fallbacks): what failed,
+    the error in words, what to do, when (site-local time), whether it was
+    handled, where to look. Nothing beyond the event, the configured inbox
+    link and a log link."""
     if not event:
         return ""
-    lines = [
-        f"{event.get('site') or '?'} {event.get('env') or '?'} "
-        f"{event.get('source') or '?'} failure"
-        + (f" [{event['classification']}]" if event.get("classification") else ""),
-        "",
-    ]
-    for key in (
-        "function",
-        "action",
-        "job_id",
-        "request_id",
-        "message_id",
-        "receive_count",
-        "exception_type",
-        "message",
-        "occurred_at",
-        "fingerprint",
-        "log_group",
-        "log_stream",
+    site = event.get("site") or "?"
+    env = event.get("env") or "?"
+    exc_name = (event.get("exception_type") or "").rsplit(".", 1)[-1]
+    source = _SOURCE_WORDS.get(event.get("source"), event.get("source") or "something")
+    lines = [f"{site} ({env}): {source} failed", ""]
+
+    what = event.get("action") or event.get("source") or "?"
+    extra = event.get("extra") if isinstance(event.get("extra"), dict) else {}
+    details = [str(extra[k]) for k in ("capability",) if extra.get(k)]
+    subject = extra.get("subject")
+    lines.append(
+        f"What:     {what}"
+        + (f" ({', '.join(details)})" if details else "")
+        + (f", for {subject}" if subject else "")
+    )
+    error = event.get("summary") or event.get("message") or exc_name or "?"
+    lines.append(f"Error:    {error}" + (f" ({exc_name})" if exc_name else ""))
+    if event.get("hint"):
+        lines.append(f"To do:    {event['hint']}")
+    if event.get("occurred_at"):
+        lines.append(f"When:     {_local_time(event['occurred_at'])}")
+    handled = _handled(event)
+    if handled is True:
+        lines.append(
+            "Handled:  yes; it was recorded and the work is tried again on its next run"
+        )
+    elif handled is False:
+        lines.append("Handled:  no; the function stopped on it")
+    if event.get("classification"):
+        lines.append(f"Class:    {event['classification']}")
+    if event.get("receive_count"):
+        lines.append(f"Attempt:  {event['receive_count']}")
+    lines.append("")
+    if event.get("function"):
+        lines.append(f"Function: {event['function']}")
+    link = log_link(event)
+    if link:
+        lines.append(f"Log:      {link}")
+    inbox = None
+    try:
+        inbox = _config(INBOX_CONFIG_KEY)
+    except Exception:
+        inbox = None
+    if inbox:
+        lines.append(f"Inbox:    {inbox}")
+    lines.append("")
+    if event.get("where"):
+        lines.append(f"Where it failed: {event['where']}")
+    if (
+        event.get("summary")
+        and event.get("message")
+        and event["message"] != event["summary"]
     ):
-        value = event.get(key)
-        if value not in (None, ""):
-            lines.append(f"{key}: {value}")
-    for key in ("payload_excerpt", "extra"):
-        if event.get(key):
-            lines.append(f"{key}: {_render(event[key])}")
-    if event.get("traceback"):
-        lines.extend(["", "Traceback (scrubbed):", event["traceback"]])
+        lines.append(f"Raw message: {event['message']}")
+    if event.get("fingerprint"):
+        lines.append(f"Reference: {str(event['fingerprint'])[:12]}")
+    while lines and not lines[-1]:
+        lines.pop()
     return "\n".join(lines)
 
 
 def subject_line(event: Optional[Dict[str, Any]]) -> str:
-    """A one-line summary (≤ 200 chars) for an alert subject."""
+    """One line for an alert subject: site, env, what failed and the error in
+    words. Plain ASCII, at most 100 characters (SNS's email subject rules)."""
     if not event:
         return "Failure"
     exc_name = (event.get("exception_type") or "Failure").rsplit(".", 1)[-1]
-    parts = [
-        f"{(event.get('env') or '?').title()} {event.get('site') or ''}".strip(),
-        event.get("source") or "",
-        event.get("action") or "",
-    ]
-    label = f" [{event['classification']}]" if event.get("classification") else ""
-    head = " ".join(part for part in parts if part)
-    return _truncate(f"{head}: {exc_name}{label}", 200)
+    what = event.get("action") or event.get("source") or "something"
+    error = event.get("summary") or event.get("message") or exc_name
+    text = (
+        f"{event.get('site') or '?'} {event.get('env') or '?'}: {what} failed: {error}"
+    )
+    text = " ".join(text.split()).encode("ascii", "ignore").decode("ascii")
+    if len(text) > EMAIL_SUBJECT_LIMIT:
+        text = text[: EMAIL_SUBJECT_LIMIT - 3].rstrip() + "..."
+    return text
 
 
 def _run_fallback(event: Dict[str, Any]) -> None:
@@ -701,13 +822,7 @@ def report(
         return None
 
     try:
-        _client().publish(
-            TopicArn=topic_arn,
-            Message=_dumps(event),
-            MessageAttributes={
-                "velocity_event": {"DataType": "String", "StringValue": "failure"}
-            },
-        )
+        _client().publish(**publish_request(topic_arn, event))
     except Exception:
         logger.exception(
             "failures: publish to %s failed (fingerprint %s)",
@@ -718,6 +833,43 @@ def report(
     return event
 
 
+# SNS refuses a message over 256 KB; the email text is dropped to a short
+# form well before that (the inbox keeps the whole event).
+_SNS_MESSAGE_BUDGET = 240 * 1024
+
+
+def publish_request(topic_arn: str, event: Dict[str, Any]) -> Dict[str, Any]:
+    """The ``sns.publish`` arguments for one event. Subscribers each get their
+    own form (``MessageStructure="json"``): a Lambda (the failure inbox) and
+    every other protocol the event's JSON, unchanged; an ``email``
+    subscription the text a person reads (:func:`render_text`) under a
+    readable subject. The ``handled`` attribute ("true"/"false"/"unknown")
+    lets a subscription filter: the person's backstop email takes only
+    failures that were not handled."""
+    machine = _dumps(event)
+    person = render_text(event)
+    message = json.dumps({"default": machine, "email": person})
+    if len(message.encode("utf-8")) > _SNS_MESSAGE_BUDGET:
+        person = person[:4000] + "\n\n(shortened; the failure inbox has the rest)"
+        message = json.dumps({"default": machine, "email": person})
+    handled = _handled(event)
+    return {
+        "TopicArn": topic_arn,
+        "Message": message,
+        "MessageStructure": "json",
+        "Subject": subject_line(event),
+        "MessageAttributes": {
+            "velocity_event": {"DataType": "String", "StringValue": "failure"},
+            "handled": {
+                "DataType": "String",
+                "StringValue": (
+                    "unknown" if handled is None else ("true" if handled else "false")
+                ),
+            },
+        },
+    }
+
+
 def is_enabled() -> bool:
     """Whether ``FailureTopicArn`` resolves (events will be published)."""
     return bool(_config(TOPIC_CONFIG_KEY))

{velocity_python-0.2.5 → velocity_python-0.2.7}/src/velocity/aws/handlers/context.py

@@ -27,7 +27,22 @@ from velocity.db.core.lazy_engine import LazyEngine
 engine = LazyEngine(velocity.db.postgres.initialize)
 
 
-cognito_client = boto3.client("cognito-idp")
+# The Cognito client is built on first use, not at import: creating it loads
+# Cognito's whole API model and resolves its endpoint (~13 MB and ~2 s on a
+# 128 MB Lambda), which every function importing a handler paid — a
+# Scheduler or queue worker that never signs anyone in included. Tests may
+# replace this attribute; whatever it holds is what `_cognito()` returns.
+cognito_client = None
+
+
+def _cognito():
+    """The shared Cognito client, created on first use."""
+    global cognito_client
+    if cognito_client is None:
+        cognito_client = boto3.client("cognito-idp")
+    return cognito_client
+
+
 logger = get_logger("velocity.aws.handlers.context")
 
 # Cognito User Pool id shape, e.g. "us-east-1_aBcD1234". Used to distinguish a
@@ -1036,18 +1051,19 @@ class Context:
         # one Cognito round trip per user per UserCacheSeconds per container
         # (velocity.cache); a lookup that fails is never cached
         def resolve():
+            client = _cognito()
             try:
                 self.perf.start("cognito admin_get_user")
-                response = cognito_client.admin_get_user(
+                response = client.admin_get_user(
                     UserPoolId=user_pool_id,
                     Username=user_sub,
                 )
                 self.perf.log("cognito admin_get_user")
                 resolved_username = response.get("Username")
-            except cognito_client.exceptions.UserNotFoundException:
+            except client.exceptions.UserNotFoundException:
                 try:
                     self.perf.start("cognito list_users")
-                    list_response = cognito_client.list_users(
+                    list_response = client.list_users(
                         UserPoolId=user_pool_id,
                         Filter=f'sub = "{user_sub}"',
                         Limit=1,

{velocity_python-0.2.5 → velocity_python-0.2.7}/src/velocity/db/core/async_support.py

@@ -528,19 +528,9 @@ class AsyncTransaction:
 
         # R12 — Slow query logging
         if _SLOW_QUERY_MS and elapsed_ms > _SLOW_QUERY_MS:
-            from velocity.db.core.transaction import _summarize_sql
-
-            sql_preview = _summarize_sql(sql)
-            _logger.warning(
-                "Slow async query: %.1f ms sql=%s",
-                elapsed_ms,
-                sql_preview,
-                extra={
-                    "query_duration_ms": round(elapsed_ms, 1),
-                    "sql_preview": sql_preview,
-                },
-                stack_info=True,
-            )
+            from velocity.db.core.transaction import _slow_query_log
+
+            _slow_query_log(_logger, sql, elapsed_ms)
 
         # R14 — N+1 detection / R33 — raw-write cache invalidation
         from velocity.db.core.transaction import _classify_sql, _extract_table_name

{velocity_python-0.2.5 → velocity_python-0.2.7}/src/velocity/db/core/transaction.py

@@ -30,6 +30,15 @@ _DEFAULT_QUERY_CACHE_SIZE = int(os.environ.get("VELOCITY_QUERY_CACHE_SIZE", "100
 # Slow-query threshold in milliseconds (0 = disabled).
 _SLOW_QUERY_MS = int(os.environ.get("VELOCITY_SLOW_QUERY_MS", "500"))
 _SLOW_QUERY_SQL_CHARS = int(os.environ.get("VELOCITY_SLOW_QUERY_SQL_CHARS", "4000"))
+# The slow-query line is for people: this much SQL, the caller's file:line,
+# no traceback unless VELOCITY_SLOW_QUERY_STACK=1 asks for one. The full
+# preview (VELOCITY_SLOW_QUERY_SQL_CHARS) still rides on the record's `extra`.
+_SLOW_QUERY_LINE_CHARS = 200
+_SLOW_QUERY_STACK = os.environ.get("VELOCITY_SLOW_QUERY_STACK", "").strip().lower() in (
+    "1",
+    "true",
+    "yes",
+)
 
 # N+1 detection: warn when the same table is SELECTed more than this many
 # times within a single transaction.  0 = disabled.  Only active when the
@@ -174,16 +183,79 @@ def _written_tables_from_sql(sql):
     return tags or None
 
 
+# a run of three or more bind placeholders: "IN (%s, %s, %s, …)"
+_PLACEHOLDER_RUN_RE = re.compile(r"(%s|\?)(?:\s*,\s*\1){2,}")
+
+
+def _collapse_placeholders(text):
+    """``%s, %s, … (812 of them)`` -> ``%s × 812``."""
+
+    def collapse(match):
+        token = match.group(1)
+        return f"{token} × {match.group(0).count(token)}"
+
+    return _PLACEHOLDER_RUN_RE.sub(collapse, text)
+
+
 def _summarize_sql(sql, limit=None):
     if not sql:
         return None
-    compact = " ".join(str(sql).split())
+    compact = _collapse_placeholders(" ".join(str(sql).split()))
     max_chars = _SLOW_QUERY_SQL_CHARS if limit is None else limit
     if max_chars and len(compact) > max_chars:
         return compact[:max_chars] + "... [truncated]"
     return compact
 
 
+_VELOCITY_DIR = os.path.dirname(
+    os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+)
+
+
+def _caller_location():
+    """``file.py:line`` of the first stack frame outside velocity (the code
+    that ran the query), or ``None``."""
+    import traceback
+
+    for frame in reversed(traceback.extract_stack()[:-1]):
+        filename = os.path.abspath(frame.filename)
+        if filename.startswith(_VELOCITY_DIR + os.sep) or "<frozen" in frame.filename:
+            continue
+        return f"{os.path.basename(frame.filename)}:{frame.lineno}"
+    return None
+
+
+def _slow_query_log(logger, sql, elapsed_ms, *, op=None, table=None):
+    """One readable line for a slow query: what, on which table, how long,
+    from where, and the start of the SQL (placeholders collapsed). The fields
+    for log tooling go in ``extra``; a traceback only with
+    VELOCITY_SLOW_QUERY_STACK=1."""
+    op = op or _classify_sql(sql)
+    table = table if table is not None else _extract_table_name(sql)
+    preview = _summarize_sql(sql)
+    line = _summarize_sql(sql, limit=_SLOW_QUERY_LINE_CHARS)
+    caller = _caller_location()
+    took = (
+        f"{elapsed_ms / 1000:.1f} s" if elapsed_ms >= 1000 else f"{elapsed_ms:.0f} ms"
+    )
+    logger.warning(
+        "Slow %s%s: %s%s — %s",
+        op or "query",
+        f" on {table}" if table else "",
+        took,
+        f" at {caller}" if caller else "",
+        line,
+        extra={
+            "query_duration_ms": round(elapsed_ms, 1),
+            "table_name": table,
+            "operation": op,
+            "sql_preview": preview,
+            "caller": caller,
+        },
+        stack_info=_SLOW_QUERY_STACK,
+    )
+
+
 def _is_prepare_kw_type_error(error):
     """True for the TypeError a DB-API driver raises when ``execute()`` has
     no ``prepare`` keyword (``unexpected keyword argument 'prepare'``)."""
@@ -650,23 +722,7 @@ class Transaction:
 
             # R12 — Slow query logging.
             if _SLOW_QUERY_MS and elapsed_ms > _SLOW_QUERY_MS:
-                op = _classify_sql(sql)
-                tbl = _extract_table_name(sql)
-                sql_preview = _summarize_sql(sql)
-                _logger.warning(
-                    "Slow query (%s): %.1f ms table=%s sql=%s",
-                    op,
-                    elapsed_ms,
-                    tbl,
-                    sql_preview,
-                    extra={
-                        "query_duration_ms": round(elapsed_ms, 1),
-                        "table_name": tbl,
-                        "operation": op,
-                        "sql_preview": sql_preview,
-                    },
-                    stack_info=True,
-                )
+                _slow_query_log(_logger, sql, elapsed_ms)
 
             # R14 — N+1 detection (only when debug=True).
             if debug and _N_PLUS_1_THRESHOLD:

{velocity_python-0.2.5 → velocity_python-0.2.7/src/velocity_python.egg-info}/PKG-INFO

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

{velocity_python-0.2.5 → velocity_python-0.2.7}/src/velocity_python.egg-info/SOURCES.txt

@@ -254,6 +254,7 @@ tests/test_client_errors_mixin.py
 tests/test_client_input_contract_export.py
 tests/test_client_sql_boundary.py
 tests/test_client_table_gate_case_and_pointers.py
+tests/test_cognito_client_lazy.py
 tests/test_cognito_user_cache.py
 tests/test_column_tx_arg.py
 tests/test_concurrency_safety.py

{velocity_python-0.2.5 → velocity_python-0.2.7}/tests/test_async_support.py

@@ -728,6 +728,8 @@ class TestAsyncSlowQueryLogging:
                 assert len(slow_calls) >= 1
                 args = slow_calls[0].args
                 kwargs = slow_calls[0].kwargs
-                assert args[2] == "SELECT * FROM large_table"
+                # the same one-line form as the sync path: op, table, SQL last
+                assert args[1:3] == ("SELECT", " on large_table")
+                assert args[-1] == "SELECT * FROM large_table"
                 assert kwargs["extra"]["sql_preview"] == "SELECT * FROM large_table"
-                assert kwargs["stack_info"] is True
+                assert kwargs["stack_info"] is False

{velocity_python-0.2.5 → velocity_python-0.2.7}/tests/test_client_errors_mixin.py

@@ -696,7 +696,11 @@ def test_real_failures_report_builds_a_publishable_event():
     ):
         run(Handler(), {"errors": [error(message="token=abc123secret failed")]})
     client.publish.assert_called_once()
-    event = json.loads(client.publish.call_args.kwargs["Message"])
+    # one body per subscriber: the inbox reads "default" (the event), a
+    # person's email reads "email"; neither may carry the secret
+    bodies = json.loads(client.publish.call_args.kwargs["Message"])
+    assert "abc123secret" not in bodies["email"]
+    event = json.loads(bodies["default"])
     assert event["source"] == client_errors.FAILURE_SOURCE
     assert event["action"] == "report-client-error"
     assert event["exception_type"].endswith("client_errors.ClientError")

velocity_python-0.2.7/tests/test_cognito_client_lazy.py

@@ -0,0 +1,45 @@
+"""The Cognito client is created on first use, not when velocity's handler
+context is imported: building it loads Cognito's API model (~13 MB, ~2 s on a
+128 MB Lambda) that a Scheduler or queue worker never needs."""
+
+import importlib
+import sys
+from unittest import mock
+
+
+def test_importing_the_context_creates_no_cognito_client():
+    name = "velocity.aws.handlers.context"
+    original = sys.modules.pop(name, None)
+    try:
+        with mock.patch("boto3.client") as client:
+            module = importlib.import_module(name)
+            cognito_calls = [
+                c for c in client.call_args_list if c.args[:1] == ("cognito-idp",)
+            ]
+            assert cognito_calls == []
+            assert module.cognito_client is None
+    finally:
+        # every other test keeps the module object it imported
+        if original is not None:
+            sys.modules[name] = original
+
+
+def test_the_client_is_created_once_on_first_use():
+    from velocity.aws.handlers import context
+
+    with (
+        mock.patch.object(context, "cognito_client", None),
+        mock.patch("boto3.client") as client,
+    ):
+        first = context._cognito()
+        second = context._cognito()
+    client.assert_called_once_with("cognito-idp")
+    assert first is second
+
+
+def test_a_client_put_in_place_is_the_one_used():
+    from velocity.aws.handlers import context
+
+    fake = object()
+    with mock.patch.object(context, "cognito_client", fake):
+        assert context._cognito() is fake