velocity-python 0.1.92__tar.gz → 0.1.94__tar.gz

{velocity_python-0.1.92/src/velocity_python.egg-info → velocity_python-0.1.94}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.1.92
+Version: 0.1.94
 Summary: A rapid application development library for interfacing with data storage
 Author-email: Velocity Team <info@codeclubs.org>
 License-Expression: MIT
@@ -35,6 +35,8 @@ Provides-Extra: templates
 Requires-Dist: jinja2>=3.1.0; extra == "templates"
 Provides-Extra: pdf
 Requires-Dist: pdfkit>=1.0.0; extra == "pdf"
+Provides-Extra: pdf-weasyprint
+Requires-Dist: weasyprint>=60.0; extra == "pdf-weasyprint"
 Provides-Extra: http
 Requires-Dist: requests>=2.32.0; extra == "http"
 Provides-Extra: mysql
@@ -248,7 +250,7 @@ Full documentation is included in the `docs/` directory of the source distributi
 | Performance & Optimization | `docs/performance.md` | Connection pooling, batch operations, query caching, prepared statements, N+1 prevention, observability |
 | Async Support | `docs/async.md` | AsyncTransaction, AsyncTable, AsyncResult, parallel queries with gather() |
 | Configuration Reference | `docs/configuration.md` | All environment variables, engine options, and connection settings |
-| AWS Lambda Handlers | `docs/aws-handlers.md` | LambdaHandler, SqsHandler, auth modes, per-record transactions |
+| AWS Lambda Handlers | `docs/aws-handlers.md` | LambdaHandler, SqsHandler, auth modes, per-record transactions, async jobs (JobHandler + job result stores) |
 | NoSQL Adapters | `docs/nosql.md` | Redis, DynamoDB, MongoDB, Elasticsearch, Cassandra, Couchbase behind one capability-honest contract |
 | Payment Processing | `docs/payment.md` | Stripe and Braintree adapters, payment lifecycle |
 | Utilities | `docs/utilities.md` | Excel export, data conversion, formatting, timers, email parsing |

{velocity_python-0.1.92 → velocity_python-0.1.94}/README.md

@@ -156,7 +156,7 @@ Full documentation is included in the `docs/` directory of the source distributi
 | Performance & Optimization | `docs/performance.md` | Connection pooling, batch operations, query caching, prepared statements, N+1 prevention, observability |
 | Async Support | `docs/async.md` | AsyncTransaction, AsyncTable, AsyncResult, parallel queries with gather() |
 | Configuration Reference | `docs/configuration.md` | All environment variables, engine options, and connection settings |
-| AWS Lambda Handlers | `docs/aws-handlers.md` | LambdaHandler, SqsHandler, auth modes, per-record transactions |
+| AWS Lambda Handlers | `docs/aws-handlers.md` | LambdaHandler, SqsHandler, auth modes, per-record transactions, async jobs (JobHandler + job result stores) |
 | NoSQL Adapters | `docs/nosql.md` | Redis, DynamoDB, MongoDB, Elasticsearch, Cassandra, Couchbase behind one capability-honest contract |
 | Payment Processing | `docs/payment.md` | Stripe and Braintree adapters, payment lifecycle |
 | Utilities | `docs/utilities.md` | Excel export, data conversion, formatting, timers, email parsing |

{velocity_python-0.1.92 → velocity_python-0.1.94}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "velocity-python"
-version = "0.1.92"
+version = "0.1.94"
 authors = [
   { name="Velocity Team", email="info@codeclubs.org" },
 ]
