velocity-python 0.1.68__tar.gz → 0.1.70__tar.gz

{velocity_python-0.1.68 → velocity_python-0.1.70}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.1.68
+Version: 0.1.70
 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.68 → velocity_python-0.1.70}/pyproject.toml

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

{velocity_python-0.1.68 → velocity_python-0.1.70}/src/velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.1.68"
+__version__ = version = "0.1.70"
 
 import importlib as _importlib
 

{velocity_python-0.1.68 → velocity_python-0.1.70}/src/velocity/db/core/engine.py

@@ -548,10 +548,32 @@ class Engine:
                 if attr_name.startswith("__") and attr_name.endswith("__"):
                     continue
 
-                attr = getattr(func_or_cls, attr_name)
-
-                if callable(attr):
-                    setattr(NewCls, attr_name, self.transaction(attr))
+                # Inspect the attribute *as defined* (without triggering the
+                # descriptor) so that @staticmethod / @classmethod keep their
+                # nature. Plain getattr() resolves a staticmethod to its bare
+                # function; re-setting that as a class attribute turns it into an
+                # instance method, silently injecting `self` as the first
+                # positional arg and breaking every static/class method on the
+                # wrapped class. Wrap the underlying function but re-apply the
+                # original descriptor so the call signature is preserved.
+                raw = inspect.getattr_static(func_or_cls, attr_name, None)
+
+                if isinstance(raw, staticmethod):
+                    setattr(
+                        NewCls,
+                        attr_name,
+                        staticmethod(self.transaction(raw.__func__)),
+                    )
+                elif isinstance(raw, classmethod):
+                    setattr(
+                        NewCls,
+                        attr_name,
+                        classmethod(self.transaction(raw.__func__)),
+                    )
+                else:
+                    attr = getattr(func_or_cls, attr_name)
+                    if callable(attr):
+                        setattr(NewCls, attr_name, self.transaction(attr))
 
             return NewCls
 

{velocity_python-0.1.68 → velocity_python-0.1.70}/src/velocity/db/core/result.py

@@ -1,4 +1,3 @@
-import warnings
 from velocity.misc.format import to_json
 from velocity.db.core.row import Row
 
@@ -288,15 +287,6 @@ class Result:
         self.transform = lambda row: list(zip(self.headers, row))
         return self
 
