velocity-python 0.0.35__py3-none-any.whl → 0.0.65__py3-none-any.whl

velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.0.35"
+__version__ = version = "0.0.65"
 
 from . import aws
 from . import db

velocity/db/core/column.py

@@ -2,64 +2,34 @@ from velocity.db import exceptions
 from velocity.db.core.decorators import return_default
 
 
-class Column(object):
+class Column:
     """
     Represents a column in a database table.
     """
 
     def __init__(self, table, name):
-        """
-        Initializes a column object with the specified table and name.
-
-        Args:
-            table (table): The table object that the column belongs to.
-            name (str): The name of the column.
-
-        Raises:
-            Exception: If the table parameter is not of type 'table'.
-        """
         if isinstance(table, str):
-            raise Exception("column table parameter must be a `table` class.")
+            raise Exception("Column 'table' parameter must be a Table instance.")
         self.tx = table.tx
         self.sql = table.tx.engine.sql
         self.name = name
         self.table = table
 
     def __str__(self):
-        """
-        Returns a string representation of the column object.
-
-        Returns:
-            str: A string representation of the column object.
-        """
-        return """
-    Table: %s
-    Column: %s
-    Column Exists: %s
-    Py Type: %s
-    SQL Type: %s
-    NULL OK: %s
-    Foreign Key: %s
-        """ % (
-            self.table.name,
-            self.name,
-            self.exists(),
-            self.py_type,
-            self.sql_type,
-            self.is_nullok,
-            self.foreign_key_to,
+        return (
+            f"Table: {self.table.name}\n"
+            f"Column: {self.name}\n"
+            f"Column Exists: {self.exists()}\n"
+            f"Py Type: {self.py_type}\n"
+            f"SQL Type: {self.sql_type}\n"
+            f"NULL OK: {self.is_nullok}\n"
+            f"Foreign Key: {self.foreign_key_to}\n"
         )
 
     @property
     def info(self):
         """
-        Retrieves information about the column from the database.
-
-        Returns:
-            dict: A dictionary containing information about the column.
-
-        Raises:
-            DbColumnMissingError: If the column does not exist in the database.
+        Retrieves information about the column from the database, raising DbColumnMissingError if not found.
         """
         sql, vals = self.sql.column_info(self.table.name, self.name)
         result = self.tx.execute(sql, vals).one()
@@ -70,13 +40,7 @@ class Column(object):
     @property
     def foreign_key_info(self):
         """
-        Retrieves information about the foreign key constraint on the column.
-
-        Returns:
-            dict: A dictionary containing information about the foreign key constraint.
-
-        Raises:
-            DbColumnMissingError: If the column does not exist in the database.
+        Retrieves information about any foreign key constraint on this column.
         """
         sql, vals = self.sql.foreign_key_info(table=self.table.name, column=self.name)
         result = self.tx.execute(sql, vals).one()
@@ -87,13 +51,7 @@ class Column(object):
     @property
     def foreign_key_to(self):
         """
-        Retrieves the name of the referenced table and column for the foreign key constraint.
-
-        Returns:
-            str: The name of the referenced table and column in the format 'referenced_table_name.referenced_column_name'.
-
-        Raises:
-            DbColumnMissingError: If the column does not exist in the database.
+        Returns a string 'referenced_table_name.referenced_column_name' or None if no foreign key.
         """
         try:
             return "{referenced_table_name}.{referenced_column_name}".format(
@@ -105,13 +63,7 @@ class Column(object):
     @property
     def foreign_key_table(self):
         """
-        Retrieves the name of the referenced table for the foreign key constraint.
-
-        Returns:
-            str: The name of the referenced table.
-
-        Raises:
-            DbColumnMissingError: If the column does not exist in the database.
+        Returns the name of the referenced table for the foreign key, or None if none.
         """
         try:
             return self.foreign_key_info["referenced_table_name"]
@@ -120,40 +72,28 @@ class Column(object):
 
     def exists(self):
         """
-        Checks if the column exists in the table.
-
-        Returns:
-            bool: True if the column exists, False otherwise.
+        True if this column name is in self.table.columns().
         """
-        return self.name in self.table.columns
+        return self.name in self.table.columns()
 
     @property
     def py_type(self):
         """
-        Retrieves the Python data type of the column.
-
-        Returns:
-            type: The Python data type of the column.
+        Returns the Python data type that corresponds to this column's SQL type.
         """
-        return self.sql.py_type(self.sql_type)
+        return self.sql.types.py_type(self.sql_type)
 
     @property
     def sql_type(self):
         """
-        Retrieves the SQL data type of the column.
-
-        Returns:
-            str: The SQL data type of the column.
+        Returns the underlying SQL type name (e.g. 'TEXT', 'INTEGER', etc.).
         """
         return self.info[self.sql.type_column_identifier]
 
     @property
     def is_nullable(self):
         """
-        Checks if the column is nullable.
-
-        Returns:
-            bool: True if the column is nullable, False otherwise.
+        True if column is nullable.
         """
         return self.info[self.sql.is_nullable]
 
@@ -162,9 +102,6 @@ class Column(object):
     def rename(self, name):
         """
         Renames the column.
-
-        Args:
-            name (str): The new name for the column.
         """
         sql, vals = self.sql.rename_column(self.table.name, self.name, name)
         self.tx.execute(sql, vals)
@@ -173,40 +110,23 @@ class Column(object):
     @return_default([])
     def distinct(self, order="asc", qty=None):
         """
-        Retrieves distinct values from the column.
-
-        Args:
-            order (str, optional): The order in which the values should be sorted. Defaults to 'asc'.
-            qty (int, optional): The maximum number of distinct values to retrieve. Defaults to None.
-
-        Returns:
-            list: A list of distinct values from the column.
+        Returns the distinct values in this column, optionally ordered and/or limited in quantity.
         """
         sql, vals = self.sql.select(
-            columns="distinct {}".format(self.name),
+            columns=f"distinct {self.name}",
             table=self.table.name,
-            orderby="{} {}".format(self.name, order),
+            orderby=f"{self.name} {order}",
             qty=qty,
         )
         return self.tx.execute(sql, vals).as_simple_list().all()
 
     def max(self, where=None):
         """
-        Retrieves the maximum value from the column.
-
-        Args:
-            where (str, optional): The WHERE clause to filter the rows. Defaults to None.
-
-        Returns:
-            int: The maximum value from the column.
-
-        Raises:
-            DbTableMissingError: If the table does not exist in the database.
-            DbColumnMissingError: If the column does not exist in the database.
+        Returns the MAX() of this column, or 0 if table/column is missing.
         """
         try:
             sql, vals = self.sql.select(
-                columns="max({})".format(self.name), table=self.table.name, where=where
+                columns=f"max({self.name})", table=self.table.name, where=where
             )
             return self.tx.execute(sql, vals).scalar()
         except (exceptions.DbTableMissingError, exceptions.DbColumnMissingError):

velocity/db/core/database.py

@@ -1,4 +1,7 @@
-class Database(object):
+class Database:
+    """
+    Represents a database within a transaction context.
+    """
 
     def __init__(self, tx, name=None):
         self.tx = tx
@@ -6,16 +9,11 @@ class Database(object):
         self.sql = tx.engine.sql
 
     def __str__(self):
-        return """
-    Engine: %s
-    Database: %s
-    (db exists) %s
-    Tables: %s
-        """ % (
-            self.tx.engine.sql.server,
-            self.name,
-            self.exists(),
-            len(self.tables),
+        return (
+            f"Engine: {self.tx.engine.sql.server}\n"
+            f"Database: {self.name}\n"
+            f"(db exists) {self.exists()}\n"
+            f"Tables: {len(self.tables)}\n"
         )
 
     def __enter__(self):
@@ -26,40 +24,98 @@ class Database(object):
             self.close()
 
     def close(self):
+        """
+        Closes the cursor if it exists.
+        """
         try:
             self._cursor.close()
-            # print("*** database('{}').cursor.close()".format(self.name))
         except AttributeError:
             pass
 
-    @property
     def cursor(self):
+        """
+        Lazy-initialize the cursor on first use.
+        """
         try:
             return self._cursor
         except AttributeError:
-            # print("*** database('{}').cursor.open()".format(self.name))
             self._cursor = self.tx.cursor()
         return self._cursor
 
     def drop(self):
-        sql, vals = self.engine.sql.drop_database(self.name)
-        self.tx.execute(sql, vals, single=True, cursor=self.cursor)
+        """
+        Drops this database.
+        """
+        sql, vals = self.tx.engine.sql.drop_database(self.name)
+        self.tx.execute(sql, vals, single=True, cursor=self.cursor())
 
     def create(self):
-        sql, vals = self.engine.sql.create_database(self.name)
-        self.tx.execute(sql, vals, single=True, cursor=self.cursor)
+        """
+        Creates this database.
+        """
+        sql, vals = self.tx.engine.sql.create_database(self.name)
+        self.tx.execute(sql, vals, single=True, cursor=self.cursor())
 
     def exists(self):
+        """
+        Returns True if the database exists, else False.
+        """
         sql, vals = self.sql.databases()
-        result = self.tx.execute(sql, vals, cursor=self.cursor)
+        result = self.tx.execute(sql, vals, cursor=self.cursor())
         return bool(self.name in [x[0] for x in result.as_tuple()])
 
     @property
     def tables(self):
+        """
+        Returns a list of 'schema.table' strings representing tables in this database.
+        """
         sql, vals = self.sql.tables()
-        result = self.tx.execute(sql, vals, cursor=self.cursor)
-        return ["%s.%s" % x for x in result.as_tuple()]
+        result = self.tx.execute(sql, vals, cursor=self.cursor())
+        return [f"{x[0]}.{x[1]}" for x in result.as_tuple()]
 
     def reindex(self):
-        sql, vals = "REINDEX DATABASE {}".format(self.name), tuple()
-        self.tx.execute(sql, vals, cursor=self.cursor)
+        """
+        Re-indexes this database.
+        """
+        sql = f"REINDEX DATABASE {self.name}"
+        vals = ()
+        self.tx.execute(sql, vals, cursor=self.cursor())
+
+    def switch(self):
+        """
+        Switches the parent transaction to this database.
+        """
+        self.tx.switch_to_database(self.name)
+        return self
+
+    def vacuum(self, analyze=True, full=False, reindex=True):
+        """
+        Performs VACUUM on this database, optionally FULL, optionally ANALYZE,
+        optionally REINDEX.
+        """
+        # Manually open a separate connection to run VACUUM in isolation_level=0
+        conn = self.tx.engine.connect()
+        old_isolation_level = conn.isolation_level
+        try:
+            # Postgres requires VACUUM to run outside a normal transaction block
+            conn.set_isolation_level(0)
+
+            # Build up the VACUUM command
+            parts = ["VACUUM"]
+            if full:
+                parts.append("FULL")
+            if analyze:
+                parts.append("ANALYZE")
+
+            # Execute VACUUM
+            with conn.cursor() as cur:
+                cur.execute(" ".join(parts))
+
+                # Optionally REINDEX the database
+                if reindex:
+                    cur.execute(f"REINDEX DATABASE {self.name}")
+
+        finally:
+            # Restore isolation level and close the connection
+            conn.set_isolation_level(old_isolation_level)
+            conn.close()

velocity/db/core/decorators.py

@@ -1,34 +1,61 @@
+import time
+import random
+import traceback
 from functools import wraps
 from velocity.db import exceptions
-import traceback
 
 
-def retry_on_dup_key(function):
-    # retry_on_dup_key is needed to skip past existing autogenerated ids when inserting
-    @wraps(function)
+def retry_on_dup_key(func):
+    """
+    Retries a function call if it raises DbDuplicateKeyError, up to max_retries.
+    """
+
+    @wraps(func)
     def retry_decorator(self, *args, **kwds):
-        sp = self.tx.create_savepoint(cursor=self.cursor)
-        while True:
+        max_retries = 10
+        retries = 0
+        while retries < max_retries:
+            sp = self.tx.create_savepoint(cursor=self.cursor())
             try:
-                return function(self, *args, **kwds)
+                result = func(self, *args, **kwds)
+                self.tx.release_savepoint(sp, cursor=self.cursor())
+                return result
             except exceptions.DbDuplicateKeyError:
-                self.tx.rollback_savepoint(sp, cursor=self.cursor)
-                continue
+                self.tx.rollback_savepoint(sp, cursor=self.cursor())
+                if "sys_id" in kwds.get("data", {}):
+                    raise
+                retries += 1
+                if retries >= max_retries:
+                    raise
+                backoff_time = (2**retries) * 0.01 + random.uniform(0, 0.02)
+                time.sleep(backoff_time)
+        raise exceptions.DbDuplicateKeyError("Max retries reached.")
 
     return retry_decorator
 
 
-def reset_id_on_dup_key(function):
-    # reset_id_on_dup_key sets sys_id to max(sys_id) + 1 when inserting
-    @wraps(function)
-    def reset_decorator(self, *args, **kwds):
-        sp = self.tx.create_savepoint(cursor=self.cursor)
+def reset_id_on_dup_key(func):
+    """
+    Wraps an INSERT/UPSERT to reset the sys_id sequence on duplicate key collisions.
+    """
+
+    @wraps(func)
+    def reset_decorator(self, *args, retries=0, **kwds):
+        sp = self.tx.create_savepoint(cursor=self.cursor())
         try:
-            return function(self, *args, **kwds)
+            result = func(self, *args, **kwds)
+            self.tx.release_savepoint(sp, cursor=self.cursor())
+            return result
         except exceptions.DbDuplicateKeyError:
-            self.tx.rollback_savepoint(sp, cursor=self.cursor)
-            self.set_sequence(self.max("sys_id") + 1)
-            return function(self, *args, **kwds)
+            self.tx.rollback_savepoint(sp, cursor=self.cursor())
+            if "sys_id" in kwds.get("data", {}):
+                raise
+            if retries < 3:
+                backoff_time = (2**retries) * 0.01 + random.uniform(0, 0.02)
+                time.sleep(backoff_time)
+                self.set_sequence(self.max("sys_id") + 1)
+                return reset_decorator(self, *args, retries=retries + 1, **kwds)
+        raise exceptions.DbDuplicateKeyError("Max retries reached.")
 
     return reset_decorator
 
@@ -44,59 +71,69 @@ def return_default(
         exceptions.DbObjectExistsError,
     ),
 ):
-    def decorator(f):
-        f.default = default
-        f.exceptions = exceptions
+    """
+    If the wrapped function raises one of the specified exceptions, or returns None,
+    this decorator returns the `default` value instead.
+    """
+
+    def decorator(func):
+        func.default = default
+        func.exceptions = exceptions
 
-        @wraps(f)
-        def return_default(self, *args, **kwds):
-            sp = self.tx.create_savepoint(cursor=self.cursor)
+        @wraps(func)
+        def wrapper(self, *args, **kwds):
+            sp = self.tx.create_savepoint(cursor=self.cursor())
             try:
-                result = f(self, *args, **kwds)
+                result = func(self, *args, **kwds)
                 if result is None:
                     result = default
-            except f.exceptions as e:
+            except func.exceptions:
                 traceback.print_exc()
-                self.tx.rollback_savepoint(sp, cursor=self.cursor)
-                return f.default
-            self.tx.release_savepoint(sp, cursor=self.cursor)
+                self.tx.rollback_savepoint(sp, cursor=self.cursor())
+                return default
+            self.tx.release_savepoint(sp, cursor=self.cursor())
             return result
 
-        return return_default
+        return wrapper
 
     return decorator
 
 
-def create_missing(function):
-    @wraps(function)
-    def create_missing_decorator(self, *args, **kwds):
-        sp = self.tx.create_savepoint(cursor=self.cursor)
+def create_missing(func):
+    """
+    If the function call fails with DbColumnMissingError or DbTableMissingError, tries to create them and re-run.
+    """
+
+    @wraps(func)
+    def wrapper(self, *args, **kwds):
+        sp = self.tx.create_savepoint(cursor=self.cursor())
         try:
-            result = function(self, *args, **kwds)
-            self.tx.release_savepoint(sp, cursor=self.cursor)
+            result = func(self, *args, **kwds)
+            self.tx.release_savepoint(sp, cursor=self.cursor())
+            return result
         except exceptions.DbColumnMissingError:
-            self.tx.rollback_savepoint(sp, cursor=self.cursor)
+            self.tx.rollback_savepoint(sp, cursor=self.cursor())
             data = {}
             if "pk" in kwds:
                 data.update(kwds["pk"])
             if "data" in kwds:
                 data.update(kwds["data"])
-            for i in range(len(args)):
-                if args[i]:
-                    data.update(args[i])
+            for i, arg in enumerate(args):
+                if isinstance(arg, dict):
+                    data.update(arg)
             self.alter(data)
-            result = function(self, *args, **kwds)
+            return func(self, *args, **kwds)
         except exceptions.DbTableMissingError:
-            self.tx.rollback_savepoint(sp, cursor=self.cursor)
+            self.tx.rollback_savepoint(sp, cursor=self.cursor())
             data = {}
             if "pk" in kwds:
                 data.update(kwds["pk"])
             if "data" in kwds:
                 data.update(kwds["data"])
-            for i in range(len(args)):
-                data.update(args[i])
+            for i, arg in enumerate(args):
+                if isinstance(arg, dict):
+                    data.update(arg)
             self.create(data)
-            result = function(self, *args, **kwds)
-        return result
+            return func(self, *args, **kwds)
 
-    return create_missing_decorator
+    return wrapper