velocity-python 0.0.138__py3-none-any.whl → 0.0.152__py3-none-any.whl

velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.0.138"
+__version__ = version = "0.0.152"
 
 from . import aws
 from . import db

velocity/app/orders.py

@@ -115,9 +115,7 @@ class Order:
             for key, default in defaults.items():
                 if key not in target:
                     target[key] = default() if callable(default) else default
-                elif key == "updated_at":
-                    # Always update updated_at if present
-                    target[key] = default() if callable(default) else default
+
 
     def _validate(self):
         self._apply_defaults()

velocity/aws/handlers/mixins/activity_tracker.py

@@ -9,33 +9,34 @@ import copy
 import json
 import os
 import time
-from abc import ABC, abstractmethod
-from typing import Dict, Any, Optional
+from abc import ABC
+from datetime import date, datetime
+from typing import Dict, Any
 
 
 class ActivityTracker(ABC):
     """
     Mixin class providing standardized activity tracking for Lambda handlers.
-    
+
     Tracks API calls to the aws_api_activity table with consistent data structure
     and automatic duration calculation.
     """
-    
+
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
         self.activity_log_key = None
         self.start_time = None
         self.end_time = None
         self.activity_data = {}
-    
+
     def track_activity_start(self, tx, context):
         """Start tracking activity for the current request"""
         self.start_time = time.time()
-        
+
         # Gather common activity data
         postdata = context.postdata()
         payload = context.payload()
-        
+
         self.activity_data = {
             "action": context.action(),
             "args": json.dumps(context.args()),
@@ -45,21 +46,34 @@ class ActivityTracker(ABC):
             "user_branch": os.environ.get("USER_BRANCH", "Unknown"),
             "start_timestamp": self.start_time,
         }
-        
+
         # Add user information if available
         user_info = self._extract_user_info(payload)
         if user_info:
             self.activity_data.update(user_info)
-            
+
         # Add session information
         session_data = context.session()
         if session_data:
-            self.activity_data.update({k: v for k, v in session_data.items() 
-                                     if k not in ['cognito_user']})
-        
+            self.activity_data.update(self._sanitize_session_data(session_data))
+
+        # Ensure all values are serializable before persisting
+        self.activity_data = {
+            key: self._normalize_activity_value(value)
+            for key, value in self.activity_data.items()
+            if value is not None
+        }
+
         # Create the activity record
-        self.activity_log_key = tx.table("aws_api_activity").new(self.activity_data).pk
-        
+        try:
+            self.activity_log_key = tx.table("aws_api_activity").new(self.activity_data).pk
+        except Exception as exc:
+            context.log(
+                f"ActivityTracker.track_activity_start failed: {exc}; keys={list(self.activity_data.keys())}",
+                "ActivityTracker.track_activity_start",
+            )
+            raise
+
         return self.activity_log_key
     
     def track_activity_success(self, tx, context):
@@ -140,3 +154,28 @@ class ActivityTracker(ABC):
                 pass
                 
         return user_info
+
+    def _sanitize_session_data(self, session: Dict[str, Any]) -> Dict[str, Any]:
+        """Remove sensitive session keys and normalize value types"""
+        sanitized = {}
+
+        for key, value in session.items():
+            if key == "cognito_user":
+                continue
+
+            sanitized[key] = self._normalize_activity_value(value)
+
+        return sanitized
+
+    def _normalize_activity_value(self, value: Any) -> Any:
+        """Convert activity data values into types acceptable by psycopg2"""
+        if isinstance(value, (dict, list, tuple, set)):
+            try:
+                return json.dumps(value)
+            except (TypeError, ValueError):
+                return str(value)
+        if isinstance(value, (datetime, date)):
+            return value.isoformat()
+        if isinstance(value, (bytes, bytearray)):
+            return value.decode("utf-8", errors="ignore")
+        return value

velocity/aws/handlers/mixins/aws_session_mixin.py

