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

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

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

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

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

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

{velocity_python-0.1.3 → velocity_python-0.1.5}/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.5}/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.5}/src/velocity/db/core/result.py

@@ -1,5 +1,6 @@
 import warnings
 from velocity.misc.format import to_json
+from velocity.db.core.row import Row
 
 
 class Result:
@@ -310,6 +311,27 @@ class Result:
         self.transform = lambda row: row
         return self
 
+    def as_rows(self, table):
+        """Transform each row into a :class:`Row` with a pre-populated cache.
+
+        This converts a ``SELECT`` result set into Row objects without
+        triggering extra queries, preventing the N+1 pattern::
+
+            rows = table.select(where={"status": "active"}).as_rows(table)
+            for row in rows.all():
+                print(row["name"])  # no extra SELECT
+
+        Args:
+            table: The :class:`Table` the rows belong to.
+
+        Returns:
+            This ``Result`` (for chaining). Each iteration yields a :class:`Row`.
+        """
+        self.as_dict()  # ensure we get dicts first
+        _original = self.transform
+        self.transform = lambda raw_row: Row._from_data(table, _original(raw_row))
+        return self
+
     def as_simple_list(self, pos=0):
         """
         Transform each row into the single value at position `pos`.

{velocity_python-0.1.3 → velocity_python-0.1.5}/src/velocity/db/core/row.py

@@ -51,6 +51,35 @@ class Row(MutableMapping):
         if lock:
             self.lock()
 
+    @classmethod
+    def _from_data(cls, table, data):
+        """Create a Row with its cache pre-populated from *data*.
+
+        This avoids the lazy SELECT that normally fires on first attribute
+        access, eliminating the N+1 problem when you already have the full
+        row dict (e.g. from a bulk ``SELECT``).
+
+        Args:
+            table: The :class:`Table` instance this row belongs to.
+            data:  A ``dict`` of ``{column_name: value}`` for the row.
+                   Must include the primary-key column(s).
+
+        Returns:
+            A fully-initialised :class:`Row` whose local cache is *data*.
+        """
+        row = cls.__new__(cls)
+        pk = {k: data[k] for k in ("sys_id",) if k in data}
+        object.__setattr__(row, "table", table)
+        object.__setattr__(row, "pk", pk)
+        object.__setattr__(row, "_cache", dict(data))
+        object.__setattr__(row, "_column_set", None)
+        object.__setattr__(row, "_batching", False)
+        object.__setattr__(row, "_pending", {})
+        object.__setattr__(row, "_cache_ttl", None)
+        object.__setattr__(row, "_cache_time", _time.monotonic())
+        object.__setattr__(row, "_no_cache", False)
+        return row
+
     # ------------------------------------------------------------------
     # Cache management
     # ------------------------------------------------------------------

{velocity_python-0.1.3 → velocity_python-0.1.5}/src/velocity/db/core/table.py

@@ -423,14 +423,40 @@ class Table:
         r = self.find(key)
         return r.to_dict() if r else {}
 
-    def rows(self, where=None, orderby=None, qty=None, lock=None, skip_locked=None, cache_ttl=None, no_cache=False):
+    def rows(self, where=None, orderby=None, qty=None, lock=None, skip_locked=None, cache_ttl=None, no_cache=False, prefetch=False):
         """
         Generator that yields Row objects matching `where`, up to `qty`.
+
+        When *prefetch* is True a single SELECT fetches all matching data
+        and each yielded Row has its cache pre-populated, avoiding the
+        N+1 pattern where every Row triggers a lazy SELECT on first access.
         """
-        for key in self.ids(
-            where=where, orderby=orderby, qty=qty, lock=lock, skip_locked=skip_locked
-        ):
-            yield Row(self, key, lock=lock, cache_ttl=cache_ttl, no_cache=no_cache)
+        if prefetch:
+            result = self.select(
+                where=where, orderby=orderby, qty=qty, lock=lock, skip_locked=skip_locked,
+            )
+            for data in result:
+                yield Row._from_data(self, data)
+        else:
+            for key in self.ids(
+                where=where, orderby=orderby, qty=qty, lock=lock, skip_locked=skip_locked
+            ):
+                yield Row(self, key, lock=lock, cache_ttl=cache_ttl, no_cache=no_cache)
+
+    def select_rows(self, where=None, orderby=None, qty=None, lock=None, skip_locked=None):
+        """Return a list of Row objects with pre-populated caches from a single SELECT.
+
+        This is the recommended way to load multiple rows when you need
+        Row-level write-through behaviour but want to avoid the N+1
+        problem inherent in :meth:`rows`.
+
+        Equivalent to ``list(table.rows(where=..., prefetch=True))``
+        but expressed as a convenience method.
+        """
+        result = self.select(
+            where=where, orderby=orderby, qty=qty, lock=lock, skip_locked=skip_locked,
+        )
+        return [Row._from_data(self, data) for data in result]
 
     def ids(
         self,

{velocity_python-0.1.3 → velocity_python-0.1.5}/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,65 @@ 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"))
+
+# N+1 detection: warn when the same table is SELECTed more than this many
+# times within a single transaction.  0 = disabled.  Only active when the
+# module-level ``debug`` flag is True.
+_N_PLUS_1_THRESHOLD = int(os.environ.get("VELOCITY_N_PLUS_1_THRESHOLD", "10"))
+
+_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 +90,13 @@ 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
+        # R14 — N+1 detection: per-table SELECT counts.
+        self._table_select_counts: dict[str, int] = {}
+        self._n1_warned: set[str] = set()
 
     def __str__(self):
         config = mask_config_for_display(self.engine.config)
@@ -119,6 +184,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 +202,41 @@ 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,
+                },
+            )
+
+        # R14 — N+1 detection (only when debug=True).
+        if debug and _N_PLUS_1_THRESHOLD:
+            op = _classify_sql(sql)
+            if op == "SELECT":
+                tbl = _extract_table_name(sql)
+                if tbl:
+                    self._table_select_counts[tbl] = self._table_select_counts.get(tbl, 0) + 1
+                    count = self._table_select_counts[tbl]
+                    if count > _N_PLUS_1_THRESHOLD and tbl not in self._n1_warned:
+                        self._n1_warned.add(tbl)
+                        _logger.warning(
+                            "Possible N+1: table %s queried %d times in this transaction "
+                            "(threshold=%d). Consider using prefetch=True or select_rows().",
+                            tbl, count, _N_PLUS_1_THRESHOLD,
+                            extra={"table_name": tbl, "select_count": count},
+                        )
+
         if single:
             self.connection.autocommit = False
 
@@ -195,6 +296,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.5}/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.5
 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.5}/src/velocity_python.egg-info/SOURCES.txt

@@ -159,6 +159,8 @@ 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_n_plus_one.py
+tests/test_observability.py
 tests/test_payment_braintree_adapter.py
 tests/test_payment_demo_profiles.py
 tests/test_payment_profiles.py