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

{velocity_python-0.2.6/src/velocity_python.egg-info → velocity_python-0.2.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.2.6
+Version: 0.2.8
 Summary: A rapid application development library for interfacing with data storage
 Author-email: Velocity Team <info@codeclubs.org>
 License-Expression: MIT
@@ -267,7 +267,6 @@ What changed in each release, and what callers must do before upgrading, is in
 | Testing Guide | `docs/TESTING.md` | Running tests, markers, coverage |
 | Security | `docs/SECURITY.md` | Pre-commit hooks, credential scanning |
 | Changelog | `CHANGELOG.md` | Per-release breaking changes, deploy ordering, additions and fixes |
-| Improvement Backlog | `docs/IMPROVEMENT_BACKLOG.md` | Proposed and deferred library improvements |
 
 ---
 

{velocity_python-0.2.6 → velocity_python-0.2.8}/README.md

@@ -174,7 +174,6 @@ What changed in each release, and what callers must do before upgrading, is in
 | Testing Guide | `docs/TESTING.md` | Running tests, markers, coverage |
 | Security | `docs/SECURITY.md` | Pre-commit hooks, credential scanning |
 | Changelog | `CHANGELOG.md` | Per-release breaking changes, deploy ordering, additions and fixes |
-| Improvement Backlog | `docs/IMPROVEMENT_BACKLOG.md` | Proposed and deferred library improvements |
 
 ---
 

{velocity_python-0.2.6 → velocity_python-0.2.8}/pyproject.toml

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

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

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

{velocity_python-0.2.6 → velocity_python-0.2.8}/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.8}/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.8}/src/velocity/payment/braintree_adapter.py

@@ -113,6 +113,24 @@ def parse_braintree_environment(value: Any = None) -> str:
     return name
 
 
+def _decline_details(transaction: Any) -> Dict[str, Any]:
+    """The processor's own verdict on a declined sale, for callers that decide
+    whether to try the card again: ``processor_response_code``,
+    ``processor_response_text`` and ``processor_response_type``
+    (``approved`` / ``soft_declined`` / ``hard_declined`` -- Braintree's
+    classification; a hard decline will not be approved on retry). Only the
+    keys Braintree set; empty without a transaction (gateway rejection or
+    validation failure)."""
+    if transaction is None:
+        return {}
+    details = {
+        "processor_response_code": _attr(transaction, "processor_response_code"),
+        "processor_response_text": _attr(transaction, "processor_response_text"),
+        "processor_response_type": _attr(transaction, "processor_response_type"),
+    }
+    return {key: value for key, value in details.items() if value not in (None, "")}
+
+
 def _deep_errors(result: Any) -> List[str]:
     errors = getattr(getattr(result, "errors", None), "deep_errors", None) or []
     return [scrub(f"{error.code}: {error.message}") for error in errors]
@@ -556,7 +574,11 @@ class BraintreeAdapter(PaymentProcessorAdapter):
             "expires_at": None,
             "error_message": error_message,
             "metadata": _with_reference(
-                {"braintree_errors": _deep_errors(result)}, order_id
+                {
+                    "braintree_errors": _deep_errors(result),
+                    **_decline_details(result.transaction),
+                },
+                order_id,
             ),
         }
 
@@ -674,7 +696,12 @@ class BraintreeAdapter(PaymentProcessorAdapter):
             )
             error_message = scrub(result.transaction.processor_response_text)
         return failure(
-            "failed", error_message, {"braintree_errors": _deep_errors(result)}
+            "failed",
+            error_message,
+            {
+                "braintree_errors": _deep_errors(result),
+                **_decline_details(result.transaction),
+            },
         )
 
     def find_charge_by_reference(

{velocity_python-0.2.6 → velocity_python-0.2.8}/src/velocity/payment/stripe_adapter.py

@@ -139,6 +139,16 @@ def _amount_captured(payment_intent: Any, charge: Any, requested: Optional[int])
     return 0
 
 
+def _decline_details(error: Any) -> Dict[str, Any]:
+    """``decline_code`` of a card decline (``CardError``): the issuer's reason
+    (``insufficient_funds``, ``lost_card``, ``expired_card`` ...), for callers
+    that decide whether to try the card again. Empty when Stripe gave none."""
+    decline_code = getattr(error, "decline_code", None) or getattr(
+        getattr(error, "error", None), "decline_code", None
+    )
+    return {"decline_code": decline_code} if decline_code else {}
+
+
 class StripeAdapter(PaymentProcessorAdapter):
     """
     Stripe Connect adapter for payment processing.
@@ -664,6 +674,7 @@ class StripeAdapter(PaymentProcessorAdapter):
                     "error_code": e.code,
                     "error_type": type(e).__name__,
                     "idempotency_key": idempotency_key,
+                    **_decline_details(e),
                 },
             }
             if reference:
@@ -824,6 +835,7 @@ class StripeAdapter(PaymentProcessorAdapter):
                     "error_code": e.code,
                     "error_type": type(e).__name__,
                     "idempotency_key": idempotency_key,
+                    **_decline_details(e),
                 },
             }
             if reference:

{velocity_python-0.2.6 → velocity_python-0.2.8/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.8
 Summary: A rapid application development library for interfacing with data storage
 Author-email: Velocity Team <info@codeclubs.org>
 License-Expression: MIT
@@ -267,7 +267,6 @@ What changed in each release, and what callers must do before upgrading, is in
 | Testing Guide | `docs/TESTING.md` | Running tests, markers, coverage |
 | Security | `docs/SECURITY.md` | Pre-commit hooks, credential scanning |
 | Changelog | `CHANGELOG.md` | Per-release breaking changes, deploy ordering, additions and fixes |
-| Improvement Backlog | `docs/IMPROVEMENT_BACKLOG.md` | Proposed and deferred library improvements |
 
 ---
 

{velocity_python-0.2.6 → velocity_python-0.2.8}/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.8}/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.8/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