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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.0.145
+Version: 0.0.146
 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.146}/pyproject.toml

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

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

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

velocity_python-0.0.146/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.146}/src/velocity/db/core/table.py

@@ -1,4 +1,5 @@
 import sqlparse
+from collections.abc import Mapping
 from velocity.db import exceptions
 from velocity.db.core.row import Row
 from velocity.db.core.result import Result
@@ -177,10 +178,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 +492,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.146}/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("`", "")

{velocity_python-0.0.145 → velocity_python-0.0.146}/src/velocity/db/servers/postgres/sql.py

@@ -562,51 +562,164 @@ class SQL(BaseSQLDialect):
 
     @classmethod
     def merge(cls, tx, table, data, pk, on_conflict_do_nothing, on_conflict_update):
+        if not isinstance(data, Mapping) or not data:
+            raise ValueError("data must be a non-empty mapping of column-value pairs.")
+
+        table_helper = TableHelper(tx, table)
+        data = dict(data)  # work with a copy to avoid mutating the caller's dict
+
         if pk is None:
             pkeys = tx.table(table).primary_keys()
             if not pkeys:
                 raise ValueError("Primary key required for merge.")
-            # If there are multiple primary keys, use all of them
-            if len(pkeys) > 1:
-                pk = {pk: data[pk] for pk in pkeys}
-            else:
-                pk = {pkeys[0]: data[pkeys[0]]}
-            # Remove primary keys from data; they will be used in the conflict target
-            data = {k: v for k, v in data.items() if k not in pk}
+            missing = [key for key in pkeys if key not in data]
+            if missing:
+                missing_cols = ", ".join(missing)
+                raise ValueError(
+                    "Primary key values missing from data for merge: "
+                    f"{missing_cols}. Provide pk=... or include the key values in data."
+                )
+            pk = {key: data[key] for key in pkeys}
+        else:
+            pk = dict(pk)
+            for key, value in pk.items():
+                if key in data and data[key] != value:
+                    raise ValueError(
+                        f"Conflicting values for primary key '{key}' between data and pk arguments."
+                    )
 
-        # Create a merged dictionary for insert (data + primary key columns)
-        full_data = {}
-        full_data.update(data)
-        full_data.update(pk)
+        insert_data = dict(data)
+        insert_data.update(pk)
 
-        sql, vals = cls.insert(table, full_data)
-        sql = [sql]
-        vals = list(vals)  # Convert to a mutable list
+        update_data = {k: v for k, v in data.items() if k not in pk}
 
-        if on_conflict_do_nothing != on_conflict_update:
-            sql.append("ON CONFLICT")
-            sql.append("(")
-            sql.append(",".join(pk.keys()))
-            sql.append(")")
-            sql.append("DO")
-            if on_conflict_do_nothing:
-                sql.append("NOTHING")
-            elif on_conflict_update:
-                # Call update() with excluded=True to produce the SET clause for the upsert.
-                sql_update, vals_update = cls.update(tx, table, data, pk, excluded=True)
-                sql.append(sql_update)
-                # Use list.extend to add the update values to vals.
-                vals.extend(vals_update)
-        else:
+        if not update_data and on_conflict_update:
+            # Nothing to update, fall back to a no-op on conflict resolution.
+            on_conflict_do_nothing = True
+            on_conflict_update = False
+
+        if on_conflict_do_nothing == on_conflict_update:
             raise Exception(
                 "Update on conflict must have one and only one option to complete on conflict."
             )
 
+        sql, vals = cls.insert(table, insert_data)
+        sql = [sql]
+        vals = list(vals)  # Convert to a mutable list
+
+        sql.append("ON CONFLICT")
+        conflict_columns = [TableHelper.quote(column) for column in pk.keys()]
+        sql.append("(")
+        sql.append(", ".join(conflict_columns))
+        sql.append(")")
+        sql.append("DO")
+        if on_conflict_do_nothing:
+            sql.append("NOTHING")
+        elif on_conflict_update:
+            sql_update, vals_update = cls.update(
+                tx, table, update_data, pk, excluded=True
+            )
+            sql.append(sql_update)
+            vals.extend(vals_update)
+
         import sqlparse
 
         final_sql = sqlparse.format(" ".join(sql), reindent=True, keyword_case="upper")
         return final_sql, tuple(vals)
 
