velocity-python 0.1.3__tar.gz → 0.1.4__tar.gz

{velocity_python-0.1.3 → velocity_python-0.1.4}/PKG-INFO

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

{velocity_python-0.1.3 → velocity_python-0.1.4}/pyproject.toml

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

{velocity_python-0.1.3 → velocity_python-0.1.4}/src/velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.1.3"
+__version__ = version = "0.1.4"
 
 import importlib as _importlib
 

{velocity_python-0.1.3 → velocity_python-0.1.4}/src/velocity/db/core/decorators.py

@@ -121,6 +121,12 @@ def return_default(
                     e,
                 )
 
+                # R12 — Increment per-transaction counter for swallowed exceptions.
+                try:
+                    self.tx._return_default_count = getattr(self.tx, "_return_default_count", 0) + 1
+                except Exception:
+                    pass
+
                 # Capture swallowed exceptions for upstream diagnostics.
                 # This decorator intentionally returns a default value instead of
                 # raising, but consumers (e.g. API handlers) may still want to

{velocity_python-0.1.3 → velocity_python-0.1.4}/src/velocity/db/core/engine.py

@@ -77,6 +77,7 @@ class ConnectionPool:
         if self._closed:
             raise exceptions.DbConnectionError("Connection pool is closed")
 
+        t0 = time.perf_counter()
         self._available.acquire()  # blocks when maxconn reached
 
         with self._lock:
@@ -84,7 +85,11 @@ class ConnectionPool:
             while self._pool:
                 conn = self._pool.pop()
                 if self._is_alive(conn):
-                    logger.debug("Pool: reusing idle connection (pool_size=%d)", len(self._pool))
+                    elapsed_ms = (time.perf_counter() - t0) * 1000
+                    logger.debug(
+                        "Pool: reusing idle connection (pool_size=%d, wait=%.1f ms)",
+                        len(self._pool), elapsed_ms,
+                    )
                     return conn
                 # Dead connection — close it silently and create a fresh one.
                 logger.debug("Pool: discarding dead idle connection")
@@ -95,7 +100,11 @@ class ConnectionPool:
             try:
                 conn = self._connect_fn()
                 self._total_created += 1
-                logger.debug("Pool: created new connection (total=%d)", self._total_created)
+                elapsed_ms = (time.perf_counter() - t0) * 1000
+                logger.debug(
+                    "Pool: created new connection (total=%d, wait=%.1f ms)",
+                    self._total_created, elapsed_ms,
+                )
                 return conn
             except Exception:
                 self._available.release()
@@ -277,10 +286,12 @@ class Engine:
         If pooling is enabled, borrows from the pool.
         If the database is missing, tries to create it, then reconnect.
         """
+        t0 = time.perf_counter()
         if self.__pool:
             try:
                 conn = self.__pool.getconn()
-                logger.debug("Engine.connect: obtained pooled connection")
+                elapsed_ms = (time.perf_counter() - t0) * 1000
+                logger.debug("Engine.connect: obtained pooled connection (%.1f ms)", elapsed_ms)
                 return conn
             except exceptions.DbDatabaseMissingError:
                 self.create_database()
@@ -291,7 +302,8 @@ class Engine:
 
         try:
             conn = self._raw_connect()
-            logger.debug("Engine.connect: created direct connection")
+            elapsed_ms = (time.perf_counter() - t0) * 1000
+            logger.debug("Engine.connect: created direct connection (%.1f ms)", elapsed_ms)
         except exceptions.DbDatabaseMissingError:
             self.create_database()
             conn = self._raw_connect()
@@ -496,6 +508,53 @@ class Engine:
             # if depth == 0:
             #     delattr(_tx, "_exec_function_depth")
 
+    def perf_log(self, func):
+        """
+        Decorator that logs wall time, query count, and total query time
+        for a ``@engine.transaction``-wrapped function.
+
+        Usage::
+
+            @engine.perf_log
+            @engine.transaction
+            def some_work(tx):
+                ...
+
+        The ``tx`` parameter **must** be a keyword argument or the first
+        positional ``Transaction`` so we can read its counters.
+        """
+
+        @wraps(func)
+        def wrapper(*args, **kwds):
+            t0 = time.perf_counter()
+            result = func(*args, **kwds)
+            wall_ms = (time.perf_counter() - t0) * 1000
+
+            # Find the Transaction among the arguments.
+            tx = kwds.get("tx")
+            if tx is None:
+                for a in args:
+                    if isinstance(a, Transaction):
+                        tx = a
+                        break
+
+            qcount = getattr(tx, "_query_count", 0) if tx else 0
+            qtime = getattr(tx, "_query_time_ms", 0.0) if tx else 0.0
+
+            logger.info(
+                "perf_log %s: wall=%.1f ms, queries=%d, query_time=%.1f ms",
+                getattr(func, "__qualname__", func.__name__),
+                wall_ms, qcount, qtime,
+                extra={
+                    "wall_ms": round(wall_ms, 1),
+                    "query_count": qcount,
+                    "query_time_ms": round(qtime, 1),
+                },
+            )
+            return result
+
+        return wrapper
+
     @property
     def driver(self):
         return self.__driver

{velocity_python-0.1.3 → velocity_python-0.1.4}/src/velocity/db/core/transaction.py

@@ -1,4 +1,6 @@
+import logging
 import os
+import time as _time
 import traceback
 from collections import OrderedDict
 
@@ -14,9 +16,60 @@ from velocity.misc.db import randomword
 
 debug = False
 
+_logger = logging.getLogger("velocity.db.transaction")
+
 # Default maximum number of cached query results per transaction.
 _DEFAULT_QUERY_CACHE_SIZE = int(os.environ.get("VELOCITY_QUERY_CACHE_SIZE", "100"))
 
+# Slow-query threshold in milliseconds (0 = disabled).
+_SLOW_QUERY_MS = int(os.environ.get("VELOCITY_SLOW_QUERY_MS", "500"))
+
+_SQL_OP_PREFIXES = {
+    "select": "SELECT",
+    "insert": "INSERT",
+    "update": "UPDATE",
+    "delete": "DELETE",
+    "create": "DDL",
+    "alter": "DDL",
+    "drop": "DDL",
+    "set": "SET",
+}
+
+
+def _classify_sql(sql):
+    """Return a short operation label (SELECT, INSERT, …) from a SQL string."""
+    if not sql:
+        return "OTHER"
+    first = sql.lstrip().split(None, 1)[0].lower() if sql.strip() else ""
+    return _SQL_OP_PREFIXES.get(first, "OTHER")
+
+
+def _extract_table_name(sql):
+    """Best-effort extraction of the main table name from a SQL statement."""
+    if not sql:
+        return None
+    upper = sql.strip().upper()
+    lowered = sql.strip()
+    try:
+        if upper.startswith("SELECT"):
+            idx = upper.find(" FROM ")
+            if idx != -1:
+                rest = lowered[idx + 6:].strip()
+                return rest.split()[0].strip('"').strip("'") if rest else None
+        elif upper.startswith("INSERT"):
+            idx = upper.find(" INTO ")
+            if idx != -1:
+                rest = lowered[idx + 6:].strip()
+                return rest.split()[0].strip('"').strip("'") if rest else None
+        elif upper.startswith(("UPDATE", "DELETE FROM")):
+            parts = lowered.split()
+            if len(parts) >= 2:
+                token = parts[2] if upper.startswith("DELETE") and len(parts) > 2 else parts[1]
+                return token.strip('"').strip("'")
+    except (IndexError, ValueError):
+        pass
+    return None
+
 
 class Transaction:
     """
