velocity-python 0.1.101__tar.gz → 0.1.102__tar.gz

{velocity_python-0.1.101 → velocity_python-0.1.102}/PKG-INFO

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

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

{velocity_python-0.1.101 → velocity_python-0.1.102}/src/velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.1.101"
+__version__ = version = "0.1.102"
 
 import importlib as _importlib
 

{velocity_python-0.1.101 → velocity_python-0.1.102}/src/velocity/aws/handlers/mixins/data_service.py

@@ -15,7 +15,7 @@ import re
 import xml.etree.ElementTree as ET
 from io import BytesIO, StringIO
 
-from velocity.aws import dirty_pipeline
+from velocity.aws import dirty_pipeline, ssm_config
 from velocity.aws.handlers.exceptions import AlertError
 from velocity.db.exceptions import DbDataIntegrityError
 from velocity.misc import export
@@ -48,6 +48,85 @@ def _fk_blocked_delete_message(table, exc):
     )
 
 
+_IDENTIFIER_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+
+def _bump_sys_id_sequence(tx, table):
+    """Keep the table's serial/identity sequence ahead of MAX(sys_id) so a
+    future auto-generated id can never collide with an explicitly chosen one
+    (renumber, Save-As)."""
+    if not _IDENTIFIER_RE.match(table or ""):
+        raise AlertError(f"'{table}' is not a valid table name.")
+    tx.execute(
+        f"""select setval(s.seq, greatest((select coalesce(max(sys_id), 1) from "{table}"), 1))
+            from (select pg_get_serial_sequence(%s, 'sys_id') as seq) s
+            where s.seq is not null""",
+        (table,),
+    )
+
+
+def renumber_row(tx, table, old_sys_id, new_sys_id, overwrite=False):
+    """Assign a CHOSEN sys_id to an existing row (admin surgery).
+
+    Rules (deliberately simple):
+    - refused when any real foreign-key constraint references this table's
+      sys_id (renumbering under FKs is a cascade problem for another day);
+    - when the target sys_id already exists: refused unless ``overwrite`` —
+      which DELETES the occupying row first;
+    - the table's sys_id sequence is bumped past MAX(sys_id) afterwards so
+      future inserts can never collide with the chosen id.
+
+    Returns "renumbered" on success, or "exists" when the target id is
+    occupied and overwrite was not requested (the caller asks the user).
+    Raises AlertError for every refusal.
+    """
+    if not _IDENTIFIER_RE.match(table or ""):
+        raise AlertError(f"'{table}' is not a valid table name.")
+    try:
+        old_id = int(old_sys_id)
+        new_id = int(new_sys_id)
+    except (TypeError, ValueError):
+        raise AlertError("sys_id values must be integers.")
+    if new_id <= 0:
+        raise AlertError("The new sys_id must be a positive integer.")
+    if new_id == old_id:
+        raise AlertError("That is already this record's sys_id.")
+
+    if not tx.table(table).find(old_id):
+        raise AlertError(f"Record {old_id} was not found in {table}.")
+
+    referencing = tx.execute(
+        """select con.conrelid::regclass::text as referencing_table
+           from pg_constraint con
+           join pg_class rel on rel.oid = con.confrelid
+           join pg_namespace nsp on nsp.oid = rel.relnamespace
+           where con.contype = 'f' and nsp.nspname = 'public'
+             and rel.relname = %s
+           limit 5""",
+        (table,),
+    ).all()
+    if referencing:
+        tables = ", ".join(sorted({r["referencing_table"] for r in referencing}))
+        raise AlertError(
+            f"Renumbering is not allowed: {tables} reference(s) {table} "
+            "through a foreign key. (Denied for now — reassigning "
+            "references is not implemented.)"
+        )
+
+    if tx.table(table).find(new_id):
+        if not overwrite:
+            return "exists"
+        tx.execute(f'DELETE FROM "{table}" WHERE sys_id = %s', (new_id,))
+
+    tx.execute(
+        f'UPDATE "{table}" SET sys_id = %s WHERE sys_id = %s',
+        (new_id, old_id),
+    )
+
+    _bump_sys_id_sequence(tx, table)
+    return "renumbered"
+
+
 class DataServiceMixin:
     """
     Mixin providing generic CRUD operations for Lambda handlers.
@@ -77,6 +156,12 @@ class DataServiceMixin:
     # which DO run hooks — remain the supported path for them.
     restricted_direct_tables = frozenset()
 
+    # Ceiling on rows a single un-paginated `query` may materialize (None =
+    # no cap). Apps set the class attribute; the `QueryMaxRows` config key
+    # overrides it per environment. Promoted 2026-09-04 from BackOffice's
+    # full query_hook override, which existed largely to carry this.
+    query_max_rows = None
+
     # PostgreSQL type mappings for frontend display
     _pg_types = {
         "bool": "string",
@@ -94,6 +179,22 @@ class DataServiceMixin:
         "timestamp": "string",
     }
 
+    def _resolve_query_max_rows(self):
+        """Effective query row ceiling: `QueryMaxRows` config key first, then
+        the class attribute. Returns a positive int or None (no cap)."""
+        raw = None
+        try:
+            raw = ssm_config.getenv("QueryMaxRows", None)
+        except Exception:
+            raw = None
+        if raw in (None, ""):
+            raw = self.query_max_rows
+        try:
+            value = int(raw) if raw not in (None, "") else None
+        except (TypeError, ValueError):
+            return None
+        return value if value and value > 0 else None
+
     def _assert_direct_access_allowed(self, table):
         """Reject hook-bypassing direct access to a restricted table."""
         if table in self.restricted_direct_tables:
@@ -185,7 +286,7 @@ class DataServiceMixin:
             row = row.to_dict()
         return row
 
-    def write_hook(self, tx, table, sys_id, incoming, context):
+    def write_hook(self, tx, table, sys_id, incoming, context, save_as=False):
         row = {}
         incoming.pop("sys_id", None)
         if sys_id == "@new":
@@ -223,9 +324,23 @@ class DataServiceMixin:
             # error rather than a phantom row inserted with a client-chosen PK.
             row = tx.table(table).find(sys_id)
             if not row:
-                raise AlertError(
-                    f"Cannot update {table}: record {sys_id} no longer exists."
+                if not save_as:
+                    raise AlertError(
+                        f"Cannot update {table}: record {sys_id} no longer exists."
+                    )
+                # Save-As: the user explicitly chose this id — claim it, then
+                # fall through to the shared update tail. before_new is skipped
+                # (the data comes from a populated form, not a blank create);
+                # after_new still fires so create-time defaults apply. The
+                # sequence is bumped past MAX(sys_id) so future auto-ids can
+                # never collide with the chosen one.
+                tx.table(table).insert({"sys_id": sys_id})
+                _bump_sys_id_sequence(tx, table)
+                row = tx.table(table).find(sys_id)
+                self._call_rwx_hook(
+                    "after_new", "common", tx, table, sys_id, row, context
                 )
+                self._call_rwx_hook("after_new", table, tx, table, sys_id, row, context)
         else:
             raise Exception("Object sys_id was not supplied on write operation.")
         row.update(incoming)
@@ -436,6 +551,23 @@ class DataServiceMixin:
                     },
                 }
 
+        # Optional ceiling on un-paginated queries: fetch one row past the cap
+        # so truncation is detectable and reportable rather than silent.
+        max_rows = self._resolve_query_max_rows()
+        requested_qty = params.get("qty")
+        try:
+            requested_qty = (
+                int(requested_qty) if requested_qty not in (None, "") else None
+            )
+        except (TypeError, ValueError):
+            requested_qty = None
+        cap_applied = bool(max_rows) and (
+            requested_qty is None or requested_qty > max_rows
+        )
+        if cap_applied:
+            params = dict(params)
+            params["qty"] = max_rows + 1
+
         result = tx.table(obj).select(**params)
 
         swallowed_error = getattr(tx, "_last_return_default_error", None)
@@ -514,6 +646,23 @@ class DataServiceMixin:
                     },
                 }
             )
+        if (
+            cap_applied
+            and isinstance(data.get("rows"), list)
+            and len(data["rows"]) > max_rows
+        ):
+            data["rows"] = data["rows"][:max_rows]
+            truncation = {"truncated": True, "maxRows": max_rows}
+            if isinstance(data.get("config"), dict):
+                data["config"]["truncated"] = truncation
+                context.response().toast(
+                    f"Showing the first {max_rows:,} rows — refine the search "
+                    "or paginate to see the rest.",
+                    "warning",
+                )
+            else:
+                data["truncated"] = truncation
+
         if payload.get("count"):
             data["count"] = tx.table(payload["obj"]).count(
                 where=params.get("where", None)
@@ -640,6 +789,29 @@ class DataServiceMixin:
         if not any(value is not None for value in incoming.values()):
             raise ValueError("Parameter 'object' cannot contain only None values")
 
+        # Save-As: the client chose the target sys_id. When that id is already
+        # taken, answer "exists" so the UI can confirm the overwrite instead of
+        # silently clobbering; with saveAsOverwrite the normal update path
+        # writes the full object onto the existing row. A free id is created
+        # by write_hook (save_as=True).
+        save_as = bool(payload.get("saveAs"))
+        if save_as:
+            target_sys_id = incoming.get("sys_id")
+            if target_sys_id not in (None, "", "@new"):
+                try:
+                    chosen = int(target_sys_id)
+                except (TypeError, ValueError):
+                    raise AlertError("Save-As ID must be a positive integer.")
+                if chosen <= 0:
+                    raise AlertError("Save-As ID must be a positive integer.")
+                if not payload.get("saveAsOverwrite") and tx.table(table_name).find(
+                    chosen
+                ):
+                    context.response().set_body(
+                        {"saveAsStatus": "exists", "sys_id": chosen}
+                    )
+                    return
+
         logger.debug(
             "Writing to table",
             extra={
@@ -656,6 +828,7 @@ class DataServiceMixin:
                 incoming.get("sys_id"),
                 incoming,
                 context,
+                save_as=save_as,
             )
 
             if not row:
@@ -964,6 +1137,42 @@ class DataServiceMixin:
         if not deleteList:
             context.response().toast("No items were selected.", "warning")
 
+    def OnActionRenumberObject(self, tx, context):
+        """Assign a chosen sys_id to one row.
+
+        Payload: tableName, sys_id (current), new_sys_id, overwrite (bool).
+        Responds {status: "exists"} when the target id is occupied and
+        overwrite was not requested; on success reloads the renumbered row
+        into the form (load-object) and reports the change.
+        """
+        payload = context.payload()
+        for field in ("tableName", "sys_id", "new_sys_id"):
+            if field not in payload:
+                raise ValueError(f"Missing required parameter '{field}' in payload")
+        table = payload["tableName"]
+        self._assert_direct_access_allowed(table)
+
+        result = renumber_row(
+            tx,
+            table,
+            payload["sys_id"],
+            payload["new_sys_id"],
+            overwrite=bool(payload.get("overwrite")),
+        )
+        if result == "exists":
+            context.response().set_body(
+                {"status": "exists", "new_sys_id": payload["new_sys_id"]}
+            )
+            return
+
+        row = tx.table(table).find(int(payload["new_sys_id"]))
+        context.response().set_body({"status": "renumbered", "object": dict(row)})
+        context.response().load_object(dict(row))
+        context.response().toast(
+            f"Record renumbered: {payload['sys_id']} → {payload['new_sys_id']}.",
+            "success",
+        )
+
     def OnActionGetTables(self, tx, context):
         """Get list of all tables in the database."""
         context.response().set_body({"tables": tx.tables()})

{velocity_python-0.1.101 → velocity_python-0.1.102}/src/velocity/aws/handlers/response.py

@@ -36,9 +36,16 @@ class Response:
         """
         Finalize the response body as JSON and return the complete response dictionary.
 