@@ -57,6 +57,10 @@ templates = [
 pdf = [
   "pdfkit>=1.0.0",
 ]
+# Maintained HTML→PDF engine; native libs (Pango/Cairo) come from the OS or a layer.
+pdf-weasyprint = [
+  "weasyprint>=60.0",
+]
 http = [
   "requests>=2.32.0",
 ]

{velocity_python-0.1.92 → velocity_python-0.1.94}/src/velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.1.92"
+__version__ = version = "0.1.94"
 
 import importlib as _importlib
 

{velocity_python-0.1.92 → velocity_python-0.1.94}/src/velocity/aws/handlers/mixins/__init__.py

@@ -5,13 +5,16 @@ This package provides mixins for common Lambda handler patterns:
 - WebHandler: Activity tracking, logging, and error handling
 - ButtonHandler: Dynamic button action handler loading
 - DataServiceMixin: Generic CRUD operations for database-backed APIs
+- JobHandler: get-job-status / download-job-result / cancel-job for async jobs
 """
 
 from .web_handler import WebHandler, ButtonHandler
 from .data_service import DataServiceMixin
+from .job_handler import JobHandler
 
 __all__ = [
     "WebHandler",
     "ButtonHandler",
     "DataServiceMixin",
+    "JobHandler",
 ]

velocity_python-0.1.94/src/velocity/aws/handlers/mixins/job_handler.py

@@ -0,0 +1,175 @@
+"""JobHandler — the web-tier half of asynchronous jobs.
+
+velocity-react's job watcher (``JobProgressPortal`` + ``startJobWatcher``) polls
+three ``/event`` actions after a response carries ``jobs.events``:
+
+* ``get-job-status``      → ``{"job_status": {job_id, status, message, batch_id, updated}}``
+* ``download-job-result`` → a ``file-download`` (or ``redirect``) response action
+* ``cancel-job``          → flags the job ``CancelRequested`` for the worker
+
+They are identical for every app, so they live here (extracted from
+BackOfficeEvents). Mix into the HTTP handler alongside ``WebHandler``::
+
+    class HttpEventHandler(ButtonHandler, JobHandler, WebHandler, LambdaHandler):
+        ...
+
+A button action that wants the watcher enqueues, then announces the job::
+
+    result = context.enqueue("zip-invoices", payload)
+    job_id = result["Successful"][0]["Id"]
+    context.response().jobs.start(job_id=job_id, label="Zipping invoices")
+
+and the worker persists its output with ``velocity.aws.job_results.store_job_result``.
+"""
+
+from __future__ import annotations
+
+import datetime
+import json
+from typing import Any, Dict, Optional
+
+from velocity.aws.handlers.exceptions import AlertError
+from velocity.aws.job_results import (
+    deliver_job_result,
+    job_result_files,
+    parse_job_message,
+)
+from velocity.misc.format import to_json
+
+TERMINAL_JOB_STATUSES = frozenset({"Completed", "Failed", "Cancelled"})
+# Statuses that can only persist this long because the worker died without
+# running onError (Lambda timeout / OOM): synthesize Failed so the UI moves on.
+STALE_JOB_STATUSES = frozenset({"Running", "Initialized"})
+
+
+class JobHandler:
+    JOB_ACTIVITY_TABLE = "aws_job_activity"
+    JOB_STALE_AFTER = datetime.timedelta(minutes=16)
+
+    # ── helpers ───────────────────────────────────────────────────────────────
+
+    def _job_id_from(self, context) -> str:
+        payload = context.payload() or {}
+        job_id = payload.get("job_id") if isinstance(payload, dict) else None
+        if not job_id:
+            raise AlertError("job_id is required")
+        return str(job_id)
+
+    def _find_job(self, tx, job_id: str):
+        return tx.table(self.JOB_ACTIVITY_TABLE).find({"job_id": job_id})
+
+    def _job_is_stale(self, job) -> bool:
+        if (job.get("status") or "") not in STALE_JOB_STATUSES:
+            return False
+        ts = job.get("sys_modified") or job.get("initial_timestamp")
+        if ts is None:
+            return False
+        now = datetime.datetime.now(datetime.timezone.utc)
+        if ts.tzinfo is None:
+            ts = ts.replace(tzinfo=datetime.timezone.utc)
+        return (now - ts) > self.JOB_STALE_AFTER
+
+    @staticmethod
+    def _job_status_body(
+        job_id: str,
+        status: str,
+        message: Optional[Dict[str, Any]],
+        job=None,
+    ) -> Dict[str, Any]:
+        body = {"job_id": job_id, "status": status, "message": message}
+        if job is not None:
+            body["batch_id"] = job.get("batch_id")
+            body["updated"] = job.get("sys_modified")
+        return {"job_status": body}
+
+    # ── actions ───────────────────────────────────────────────────────────────
+
+    def OnActionGetJobStatus(self, tx, context):
+        """Current status + message for one job (polled by the job watcher)."""
+        job_id = self._job_id_from(context)
+        job = self._find_job(tx, job_id)
+        if not job:
+            context.response().set_body(
+                self._job_status_body(
+                    job_id, "NotFound", {"detail": "Job not found"}
+                )
+            )
+            return
+
+        if self._job_is_stale(job):
+            context.response().set_body(
+                self._job_status_body(
+                    job_id,
+                    "Failed",
+                    {
+                        "detail": "Job timed out — the server ran out of time or memory.",
+                        "error": "Lambda timed out or was killed (OOM)",
+                    },
+                    job,
+                )
+            )
+            return
+
+        message = parse_job_message(job.get("message")) or None
+        context.response().set_body(
+            self._job_status_body(job_id, job.get("status") or "", message, job)
+        )
+
+    def OnActionDownloadJobResult(self, tx, context):
+        """Deliver a completed job's file via the store that holds it."""
+        job_id = self._job_id_from(context)
+        job = self._find_job(tx, job_id)
+        if not job:
+            raise AlertError("Job result not found")
+
+        files = job_result_files(job.get("message"))
+        if not files:
+            raise AlertError("Job result is not ready")
+
+        # One file per job result; descriptors without a store are legacy
+        # BackOffice S3 entries.
+        descriptor = dict(files[0])
+        descriptor.setdefault("store", "s3" if descriptor.get("bucket") else "db")
+        deliver_job_result(tx, context, descriptor)
+        context.response().toast("Download ready.")
+
+    def OnActionCancelJob(self, tx, context):
+        """Ask the worker to stop: status CancelRequested + message flag.
+
+        Workers poll ``context.is_job_cancel_requested(tx)`` between units of
+        work and call ``context.mark_job_cancelled`` when they honour it.
+        """
+        job_id = self._job_id_from(context)
+        job = self._find_job(tx, job_id)
+        if not job:
+            raise AlertError("Job not found")
+
+        current = job.get("status") or ""
+        if current in TERMINAL_JOB_STATUSES:
+            raise AlertError(f"Job is already {current.lower()}")
+
+        payload = context.payload() or {}
+        message = parse_job_message(job.get("message"))
+        message.update(
+            {
+                "detail": payload.get("detail")
+                or payload.get("reason")
+                or "Cancellation requested by user",
+                "cancel_requested": True,
+            }
+        )
+        tx.table(self.JOB_ACTIVITY_TABLE).update(
+            {
+                "status": "CancelRequested",
+                "message": to_json(message),
+                "sys_modified": datetime.datetime.now(),
+                "sys_modified_by": (context.session() or {}).get("email_address"),
+            },
+            {"job_id": job_id},
+        )
+        context.response().set_body(
+            self._job_status_body(job_id, "CancelRequested", message)
+        )
+
+
+__all__ = ["JobHandler", "TERMINAL_JOB_STATUSES", "STALE_JOB_STATUSES"]