@@ -0,0 +1,192 @@
+"""
+Error Handler Mixin for Lambda Handlers.
+
+Provides standardized error handling, logging, and notification functionality
+for Lambda handlers.
+"""
+
+import copy
+import os
+import pprint
+import time
+from abc import ABC, abstractmethod
+from typing import Dict, Any, Optional
+
+
+class AwsSessionMixin(ABC):
+    """
+    Mixin class providing standardized error handling for Lambda handlers.
+    
+    Handles error logging to sys_log table, email notifications to administrators,
+    and error metrics collection.
+    """
+    
+    def handle_standard_error(self, tx, context, exception: Exception, tb_string: str):
+        """Handle errors with consistent logging and notification patterns"""
+        
+        # Log to sys_log for centralized logging
+        self.log_error_to_system(tx, context, exception, tb_string)
+        
+        # Determine if this error requires notification
+        if self._should_notify_error(exception):
+            self.send_error_notification(tx, context, exception, tb_string)
+        
+        # Log error metrics for monitoring
+        self.log_error_metrics(tx, context, exception)
+    
+    def log_error_to_system(self, tx, context, exception: Exception, tb_string: str):
+        """Log error to sys_log table"""
+        error_data = {
+            "level": "ERROR",
+            "message": str(exception),
+            "function": f"{self.__class__.__name__}.{context.action()}",
+            "traceback": tb_string,
+            "exception_type": exception.__class__.__name__,
+            "handler_name": self.__class__.__name__,
+            "action": context.action(),
+            "user_branch": os.environ.get("USER_BRANCH", "Unknown"),
+            "function_name": os.environ.get("AWS_LAMBDA_FUNCTION_NAME", "Unknown"),
+            "app_name": os.environ.get("ProjectName", "Unknown"),
+            "user_agent": "AWS Lambda",
+            "device_type": "Lambda",
+            "sys_modified_by": "Lambda",
+        }
+        
+        # Add user context if available
+        try:
+            if hasattr(self, 'current_user') and self.current_user:
+                error_data["user_email"] = self.current_user.get("email_address")
+        except:
+            pass
+            
+        tx.table("sys_log").insert(error_data)
+    
+    def send_error_notification(self, tx, context, exception: Exception, tb_string: str):
+        """Send error notification email to administrators"""
+        try:
+            # Import here to avoid circular dependency
+            from support.app import helpers
+            
+            environment = os.environ.get('USER_BRANCH', 'Unknown').title()
+            function_name = os.environ.get('AWS_LAMBDA_FUNCTION_NAME', 'Unknown')
+            
+            subject = f"{environment} Lambda Error - {function_name}"
+            
+            body = f"""
+Error Details:
+- Handler: {self.__class__.__name__}
+- Action: {context.action()}
+- Exception: {exception.__class__.__name__}
+- Message: {str(exception)}
+- Environment: {environment}
+- Function: {function_name}
+
+Full Traceback:
+{tb_string}
+
+Request Details:
+{self._get_error_context(context)}
+            """
+            
+            sender = self._get_error_notification_sender()
+            recipients = self._get_error_notification_recipients()
+            
+            helpers.sendmail(
+                tx,
+                subject=subject,
+                body=body,
+                html=None,
+                sender=sender,
+                recipient=recipients[0],
+                cc=recipients[1:] if len(recipients) > 1 else None,
+                bcc=None,
+                email_settings_id=1001,
+            )
+        except Exception as email_error:
+            print(f"Failed to send error notification email: {email_error}")
+    
+    def _should_notify_error(self, exception: Exception) -> bool:
+        """Determine if an error should trigger email notifications"""
+        # Don't notify for user authentication errors or validation errors
+        non_notification_types = [
+            "AuthenticationError", 
+            "ValidationError", 
+            "ValueError",
+            "AlertError"
+        ]
+        
+        exception_name = exception.__class__.__name__
+        
+        # Check for authentication-related exceptions
+        if "Authentication" in exception_name or "Auth" in exception_name:
+            return False
+            
+        return exception_name not in non_notification_types
+    
+    @abstractmethod
+    def _get_error_notification_recipients(self) -> list:
+        """
+        Get list of email recipients for error notifications.
+        
+        Must be implemented by the handler class.
+        
+        Returns:
+            List of email addresses to notify when errors occur
+            
+        Example:
+            return ["admin@company.com", "devops@company.com"]
+        """
+        pass
+    
+    @abstractmethod
+    def _get_error_notification_sender(self) -> str:
+        """
+        Get email sender for error notifications.
+        
+        Must be implemented by the handler class.
+        
+        Returns:
+            Email address to use as sender for error notifications
+            
+        Example:
+            return "no-reply@company.com"
+        """
+        pass
+    
+    def _get_error_context(self, context) -> str:
+        """Get sanitized request context for error reporting"""
+        try:
+            postdata = context.postdata()
+            sanitized = copy.deepcopy(postdata)
+            
+            # Remove sensitive data
+            if "payload" in sanitized and isinstance(sanitized["payload"], dict):
+                sanitized["payload"].pop("cognito_user", None)
+                
+            return pprint.pformat(sanitized)
+        except:
+            return "Unable to retrieve request context"
+    
+    def log_error_metrics(self, tx, context, exception: Exception):
+        """Log error metrics for monitoring and alerting"""
+        try:
+            metrics_data = {
+                "metric_type": "error_count",
+                "handler_name": self.__class__.__name__,
+                "action": context.action(),
+                "exception_type": exception.__class__.__name__,
+                "environment": os.environ.get("USER_BRANCH", "Unknown"),
+                "function_name": os.environ.get("AWS_LAMBDA_FUNCTION_NAME", "Unknown"),
+                "timestamp": time.time(),
+                "sys_modified_by": "Lambda"
+            }
+            
+            # Try to insert into metrics table if it exists
+            try:
+                tx.table("lambda_metrics").insert(metrics_data)
+            except:
+                # Metrics table might not exist yet, don't fail error handler
+                pass
+        except:
+            # Don't fail the error handler if metrics logging fails
+            pass