-    def as_named_tuple(self):
-        """Deprecated: use as_pairs() instead."""
-        warnings.warn(
-            "Result.as_named_tuple() is deprecated, use Result.as_pairs() instead.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        return self.as_pairs()
-
     def as_list(self):
         """
         Transform each row into a list of values.

{velocity_python-0.1.68 → velocity_python-0.1.70}/src/velocity/db/core/row.py

@@ -1,3 +1,4 @@
+import json as _json
 import pprint
 import time as _time
 from collections.abc import MutableMapping
@@ -9,7 +10,7 @@ from velocity.db.core import jsonproxy
 # intercepted by __getattr__ / __setattr__.
 _INTERNAL_ATTRS = frozenset({
     "table", "pk", "_cache", "_column_set", "_batching", "_pending",
-    "_cache_ttl", "_cache_time", "_no_cache", "_dirty_tracking", "_dirty",
+    "_cache_ttl", "_cache_time", "_no_cache",
 })
 
 
@@ -25,7 +26,7 @@ class Row(MutableMapping):
     write-through (immediate UPDATE) and also update the local cache.
     """
 
-    def __init__(self, table, key, lock=None, cache_ttl=None, no_cache=False, dirty_tracking=False):
+    def __init__(self, table, key, lock=None, cache_ttl=None, no_cache=False):
         if isinstance(table, str):
             raise Exception("Table parameter must be a `table` instance.")
         object.__setattr__(self, "table", table)
@@ -48,8 +49,6 @@ class Row(MutableMapping):
         object.__setattr__(self, "_cache_ttl", cache_ttl)
         object.__setattr__(self, "_cache_time", None)
         object.__setattr__(self, "_no_cache", no_cache)
-        object.__setattr__(self, "_dirty_tracking", dirty_tracking)
-        object.__setattr__(self, "_dirty", {})
         if lock:
             self.lock()
 
@@ -80,8 +79,6 @@ class Row(MutableMapping):
         object.__setattr__(row, "_cache_ttl", None)
         object.__setattr__(row, "_cache_time", _time.monotonic())
         object.__setattr__(row, "_no_cache", False)
-        object.__setattr__(row, "_dirty_tracking", False)
-        object.__setattr__(row, "_dirty", {})
         return row
 
     # ------------------------------------------------------------------
@@ -129,29 +126,46 @@ class Row(MutableMapping):
     # MutableMapping protocol
     # ------------------------------------------------------------------
 
+    def _bind_json(self, key, val):
+        """
+        Wrap a JSON column value in a live proxy so in-place mutation writes
+        the whole value back.  On backends whose driver returns JSON as text
+        (everything except PostgreSQL), decode the string first when *key* is a
+        known JSON column.  Non-JSON values pass through unchanged.
+        """
+        if isinstance(val, (jsonproxy.BoundDict, jsonproxy.BoundList)):
+            return val
+        if isinstance(val, str):
+            # Possible JSON text from a non-native backend.  Decode only for
+            # columns the table reports as JSON; tables that don't implement
+            # json_columns() (mocks, external Table-likes) skip decoding.
+            json_cols = getattr(self.table, "json_columns", None)
+            if json_cols is None:
+                return val
+            try:
+                if key in json_cols():
+                    val = _json.loads(val)
+                else:
+                    return val
+            except (ValueError, TypeError):
+                return val
+        if isinstance(val, (dict, list)):
+            return jsonproxy.bind(
+                val, lambda plain, _k=key: self.__setitem__(_k, plain)
+            )
+        return val
+
     def __getitem__(self, key):
         if key in self.pk:
             return self.pk[key]
         cache = self._ensure_cache()
         if key in cache:
-            val = cache[key]
-            # JSON columns come back as plain dict/list — wrap them in live
-            # proxies so in-place mutation writes the whole value back.
-            if isinstance(val, (dict, list)) and not isinstance(
-                val, (jsonproxy.BoundDict, jsonproxy.BoundList)
-            ):
-                val = jsonproxy.bind(
-                    val, lambda plain, _k=key: self.__setitem__(_k, plain)
-                )
+            val = self._bind_json(key, cache[key])
+            if isinstance(val, (jsonproxy.BoundDict, jsonproxy.BoundList)):
                 cache[key] = val
             return val
         # Fall back to a direct DB fetch for columns not in the initial SELECT
-        val = self.table.get_value(key, self.pk)
-        if isinstance(val, (dict, list)):
-            val = jsonproxy.bind(
-                val, lambda plain, _k=key: self.__setitem__(_k, plain)
-            )
-        return val
+        return self._bind_json(key, self.table.get_value(key, self.pk))
 
     def __setitem__(self, key, val):
         if key in self.pk:
@@ -163,13 +177,6 @@ class Row(MutableMapping):
                 self._cache[key] = val
                 object.__setattr__(self, "_column_set", None)
             return
-        if self._dirty_tracking:
-            self._dirty[key] = val
-            # Update local cache optimistically so reads see the dirty value
-            if self._cache is not None:
-                self._cache[key] = val
-                object.__setattr__(self, "_column_set", None)
-            return
         self.table.update_or_insert({key: val}, pk=self.pk)
         # Invalidate cache so trigger-computed columns are re-fetched
         object.__setattr__(self, "_cache", None)
@@ -420,55 +427,6 @@ class Row(MutableMapping):
         """
         return _BatchContext(self)
 
-    def save(self):
-        """Flush accumulated dirty-tracking changes to the database.
-
-        When ``dirty_tracking=True``, assignments to the row accumulate
-        in memory instead of writing through immediately.  Call
-        ``.save()`` to flush them all in a single UPDATE::
-
-            row = Row(table, 1, dirty_tracking=True)
-            row["name"] = "John"
-            row["email"] = "john@example.com"
-            row.save()  # Single UPDATE with both columns
-
-        Returns ``self`` for chaining.
-
-        Raises:
-            RuntimeError: If dirty tracking is not enabled on this row.
-        """
-        if not self._dirty_tracking:
-            raise RuntimeError(
-                "save() requires dirty_tracking=True. "
-                "Use Row(table, key, dirty_tracking=True) or row.update({...})."
-            )
-        dirty = self._dirty
-        object.__setattr__(self, "_dirty", {})
-        if dirty:
-            self.table.update_or_insert(dirty, pk=self.pk)
-            # Invalidate cache so trigger-computed columns are re-fetched
-            object.__setattr__(self, "_cache", None)
-            object.__setattr__(self, "_column_set", None)
-        return self
-
-    @property
-    def is_dirty(self):
-        """Return True if there are unsaved dirty-tracking changes."""
-        return bool(self._dirty)
-
-    def discard(self):
-        """Discard accumulated dirty-tracking changes without writing to DB.
-
-        Also invalidates the cache so the next read re-fetches from the
-        database, undoing any optimistic cache updates.
-
-        Returns ``self`` for chaining.
-        """
-        object.__setattr__(self, "_dirty", {})
-        object.__setattr__(self, "_cache", None)
-        object.__setattr__(self, "_column_set", None)
-        return self
-
     def touch(self):
         """
         Update sys_modified to current timestamp.

{velocity_python-0.1.68 → velocity_python-0.1.70}/src/velocity/db/core/table.py

@@ -1,6 +1,5 @@
 import logging
 import re
-import warnings
 import sqlparse
 from collections import defaultdict
 from collections.abc import Iterable, Mapping, Sequence
@@ -106,6 +105,11 @@ def _is_nullable_flag(value):
     return None
 
 
+_COLUMN_SPEC_OPTION_KEYS = frozenset(
+    {"type", "value", "add_value", "nullable", "sql", "using"}
+)
+
+
 def _parse_column_spec(spec, default_nullable):
     """Normalize user-provided column specification into a common structure."""
 
@@ -121,7 +125,11 @@ def _parse_column_spec(spec, default_nullable):
         base, override_options = spec
 
     options = {}
-    if isinstance(base, Mapping):
+    # A Mapping base is an options spec (e.g. {"type": "TEXT", "nullable": False})
+    # only when every key is a recognized option keyword.  A plain JSON data
+    # value that happens to be a dict (e.g. {"k": 1}) must be kept as the value
+    # so its column types as JSON/JSONB — not silently mis-read as options.
+    if isinstance(base, Mapping) and base and set(base) <= _COLUMN_SPEC_OPTION_KEYS:
         options.update(base)
         base = options.get("type", options.get("value"))
 
@@ -590,7 +598,8 @@ class Table:
         if kwds.get("sql_only", False):
             return sql, vals
         result = self.tx.execute(sql, vals, cursor=self.cursor())
-        return [x[0] for x in result.as_tuple()]
+        name_idx = self.sql.columns_name_index
+        return [x[name_idx] for x in result.as_tuple()]
 
     def columns(self):
         """
@@ -723,9 +732,12 @@ class Table:
         Optionally drops any existing table first.
         """
         columns = columns or {}
-        sql, vals = self.sql.create_table(self.name, columns, drop)
         _ddl_logger.warning("DDL CREATE TABLE %s columns=%s drop=%s", self.name, list(columns.keys()), drop)
-        self.tx.execute(sql, vals, cursor=self.cursor())
+        # Execute statement-by-statement: SQLite's driver rejects
+        # multi-statement execute() calls.  Backends whose CREATE TABLE is a
+        # single (possibly multi-statement) string return a one-element list.
+        for stmt in self.sql.create_table_statements(self.name, columns, drop):
+            self.tx.execute(stmt, tuple(), cursor=self.cursor())
 
     def _ensure_schema_unlocked(self, operation):
         if self.tx.engine.schema_locked:
@@ -1921,8 +1933,16 @@ class Table:
                     null_statements.append((sql, vals))
 
         if to_add:
-            sql, vals = self.sql.alter_add(self.name, to_add, default_nullable)
-            statements.append((sql, vals))
+            # alter_add_statements returns one (sql, vals) per column so SQLite
+            # (single-statement execute) works; other dialects return a single
+            # combined statement.  Fall back to alter_add for SQL implementations
+            # that predate the per-statement contract.
+            add_stmts_fn = getattr(self.sql, "alter_add_statements", None)
+            if add_stmts_fn is not None:
+                statements.extend(add_stmts_fn(self.name, to_add, default_nullable))
+            else:
+                sql, vals = self.sql.alter_add(self.name, to_add, default_nullable)
+                statements.append((sql, vals))
 
             for column_name, spec in add_specs.items():
                 if (
@@ -1984,6 +2004,26 @@ class Table:
         _ddl_logger.warning("DDL ALTER COLUMN TYPE on %s column=%s", self.name, column)
         self.tx.execute(sql, vals, cursor=self.cursor())
 
+    def json_columns(self):
+        """
+        Return the (cached) set of column names on this table that hold JSON
+        values and need Row-layer decoding on read.
+
+        Empty on backends whose driver round-trips JSON natively (PostgreSQL),
+        so the Row read path stays zero-cost there.
+        """
+        if self.sql.json_round_trips_natively:
+            return frozenset()
+        cache = self.tx._json_columns_cache
+        names = cache.get(self.name)
+        if names is None:
+            try:
+                names = self.sql.json_column_names(self.tx, self.name)
+            except Exception:
+                names = frozenset()
+            cache[self.name] = names
+        return names
+
     def _adapt_data(self, data):
         """
         Apply the dialect's data-value adaptation (e.g. dict/list -> JSONB on
@@ -2177,9 +2217,7 @@ class Table:
         else:
             exists_where = pk
 
-        ins_builder = getattr(self.sql, "insert_if_not_exists", None) or getattr(
-            self.sql, "insnx", None
-        )
+        ins_builder = 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."
@@ -2193,15 +2231,6 @@ class Table:
         result = self.tx.execute(sql, vals, cursor=self.cursor())
         return result.cursor.rowcount if result.cursor else 0
 
-    @property
-    def updins(self):
-        warnings.warn(
-            "Table.updins is deprecated, use Table.update_or_insert instead.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        return self.update_or_insert
-
     @create_missing
     def insert_if_not_exists(self, data, where=None, **kwds):
         """
@@ -2223,26 +2252,8 @@ class Table:
         result = self.tx.execute(sql, vals, cursor=self.cursor())
         return result.cursor.rowcount if result.cursor else 0
 
-    @property
-    def insnx(self):
-        warnings.warn(
-            "Table.insnx is deprecated, use Table.insert_if_not_exists instead.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        return self.insert_if_not_exists
-
     upsert = merge
 
-    @property
-    def indate(self):
-        warnings.warn(
-            "Table.indate is deprecated, use Table.merge (or Table.upsert) instead.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        return self.merge
-
     @return_default(0)
     def count(self, where=None, **kwds):
         """

{velocity_python-0.1.68 → velocity_python-0.1.70}/src/velocity/db/core/transaction.py

@@ -176,6 +176,10 @@ class Transaction:
         # R14 — N+1 detection: per-table SELECT counts.
         self._table_select_counts: dict[str, int] = {}
         self._n1_warned: set[str] = set()
+        # JSON-column name cache (per table) for backends whose driver returns
+        # JSON columns as text and need Row-layer decoding.  None = not yet
+        # looked up; invalidated by invalidate_cache().
+        self._json_columns_cache: dict[str, frozenset] = {}
         # R21 — set once an irreversible external side effect (e.g. a payment
         # charge/capture) has happened in this transaction. The engine's
         # auto-retry envelope must NOT re-run a function after this, or a
@@ -268,15 +272,32 @@ class Transaction:
         if prepare is None:
             prepare = getattr(self.engine, "prepare_enabled", False)
 
+        # Only psycopg3 accepts the 'prepare' keyword.  Once a driver rejects
+        # it we remember that on the engine so we don't raise+catch a TypeError
+        # on every subsequent statement (sqlite/mysql/sqlserver).
+        supports_prepare_kw = getattr(self.engine, "_supports_prepare_kw", True)
+
         t0 = _time.perf_counter()
         try:
-            try:
-                if parms:
-                    cursor.execute(sql, parms, prepare=prepare)
-                else:
-                    cursor.execute(sql, prepare=prepare)
-            except TypeError:
-                # Driver doesn't support 'prepare' keyword (non-psycopg3).
+            if supports_prepare_kw:
+                try:
+                    if parms:
+                        cursor.execute(sql, parms, prepare=prepare)
+                    else:
+                        cursor.execute(sql, prepare=prepare)
+                except TypeError:
+                    # Driver doesn't support 'prepare' keyword (non-psycopg3).
+                    self.engine._supports_prepare_kw = False
+                    try:
+                        if parms:
+                            cursor.execute(sql, parms)
+                        else:
+                            cursor.execute(sql)
+                    except Exception as e:
+                        raise self.engine.process_error(e, sql, parms)
+                except Exception as e:
+                    raise self.engine.process_error(e, sql, parms)
+            else:
                 try:
                     if parms:
                         cursor.execute(sql, parms)
@@ -284,8 +305,6 @@ class Transaction:
                         cursor.execute(sql)
                 except Exception as e:
                     raise self.engine.process_error(e, sql, parms)
-            except Exception as e:
-                raise self.engine.process_error(e, sql, parms)
 
             elapsed_ms = (_time.perf_counter() - t0) * 1000
             self._query_count += 1
@@ -481,10 +500,16 @@ class Transaction:
         rolls back.  Use this to serialize DDL or other operations across
         concurrent Lambda containers.
 
+        No-op on non-PostgreSQL backends (advisory locks are a PostgreSQL
+        feature) — emitting the ``pg_advisory_xact_lock`` statement elsewhere
+        would raise a syntax error that callers must then swallow.
+
         Args:
             key: An integer lock key, or a string that will be hashed to
                  a 64-bit integer.
         """
+        if not getattr(self.engine.sql, "supports_advisory_lock", False):
+            return
         if isinstance(key, str):
             import hashlib
             # Use first 8 bytes of SHA-256 as a signed 64-bit int.
@@ -531,7 +556,9 @@ class Transaction:
         """
         if table_name is None:
             self.__query_cache.clear()
+            self._json_columns_cache.clear()
             return
+        self._json_columns_cache.pop(table_name, None)
         # Simple substring match on the SQL text (first element of the key).
         tbl_lower = table_name.lower()
         to_remove = [

{velocity_python-0.1.68 → velocity_python-0.1.70}/src/velocity/db/servers/base/sql.py

@@ -22,9 +22,19 @@ class BaseSQLDialect(ABC):
     type_column_identifier: str = ""
     is_nullable: str = ""
 
+    # Position of the column NAME within each row returned by columns().
+    # Most dialects put it first; SQLite's PRAGMA table_info has cid at 0 and
+    # the name at 1.
+    columns_name_index: int = 0
+
     # Default schema name for this database
     default_schema: str = ""
 
+    # PostgreSQL-style transaction advisory locks (pg_advisory_xact_lock).
+    # False elsewhere so Transaction.advisory_lock() is a clean no-op instead
+    # of emitting a statement the backend can't parse.
+    supports_advisory_lock: bool = False
+
     # Error code classifications - must be set by subclasses
     ApplicationErrorCodes: List[str] = []
     DatabaseMissingErrorCodes: List[str] = []
@@ -54,6 +64,52 @@ class BaseSQLDialect(ABC):
             return json.dumps(val)
         return val
 
+    # ------------------------------------------------------------------
+    # JSON-column read support
+    # ------------------------------------------------------------------
+    # When True, the driver returns JSON columns already decoded into
+    # Python dict/list (PostgreSQL/psycopg).  When False, JSON columns come
+    # back as text and the Row layer decodes them — see ``json_column_names``.
+    json_round_trips_natively: bool = False
+
+    @classmethod
+    def json_column_names(cls, tx, table):
+        """
+        Return the set of column names on *table* that hold JSON values, used
+        by the Row layer to decode JSON text on backends where the driver does
+        not round-trip JSON natively.
+
+        Default: empty set (no decoding).  Backends that store JSON in a
+        distinguishable declared type override this.
+        """
+        return frozenset()
+
+    @classmethod
+    def create_table_statements(cls, name, columns=None, drop=False):
+        """
+        Return CREATE TABLE as a list of individual SQL statements.
+
+        Most dialects build one (possibly multi-statement) string that the
+        driver executes in a single call; the default wraps that string as a
+        one-element list.  SQLite overrides this because ``sqlite3`` rejects
+        multi-statement ``execute()`` calls, so each statement must run
+        separately.
+        """
+        sql, _vals = cls.create_table(name, columns or {}, drop)
+        return [sql]
+
+    @classmethod
+    def alter_add_statements(cls, table, columns, null_allowed=True):
+        """
+        Return ADD COLUMN DDL as a list of ``(sql, params)`` statements.
+
+        Default wraps the dialect's single ``alter_add`` string as one element;
+        SQLite overrides this so each column is its own statement (its driver
+        rejects multi-statement ``execute()``).
+        """
+        sql, vals = cls.alter_add(table, columns, null_allowed)
+        return [(sql, vals)]
+
     @classmethod
     def quote_identifier(cls, name: str) -> str:
         """Always-quote a single SQL identifier to prevent injection.

{velocity_python-0.1.68 → velocity_python-0.1.70}/src/velocity/db/servers/mysql/sql.py

@@ -588,11 +588,12 @@ END;
 
     @classmethod
     def columns(cls, name):
-        return f"SHOW COLUMNS FROM {quote(name)}"
+        # SHOW COLUMNS rows: (Field, Type, Null, Key, Default, Extra) — name at 0.
+        return f"SHOW COLUMNS FROM {quote(name)}", tuple()
 
     @classmethod
     def column_info(cls, table, name):
-        return f"SHOW COLUMNS FROM {quote(table)} LIKE '{name}'"
+        return f"SHOW COLUMNS FROM {quote(table)} LIKE '{name}'", tuple()
 
     @classmethod
     def drop_column(cls, table, name, cascade=True):

{velocity_python-0.1.68 → velocity_python-0.1.70}/src/velocity/db/servers/postgres/sql.py

@@ -37,6 +37,13 @@ class SQL(BaseSQLDialect):
 
     default_schema = "public"
 
+    # psycopg decodes JSONB/JSON into dict/list automatically — no Row-layer
+    # decode needed (and the Row layer skips all JSON metadata lookups).
+    json_round_trips_natively = True
+
+    # PostgreSQL supports pg_advisory_xact_lock (see Transaction.advisory_lock).
+    supports_advisory_lock = True
+
     ApplicationErrorCodes = [
         "22P02",
         "42883",
@@ -907,7 +914,7 @@ class SQL(BaseSQLDialect):
         return sql, args_list, values_template
 
     @classmethod
-    def insnx(cls, tx, table, data, where=None):
+    def insert_if_not_exists(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.")
@@ -1001,8 +1008,6 @@ class SQL(BaseSQLDialect):
         )
         return final_sql, tuple(vals)
 
-    insert_if_not_exists = insnx
-
     @classmethod
     def version(cls):
         return "select version()", tuple()