velocity-python 0.0.105__py3-none-any.whl → 0.0.155__py3-none-any.whl

velocity/db/core/result.py

@@ -1,5 +1,3 @@
-import datetime
-import decimal
 from velocity.misc.format import to_json
 
 
@@ -7,14 +5,14 @@ class Result:
     """
     Wraps a database cursor to provide various convenience transformations
     (dict, list, tuple, etc.) and helps iterate over query results.
-    
+
     Features:
     - Pre-fetches first row for immediate boolean evaluation
     - Boolean state changes as rows are consumed: bool(result) tells you if MORE rows are available
     - Supports __bool__, is_empty(), has_results() for checking remaining results
     - Efficient iteration without unnecessary fetchall() calls
     - Caches next row to maintain accurate state without redundant database calls
-    
+
     Boolean Behavior:
     - Initially: bool(result) = True if query returned any rows
     - After each row: bool(result) = True if more rows are available to fetch
@@ -29,15 +27,15 @@ class Result:
             description = getattr(cursor, "description", []) or []
             self._headers = []
             for col in description:
-                if hasattr(col, '__getitem__'):  # Tuple-like (col[0])
+                if hasattr(col, "__getitem__"):  # Tuple-like (col[0])
                     self._headers.append(col[0].lower())
-                elif hasattr(col, 'name'):  # Object with name attribute
+                elif hasattr(col, "name"):  # Object with name attribute
                     self._headers.append(col.name.lower())
                 else:
-                    self._headers.append(f'column_{len(self._headers)}')
+                    self._headers.append(f"column_{len(self._headers)}")
         except (AttributeError, TypeError, IndexError):
             self._headers = []
-            
+
         self.__as_strings = False
         self.__enumerate = False
         self.__count = -1
@@ -49,17 +47,27 @@ class Result:
         self._cached_first_row = None
         self._first_row_fetched = False
         self._exhausted = False
-        
+
         # Pre-fetch the first row to enable immediate boolean evaluation
         self._fetch_first_row()
 
     def _fetch_first_row(self):
         """
         Pre-fetch the first row from the cursor to enable immediate boolean evaluation.
+        Only attempts to fetch for SELECT-like operations that return rows.
         """
         if self._first_row_fetched or not self._cursor:
             return
-            
+
+        # Don't try to fetch from INSERT/UPDATE/DELETE operations
+        # These operations don't return rows, only rowcount
+        if self.__sql and self.__sql.strip().upper().startswith(
+            ("INSERT", "UPDATE", "DELETE", "TRUNCATE")
+        ):
+            self._exhausted = True
+            self._first_row_fetched = True
+            return
+
         try:
             raw_row = self._cursor.fetchone()
             if raw_row:
@@ -101,7 +109,9 @@ class Result:
         Return True if there are more rows available to fetch.
         This is based on whether we have a cached row or the cursor isn't exhausted.
         """
-        return self._cached_first_row is not None or (not self._exhausted and self._cursor)
+        return self._cached_first_row is not None or (
+            not self._exhausted and self._cursor
+        )
 
     def __next__(self):
         """
@@ -119,7 +129,7 @@ class Result:
                 if not row:
                     self._exhausted = True
                     raise StopIteration
-                # Try to pre-fetch the next row to update our state  
+                # Try to pre-fetch the next row to update our state
                 self._try_cache_next_row()
             except Exception as e:
                 # Handle cursor errors (e.g., closed cursor)
@@ -146,7 +156,7 @@ class Result:
         """
         if not self._cursor or self._cached_first_row is not None:
             return
-            
+
         try:
             next_row = self._cursor.fetchone()
             if next_row:
