velocity-python 0.0.109__py3-none-any.whl → 0.0.161__py3-none-any.whl

velocity/db/core/table.py

@@ -1,4 +1,6 @@
+import re
 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 +25,121 @@ 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}
+
+_NULLABLE_TRUE = {"YES", "TRUE", "T", "1", "Y"}
+_NULLABLE_FALSE = {"NO", "FALSE", "F", "0", "N"}
+
+
+def _normalize_sql_type(value):
+    """Return a simplified SQL type identifier for comparison purposes."""
+
+    if value is None:
+        return None
+
+    normalized = re.sub(r"\s+", " ", str(value).strip()).upper()
+
+    if not normalized:
+        return None
+
+    if normalized.startswith("CHARACTER VARYING") or normalized.startswith("VARCHAR"):
+        return "TEXT"
+    if normalized.startswith("CHAR(") or normalized == "CHARACTER" or normalized == "BPCHAR":
+        return "TEXT"
+    if normalized.startswith("NUMERIC(") or normalized.startswith("DECIMAL("):
+        return "NUMERIC"
+    if normalized == "TIMESTAMP":
+        return "TIMESTAMP WITHOUT TIME ZONE"
+    if normalized.startswith("TIMESTAMP WITHOUT TIME ZONE"):
+        return "TIMESTAMP WITHOUT TIME ZONE"
+    if normalized in {"TIMESTAMPTZ", "TIMESTAMP WITH TIME ZONE"}:
+        return "TIMESTAMP WITH TIME ZONE"
+    if normalized.startswith("TIME WITHOUT TIME ZONE"):
+        return "TIME WITHOUT TIME ZONE"
+    if normalized in {"TIME WITH TIME ZONE", "TIMETZ"}:
+        return "TIME WITH TIME ZONE"
+    if normalized == "BOOL":
+        return "BOOLEAN"
+    return normalized
+
+
+def _types_equivalent(current, expected):
+    return _normalize_sql_type(current) == _normalize_sql_type(expected)
+
+
+def _is_nullable_flag(value):
+    if isinstance(value, bool):
+        return value
+    if value is None:
+        return None
+    text = str(value).strip().upper()
+    if text in _NULLABLE_TRUE:
+        return True
+    if text in _NULLABLE_FALSE:
+        return False
+    return None
+
+
+def _parse_column_spec(spec, default_nullable):
+    """Normalize user-provided column specification into a common structure."""
+
+    nullable = default_nullable
+    nullable_specified = False
+    alter_sql = None
+    using_expression = None
+
+    base = spec
+    override_options = {}
+
+    if isinstance(spec, tuple) and len(spec) == 2 and isinstance(spec[1], Mapping):
+        base, override_options = spec
+
+    options = {}
+    if isinstance(base, Mapping):
+        options.update(base)
+        base = options.get("type", options.get("value"))
+
+    if override_options:
+        options.update(override_options)
+
+    type_hint = options.get("type", base)
+    if type_hint is None and "value" in options:
+        type_hint = options["value"]
+
+    add_value = options.get("add_value", options.get("value", type_hint))
+
+    if "nullable" in options:
+        nullable = bool(options["nullable"])
+        nullable_specified = True
+
+    alter_sql = options.get("sql")
+    using_expression = options.get("using")
+
+    return {
+        "type_hint": type_hint,
+        "add_value": add_value,
+        "nullable": nullable,
+        "nullable_specified": nullable_specified,
+        "alter_sql": alter_sql,
+        "using": using_expression,
+    }
+
+
 class Table:
+    SYSTEM_COLUMNS = SYSTEM_COLUMN_NAMES
+
     """
     Provides an interface for performing CRUD and metadata operations on a DB table.
     """
@@ -54,13 +170,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 +209,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 +241,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 +338,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 +444,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 = one_or_none = find
 
     @return_default(None)
     def first(
@@ -302,23 +543,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):
@@ -394,22 +633,128 @@ class Table:
     @create_missing
     def alter(self, columns, **kwds):
         """
-        Adds any missing columns (based on the provided dict) to the table.
+        Create or update columns so they match the supplied specification.
         """
+
         if not isinstance(columns, dict):
             raise Exception("Columns must be a dict.")
+
+        mode = kwds.pop("mode", "smart")
+        mode = (mode or "smart").lower()
+        if mode not in {"smart", "add"}:
+            raise ValueError(f"Unsupported alter mode: {mode}")
+
+        sql_only = kwds.get("sql_only", False)
+        default_nullable = kwds.get("null_allowed", True)
+
         columns = self.lower_keys(columns)