velocity/db/core/row.py

@@ -44,7 +44,12 @@ class Row:
     def __setitem__(self, key, val):
         if key in self.pk:
             raise Exception("Cannot update a primary key.")
-        self.table.upsert({key: val}, self.pk)
+        if hasattr(self.table, "updins"):
+            self.table.updins({key: val}, pk=self.pk)
+        elif hasattr(self.table, "upsert"):
+            self.table.upsert({key: val}, pk=self.pk)
+        else:
+            self.table.update({key: val}, pk=self.pk)
 
     def __delitem__(self, key):
         if key in self.pk:
@@ -121,7 +126,12 @@ class Row:
         if kwds:
             data.update(kwds)
         if data:
-            self.table.upsert(data, self.pk)
+            if hasattr(self.table, "updins"):
+                self.table.updins(data, pk=self.pk)
+            elif hasattr(self.table, "upsert"):
+                self.table.upsert(data, pk=self.pk)
+            else:
+                self.table.update(data, pk=self.pk)
         return self
 
     def __cmp__(self, other):

velocity/db/core/table.py

@@ -1,4 +1,5 @@
 import sqlparse
+from collections.abc import Iterable, Mapping
 from velocity.db import exceptions
 from velocity.db.core.row import Row
 from velocity.db.core.result import Result
@@ -119,6 +120,59 @@ class Table:
             return sql, vals
         self.tx.execute(sql, vals, cursor=self.cursor())
 
+    def create_indexes(self, indexes, **kwds):
+        """
+        Convenience wrapper to create multiple indexes in order.
+
+        Accepts an iterable of definitions. Each definition may be either:
+        - Mapping with a required "columns" entry plus optional "unique",
+          "direction", "where", and "lower" keys.
+        - A simple sequence/string of columns, in which case defaults apply.
+
+        When sql_only=True, a list of (sql, params) tuples is returned.
+        """
+
+        if indexes is None:
+            return [] if kwds.get("sql_only", False) else None
+
+        if not isinstance(indexes, Iterable) or isinstance(indexes, (str, bytes)):
+            raise TypeError("indexes must be an iterable of index definitions")
+
+        sql_only = kwds.get("sql_only", False)
+        statements = []
+
+        for definition in indexes:
+            if isinstance(definition, Mapping):
+                columns = definition.get("columns")
+                if not columns:
+                    raise ValueError("Index definition requires a non-empty 'columns' entry")
+                params = {
+                    "unique": definition.get("unique", False),
+                    "direction": definition.get("direction"),
+                    "where": definition.get("where"),
+                    "lower": definition.get("lower"),
+                }
+            else:
+                columns = definition
+                params = {
+                    "unique": False,
+                    "direction": None,
+                    "where": None,
+                    "lower": None,
+                }
+
+            if isinstance(columns, str):
+                columns = columns.split(",")
+
+            if not columns:
+                raise ValueError("Index columns cannot be empty")
+
+            result = self.create_index(columns, **params, **kwds)
+            if sql_only:
+                statements.append(result)
+
+        return statements if sql_only else None
+
     @return_default(None)
     def drop_index(self, columns, **kwds):
         """
@@ -163,6 +217,32 @@ class Table:
             return self.name in [f"{x[0]}.{x[1]}" for x in result.as_tuple()]
         return self.name in [x[1] for x in result.as_tuple()]
 
+    def ensure_sys_modified_count(self, **kwds):
+        """
+        Ensure the sys_modified_count column and trigger exist for this table.
+
+        Returns early when the column is already present unless `force=True` is provided.
+        """
+        force = kwds.get("force", False)
+
+        try:
+            columns = [col.lower() for col in self.sys_columns()]
+        except Exception:
+            columns = []
+
+        has_column = "sys_modified_count" in columns
+        has_row_column = "sys_modified_row" in columns
+
+        if has_column and has_row_column and not force:
+            return
+
+        sql, vals = self.sql.ensure_sys_modified_count(
+            self.name, has_column=has_column, has_row_column=has_row_column
+        )
+        if kwds.get("sql_only", False):
+            return sql, vals
+        self.tx.execute(sql, vals, cursor=self.cursor())
+
     def column(self, name):
         """
         Returns a Column object for the given column name.
@@ -465,6 +545,104 @@ class Table:
         result = self.tx.execute(sql, vals, cursor=self.cursor())
         return result.cursor.rowcount if result.cursor else 0
 