@@ -206,18 +216,22 @@ class Result:
         """
         if not self.__columns and self._cursor and hasattr(self._cursor, "description"):
             for column in self._cursor.description:
-                data = {
-                    "type_name": "unknown"  # Default value
-                }
-                
+                data = {"type_name": "unknown"}  # Default value
+
                 # Try to get type information (PostgreSQL specific)
                 try:
-                    if hasattr(column, 'type_code') and self.__tx and hasattr(self.__tx, 'pg_types'):
-                        data["type_name"] = self.__tx.pg_types.get(column.type_code, "unknown")
+                    if (
+                        hasattr(column, "type_code")
+                        and self.__tx
+                        and hasattr(self.__tx, "pg_types")
+                    ):
+                        data["type_name"] = self.__tx.pg_types.get(
+                            column.type_code, "unknown"
+                        )
                 except (AttributeError, KeyError):
                     # Keep default value
                     pass
-                
+
                 # Get all other column attributes safely
                 for key in dir(column):
                     if not key.startswith("__"):
@@ -226,8 +240,8 @@ class Result:
                         except (AttributeError, TypeError):
                             # Skip attributes that can't be accessed
                             continue
-                            
-                column_name = getattr(column, 'name', f'column_{len(self.__columns)}')
+
+                column_name = getattr(column, "name", f"column_{len(self.__columns)}")
                 self.__columns[column_name] = data
         return self.__columns
 

velocity/db/core/row.py

@@ -44,7 +44,12 @@ class Row:
     def __setitem__(self, key, val):
         if key in self.pk:
             raise Exception("Cannot update a primary key.")
-        self.table.upsert({key: val}, self.pk)
+        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)
 
     def __delitem__(self, key):
         if key in self.pk:
@@ -97,7 +102,9 @@ class Row:
         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):
+            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
@@ -119,7 +126,12 @@ class Row:
         if kwds:
             data.update(kwds)
         if data:
-            self.table.upsert(data, self.pk)
+            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)
         return self
 
     def __cmp__(self, other):

velocity/db/core/table.py

@@ -1,4 +1,5 @@
 import sqlparse
+from collections.abc import Iterable, Mapping
 from velocity.db import exceptions
 from velocity.db.core.row import Row
 from velocity.db.core.result import Result
@@ -23,7 +24,24 @@ class Query:
         return self.sql
 
 
+SYSTEM_COLUMN_NAMES = (
+    "sys_id",
+    "sys_created",
+    "sys_modified",
+    "sys_modified_by",
+    "sys_modified_row",
+    "sys_modified_count",
+    "sys_dirty",
+    "sys_table",
+    "description",
+)
+
+_SYSTEM_COLUMN_SET = {name.lower() for name in SYSTEM_COLUMN_NAMES}
+
+
 class Table:
+    SYSTEM_COLUMNS = SYSTEM_COLUMN_NAMES
+
     """
     Provides an interface for performing CRUD and metadata operations on a DB table.
     """
@@ -54,13 +72,13 @@ class Table:
         """
         try:
             self._cursor.close()
-        except:
+        except Exception:
             pass
 
     def cursor(self):
         try:
             return self._cursor
-        except:
+        except AttributeError:
             pass
         self._cursor = self.tx.cursor()
         return self._cursor
@@ -93,9 +111,15 @@ class Table:
 
     def columns(self):
         """
-        Returns column names, excluding columns that start with 'sys_'.
+        Returns non-system column names.
         """
