velocity-python 0.0.218__tar.gz → 0.0.220__tar.gz

{velocity_python-0.0.218/src/velocity_python.egg-info → velocity_python-0.0.220}/PKG-INFO

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

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

{velocity_python-0.0.218 → velocity_python-0.0.220}/src/velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.0.218"
+__version__ = version = "0.0.220"
 
 from . import aws
 from . import db

{velocity_python-0.0.218 → velocity_python-0.0.220}/src/velocity/db/core/decorators.py

@@ -1,8 +1,11 @@
+import logging
 import time
 import random
 from functools import wraps
 from velocity.db import exceptions
 
+logger = logging.getLogger("velocity.db")
+
 
 _PRIMARY_KEY_PATTERNS = (
     "primary key",
@@ -108,6 +111,15 @@ def return_default(
             except func.exceptions as e:
                 self.tx.rollback_savepoint(sp, cursor=self.cursor())
 
+                # Log the swallowed exception so silent failures are visible.
+                logger.warning(
+                    "@return_default swallowed %s in %s.%s: %s",
+                    e.__class__.__name__,
+                    func.__module__,
+                    getattr(func, "__qualname__", func.__name__),
+                    e,
+                )
+
                 # 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.0.218 → velocity_python-0.0.220}/src/velocity/db/core/result.py

@@ -1,3 +1,4 @@
+import warnings
 from velocity.misc.format import to_json
 
 
@@ -279,13 +280,22 @@ class Result:
         self.transform = lambda row: to_json(dict(zip(self.headers, row)))
         return self
 
-    def as_named_tuple(self):
+    def as_pairs(self):
         """
         Transform each row into a list of (column_name, value) pairs.
         """
         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.0.218 → velocity_python-0.0.220}/src/velocity/db/core/row.py

@@ -1,16 +1,32 @@
 import pprint
+import warnings
+from collections.abc import MutableMapping
 from velocity.db.exceptions import DbColumnMissingError
 
 
-class Row:
+# Attributes that live on the Row instance itself and must never be
+# intercepted by __getattr__ / __setattr__.
+_INTERNAL_ATTRS = frozenset({
+    "table", "pk", "_cache", "_column_set",
+})
+
+
+class Row(MutableMapping):
     """
-    Represents a single row in a given table, identified by a primary key or a dictionary of conditions.
+    Represents a single row in a given table, identified by a primary key.
+
+    Acts as a ``MutableMapping`` so that standard dict idioms work:
+    ``dict(row)``, ``{**row}``, ``for k in row:``, ``json.dumps(row)``.
+
+    Data is fetched from the database **once** on first access and cached
+    locally.  Call ``row.refresh()`` to re-fetch.  Writes are still
+    write-through (immediate UPDATE) and also update the local cache.
     """
 
     def __init__(self, table, key, lock=None):
         if isinstance(table, str):
             raise Exception("Table parameter must be a `table` instance.")
-        self.table = table
+        object.__setattr__(self, "table", table)
 
         if isinstance(key, (dict, Row)):
             pk = {}
@@ -18,38 +34,68 @@ class Row:
                 for k in self.key_cols:
                     pk[k] = key[k]
             except KeyError:
-                pk = key
+                pk = dict(key) if isinstance(key, Row) else key
         else:
             pk = {self.key_cols[0]: key}
 
-        self.pk = pk
-        self.cache = key
+        object.__setattr__(self, "pk", pk)
+        object.__setattr__(self, "_cache", None)
+        object.__setattr__(self, "_column_set", None)
         if lock:
             self.lock()
 
-    def __repr__(self):
-        return repr(self.to_dict())
+    # ------------------------------------------------------------------
+    # Cache management
+    # ------------------------------------------------------------------
+
+    def _ensure_cache(self):
+        """Populate the local cache from the database if not yet loaded."""
+        if self._cache is None:
+            data = self.table.select(where=self.pk).as_dict().one()
+            object.__setattr__(self, "_cache", data or {})
+        return self._cache
+
+    def _column_names_lower(self):
+        """Return a frozenset of lowered column names (cached)."""
+        if self._column_set is None:
+            cols = frozenset(k.lower() for k in self._ensure_cache())
+            object.__setattr__(self, "_column_set", cols)
+        return self._column_set
+
+    def refresh(self):
+        """Re-fetch the row data from the database, clearing the local cache."""
+        object.__setattr__(self, "_cache", None)
+        object.__setattr__(self, "_column_set", None)
+        self._ensure_cache()
+        return self
 
-    def __str__(self):
-        return pprint.pformat(self.to_dict())
+    def invalidate(self):
+        """Clear the local cache so the next access re-fetches from the database."""
+        object.__setattr__(self, "_cache", None)
+        object.__setattr__(self, "_column_set", None)
+        return self
 
-    def __len__(self):
-        return int(self.table.count(self.pk))
+    # ------------------------------------------------------------------
+    # MutableMapping protocol
+    # ------------------------------------------------------------------
 
     def __getitem__(self, key):
         if key in self.pk:
             return self.pk[key]
+        cache = self._ensure_cache()
+        if key in cache:
+            return cache[key]
+        # Fall back to a direct DB fetch for columns not in the initial SELECT
         return self.table.get_value(key, self.pk)
 
     def __setitem__(self, key, val):
         if key in self.pk:
             raise Exception("Cannot update a primary key.")
-        if hasattr(self.table, "updins"):
-            self.table.updins({key: val}, pk=self.pk)
-        elif hasattr(self.table, "upsert"):
-            self.table.upsert({key: val}, pk=self.pk)
-        else:
-            self.table.update({key: val}, pk=self.pk)
+        self.table.update_or_insert({key: val}, pk=self.pk)
+        # Update local cache
+        if self._cache is not None:
+            self._cache[key] = val
+            object.__setattr__(self, "_column_set", None)
 
     def __delitem__(self, key):
         if key in self.pk:
@@ -58,37 +104,91 @@ class Row:
             return
         self[key] = None
 
+    def __iter__(self):
+        return iter(self._ensure_cache())
+
+    def __len__(self):
+        return len(self._ensure_cache())
+
     def __contains__(self, key):
-        return key.lower() in [x.lower() for x in self.keys()]
+        return key.lower() in self._column_names_lower()
+
+    # ------------------------------------------------------------------
+    # Attribute-style access  (row.name instead of row['name'])
+    # ------------------------------------------------------------------
+
+    def __getattr__(self, key):
+        if key.startswith("_") or key in _INTERNAL_ATTRS:
+            raise AttributeError(key)
+        try:
+            return self[key]
+        except (KeyError, DbColumnMissingError):
+            raise AttributeError(
+                f"'{type(self).__name__}' object has no attribute '{key}'"
+            )
+
+    def __setattr__(self, key, val):
+        if key in _INTERNAL_ATTRS or key.startswith("_"):
+            object.__setattr__(self, key, val)
+        else:
+            self[key] = val
+
+    # ------------------------------------------------------------------
+    # Equality and hashing — based on (table name, pk)
+    # ------------------------------------------------------------------
+
+    def __eq__(self, other):
+        if isinstance(other, Row):
+            return self.table.name == other.table.name and self.pk == other.pk
+        if isinstance(other, dict):
+            return self.to_dict() == other
+        return NotImplemented
+
+    def __hash__(self):
+        return hash((self.table.name, tuple(sorted(self.pk.items()))))
+
+    def __ne__(self, other):
+        result = self.__eq__(other)
+        if result is NotImplemented:
+            return result
+        return not result
+
+    # ------------------------------------------------------------------
+    # Representations
+    # ------------------------------------------------------------------
+
+    def __repr__(self):
+        return repr(self.to_dict())
+
+    def __str__(self):
+        return pprint.pformat(self.to_dict())
+
+    def __bool__(self):
+        return bool(self._ensure_cache())
+
+    # ------------------------------------------------------------------
+    # dict-like helpers
+    # ------------------------------------------------------------------
 
     def clear(self):
         """
         Deletes this row from the database.
         """
         self.table.delete(where=self.pk)
+        self.invalidate()
         return self
 
     def keys(self):
-        """
-        Returns the column names in the table (including sys_ columns).
-        """
-        return self.table.sys_columns()
+        return self._ensure_cache().keys()
 
     def values(self, *args):
-        """
-        Returns values from this row, optionally restricted to columns in `args`.
-        """
-        d = self.table.select(where=self.pk).as_dict().one()
+        d = self._ensure_cache()
         if args:
             return [d[arg] for arg in args]
         return list(d.values())
 
     def items(self):
-        """
-        Returns (key, value) pairs for all columns.
-        """
-        d = self.table.select(where=self.pk).as_dict().one()
-        return list(d.items())
+        return self._ensure_cache().items()
 
     def get(self, key, failobj=None):
         try:
@@ -97,16 +197,13 @@ class Row:
                 return failobj
             return data
         except DbColumnMissingError:
-            # Column doesn't exist in the table, return the default value
             return failobj
         except Exception as e:
-            # Check if the error message indicates a missing column
             error_msg = str(e).lower()
             if "column" in error_msg and (
                 "does not exist" in error_msg or "not found" in error_msg
             ):
                 return failobj
-            # Re-raise other exceptions
             raise
 
     def setdefault(self, key, default=None):
@@ -118,7 +215,7 @@ class Row:
 
     def update(self, dict_=None, **kwds):
         """
-        Updates columns in this row.
+        Updates columns in this row (write-through to DB + local cache).
         """
         data = {}
         if dict_:
@@ -126,33 +223,12 @@ class Row:
         if kwds:
             data.update(kwds)
         if data:
-            if hasattr(self.table, "updins"):
-                self.table.updins(data, pk=self.pk)
-            elif hasattr(self.table, "upsert"):
-                self.table.upsert(data, pk=self.pk)
-            else:
-                self.table.update(data, pk=self.pk)
+            self.table.update_or_insert(data, pk=self.pk)
+            if self._cache is not None:
+                self._cache.update(data)
+                object.__setattr__(self, "_column_set", None)
         return self
 
-    def __cmp__(self, other):
-        """
-        Legacy comparison method; returns 0 if self and other share keys/values, else -1.
-        """
-        diff = -1
-        if hasattr(other, "keys"):
-            k1 = list(self.keys())
-            k2 = list(other.keys())
-            if k1 == k2:
-                diff = 0
-                for k in k1:
-                    if self[k] != other[k]:
-                        diff = -1
-                        break
-        return diff
-
-    def __bool__(self):
-        return bool(len(self))
-
     def copy(self, lock=None):
         """
         Makes a copy of this row with a new sys_id, dropping sys_-prefixed columns from the new dict.
@@ -163,7 +239,7 @@ class Row:
                 old.pop(k)
         return self.table.new(old, lock=lock)
 
-    def pop(self):
+    def pop(self, key, *args):
         raise NotImplementedError
 
     def popitem(self):
@@ -187,9 +263,9 @@ class Row:
 
     def to_dict(self):
         """
-        Returns the row as a dictionary via a SELECT on self.pk.
+        Returns the row as a dictionary (from cache or via a SELECT on self.pk).
         """
-        return self.table.select(where=self.pk).as_dict().one()
+        return dict(self._ensure_cache())
 
     def extract(self, *args):
         """

{velocity_python-0.0.218 → velocity_python-0.0.220}/src/velocity/db/core/sequence.py

@@ -1,6 +1,3 @@
-import psycopg2
-
-
 class Sequence:
     """
     Represents a database sequence in PostgreSQL.
@@ -48,8 +45,12 @@ class Sequence:
         sql = f"SELECT currval('{self.name}');"
         try:
             return self.tx.execute(sql, ()).scalar()
-        except psycopg2.ProgrammingError:
-            return None
+        except Exception as e:
+            # Catch psycopg2.ProgrammingError (or equivalent) when no
+            # value has been generated in this session.
+            if "currval" in str(e).lower():
+                return None
+            raise
 
     def set_value(self, start=None):
         """

{velocity_python-0.0.218 → velocity_python-0.0.220}/src/velocity/db/core/table.py

@@ -1,4 +1,5 @@
 import re
+import warnings
 import sqlparse
 from collections.abc import Iterable, Mapping
 from velocity.db import exceptions
@@ -597,9 +598,9 @@ class Table:
 
     def foreign_keys(self):
         """
-        Returns the list of foreign key columns for this table (may be incomplete).
+        Returns the list of foreign key columns for this table.
         """
-        sql, vals = self.sql.primary_keys(self.name)
+        sql, vals = self.sql.foreign_keys(self.name)
         result = self.tx.execute(sql, vals, cursor=self.cursor())
         return [x[0] for x in result.as_tuple()]
 
@@ -918,8 +919,8 @@ class Table:
         else:
             exists_where = pk
 
-        ins_builder = getattr(self.sql, "insnx", None) or getattr(
-            self.sql, "insert_if_not_exists", None
+        ins_builder = getattr(self.sql, "insert_if_not_exists", None) or getattr(
+            self.sql, "insnx", None
         )
         if ins_builder is None:
             raise NotImplementedError(
@@ -932,7 +933,14 @@ class Table:
         result = self.tx.execute(sql, vals, cursor=self.cursor())
         return result.cursor.rowcount if result.cursor else 0
 
-    updins = update_or_insert
+    @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):
@@ -953,10 +961,25 @@ class Table:
         result = self.tx.execute(sql, vals, cursor=self.cursor())
         return result.cursor.rowcount if result.cursor else 0
 
-    insnx = insert_if_not_exists
+    @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
-    indate = 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):
@@ -1167,37 +1190,17 @@ class Table:
     def duplicate_rows(self, columns=None, where=None, orderby=None, **kwds):
         """
         Returns rows that have duplicates in the specified `columns`.
-        TBD: Move code to generate sql to the sql module. it should not be
-        here so different sql engines can use this function.
         """
         if not columns:
             raise ValueError(
                 "You must specify at least one column to check for duplicates."
             )
-        sql, vals = self.sql.select(
-            self.tx,
-            columns=columns,
-            table=self.name,
-            where=where,
-            groupby=columns,
-            having={">count(*)": 1},
+        sql, vals = self.sql.duplicate_rows(
+            self.tx, table=self.name, columns=columns, where=where, orderby=orderby
         )
-        if orderby:
-            orderby = [orderby] if isinstance(orderby, str) else orderby
-        else:
-            orderby = columns
-        subjoin = " AND ".join([f"t.{col} = dup.{col}" for col in columns])
-        ob = ", ".join(orderby)
-        final_sql = f"""
-        SELECT t.*
-        FROM {self.name} t
-        JOIN ({sql}) dup
-        ON {subjoin}
-        ORDER BY {ob}
-        """
         if kwds.get("sql_only", False):
-            return final_sql, vals
-        return self.tx.execute(final_sql, vals)
+            return sql, vals
+        return self.tx.execute(sql, vals)
 
     def has_duplicates(self, columns=None, where=None, **kwds):
         """
@@ -1290,12 +1293,10 @@ class Table:
     def lock(self, mode="ACCESS EXCLUSIVE", wait_for_lock=None, **kwds):
         """
         Issues a LOCK TABLE statement for this table.
-        TBD: MOve SQL To sql module so we can use this function with other engines.
         """
-        sql = f"LOCK TABLE {self.name} IN {mode} MODE"
-        if not wait_for_lock:
-            sql += " NOWAIT"
-        vals = None
+        sql, vals = self.sql.lock_table(
+            table=self.name, mode=mode, wait_for_lock=wait_for_lock
+        )
         if kwds.get("sql_only", False):
             return sql, vals
         return self.tx.execute(sql, vals)
@@ -1468,62 +1469,14 @@ class Table:
     def find_duplicates(self, columns, sql_only=False):
         """
         Returns duplicate groups from the table based on the specified columns in a case-insensitive way.
-
-        For each column, the subquery computes:
-        - lower(column) AS normalized_<column>
-        - array_agg(column) AS variations_<column>
-        - array_agg(sys_id) AS sys_ids
-        - COUNT(*) AS total_count
-
-        The subquery groups by lower(column) values and retains only groups with more than one row.
-
-        Example SQL for a single column "email_address":
-
-            SELECT
-            lower(email_address) AS normalized_email_address,
-            array_agg(email_address) AS variations_email_address,
-            array_agg(sys_id) AS sys_ids,
-            COUNT(*) AS total_count
-            FROM donor_users
-            GROUP BY lower(email_address)
-            HAVING COUNT(*) > 1
-
-        Parameters:
-        columns (list or str): Column name or list of column names to check duplicates on.
-        sql_only (bool): If True, returns the SQL string and an empty tuple; otherwise,
-                        executes the query using self.tx.execute.
-
-        Returns:
-        A tuple of (SQL string, parameters) if sql_only is True, otherwise the result of executing the query.
         """
         if not columns:
             raise ValueError(
                 "You must specify at least one column to check for duplicates."
             )
-
         if isinstance(columns, str):
             columns = [columns]
-
-        # Build subquery SELECT clause parts for normalized values and variations.
-        normalized_cols = [f"lower({col}) AS normalized_{col}" for col in columns]
-        variations_cols = [f"array_agg({col}) AS variations_{col}" for col in columns]
-
-        subquery_select = ",\n  ".join(
-            normalized_cols
-            + variations_cols
-            + ["array_agg(sys_id) AS sys_ids", "COUNT(*) AS total_count"]
-        )
-
-        groupby_clause = ", ".join([f"lower({col})" for col in columns])
-
-        subquery = f"""
-        SELECT
-        {subquery_select}
-        FROM {self.name}
-        GROUP BY {groupby_clause}
-        HAVING COUNT(*) > 1
-        """
-
+        sql, vals = self.sql.find_duplicates(table=self.name, columns=columns)
         if sql_only:
-            return subquery, ()
-        return self.tx.execute(subquery, ())
+            return sql, vals
+        return self.tx.execute(sql, vals)

{velocity_python-0.0.218 → velocity_python-0.0.220}/src/velocity/db/servers/base/sql.py

@@ -530,3 +530,51 @@ class BaseSQLDialect(ABC):
             Tuple of (sql_string, parameters)
         """
         pass
+
+    # ------------------------------------------------------------------
+    # Optional methods — dialects may override if they support these
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def foreign_keys(cls, table: str) -> Tuple[str, tuple]:
+        """Return foreign key column names for the given table."""
+        raise NotImplementedError(
+            f"{cls.server} dialect does not implement foreign_keys()"
+        )
+
+    @classmethod
+    def lock_table(
+        cls,
+        table: str,
+        mode: str = "ACCESS EXCLUSIVE",
+        wait_for_lock: Optional[bool] = None,
+    ) -> Tuple[str, tuple]:
+        """Generate a LOCK TABLE statement."""
+        raise NotImplementedError(
+            f"{cls.server} dialect does not implement lock_table()"
+        )
+
+    @classmethod
+    def duplicate_rows(
+        cls,
+        tx: Any,
+        table: str,
+        columns: List[str],
+        where: Optional[Union[str, Dict, List]] = None,
+        orderby: Optional[Union[str, List[str]]] = None,
+    ) -> Tuple[str, tuple]:
+        """Return rows that have duplicates in the specified columns."""
+        raise NotImplementedError(
+            f"{cls.server} dialect does not implement duplicate_rows()"
+        )
+
+    @classmethod
+    def find_duplicates(
+        cls,
+        table: str,
+        columns: List[str],
+    ) -> Tuple[str, tuple]:
+        """Return duplicate groups with case-insensitive matching."""
+        raise NotImplementedError(
+            f"{cls.server} dialect does not implement find_duplicates()"
+        )