+        When a raw body has been set via :meth:`set_raw_body`, it is returned
+        verbatim (no JSON encoding, no actions envelope) — the escape hatch
+        for non-JSON responses like TwiML or plain text.
+
         Returns:
-            Dict[str, Any]: The complete HTTP response with headers, status code, and JSON body.
+            Dict[str, Any]: The complete HTTP response with headers, status code, and body.
         """
+        if getattr(self, "_raw_body", None) is not None:
+            self.raw["body"] = self._raw_body
+            return self.raw
         if self.actions:
             self.body["actions"] = self.actions
         if self.jobs.events:
@@ -46,6 +53,25 @@ class Response:
         self.raw["body"] = to_json(self.body)
         return self.raw
 
+    def set_raw_body(self, body: str, content_type: str = "text/plain") -> "Response":
+        """
+        Send a non-JSON body verbatim (e.g. TwiML, plain text, XML).
+
+        Bypasses the JSON envelope entirely: render() returns this body
+        unencoded and skips actions/jobs. Added 2026-09-04 — apps previously
+        had to override serve() to do this.
+
+        Args:
+            body (str): The exact body string to return.
+            content_type (str): Content-Type header value. Defaults to "text/plain".
+
+        Returns:
+            Response: The current Response object, allowing method chaining.
+        """
+        self._raw_body = body
+        self.raw["headers"]["Content-Type"] = content_type
+        return self
+
     def alert(self, message: str, title: str = "Notification") -> "Response":
         """
         Add an alert action to the response.