-        return [col for col in self.sys_columns() if not col.startswith("sys_")]
+        return [col for col in self.sys_columns() if not self.is_system_column(col)]
+
+    @staticmethod
+    def is_system_column(column_name):
+        if not column_name:
+            return False
+        return column_name.lower() in _SYSTEM_COLUMN_SET or column_name.lower().startswith("sys_")
 
     @return_default(None, (exceptions.DbObjectExistsError,))
     def create_index(
@@ -119,6 +143,59 @@ class Table:
             return sql, vals
         self.tx.execute(sql, vals, cursor=self.cursor())
 
+    def create_indexes(self, indexes, **kwds):
+        """
+        Convenience wrapper to create multiple indexes in order.
+
+        Accepts an iterable of definitions. Each definition may be either:
+        - Mapping with a required "columns" entry plus optional "unique",
+          "direction", "where", and "lower" keys.
+        - A simple sequence/string of columns, in which case defaults apply.
+
+        When sql_only=True, a list of (sql, params) tuples is returned.
+        """
+
+        if indexes is None:
+            return [] if kwds.get("sql_only", False) else None
+
+        if not isinstance(indexes, Iterable) or isinstance(indexes, (str, bytes)):
+            raise TypeError("indexes must be an iterable of index definitions")
+
+        sql_only = kwds.get("sql_only", False)
+        statements = []
+
+        for definition in indexes:
+            if isinstance(definition, Mapping):
+                columns = definition.get("columns")
+                if not columns:
+                    raise ValueError("Index definition requires a non-empty 'columns' entry")
+                params = {
+                    "unique": definition.get("unique", False),
+                    "direction": definition.get("direction"),
+                    "where": definition.get("where"),
+                    "lower": definition.get("lower"),
+                }
+            else:
+                columns = definition
+                params = {
+                    "unique": False,
+                    "direction": None,
+                    "where": None,
+                    "lower": None,
+                }
+
+            if isinstance(columns, str):
+                columns = columns.split(",")
+
+            if not columns:
+                raise ValueError("Index columns cannot be empty")
+
+            result = self.create_index(columns, **params, **kwds)
+            if sql_only:
+                statements.append(result)
+
+        return statements if sql_only else None
+
     @return_default(None)
     def drop_index(self, columns, **kwds):
         """
@@ -163,6 +240,34 @@ class Table:
             return self.name in [f"{x[0]}.{x[1]}" for x in result.as_tuple()]
         return self.name in [x[1] for x in result.as_tuple()]
 
+    def ensure_system_columns(self, **kwds):
+        """Ensure Velocity system columns and triggers exist for this table."""
+        force = kwds.get("force", False)
+
+        try:
+            columns = [col.lower() for col in self.sys_columns()]
+        except Exception:
+            columns = []
+
+        sql_method = getattr(self.sql, "ensure_system_columns", None)
+
+        if sql_method is None:
+            raise AttributeError(
+                f"{self.sql.__class__.__name__} does not implement ensure_system_columns"
+            )
+
+        result = sql_method(
+            self.name, existing_columns=columns, force=force
+        )
+
+        if not result:
+            return
+
+        sql, vals = result
+        if kwds.get("sql_only", False):
+            return sql, vals
+        self.tx.execute(sql, vals, cursor=self.cursor())
+
     def column(self, name):
         """
         Returns a Column object for the given column name.
@@ -241,53 +346,91 @@ class Table:
         sys_id = self.tx.execute(sql, vals).scalar()
         return self.row(sys_id, lock=lock)
 
+    def _normalize_lookup_where(self, where):
+        if where is None:
+            raise Exception("None is not allowed as a primary key.")
+        if isinstance(where, Row):
+            return dict(where.pk)
+        if isinstance(where, int):
+            return {"sys_id": where}
+        if not isinstance(where, Mapping):
+            raise TypeError(
+                "Lookup criteria must be an int, Row, or mapping of column -> value."
+            )
+        return dict(where)
+
+    def _select_sys_ids(
+        self,
+        where,
+        *,
+        lock=None,
+        orderby=None,
+        skip_locked=None,
+        limit=2,
+    ):
+        select_kwargs = {
+            "where": where,
+            "lock": lock,
+            "orderby": orderby,
+            "skip_locked": skip_locked,
+        }
+        if limit is not None:
+            select_kwargs["qty"] = limit
+        return self.select("sys_id", **select_kwargs).all()
+
+    def _clean_where_for_insert(self, where):
+        clean = {}
+        for key, val in where.items():
+            if not isinstance(key, str):
+                continue
+            if set("<>!=%").intersection(key):
+                continue
+            clean.setdefault(key, val)
+        return clean
+
     def get(self, where, lock=None, use_where=False):
         """
         Gets or creates a row matching `where`. If multiple rows match, raises DuplicateRowsFoundError.
         If none match, a new row is created with the non-operator aspects of `where`.
         """
-        if where is None:
-            raise Exception("None is not allowed as a primary key.")
-        if isinstance(where, int):
-            where = {"sys_id": where}
-        result = self.select("sys_id", where=where, lock=lock).all()
+        lookup = self._normalize_lookup_where(where)
+        result = self._select_sys_ids(lookup, lock=lock, limit=2)
         if len(result) > 1:
-            sql = self.select("sys_id", sql_only=True, where=where, lock=lock)
+            sql = self.select("sys_id", sql_only=True, where=lookup, lock=lock)
             raise exceptions.DuplicateRowsFoundError(
                 f"More than one entry found. {sql}"
             )
         if not result:
-            new_data = where.copy()
-            for k in list(new_data.keys()):
-                if set("<>!=%").intersection(k):
-                    new_data.pop(k)
+            new_data = self._clean_where_for_insert(lookup)
             return self.new(new_data, lock=lock)
         if use_where:
-            return Row(self, where, lock=lock)
+            return Row(self, lookup, lock=lock)
         return Row(self, result[0]["sys_id"], lock=lock)
 
     @return_default(None)
-    def find(self, where, lock=None, use_where=False):
+    def find(self, where, lock=None, use_where=False, raise_if_missing=False):
         """
-        Finds a single row matching `where`, or returns None if none found.
-        Raises DuplicateRowsFoundError if multiple rows match.
+        Finds a single row matching `where`, or returns None if none found unless
+        ``raise_if_missing`` is True. Raises DuplicateRowsFoundError if multiple rows match.
         """
-        if where is None:
-            raise Exception("None is not allowed as a primary key.")
-        if isinstance(where, int):
-            where = {"sys_id": where}
-        result = self.select("sys_id", where=where, lock=lock).all()
+        lookup = self._normalize_lookup_where(where)
+        result = self._select_sys_ids(lookup, lock=lock, limit=2)
         if not result:
+            if raise_if_missing:
+                raise LookupError(
+                    f"No rows found in `{self.name}` for criteria: {lookup!r}"
+                )
             return None
         if len(result) > 1:
-            sql = self.select("sys_id", sql_only=True, where=where, lock=lock)
+            sql = self.select("sys_id", sql_only=True, where=lookup, lock=lock)
             raise exceptions.DuplicateRowsFoundError(
                 f"More than one entry found. {sql}"
             )
         if use_where:
-            return Row(self, where, lock=lock)
+            return Row(self, lookup, lock=lock)
         return Row(self, result[0]["sys_id"], lock=lock)
-    one=find
+
+    one = find
 
     @return_default(None)
     def first(
@@ -302,23 +445,21 @@ class Table:
         """
         Finds the first matching row (by `orderby`) or creates one if `create_new=True` and none found.
         """
-        if where is None:
-            raise Exception("None is not allowed as a where clause.")
-        if isinstance(where, int):
-            where = {"sys_id": where}
-        results = self.select(
-            "sys_id", where=where, orderby=orderby, skip_locked=skip_locked
-        ).all()
+        lookup = self._normalize_lookup_where(where)
+        results = self._select_sys_ids(
+            lookup,
+            lock=lock,
+            orderby=orderby,
+            skip_locked=skip_locked,
+            limit=1,
+        )
         if not results:
             if create_new:
-                new_data = where.copy()
-                for k in list(new_data.keys()):
-                    if set("<>!=%").intersection(k):
-                        new_data.pop(k)
+                new_data = self._clean_where_for_insert(lookup)
                 return self.new(new_data, lock=lock)
             return None
         if use_where:
-            return Row(self, where, lock=lock)
+            return Row(self, lookup, lock=lock)
         return Row(self, results[0]["sys_id"], lock=lock)
 
     def primary_keys(self):
@@ -431,7 +572,7 @@ class Table:
         if kwds.get("sql_only", False):
             return sql, vals
         result = self.tx.execute(sql, vals, cursor=self.cursor())
-        return result.cursor.rowcount
+        return result.cursor.rowcount if result.cursor else 0
 
     @reset_id_on_dup_key
     @create_missing
@@ -443,7 +584,7 @@ class Table:
         if kwds.get("sql_only", False):
             return sql, vals
         result = self.tx.execute(sql, vals, cursor=self.cursor())
-        return result.cursor.rowcount
+        return result.cursor.rowcount if result.cursor else 0
 
     @reset_id_on_dup_key
     @create_missing
@@ -462,7 +603,105 @@ class Table:
         if kwds.get("sql_only", False):
             return sql, vals
         result = self.tx.execute(sql, vals, cursor=self.cursor())
-        return result.cursor.rowcount
+        return result.cursor.rowcount if result.cursor else 0
+
+    @create_missing
+    def update_or_insert(self, update_data, insert_data=None, where=None, pk=None, **kwds):
+        """
+        Attempts an UPDATE first; if no rows change, performs an INSERT guarded by NOT EXISTS.
+
+        :param update_data: Mapping of columns to update.
+        :param insert_data: Optional mapping used for the INSERT. When omitted, values are
+                             derived from update_data combined with simple equality predicates
+                             from ``where`` and primary key values.
+        :param where: Criteria for the UPDATE and existence check.
+        :param pk: Optional primary key mapping for UPDATE (merged into WHERE) and INSERT.
+        :param sql_only: When True, return the SQL/parameter tuples for both phases instead of executing.
+        :return: Number of rows affected, or a dict with ``update``/``insert`` entries when sql_only=True.
+        """
+        sql_only = kwds.get("sql_only", False)
+        if not isinstance(update_data, Mapping) or not update_data:
+            raise ValueError("update_data must be a non-empty mapping of column-value pairs.")
+        if where is None and pk is None:
+            raise ValueError("Either where or pk must be provided for update_or_insert.")
+
+        update_stmt = None
+        if sql_only:
+            update_stmt = self.update(update_data, where=where, pk=pk, sql_only=True)
+        else:
+            updated = self.update(update_data, where=where, pk=pk)
+            if updated:
+                return updated
+
+        if insert_data is not None:
+            if not isinstance(insert_data, Mapping):
+                raise ValueError("insert_data must be a mapping when provided.")
+            insert_payload = dict(insert_data)
+        else:
+            insert_payload = dict(update_data)
+            if isinstance(where, Mapping):
+                for key, val in where.items():
+                    if not isinstance(key, str):
+                        continue
+                    if set("<>!=%").intersection(key):
+                        continue
+                    insert_payload.setdefault(key, val)
+            if isinstance(pk, Mapping):
+                for key, val in pk.items():
+                    insert_payload.setdefault(key, val)
+
+        if not insert_payload:
+            raise ValueError("Unable to derive insert payload for update_or_insert.")
+
+        exists_where = None
+        if where is not None and pk is not None:
+            if isinstance(where, Mapping) and isinstance(pk, Mapping):
+                combined = dict(where)
+                combined.update(pk)
+                exists_where = combined
+            else:
+                exists_where = where
+        elif where is not None:
+            exists_where = where
+        else:
+            exists_where = pk
+
+        ins_builder = getattr(self.sql, "insnx", None) or 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."
+            )
+
+        sql, vals = ins_builder(self.tx, self.name, insert_payload, exists_where)
+        if sql_only:
+            return {"update": update_stmt, "insert": (sql, vals)}
+        result = self.tx.execute(sql, vals, cursor=self.cursor())
+        return result.cursor.rowcount if result.cursor else 0
+
+    updins = update_or_insert
+
+    @create_missing
+    def insert_if_not_exists(self, data, where=None, **kwds):
+        """
+        Inserts `data` into the table only if the existence check (`where`) does not match any rows.
+
+        Usage:
+            table.insert_if_not_exists({'key_col': 'k', 'value': 'v'}, where={'key_col': 'k'})
+
+        :param data: dict of column -> value for insert
+        :param where: mapping/list/str used for the EXISTS check; if None primary keys are used and
+                      must be present in `data`.
+        :return: rowcount (0 or 1) or (sql, params) when sql_only=True
+        """
+        sql, vals = self.sql.insert_if_not_exists(self.tx, self.name, data, where)
+        if kwds.get("sql_only", False):
+            return sql, vals
+        result = self.tx.execute(sql, vals, cursor=self.cursor())
+        return result.cursor.rowcount if result.cursor else 0
+
+    insnx = insert_if_not_exists
 
     upsert = merge
     indate = merge
@@ -662,7 +901,7 @@ class Table:
         if kwds.get("sql_only", False):
             return sql, vals
         result = self.tx.execute(sql, vals)
-        return result.cursor.rowcount
+        return result.cursor.rowcount if result.cursor else 0
 
     def truncate(self, **kwds):
         """
@@ -886,8 +1125,8 @@ class Table:
         # Return a descriptive string of differences.
         if differences:
             differences.insert(0, f"Comparing {self.name}: {pk1} vs {pk2}")
-            differences.insert(0, f"--------------------------------------")
-            differences.append(f"--------------------------------------")
+            differences.insert(0, "--------------------------------------")
+            differences.append("--------------------------------------")
             return "\n".join(differences)
         else:
             return f"{self.name} rows {pk1} and {pk2} are identical."

velocity/db/core/transaction.py

@@ -164,17 +164,25 @@ class Transaction:
         """
         return Row(self.table(tablename), pk, lock=lock)
 
-    def get(self, tablename, where, lock=None):
-        """
-        Shortcut to table.get().
-        """
-        return self.table(tablename).get(where, lock=lock)
-
-    def find(self, tablename, where, lock=None):
-        """
-        Shortcut to table.find().
-        """
-        return self.table(tablename).find(where, lock=lock)
+    def get(self, tablename, where, lock=None, use_where=False):
+        """Shortcut to table.get() with optional ``use_where`` passthrough."""
+        return self.table(tablename).get(where, lock=lock, use_where=use_where)
+
+    def find(
+        self,
+        tablename,
+        where,
+        lock=None,
+        use_where=False,
+        raise_if_missing=False,
+    ):
+        """Shortcut to table.find() with ``use_where``/``raise_if_missing`` passthrough."""
+        return self.table(tablename).find(
+            where,
+            lock=lock,
+            use_where=use_where,
+            raise_if_missing=raise_if_missing,
+        )
 
     def column(self, tablename, colname):
         """