+    @classmethod
+    def insnx(cls, tx, table, data, where=None):
+        """Insert only when the supplied predicate finds no existing row."""
+        if not table:
+            raise ValueError("Table name is required.")
+        if not isinstance(data, Mapping) or not data:
+            raise ValueError("data must be a non-empty mapping of column-value pairs.")
+
+        # Helper used for quoting and foreign key resolution
+        th = TableHelper(tx, table)
+        quote_helper = TableHelper(None, table)
+
+        columns_sql = []
+        select_parts = []
+        vals = []
+
+        for key, val in data.items():
+            columns_sql.append(quote_helper.quote(key.lower()))
+            if isinstance(val, str) and len(val) > 2 and val.startswith("@@") and val[2:]:
+                select_parts.append(val[2:])
+            else:
+                select_parts.append("%s")
+                vals.append(val)
+
+        if not select_parts:
+            raise ValueError("At least one column is required for insert.")
+
+        if where is None:
+            if tx is None:
+                raise ValueError(
+                    "A transaction context is required when deriving WHERE from primary keys."
+                )
+            pk_cols = tx.table(table).primary_keys()
+            if not pk_cols:
+                raise ValueError("Primary key required to derive WHERE clause.")
+            missing = [pk for pk in pk_cols if pk not in data]
+            if missing:
+                raise ValueError(
+                    "Missing primary key value(s) for insert condition: " + ", ".join(missing)
+                )
+            where = {pk: data[pk] for pk in pk_cols}
+
+        where_clauses = []
+        where_vals = []
+
+        if isinstance(where, Mapping):
+            compiled = []
+            for key, val in where.items():
+                compiled.append(th.make_predicate(key, val))
+            where = compiled
+
+        if isinstance(where, str):
+            where_clauses.append(where)
+        else:
+            try:
+                for predicate, value in where:
+                    where_clauses.append(predicate)
+                    if value is None:
+                        continue
+                    if isinstance(value, tuple):
+                        where_vals.extend(value)
+                    else:
+                        where_vals.append(value)
+            except (TypeError, ValueError) as exc:
+                raise ValueError(
+                    "Invalid WHERE clause format. Expected mapping, SQL string, or iterable of predicate/value pairs."
+                ) from exc
+
+        vals.extend(where_vals)
+
+        exists_sql = [
+            "SELECT 1 FROM",
+            TableHelper.quote(table),
+        ]
+        if where_clauses:
+            exists_sql.append("WHERE " + " AND ".join(where_clauses))
+
+        sql_parts = [
+            "INSERT INTO",
+            TableHelper.quote(table),
+            f"({','.join(columns_sql)})",
+            "SELECT",
+            ", ".join(select_parts),
+            "WHERE NOT EXISTS (",
+            " ".join(exists_sql),
+            ")",
+        ]
+
+        final_sql = sqlparse.format(" ".join(sql_parts), reindent=True, keyword_case="upper")
+        return final_sql, tuple(vals)
+
+    insert_if_not_exists = insnx
+
     @classmethod
     def version(cls):
         return "select version()", tuple()
@@ -704,6 +817,7 @@ class SQL(BaseSQLDialect):
               sys_created TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
               sys_modified TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
               sys_modified_by TEXT NOT NULL DEFAULT 'SYSTEM',
+              sys_modified_row TIMESTAMP NOT NULL DEFAULT CLOCK_TIMESTAMP(),
               sys_modified_count INTEGER NOT NULL DEFAULT 0,
               sys_dirty BOOLEAN NOT NULL DEFAULT FALSE,
               sys_table TEXT NOT NULL,
@@ -718,8 +832,9 @@ class SQL(BaseSQLDialect):
                 BEGIN
                 IF (TG_OP = 'INSERT') THEN
                     NEW.sys_table := TG_TABLE_NAME;
-                    NEW.sys_created := clock_timestamp();
-                    NEW.sys_modified := clock_timestamp();
+                    NEW.sys_created := transaction_timestamp();
+                    NEW.sys_modified := transaction_timestamp();
+                    NEW.sys_modified_row := clock_timestamp();
                     NEW.sys_modified_count := 0;
                 ELSIF (TG_OP = 'UPDATE') THEN
                     NEW.sys_table := TG_TABLE_NAME;