+    @create_missing
+    def update_or_insert(self, update_data, insert_data=None, where=None, pk=None, **kwds):
+        """
+        Attempts an UPDATE first; if no rows change, performs an INSERT guarded by NOT EXISTS.
+
+        :param update_data: Mapping of columns to update.
+        :param insert_data: Optional mapping used for the INSERT. When omitted, values are
+                             derived from update_data combined with simple equality predicates
+                             from ``where`` and primary key values.
+        :param where: Criteria for the UPDATE and existence check.
+        :param pk: Optional primary key mapping for UPDATE (merged into WHERE) and INSERT.
+        :param sql_only: When True, return the SQL/parameter tuples for both phases instead of executing.
+        :return: Number of rows affected, or a dict with ``update``/``insert`` entries when sql_only=True.
+        """
+        sql_only = kwds.get("sql_only", False)
+        if not isinstance(update_data, Mapping) or not update_data:
+            raise ValueError("update_data must be a non-empty mapping of column-value pairs.")
+        if where is None and pk is None:
+            raise ValueError("Either where or pk must be provided for update_or_insert.")
+
+        update_stmt = None
+        if sql_only:
+            update_stmt = self.update(update_data, where=where, pk=pk, sql_only=True)
+        else:
+            updated = self.update(update_data, where=where, pk=pk)
+            if updated:
+                return updated
+
+        if insert_data is not None:
+            if not isinstance(insert_data, Mapping):
+                raise ValueError("insert_data must be a mapping when provided.")
+            insert_payload = dict(insert_data)
+        else:
+            insert_payload = dict(update_data)
+            if isinstance(where, Mapping):
+                for key, val in where.items():
+                    if not isinstance(key, str):
+                        continue
+                    if set("<>!=%").intersection(key):
+                        continue
+                    insert_payload.setdefault(key, val)
+            if isinstance(pk, Mapping):
+                for key, val in pk.items():
+                    insert_payload.setdefault(key, val)
+
+        if not insert_payload:
+            raise ValueError("Unable to derive insert payload for update_or_insert.")
+
+        exists_where = None
+        if where is not None and pk is not None:
+            if isinstance(where, Mapping) and isinstance(pk, Mapping):
+                combined = dict(where)
+                combined.update(pk)
+                exists_where = combined
+            else:
+                exists_where = where
+        elif where is not None:
+            exists_where = where
+        else:
+            exists_where = pk
+
+        ins_builder = getattr(self.sql, "insnx", None) or getattr(
+            self.sql, "insert_if_not_exists", None
+        )
+        if ins_builder is None:
+            raise NotImplementedError(
+                "Current SQL dialect does not support insert-if-not-exists operations."
+            )
+
+        sql, vals = ins_builder(self.tx, self.name, insert_payload, exists_where)
+        if sql_only:
+            return {"update": update_stmt, "insert": (sql, vals)}
+        result = self.tx.execute(sql, vals, cursor=self.cursor())
+        return result.cursor.rowcount if result.cursor else 0
+
+    updins = update_or_insert
+
+    @create_missing
+    def insert_if_not_exists(self, data, where=None, **kwds):
+        """
+        Inserts `data` into the table only if the existence check (`where`) does not match any rows.
+
+        Usage:
+            table.insert_if_not_exists({'key_col': 'k', 'value': 'v'}, where={'key_col': 'k'})
+
+        :param data: dict of column -> value for insert
+        :param where: mapping/list/str used for the EXISTS check; if None primary keys are used and
+                      must be present in `data`.
+        :return: rowcount (0 or 1) or (sql, params) when sql_only=True
+        """
+        sql, vals = self.sql.insert_if_not_exists(self.tx, self.name, data, where)
+        if kwds.get("sql_only", False):
+            return sql, vals
+        result = self.tx.execute(sql, vals, cursor=self.cursor())
+        return result.cursor.rowcount if result.cursor else 0
+
+    insnx = insert_if_not_exists
+
     upsert = merge
     indate = merge
 

velocity/db/core/transaction.py

@@ -164,17 +164,13 @@ class Transaction:
         """
         return Row(self.table(tablename), pk, lock=lock)
 
-    def get(self, tablename, where, lock=None):
-        """
-        Shortcut to table.get().
-        """
-        return self.table(tablename).get(where, lock=lock)
+    def get(self, tablename, where, lock=None, use_where=False):
+        """Shortcut to table.get() with optional ``use_where`` passthrough."""
+        return self.table(tablename).get(where, lock=lock, use_where=use_where)
 
-    def find(self, tablename, where, lock=None):
-        """
-        Shortcut to table.find().
-        """
-        return self.table(tablename).find(where, lock=lock)
+    def find(self, tablename, where, lock=None, use_where=False):
+        """Shortcut to table.find() with optional ``use_where`` passthrough."""
+        return self.table(tablename).find(where, lock=lock, use_where=use_where)
 
     def column(self, tablename, colname):
         """