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

{velocity_python-0.2.6/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.6
+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.6 → velocity_python-0.2.7}/pyproject.toml

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

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

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

{velocity_python-0.2.6 → 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.6 → 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.6 → 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.6
+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.6 → 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.6 → 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

{velocity_python-0.2.6 → velocity_python-0.2.7}/tests/test_failures.py

@@ -55,8 +55,11 @@ def _stubbed_sns(expect_message=True):
             {
                 "TopicArn": TOPIC,
                 "Message": ANY,
+                "MessageStructure": "json",
+                "Subject": ANY,
                 "MessageAttributes": {
-                    "velocity_event": {"DataType": "String", "StringValue": "failure"}
+                    "velocity_event": {"DataType": "String", "StringValue": "failure"},
+                    "handled": ANY,
                 },
             },
         )
@@ -436,13 +439,18 @@ class ConfigureHookTests(unittest.TestCase):
         event = failures.build_event(
             None, _caught(), source="scheduler", action="task:nightly"
         )
-        text = failures.render_text(event)
-        self.assertIn("Example demo scheduler failure [DATABASE]", text)
-        self.assertIn("action: task:nightly", text)
-        self.assertIn("Traceback (scrubbed):", text)
+        with patch.object(failures, "_config", return_value=None):
+            text = failures.render_text(event)
+        # written for a person: what, the error, the class; no traceback dump
+        self.assertIn("Example (demo): a scheduled task failed", text)
+        self.assertIn("What:     task:nightly", text)
+        self.assertIn("Error:    it broke (RuntimeError)", text)
+        self.assertIn("Class:    DATABASE", text)
+        self.assertIn("Where it failed: tests/test_failures.py:_raise", text)
+        self.assertNotIn("Traceback", text)
         self.assertEqual(
             failures.subject_line(event),
-            "Demo Example scheduler task:nightly: RuntimeError [DATABASE]",
+            "Example demo: task:nightly failed: it broke",
         )
         self.assertEqual(failures.render_text(None), "")
 
@@ -461,3 +469,106 @@ class ConfigureHookTests(unittest.TestCase):
 
 if __name__ == "__main__":
     unittest.main()
+
+
+class PersonFacingTests(unittest.TestCase):
+    """The alert email is written for a person; the failure inbox still gets
+    the event's JSON; the backstop email can filter out handled failures."""
+
+    def setUp(self):
+        failures._reset_for_tests()
+        env = patch.dict("os.environ", {**ENV, "AWS_REGION": "us-west-2"}, clear=False)
+        env.start()
+        self.addCleanup(env.stop)
+
+    def _event(self, exc=None, **extra):
+        return failures.build_event(
+            SimpleNamespace(aws_request_id="req-1"),
+            exc or _caught(),
+            source="job",
+            action="sync-mail",
+            extra=extra or None,
+        )
+
+    def test_summary_and_hint_come_from_the_exception(self):
+        class ReauthRequired(Exception):
+            summary = "Gmail sign-in expired or revoked"
+            hint = "Reconnect the account."
+
+        try:
+            raise ReauthRequired("https://oauth2.example.test/token failed (400)")
+        except ReauthRequired as exc:
+            event = self._event(exc, handled=True, subject="a@example.com")
+        self.assertEqual(event["summary"], "Gmail sign-in expired or revoked")
+        self.assertEqual(event["hint"], "Reconnect the account.")
+        self.assertEqual(event["extra"], {"handled": True, "subject": "a@example.com"})
+        with patch.object(failures, "_config", return_value=None):
+            text = failures.render_text(event)
+        self.assertIn(
+            "Error:    Gmail sign-in expired or revoked (ReauthRequired)", text
+        )
+        self.assertIn("To do:    Reconnect the account.", text)
+        self.assertIn(", for a@example.com", text)
+        self.assertIn("Handled:  yes", text)
+        self.assertIn(
+            "Raw message: https://oauth2.example.test/token failed (400)", text
+        )
+
+    def test_time_is_the_sites_and_links_are_given(self):
+        event = self._event(handled=False)
+        event["occurred_at"] = "2026-10-20T17:18:03Z"
+        config = {
+            "SiteTimezone": "America/Denver",
+            "FailureInboxUrl": "https://admin.example.test/app/site-failures",
+        }
+        with patch.object(failures, "_config", side_effect=config.get):
+            text = failures.render_text(event)
+        self.assertIn("When:     Oct 20, 2026, 11:18 AM MDT", text)
+        self.assertIn("Inbox:    https://admin.example.test/app/site-failures", text)
+        self.assertIn("Handled:  no", text)
+        self.assertIn(
+            "Log:      https://us-west-2.console.aws.amazon.com/cloudwatch/home"
+            "?region=us-west-2#logsV2:log-groups/log-group/"
+            "$252Faws$252Flambda$252FExampleEvents-demo/log-events/",
+            text,
+        )
+
+    def test_without_a_zone_the_time_is_utc(self):
+        event = self._event()
+        event["occurred_at"] = "2026-10-20T17:18:03Z"
+        with patch.object(failures, "_config", return_value=None):
+            self.assertIn(
+                "When:     Oct 20, 2026, 5:18 PM UTC", failures.render_text(event)
+            )
+
+    def test_the_subject_is_plain_ascii_within_100_characters(self):
+        event = self._event()
+        event["summary"] = "Long — " + "x" * 200
+        subject = failures.subject_line(event)
+        self.assertLessEqual(len(subject), 100)
+        self.assertTrue(subject.isascii())
+        self.assertTrue(subject.endswith("..."))
+
+    def test_publish_gives_the_inbox_json_and_the_email_text(self):
+        event = self._event(handled=True)
+        with patch.object(failures, "_config", return_value=None):
+            request = failures.publish_request(TOPIC, event)
+        self.assertEqual(request["MessageStructure"], "json")
+        bodies = json.loads(request["Message"])
+        # the failure inbox (a Lambda) gets the event exactly as before
+        self.assertEqual(
+            json.loads(bodies["default"]), json.loads(failures._dumps(event))
+        )
+        self.assertIn("Example (demo): a background job failed", bodies["email"])
+        self.assertEqual(request["Subject"], failures.subject_line(event))
+        self.assertEqual(
+            request["MessageAttributes"]["handled"],
+            {"DataType": "String", "StringValue": "true"},
+        )
+
+    def test_handled_is_unknown_when_the_caller_did_not_say(self):
+        with patch.object(failures, "_config", return_value=None):
+            request = failures.publish_request(TOPIC, self._event())
+        self.assertEqual(
+            request["MessageAttributes"]["handled"]["StringValue"], "unknown"
+        )