@@ -731,7 +846,7 @@ class SQL(BaseSQLDialect):
                         ELSE
                             NEW.sys_dirty := TRUE;
                         END IF;
-                        NEW.sys_modified := clock_timestamp();
+                        NEW.sys_modified := transaction_timestamp();
                         NEW.sys_modified_count := COALESCE(OLD.sys_modified_count, 0) + 1;
                     END IF;
                 END IF;
@@ -761,8 +876,10 @@ class SQL(BaseSQLDialect):
         return sql, tuple()
 
     @classmethod
-    def ensure_sys_modified_count(cls, name, has_column=False):
-        """Return SQL to backfill sys_modified_count and refresh the on_sys_modified trigger."""
+    def ensure_sys_modified_count(
+        cls, name, has_column=False, has_row_column=False
+    ):
+        """Return SQL to backfill sys_modified_count/sys_modified_row and refresh the on_sys_modified trigger."""
         if "." in name:
             schema_name, table_name = name.split(".", 1)
         else:
@@ -780,15 +897,21 @@ class SQL(BaseSQLDialect):
         )
         trigger_identifier = TableHelper.quote(trigger_name)
         column_name = TableHelper.quote("sys_modified_count")
+        row_column_name = TableHelper.quote("sys_modified_row")
         
         statements = []
         if not has_column:
             statements.append(
                 f"ALTER TABLE {fqtn} ADD COLUMN {column_name} INTEGER NOT NULL DEFAULT 0;"
             )
+        if not has_row_column:
+            statements.append(
+                f"ALTER TABLE {fqtn} ADD COLUMN {row_column_name} TIMESTAMPTZ;"
+            )
 
         statements.extend([
             f"UPDATE {fqtn} SET {column_name} = 0 WHERE {column_name} IS NULL;",
+            f"UPDATE {fqtn} SET {row_column_name} = COALESCE({row_column_name}, clock_timestamp());",
             f"""
             CREATE OR REPLACE FUNCTION {schema_identifier}.on_sys_modified()
               RETURNS TRIGGER AS
@@ -796,8 +919,9 @@ class SQL(BaseSQLDialect):
             BEGIN
                 IF (TG_OP = 'INSERT') THEN
                     NEW.sys_table := TG_TABLE_NAME;
-                    NEW.sys_created := clock_timestamp();
-                    NEW.sys_modified := clock_timestamp();
+                    NEW.sys_created := transaction_timestamp();
+                    NEW.sys_modified := transaction_timestamp();
+                    NEW.sys_modified_row := clock_timestamp();
                     NEW.sys_modified_count := 0;
                 ELSIF (TG_OP = 'UPDATE') THEN
                     NEW.sys_table := TG_TABLE_NAME;
@@ -809,7 +933,8 @@ class SQL(BaseSQLDialect):
                         ELSE
                             NEW.sys_dirty := TRUE;
                         END IF;
-                        NEW.sys_modified := clock_timestamp();
+                        NEW.sys_modified := transaction_timestamp();
+                        NEW.sys_modified_row := clock_timestamp();
                         NEW.sys_modified_count := COALESCE(OLD.sys_modified_count, 0) + 1;
                     END IF;
                 END IF;

{velocity_python-0.0.145 → velocity_python-0.0.146}/src/velocity/db/servers/sqlite/sql.py

@@ -431,7 +431,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 exists for SQLite tables."""
         table_identifier = quote(name)
         base_name = name.split(".")[-1].replace('"', "")

{velocity_python-0.0.145 → velocity_python-0.0.146}/src/velocity/db/servers/sqlserver/sql.py

@@ -485,7 +485,9 @@ END;
         return "\n".join(statements), tuple()
 
     @classmethod
-    def ensure_sys_modified_count(cls, name, has_column=False):
+    def ensure_sys_modified_count(
+        cls, name, has_column=False, has_row_column=False
+    ):
         """Ensure sys_modified_count exists for SQL Server tables along with maintenance triggers."""
         if "." in name:
             schema, table_name = name.split(".", 1)