velocity-python 0.1.12__tar.gz → 0.1.14__tar.gz

{velocity_python-0.1.12/src/velocity_python.egg-info → velocity_python-0.1.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.1.12
+Version: 0.1.14
 Summary: A rapid application development library for interfacing with data storage
 Author-email: Velocity Team <info@codeclubs.org>
 License-Expression: MIT
@@ -29,6 +29,8 @@ Provides-Extra: excel
 Requires-Dist: openpyxl>=3.1.0; extra == "excel"
 Provides-Extra: templates
 Requires-Dist: jinja2>=3.1.0; extra == "templates"
+Provides-Extra: pdf
+Requires-Dist: weasyprint>=62.0; extra == "pdf"
 Provides-Extra: http
 Requires-Dist: requests>=2.32.0; extra == "http"
 Provides-Extra: mysql
@@ -41,7 +43,7 @@ Provides-Extra: payment
 Requires-Dist: stripe>=12.0.0; extra == "payment"
 Requires-Dist: braintree>=4.30.0; extra == "payment"
 Provides-Extra: all
-Requires-Dist: velocity-python[aws,excel,http,payment,postgres,templates]; extra == "all"
+Requires-Dist: velocity-python[aws,excel,http,payment,pdf,postgres,templates]; extra == "all"
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0.0; extra == "dev"
 Requires-Dist: pytest-cov>=6.0.0; extra == "dev"

{velocity_python-0.1.12 → velocity_python-0.1.14}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "velocity-python"
-version = "0.1.12"
+version = "0.1.14"
 authors = [
   { name="Velocity Team", email="info@codeclubs.org" },
 ]
@@ -48,6 +48,9 @@ excel = [
 templates = [
   "jinja2>=3.1.0",
 ]
+pdf = [
+  "weasyprint>=62.0",
+]
 http = [
   "requests>=2.32.0",
 ]
@@ -65,7 +68,7 @@ payment = [
   "braintree>=4.30.0",
 ]
 all = [
-  "velocity-python[postgres,aws,excel,templates,http,payment]",
+  "velocity-python[postgres,aws,excel,templates,http,payment,pdf]",
 ]
 dev = [
   "pytest>=8.0.0",

{velocity_python-0.1.12 → velocity_python-0.1.14}/src/velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.1.12"
+__version__ = version = "0.1.14"
 
 import importlib as _importlib
 

{velocity_python-0.1.12 → velocity_python-0.1.14}/src/velocity/db/core/engine.py

@@ -2,6 +2,7 @@ import inspect
 import os
 import re
 import time
+import traceback
 import threading
 from contextlib import contextmanager
 from functools import wraps
@@ -14,6 +15,51 @@ import logging
 logger = logging.getLogger("velocity.db.engine")
 logger.setLevel(logging.INFO)  # Or DEBUG for more verbosity
 
+# Map category keys (matching SQL dialect attribute name prefixes) to exception classes.
+_CATEGORY_EXCEPTION_MAP = {
+    "Application":       exceptions.DbApplicationError,
+    "ColumnMissing":     exceptions.DbColumnMissingError,
+    "TableMissing":      exceptions.DbTableMissingError,
+    "DatabaseMissing":   exceptions.DbDatabaseMissingError,
+    "ForeignKeyMissing": exceptions.DbForeignKeyMissingError,
+    "Truncation":        exceptions.DbTruncationError,
+    "DataIntegrity":     exceptions.DbDataIntegrityError,
+    "Connection":        exceptions.DbConnectionError,
+    "DuplicateKey":      exceptions.DbDuplicateKeyError,
+    "ObjectExists":      exceptions.DbObjectExistsError,
+    "LockTimeout":       exceptions.DbLockTimeoutError,
+    "RetryTransaction":  exceptions.DbRetryTransaction,
+}
+
+# Attribute names on BaseSQLDialect, in the order they should be checked.
+_CODE_LIST_ATTRS = [
+    ("ApplicationErrorCodes",          "Application"),
+    ("ColumnMissingErrorCodes",        "ColumnMissing"),
+    ("TableMissingErrorCodes",         "TableMissing"),
+    ("DatabaseMissingErrorCodes",      "DatabaseMissing"),
+    ("ForeignKeyMissingErrorCodes",    "ForeignKeyMissing"),
+    ("TruncationErrorCodes",           "Truncation"),
+    ("DataIntegrityErrorCodes",        "DataIntegrity"),
+    ("ConnectionErrorCodes",           "Connection"),
+    ("DuplicateKeyErrorCodes",         "DuplicateKey"),
+    ("DatabaseObjectExistsErrorCodes", "ObjectExists"),
+    ("LockTimeoutErrorCodes",          "LockTimeout"),
+    ("RetryTransactionCodes",          "RetryTransaction"),
+]
+
+
+def _build_error_code_map(sql_dialect) -> dict:
+    """Build a {code: exception_class} dict from a dialect's code lists."""
+    code_map: dict = {}
+    for attr, category in _CODE_LIST_ATTRS:
+        exc_cls = _CATEGORY_EXCEPTION_MAP[category]
+        for code in getattr(sql_dialect, attr, ()):
+            code_map.setdefault(code, exc_cls)   # first match wins
+    return code_map
+
+# Path of this file — used to filter stack frames.
+_ENGINE_FILE = os.path.normpath(__file__)
+
 
 class ConnectionPool:
     """
@@ -198,6 +244,9 @@ class Engine:
         self.__sql = sql
         self.__driver = driver
 
+        # Pre-build the error-code → exception-class lookup for O(1) classification.
+        self.__error_code_map = _build_error_code_map(sql) if sql else {}
+
         if connect_timeout is None:
             connect_timeout = int(os.environ.get("VELOCITY_CONNECT_TIMEOUT", "5"))
         self.__connect_timeout = connect_timeout
@@ -739,115 +788,88 @@ class Engine:
         """
         Central method to parse driver exceptions and re-raise them as our custom exceptions.
         """
-        logger = logging.getLogger(__name__)
-
-        # If it's already a velocity exception, just re-raise it
+        # If it's already a velocity exception, just re-raise it.
         if isinstance(exception, exceptions.DbException):
             raise exception
 
-        # Get error code and message from the SQL driver
+        # Extract error code & message from the driver exception.
         try:
             error_code, error_message = self.sql.get_error(exception)
         except Exception:
             error_code, error_message = None, str(exception)
 
-        msg = str(exception).strip().lower()
+        msg = str(exception)
 
-        # Create enhanced error message with SQL query and context
-        enhanced_message = str(exception)
+        # ── Build enhanced message ───────────────────────────────────
+        enhanced_message = msg
 
-        # Add specific guidance for common WHERE clause errors
-        exception_str_lower = str(exception).lower()
-        if "argument of where must be type boolean" in exception_str_lower:
-            enhanced_message += (
-                "\n\n*** WHERE CLAUSE ERROR ***\n"
-                "This error typically occurs when a WHERE clause contains a bare value "
-                "instead of a proper boolean expression.\n"
-                "Common fixes:\n"
-                "  - Change WHERE 1001 to WHERE sys_id = 1001\n"
-                "  - Change WHERE {'column': value} format in dictionaries\n"
-                "  - Ensure string WHERE clauses are complete SQL expressions"
-            )
+        # Dialect-specific developer guidance (e.g. WHERE-clause hints).
+        try:
+            hint = self.sql.enhance_message(msg)
+        except (AttributeError, TypeError):
+            hint = None
+        if isinstance(hint, str):
+            enhanced_message += hint
 
         if sql:
             enhanced_message += (
                 f"\n\nSQL Query:\n{self._format_sql_with_params(sql, parameters)}"
             )
 
-        # Add call stack context for better debugging
-        import traceback
-
-        stack_trace = traceback.format_stack()
-        # Get the last few frames that aren't in the error handling itself
+        # Append a few relevant call-stack frames for context.
         relevant_frames = [
-            frame
-            for frame in stack_trace
-            if "process_error" not in frame and "logging" not in frame
+            frame for frame in traceback.format_stack()
+            if _ENGINE_FILE not in frame
         ][-3:]
         if relevant_frames:
             enhanced_message += "\n\nCall Context:\n" + "".join(relevant_frames)
 
-        # Mask any credentials that may have leaked into driver error messages
-        # (e.g. connection strings containing password=...).
+        # Mask credentials that may have leaked into driver error text.
         enhanced_message = mask_sensitive_in_string(enhanced_message)
 
-        # Note: SQL formatting for logging is available via _format_sql_with_params,
-        # but we intentionally avoid eager logging here.
-
-        # Direct error code mapping
-        if error_code in self.sql.ApplicationErrorCodes:
-            raise exceptions.DbApplicationError(enhanced_message) from exception
-        if error_code in self.sql.ColumnMissingErrorCodes:
-            raise exceptions.DbColumnMissingError(enhanced_message) from exception
-        if error_code in self.sql.TableMissingErrorCodes:
-            raise exceptions.DbTableMissingError(enhanced_message) from exception
-        if error_code in self.sql.DatabaseMissingErrorCodes:
-            raise exceptions.DbDatabaseMissingError(enhanced_message) from exception
-        if error_code in self.sql.ForeignKeyMissingErrorCodes:
-            raise exceptions.DbForeignKeyMissingError(enhanced_message) from exception
-        if error_code in self.sql.TruncationErrorCodes:
-            raise exceptions.DbTruncationError(enhanced_message) from exception
-        if error_code in self.sql.DataIntegrityErrorCodes:
-            raise exceptions.DbDataIntegrityError(enhanced_message) from exception
-        if error_code in self.sql.ConnectionErrorCodes:
-            raise exceptions.DbConnectionError(enhanced_message) from exception
-        if error_code in self.sql.DuplicateKeyErrorCodes:
-            raise exceptions.DbDuplicateKeyError(enhanced_message) from exception
-        if error_code in self.sql.DatabaseObjectExistsErrorCodes:
-            raise exceptions.DbObjectExistsError(enhanced_message) from exception
-        if error_code in self.sql.LockTimeoutErrorCodes:
-            raise exceptions.DbLockTimeoutError(enhanced_message) from exception
-        if error_code in self.sql.RetryTransactionCodes:
-            raise exceptions.DbRetryTransaction(enhanced_message) from exception
-
-        # Regex-based fallback patterns
-        if re.search(r"key \(sys_id\)=\(\d+\) already exists.", msg, re.M):
-            raise exceptions.DbDuplicateKeyError(enhanced_message) from exception
-        if re.findall(r"database.*does not exist", msg, re.M):
-            raise exceptions.DbDatabaseMissingError(enhanced_message) from exception
-        if re.findall(r"no such database", msg, re.M):
-            raise exceptions.DbDatabaseMissingError(enhanced_message) from exception
-        if re.findall(r"already exists", msg, re.M):
-            raise exceptions.DbObjectExistsError(enhanced_message) from exception
-        # Dialect-specific connection error message classification (fallback when no/unknown code).
-        if getattr(self.sql, "is_connection_error_message", lambda _m: False)(msg):
-            raise exceptions.DbConnectionError(enhanced_message) from exception
-        if "no such table:" in msg:
-            raise exceptions.DbTableMissingError(enhanced_message) from exception
+        # ── Classify by error code (O(1) dict lookup) ────────────────
+        code_map = getattr(self, '_Engine__error_code_map', None) or {}
+        exc_cls = code_map.get(error_code) if error_code else None
 
+        # ── Classify by message text (dialect-specific fallback) ─────
+        if exc_cls is None:
+            try:
+                category = self.sql.classify_by_message(msg)
+            except (AttributeError, TypeError):
+                category = None
+            if isinstance(category, str):
+                exc_cls = _CATEGORY_EXCEPTION_MAP.get(category)
+
+        # ── Raise the classified exception ───────────────────────────
+        if exc_cls is not None:
+            logger.warning(
+                "DB error classified: code=%s message=%s type=%s → %s",
+                error_code, error_message,
+                type(exception).__name__, exc_cls.__name__,
+                extra={
+                    "error_code": error_code,
+                    "error_msg": error_message,
+                    "classified_as": exc_cls.__name__,
+                    "sql_stmt": sql,
+                    "sql_params": parameters,
+                },
+            )
+            raise exc_cls(enhanced_message) from exception
+
+        # ── Unclassified — log and wrap in DbException ───────────────
         logger.error(
             "Unhandled/Unknown Error in engine.process_error",
             exc_info=True,
             extra={
                 "error_code": error_code,
                 "error_msg": error_message,
+                "original_exception_type": type(exception).__name__,
+                "available_error_codes": list(code_map.keys()),
                 "sql_stmt": sql,
                 "sql_params": parameters,
             },
         )
-
-        # If we can't classify it, re-raise with enhanced message
-        raise type(exception)(enhanced_message) from exception
+        raise exceptions.DbException(enhanced_message) from exception
 
     def _format_sql_with_params(self, sql, parameters):
         """

{velocity_python-0.1.12 → velocity_python-0.1.14}/src/velocity/db/servers/base/sql.py

@@ -79,6 +79,30 @@ class BaseSQLDialect(ABC):
         """
         return False
 
+    @classmethod
+    def classify_by_message(cls, msg: str) -> Optional[str]:
+        """Classify an error by its message text when no error code is available.
+
+        Returns an exception-category key understood by Engine._error_code_map,
+        or None if the message cannot be classified.  Dialects override this to
+        add database-specific message patterns.
+
+        Recognised keys (matching the code-list attribute names):
+            "DuplicateKey", "DatabaseMissing", "TableMissing", "ColumnMissing",
+            "Connection", "ObjectExists", "Application", "DataIntegrity",
+            "Truncation", "ForeignKeyMissing", "LockTimeout", "RetryTransaction"
+        """
+        return None
+
+    @classmethod
+    def enhance_message(cls, msg: str) -> Optional[str]:
+        """Return additional guidance text for a driver error, or None.
+
+        Dialects override this to provide developer-friendly hints for common
+        mistakes (e.g. bare values in WHERE clauses).
+        """
+        return None
+
     # Core CRUD Operations
     @classmethod
     @abstractmethod

{velocity_python-0.1.12 → velocity_python-0.1.14}/src/velocity/db/servers/mysql/sql.py

@@ -116,6 +116,29 @@ class SQL(BaseSQLDialect):
         )
         return not any(n in m for n in non_transient)
 
+    @classmethod
+    def classify_by_message(cls, msg: str):
+        if not msg:
+            return None
+        m = msg.strip().lower()
+        if "duplicate entry" in m:
+            return "DuplicateKey"
+        if "unknown database" in m:
+            return "DatabaseMissing"
+        if "doesn't exist" in m and "table" in m:
+            return "TableMissing"
+        if "unknown column" in m:
+            return "ColumnMissing"
+        if "already exists" in m:
+            return "ObjectExists"
+        if "deadlock found" in m:
+            return "RetryTransaction"
+        if "lock wait timeout" in m:
+            return "LockTimeout"
+        if cls.is_connection_error_message(msg):
+            return "Connection"
+        return None
+
     @classmethod
     def select(
         cls,

{velocity_python-0.1.12 → velocity_python-0.1.14}/src/velocity/db/servers/postgres/sql.py

@@ -116,6 +116,42 @@ class SQL(BaseSQLDialect):
         # For Postgres, low-level disconnects/restarts are typically transient.
         return cls.is_connection_error_message(msg)
 
+    @classmethod
+    def classify_by_message(cls, msg: str):
+        if not msg:
+            return None
+        m = msg.strip().lower()
+        # Order matters — more specific patterns first.
+        if re.search(r"key \(.*?\)=\(.*?\) already exists", m):
+            return "DuplicateKey"
+        if re.search(r"duplicate key value violates unique constraint", m):
+            return "DuplicateKey"
+        if re.search(r"database.*does not exist", m):
+            return "DatabaseMissing"
+        if "no such database" in m:
+            return "DatabaseMissing"
+        if re.search(r"relation .* already exists", m):
+            return "ObjectExists"
+        if "already exists" in m:
+            return "ObjectExists"
+        if cls.is_connection_error_message(msg):
+            return "Connection"
+        return None
+
+    @classmethod
+    def enhance_message(cls, msg: str):
+        if msg and "argument of where must be type boolean" in msg.lower():
+            return (
+                "\n\n*** WHERE CLAUSE ERROR ***\n"
+                "This error typically occurs when a WHERE clause contains a bare value "
+                "instead of a proper boolean expression.\n"
+                "Common fixes:\n"
+                "  - Change WHERE 1001 to WHERE sys_id = 1001\n"
+                "  - Change WHERE {'column': value} format in dictionaries\n"
+                "  - Ensure string WHERE clauses are complete SQL expressions"
+            )
+        return None
+
     @staticmethod
     def _validate_where_string(where):
         """

{velocity_python-0.1.12 → velocity_python-0.1.14}/src/velocity/db/servers/sqlite/sql.py

@@ -90,6 +90,25 @@ class SQL(BaseSQLDialect):
         # SQLite connection/file errors are typically not transient in-process.
         return False
 
+    @classmethod
+    def classify_by_message(cls, msg: str):
+        if not msg:
+            return None
+        m = msg.strip().lower()
+        if "unique constraint failed" in m or "is not unique" in m:
+            return "DuplicateKey"
+        if "no such table:" in m:
+            return "TableMissing"
+        if "no such column:" in m:
+            return "ColumnMissing"
+        if "already exists" in m:
+            return "ObjectExists"
+        if "database is locked" in m:
+            return "LockTimeout"
+        if cls.is_connection_error_message(msg):
+            return "Connection"
+        return None
+
     @classmethod
     def select(
         cls,

{velocity_python-0.1.12 → velocity_python-0.1.14}/src/velocity/db/servers/sqlserver/sql.py

@@ -113,6 +113,29 @@ class SQL(BaseSQLDialect):
             return False
         return True
 
+    @classmethod
+    def classify_by_message(cls, msg: str):
+        if not msg:
+            return None
+        m = msg.strip().lower()
+        if "violation of primary key" in m or "violation of unique key" in m:
+            return "DuplicateKey"
+        if "cannot open database" in m:
+            return "DatabaseMissing"
+        if "invalid object name" in m:
+            return "TableMissing"
+        if "invalid column name" in m:
+            return "ColumnMissing"
+        if "already exists" in m:
+            return "ObjectExists"
+        if "deadlock victim" in m:
+            return "RetryTransaction"
+        if "lock request time out" in m:
+            return "LockTimeout"
+        if cls.is_connection_error_message(msg):
+            return "Connection"
+        return None
+
     @classmethod
     def select(
         cls,

{velocity_python-0.1.12 → velocity_python-0.1.14}/src/velocity/db/tests/postgres/test_engine.py

@@ -1,6 +1,7 @@
 import os
 import datetime
 import unittest
+from velocity.db import exceptions
 from velocity.db.core.engine import Engine
 from velocity.db.core.transaction import Transaction
 from .common import CommonPostgresTest, engine, test_db
@@ -51,14 +52,9 @@ class TestEngine(CommonPostgresTest):
         assert [] == engine.tables
 
     def test_process_error(self, tx):
-        local_engine = Engine(
-            None, None, None
-        )  # Replace None with appropriate arguments
-        with self.assertRaises(
-            Exception
-        ):  # Replace Exception with the specific exception raised by process_error
-            local_engine.process_error(sql_stmt=None, sql_params=None)
-        # Add additional assertions as needed
+        exc = Exception("some driver error")
+        with self.assertRaises(exceptions.DbException):
+            engine.process_error(exc)
 
     def test_transaction_injection_1(self, tx):
         @engine.transaction