@@ -32,6 +85,10 @@ class Transaction:
         # R5 — Transaction-scoped query cache (opt-in via cache=True on select).
         self.__query_cache: OrderedDict = OrderedDict()
         self.__query_cache_max = _DEFAULT_QUERY_CACHE_SIZE
+        # R12 — Observability counters.
+        self._query_count = 0
+        self._query_time_ms = 0.0
+        self._return_default_count = 0
 
     def __str__(self):
         config = mask_config_for_display(self.engine.config)
@@ -119,6 +176,7 @@ class Transaction:
         if prepare is None:
             prepare = getattr(self.engine, "prepare_enabled", False)
 
+        t0 = _time.perf_counter()
         try:
             if parms:
                 cursor.execute(sql, parms, prepare=prepare)
@@ -136,6 +194,24 @@ class Transaction:
         except Exception as e:
             raise self.engine.process_error(e, sql, parms)
 
+        elapsed_ms = (_time.perf_counter() - t0) * 1000
+        self._query_count += 1
+        self._query_time_ms += elapsed_ms
+
+        # R12 — Slow query logging.
+        if _SLOW_QUERY_MS and elapsed_ms > _SLOW_QUERY_MS:
+            op = _classify_sql(sql)
+            tbl = _extract_table_name(sql)
+            _logger.warning(
+                "Slow query (%s): %.1f ms table=%s",
+                op, elapsed_ms, tbl,
+                extra={
+                    "query_duration_ms": round(elapsed_ms, 1),
+                    "table_name": tbl,
+                    "operation": op,
+                },
+            )
+
         if single:
             self.connection.autocommit = False
 
@@ -195,6 +271,15 @@ class Transaction:
             if debug:
                 print(f"{id(self)} --- connection commit.")
             self.connection.commit()
+            if self._query_count:
+                _logger.debug(
+                    "Transaction commit: %d queries in %.1f ms",
+                    self._query_count, self._query_time_ms,
+                    extra={
+                        "query_count": self._query_count,
+                        "query_time_ms": round(self._query_time_ms, 1),
+                    },
+                )
 
     def rollback(self):
         """

{velocity_python-0.1.3 → velocity_python-0.1.4}/src/velocity_python.egg-info/PKG-INFO

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

{velocity_python-0.1.3 → velocity_python-0.1.4}/src/velocity_python.egg-info/SOURCES.txt

@@ -159,6 +159,7 @@ tests/test_iconv_money_to_cents.py
 tests/test_lambda_handler.py
 tests/test_lambda_handler_auth.py
 tests/test_mixins_import.py
+tests/test_observability.py
 tests/test_payment_braintree_adapter.py
 tests/test_payment_demo_profiles.py
 tests/test_payment_profiles.py