{velocity_python-0.1.101 → velocity_python-0.1.102}/src/velocity/aws/ssm_config.py

@@ -122,6 +122,15 @@ def get_stage(default: Optional[str] = None) -> Optional[str]:
     return _first_nonempty_env(*_STAGE_ENV_KEYS) or default
 
 
+def is_production() -> bool:
+    """True when the resolved stage is the production branch.
+
+    The missing primitive behind six per-app ``runtime_config`` copies: apps
+    kept re-wrapping :func:`get_stage` just to ask this one question.
+    """
+    return (get_stage() or "").strip().lower() == "production"
+
+
 def get_region(default: Optional[str] = "us-east-1") -> Optional[str]:
     return _first_nonempty_env("AWS_REGION", "REGION", "USER_REGION") or default
 

{velocity_python-0.1.101 → velocity_python-0.1.102}/src/velocity/payment/braintree_adapter.py

@@ -14,6 +14,8 @@ Key Features:
 - Authorization with later capture support
 """
 
+import time
+
 import braintree
 from typing import Dict, Any, Optional
 from datetime import datetime, timezone, timedelta
@@ -66,6 +68,33 @@ class BraintreeAdapter(PaymentProcessorAdapter):
         self.environment = environment_name
         self.platform = config.get("platform")
 
+    def generate_client_token(
+        self,
+        customer_id: Optional[str] = None,
+        attempts: int = 3,
+        backoff_seconds: float = 0.25,
+    ) -> str:
+        """Generate a Braintree client token, retrying transient failures.
+
+        The retry policy lives here, once — apps were hand-rolling identical
+        backoff loops around raw ``client_token.generate()`` calls (promoted
+        2026-09-04 from DonateMain / BackOffice copies).
+        """
+        params: Dict[str, Any] = {"customer_id": customer_id} if customer_id else {}
+        last_exc: Optional[Exception] = None
+        for attempt in range(max(1, attempts)):
+            try:
+                return self.gateway.client_token.generate(params)
+            except Exception as exc:
+                last_exc = exc
+                if attempt < attempts - 1:
+                    time.sleep(backoff_seconds * (attempt + 1))
+        raise ProcessorError(
+            "braintree",
+            "client_token_unavailable",
+            f"Client token unavailable after {attempts} attempts: {last_exc}",
+        ) from last_exc
+
     # ========================================================================
     # ACCOUNT MANAGEMENT
     # ========================================================================

{velocity_python-0.1.101 → velocity_python-0.1.102}/src/velocity_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.1.101
+Version: 0.1.102
 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.101 → velocity_python-0.1.102}/src/velocity_python.egg-info/SOURCES.txt

@@ -202,6 +202,9 @@ tests/test_concurrency_safety.py
 tests/test_connection_pool.py
 tests/test_connection_resilience.py
 tests/test_context_job_descriptions.py
+tests/test_data_service_query_cap.py
+tests/test_data_service_renumber.py
+tests/test_data_service_save_as.py
 tests/test_db_credentials_ssm_cascade.py
 tests/test_db_maintenance.py
 tests/test_decorators.py
@@ -242,6 +245,7 @@ tests/test_prepared_statements.py
 tests/test_psycopg3_upgrade.py
 tests/test_query_cache.py
 tests/test_query_missing_table_unlocked.py
+tests/test_response.py
 tests/test_restricted_direct_tables.py
 tests/test_retry_side_effect_guard.py
 tests/test_return_default_safety.py

velocity_python-0.1.102/tests/test_data_service_query_cap.py

@@ -0,0 +1,115 @@
+"""query_hook row ceiling: QueryMaxRows config / query_max_rows attribute,
+fetch-one-extra truncation detection, and the no-cap default."""
+
+import pytest
+
+from velocity.aws.handlers.mixins.data_service import DataServiceMixin
+
+
+class FakeResult:
+    def __init__(self, rows):
+        self._rows = rows
+        self.sql = "select 1"
+        self.headers = ["sys_id"]
+
+    def all(self):
+        return list(self._rows)
+
+    def as_list(self):
+        return self
+
+
+class FakeTable:
+    def __init__(self, tx):
+        self.tx = tx
+
+    def select(self, **params):
+        self.tx.select_params = params
+        qty = params.get("qty")
+        rows = [{"sys_id": i} for i in range(1, self.tx.row_count + 1)]
+        if qty:
+            rows = rows[: int(qty)]
+        return FakeResult(rows)
+
+
+class FakeTx:
+    def __init__(self, row_count):
+        self.row_count = row_count
+        self.select_params = None
+
+    def table(self, name):
+        return FakeTable(self)
+
+
+class FakeResponse:
+    def __init__(self):
+        self.toasts = []
+
+    def toast(self, message, level=None):
+        self.toasts.append((message, level))
+
+
+class FakeContext:
+    def __init__(self):
+        self._response = FakeResponse()
+
+    def response(self):
+        return self._response
+
+
+class Handler(DataServiceMixin):
+    def _call_rwx_hook(self, *args, **kwargs):
+        pass
+
+
+class CappedHandler(Handler):
+    query_max_rows = 3
+
+
+@pytest.fixture(autouse=True)
+def _no_env_cap(monkeypatch):
+    monkeypatch.delenv("QueryMaxRows", raising=False)
+
+
+def test_resolver_uses_attribute_then_env(monkeypatch):
+    assert Handler()._resolve_query_max_rows() is None
+    assert CappedHandler()._resolve_query_max_rows() == 3
+    monkeypatch.setenv("QueryMaxRows", "7")
+    assert CappedHandler()._resolve_query_max_rows() == 7
+    monkeypatch.setenv("QueryMaxRows", "not-a-number")
+    assert CappedHandler()._resolve_query_max_rows() is None
+    monkeypatch.setenv("QueryMaxRows", "0")
+    assert CappedHandler()._resolve_query_max_rows() is None
+
+
+def test_unpaginated_query_is_capped_and_reported():
+    tx = FakeTx(row_count=10)
+    context = FakeContext()
+    data = CappedHandler().query_hook(
+        tx, "studio", {"obj": "studio", "params": {}}, context
+    )
+    assert tx.select_params["qty"] == 4  # cap + 1 to detect truncation
+    assert len(data["rows"]) == 3
+    assert data["config"]["truncated"] == {"truncated": True, "maxRows": 3}
+    assert context.response().toasts and "first 3" in context.response().toasts[0][0]
+
+
+def test_paginated_query_below_cap_is_untouched():
+    tx = FakeTx(row_count=10)
+    context = FakeContext()
+    data = CappedHandler().query_hook(
+        tx, "studio", {"obj": "studio", "params": {"qty": 2}}, context
+    )
+    assert tx.select_params["qty"] == 2
+    assert len(data["rows"]) == 2
+    assert "truncated" not in data["config"]
+    assert not context.response().toasts
+
+
+def test_no_cap_by_default():
+    tx = FakeTx(row_count=10)
+    context = FakeContext()
+    data = Handler().query_hook(tx, "studio", {"obj": "studio", "params": {}}, context)
+    assert tx.select_params.get("qty") is None
+    assert len(data["rows"]) == 10
+    assert "truncated" not in data["config"]

velocity_python-0.1.102/tests/test_data_service_renumber.py

@@ -0,0 +1,93 @@
+"""renumber_row: chosen-sys_id assignment with FK denial, occupied-target
+confirmation, overwrite semantics, and the sequence bump."""
+
+import pytest
+from unittest.mock import MagicMock
+
+from velocity.aws.handlers.exceptions import AlertError
+from velocity.aws.handlers.mixins.data_service import renumber_row
+
+
+class FakeTx:
+    def __init__(self, existing_ids=(5,), fk_tables=()):
+        self.existing = set(existing_ids)
+        self.fk_tables = list(fk_tables)
+        self.executed = []
+        outer = self
+
+        class _Table:
+            def find(self, sys_id):
+                return {"sys_id": sys_id} if sys_id in outer.existing else None
+
+        self._table = _Table()
+
+    def table(self, name):
+        return self._table
+
+    def execute(self, sql, params=None):
+        self.executed.append((" ".join(sql.split()), params))
+        result = MagicMock()
+        if "pg_constraint" in sql:
+            result.all.return_value = [
+                {"referencing_table": t} for t in self.fk_tables
+            ]
+        else:
+            result.all.return_value = []
+        if sql.strip().upper().startswith("DELETE"):
+            self.existing.discard(params[0])
+        if sql.strip().upper().startswith("UPDATE"):
+            self.existing.discard(params[1])
+            self.existing.add(params[0])
+        return result
+
+
+def sqls(tx):
+    return [s for s, _ in tx.executed]
+
+
+def test_simple_renumber_updates_and_bumps_sequence():
+    tx = FakeTx(existing_ids=(5,))
+    assert renumber_row(tx, "studio", 5, 42) == "renumbered"
+    update = [s for s in sqls(tx) if s.startswith('UPDATE "studio" SET sys_id')]
+    assert update and tx.executed[-2][1] == (42, 5)
+    assert "pg_get_serial_sequence" in sqls(tx)[-1]
+    assert 42 in tx.existing and 5 not in tx.existing
+
+
+def test_occupied_target_reports_exists_without_touching_data():
+    tx = FakeTx(existing_ids=(5, 42))
+    assert renumber_row(tx, "studio", 5, 42) == "exists"
+    assert not any(s.startswith(("DELETE", "UPDATE")) for s in sqls(tx))
+
+
+def test_overwrite_deletes_the_occupant_then_renumbers():
+    tx = FakeTx(existing_ids=(5, 42))
+    assert renumber_row(tx, "studio", 5, 42, overwrite=True) == "renumbered"
+    ordered = [s.split()[0] for s in sqls(tx) if s.split()[0] in ("DELETE", "UPDATE")]
+    assert ordered == ["DELETE", "UPDATE"]
+    assert tx.existing == {42}
+
+
+def test_foreign_key_reference_denies_the_change():
+    tx = FakeTx(existing_ids=(5,), fk_tables=("event_link_student",))
+    with pytest.raises(AlertError) as err:
+        renumber_row(tx, "people", 5, 42)
+    assert "event_link_student" in str(err.value)
+    assert not any(s.startswith(("DELETE", "UPDATE")) for s in sqls(tx))
+
+
+@pytest.mark.parametrize(
+    "table,old,new,message",
+    [
+        ("studio; drop", 5, 42, "not a valid table name"),
+        ("studio", 5, "abc", "must be integers"),
+        ("studio", 5, 0, "positive integer"),
+        ("studio", 5, 5, "already this record"),
+        ("studio", 99, 42, "was not found"),
+    ],
+)
+def test_validation_refusals(table, old, new, message):
+    tx = FakeTx(existing_ids=(5,))
+    with pytest.raises(AlertError) as err:
+        renumber_row(tx, table, old, new)
+    assert message in str(err.value)