velocity-python 0.0.145__tar.gz → 0.0.147__tar.gz

{velocity_python-0.0.145 → velocity_python-0.0.147}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.0.145
+Version: 0.0.147
 Summary: A rapid application development library for interfacing with data storage
 Author-email: Velocity Team <info@codeclubs.org>
 License-Expression: MIT

{velocity_python-0.0.145 → velocity_python-0.0.147}/pyproject.toml

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

{velocity_python-0.0.145 → velocity_python-0.0.147}/src/velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.0.145"
+__version__ = version = "0.0.147"
 
 from . import aws
 from . import db

velocity_python-0.0.147/src/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_python-0.0.145 → velocity_python-0.0.147}/src/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]
+
+            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):
         """
@@ -177,10 +231,14 @@ class Table:
             columns = []
 
         has_column = "sys_modified_count" in columns
-        if has_column and not force:
+        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)
+        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())
@@ -487,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_python-0.0.145 → velocity_python-0.0.147}/src/velocity/db/servers/mysql/sql.py

@@ -450,7 +450,7 @@ END;
         return "\n".join(statements), tuple()
 
     @classmethod
-    def ensure_sys_modified_count(cls, name):
+    def ensure_sys_modified_count(cls, name, has_column=False, has_row_column=False):
         """Ensure sys_modified_count column and associated triggers exist for the table."""
         table_identifier = quote(name)
         base_name = name.split(".")[-1].replace("`", "")