velocity-python 0.0.35__tar.gz → 0.0.65__tar.gz

{velocity_python-0.0.35 → velocity_python-0.0.65}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.0.35
+Version: 0.0.65
 Summary: A rapid application development library for interfacing with data storage
 Author-email: Paul Perez <pperez@codeclubs.org>
 Project-URL: Homepage, https://codeclubs.org/projects/velocity
@@ -20,6 +20,7 @@ Provides-Extra: sqlserver
 Requires-Dist: python-tds; extra == "sqlserver"
 Provides-Extra: postgres
 Requires-Dist: psycopg2-binary; extra == "postgres"
+Dynamic: license-file
 
 # Velocity.DB
 

{velocity_python-0.0.35 → velocity_python-0.0.65}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "velocity-python"
-version = "0.0.35"
+version = "0.0.65"
 authors = [
   { name="Paul Perez", email="pperez@codeclubs.org" },
 ]

{velocity_python-0.0.35 → velocity_python-0.0.65}/src/velocity/__init__.py

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

velocity_python-0.0.65/src/velocity/db/core/column.py

@@ -0,0 +1,133 @@
+from velocity.db import exceptions
+from velocity.db.core.decorators import return_default
+
+
+class Column:
+    """
+    Represents a column in a database table.
+    """
+
+    def __init__(self, table, name):
+        if isinstance(table, str):
+            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):
+        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, raising DbColumnMissingError if not found.
+        """
+        sql, vals = self.sql.column_info(self.table.name, self.name)
+        result = self.tx.execute(sql, vals).one()
+        if not result:
+            raise exceptions.DbColumnMissingError
+        return result
+
+    @property
+    def foreign_key_info(self):
+        """
+        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()
+        if not result:
+            raise exceptions.DbColumnMissingError
+        return result
+
+    @property
+    def foreign_key_to(self):
+        """
+        Returns a string 'referenced_table_name.referenced_column_name' or None if no foreign key.
+        """
+        try:
+            return "{referenced_table_name}.{referenced_column_name}".format(
+                **self.foreign_key_info
+            )
+        except exceptions.DbColumnMissingError:
+            return None
+
+    @property
+    def foreign_key_table(self):
+        """
+        Returns the name of the referenced table for the foreign key, or None if none.
+        """
+        try:
+            return self.foreign_key_info["referenced_table_name"]
+        except exceptions.DbColumnMissingError:
+            return None
+
+    def exists(self):
+        """
+        True if this column name is in self.table.columns().
+        """
+        return self.name in self.table.columns()
+
+    @property
+    def py_type(self):
+        """
+        Returns the Python data type that corresponds to this column's SQL type.
+        """
+        return self.sql.types.py_type(self.sql_type)
+
+    @property
+    def sql_type(self):
+        """
+        Returns the underlying SQL type name (e.g. 'TEXT', 'INTEGER', etc.).
+        """
+        return self.info[self.sql.type_column_identifier]
+
+    @property
+    def is_nullable(self):
+        """
+        True if column is nullable.
+        """
+        return self.info[self.sql.is_nullable]
+
+    is_nullok = is_nullable
+
+    def rename(self, name):
+        """
+        Renames the column.
+        """
+        sql, vals = self.sql.rename_column(self.table.name, self.name, name)
+        self.tx.execute(sql, vals)
+        self.name = name
+
+    @return_default([])
+    def distinct(self, order="asc", qty=None):
+        """
+        Returns the distinct values in this column, optionally ordered and/or limited in quantity.
+        """
+        sql, vals = self.sql.select(
+            columns=f"distinct {self.name}",
+            table=self.table.name,
+            orderby=f"{self.name} {order}",
+            qty=qty,
+        )
+        return self.tx.execute(sql, vals).as_simple_list().all()
+
+    def max(self, where=None):
+        """
+        Returns the MAX() of this column, or 0 if table/column is missing.
+        """
+        try:
+            sql, vals = self.sql.select(
+                columns=f"max({self.name})", table=self.table.name, where=where
+            )
+            return self.tx.execute(sql, vals).scalar()
+        except (exceptions.DbTableMissingError, exceptions.DbColumnMissingError):
+            return 0

velocity_python-0.0.65/src/velocity/db/core/database.py

@@ -0,0 +1,121 @@
+class Database:
+    """
+    Represents a database within a transaction context.
+    """
+
+    def __init__(self, tx, name=None):
+        self.tx = tx
+        self.name = name or self.tx.engine.config["database"]
+        self.sql = tx.engine.sql
+
+    def __str__(self):
+        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):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        if not exc_type:
+            self.close()
+
+    def close(self):
+        """
+        Closes the cursor if it exists.
+        """
+        try:
+            self._cursor.close()
+        except AttributeError:
+            pass
+
+    def cursor(self):
+        """
+        Lazy-initialize the cursor on first use.
+        """
+        try:
+            return self._cursor
+        except AttributeError:
+            self._cursor = self.tx.cursor()
+        return self._cursor
+
+    def drop(self):
+        """
+        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):
+        """
+        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())
+        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 [f"{x[0]}.{x[1]}" for x in result.as_tuple()]
+
+    def reindex(self):
+        """
+        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_python-0.0.65/src/velocity/db/core/decorators.py

@@ -0,0 +1,139 @@
+import time
+import random
+import traceback
+from functools import wraps
+from velocity.db import exceptions
+
+
+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):
+        max_retries = 10
+        retries = 0
+        while retries < max_retries:
+            sp = self.tx.create_savepoint(cursor=self.cursor())
+            try:
+                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())
+                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(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:
+            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())
+            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
+
+
+def return_default(
+    default=None,
+    exceptions=(
+        StopIteration,
+        exceptions.DbApplicationError,
+        exceptions.DbTableMissingError,
+        exceptions.DbColumnMissingError,
+        exceptions.DbTruncationError,
+        exceptions.DbObjectExistsError,
+    ),
+):
+    """
+    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(func)
+        def wrapper(self, *args, **kwds):
+            sp = self.tx.create_savepoint(cursor=self.cursor())
+            try:
+                result = func(self, *args, **kwds)
+                if result is None:
+                    result = default
+            except func.exceptions:
+                traceback.print_exc()
+                self.tx.rollback_savepoint(sp, cursor=self.cursor())
+                return default
+            self.tx.release_savepoint(sp, cursor=self.cursor())
+            return result
+
+        return wrapper
+
+    return decorator
+
+
+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 = 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())
+            data = {}
+            if "pk" in kwds:
+                data.update(kwds["pk"])
+            if "data" in kwds:
+                data.update(kwds["data"])
+            for i, arg in enumerate(args):
+                if isinstance(arg, dict):
+                    data.update(arg)
+            self.alter(data)
+            return func(self, *args, **kwds)
+        except exceptions.DbTableMissingError:
+            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, arg in enumerate(args):
+                if isinstance(arg, dict):
+                    data.update(arg)
+            self.create(data)
+            return func(self, *args, **kwds)
+
+    return wrapper