-        diff = []
-        for k in columns.keys():
-            if k not in self.sys_columns():
-                diff.append(k)
-        if diff:
-            newcols = {key: columns[key] for key in diff}
-            sql, vals = self.sql.alter_add(self.name, newcols)
-            if kwds.get("sql_only", False):
-                return sql, vals
+        existing_columns = {col.lower() for col in self.sys_columns()}
+
+        to_add = {}
+        add_specs = {}
+        statements = []
+        null_statements = []
+        type_statements = []
+        custom_statements = []
+
+        for column_name, raw_spec in columns.items():
+            spec = _parse_column_spec(raw_spec, default_nullable)
+
+            if column_name not in existing_columns:
+                to_add[column_name] = spec["add_value"]
+                add_specs[column_name] = spec
+                continue
+
+            if mode == "add":
+                continue
+
+            column_obj = self.column(column_name)
+            current_type = column_obj.sql_type
+            type_hint = spec["type_hint"]
+
+            if not (isinstance(type_hint, str) and type_hint.startswith("@@")) and type_hint is not None:
+                expected_type = self.sql.types.get_type(type_hint)
+                if expected_type and not _types_equivalent(current_type, expected_type):
+                    if spec["using"]:
+                        clause = f"TYPE {expected_type} USING {spec['using']}"
+                        sql, vals = self.sql.alter_column_by_sql(self.name, column_name, clause)
+                    else:
+                        nullable_flag = _is_nullable_flag(column_obj.is_nullable)
+                        if nullable_flag is None:
+                            nullable_flag = True
+                        server_name = getattr(self.sql, "server", "").lower()
+                        if server_name.startswith("postgre"):
+                            type_argument = type_hint
+                        else:
+                            type_argument = expected_type or type_hint
+                        sql, vals = self.sql.alter_column_by_type(
+                            self.name,
+                            column_name,
+                            type_argument,
+                            nullable_flag,
+                        )
+                    type_statements.append((sql, vals))
+
+            if spec["alter_sql"]:
+                sql, vals = self.sql.alter_column_by_sql(self.name, column_name, spec["alter_sql"])
+                custom_statements.append((sql, vals))
+
+            if spec["nullable_specified"]:
+                desired_nullable = spec["nullable"]
+                current_nullable = _is_nullable_flag(column_obj.is_nullable)
+                if desired_nullable and current_nullable is False:
+                    sql, vals = self.sql.alter_column_by_sql(
+                        self.name, column_name, "DROP NOT NULL"
+                    )
+                    null_statements.append((sql, vals))
+                elif not desired_nullable and current_nullable is True:
+                    sql, vals = self.sql.alter_column_by_sql(
+                        self.name, column_name, "SET NOT NULL"
+                    )
+                    null_statements.append((sql, vals))
+
+        if to_add:
+            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 spec["nullable_specified"] and not spec["nullable"] and default_nullable:
+                    sql, vals = self.sql.alter_column_by_sql(
+                        self.name, column_name, "SET NOT NULL"
+                    )
+                    null_statements.append((sql, vals))
+                elif spec["nullable_specified"] and spec["nullable"] and not default_nullable:
+                    sql, vals = self.sql.alter_column_by_sql(
+                        self.name, column_name, "DROP NOT NULL"
+                    )
+                    null_statements.append((sql, vals))
+
+        statements.extend(type_statements)
+        statements.extend(custom_statements)
+        statements.extend(null_statements)
+
+        if not statements:
+            return None
+
+        if sql_only:
+            if len(statements) == 1:
+                return statements[0]
+            return statements
+
+        for sql, vals in statements:
+            if not sql:
+                continue
             self.tx.execute(sql, vals, cursor=self.cursor())
 
+    def alter_add(self, columns, **kwds):
+        """
+        Add missing columns without modifying existing column definitions.
+        """
+
+        kwds = dict(kwds)
+        kwds["mode"] = "add"
+        return self.alter(columns, **kwds)
+
     @create_missing
     def alter_type(self, column, type_or_value, nullable=True, **kwds):
         """
@@ -464,6 +809,104 @@ class Table:
         result = self.tx.execute(sql, vals, cursor=self.cursor())
         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
 
@@ -886,8 +1329,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."