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

velocity/db/core/result.py

@@ -1,16 +1,17 @@
 import datetime
-from velocity.misc.format import to_json
 import decimal
+from velocity.misc.format import to_json
 
 
-class Result(object):
+class Result:
+    """
+    Wraps a database cursor to provide various convenience transformations
+    (dict, list, tuple, etc.) and helps iterate over query results.
+    """
+
     def __init__(self, cursor=None, tx=None, sql=None, params=None):
         self._cursor = cursor
-        if hasattr(cursor, "description") and cursor.description:
-            self._headers = [x[0].lower() for x in cursor.description]
-        else:
-            self._headers = []
-        self.as_dict()
+        self._headers = [x[0].lower() for x in getattr(cursor, "description", []) or []]
         self.__as_strings = False
         self.__enumerate = False
         self.__count = -1
@@ -18,32 +19,7 @@ class Result(object):
         self.__tx = tx
         self.__sql = sql
         self.__params = params
-
-    @property
-    def headers(self):
-        if not self._headers:
-            if self._cursor and hasattr(self._cursor, "description"):
-                self._headers = [x[0].lower() for x in self._cursor.description]
-        return self._headers
-
-    @property
-    def columns(self):
-        if not self.__columns:
-            if self._cursor and hasattr(self._cursor, "description"):
-                for column in self._cursor.description:
-                    data = {
-                        "type_name": self.__tx.pg_types[column.type_code],
-                        # TBD This can be implemented if needed but turning off
-                        # since it is not complete set of all codes and could raise
-                        # exception
-                        #'pytype': types[self.__tx.pg_types[column.type_code]]
-                    }
-                    for key in dir(column):
-                        if "__" in key:
-                            continue
-                        data[key] = getattr(column, key)
-                    self.__columns[column.name] = data
-        return self.__columns
+        self.transform = lambda row: dict(zip(self.headers, row))  # Default transform
 
     def __str__(self):
         return repr(self.all())
@@ -56,6 +32,9 @@ class Result(object):
             self.close()
 
     def __next__(self):
+        """
+        Iterator interface to retrieve the next row.
+        """
         if self._cursor:
             row = self._cursor.fetchone()
             if row:
@@ -64,11 +43,13 @@ class Result(object):
                 if self.__enumerate:
                     self.__count += 1
                     return (self.__count, self.transform(row))
-                else:
-                    return self.transform(row)
+                return self.transform(row)
         raise StopIteration
 
     def batch(self, qty=1):
+        """
+        Yields lists (batches) of rows with size = qty until no rows remain.
+        """
         results = []
         while True:
             try:
@@ -76,14 +57,15 @@ class Result(object):
             except StopIteration:
                 if results:
                     yield results
-                    results = []
-                    continue
-                raise
+                break
             if len(results) == qty:
                 yield results
                 results = []
 
     def all(self):
+        """
+        Retrieves all rows at once into a list.
+        """
         results = []
         while True:
             try:
@@ -95,62 +77,124 @@ class Result(object):
     def __iter__(self):
         return self
 
+    @property
+    def headers(self):
+        """
+        Retrieves column headers from the cursor if not already set.
+        """
+        if not self._headers and self._cursor and hasattr(self._cursor, "description"):
+            self._headers = [x[0].lower() for x in self._cursor.description]
+        return self._headers
+
+    @property
+    def columns(self):
+        """
+        Retrieves detailed column information from the cursor.
+        """
+        if not self.__columns and self._cursor and hasattr(self._cursor, "description"):
+            for column in self._cursor.description:
+                data = {
+                    "type_name": self.__tx.pg_types[column.type_code],
+                }
+                for key in dir(column):
+                    if "__" not in key:
+                        data[key] = getattr(column, key)
+                self.__columns[column.name] = data
+        return self.__columns
+
     @property
     def cursor(self):
         return self._cursor
 
     def close(self):
-        self._cursor.close()
+        """
+        Closes the underlying cursor if it exists.
+        """
+        if self._cursor:
+            self._cursor.close()
 
     def as_dict(self):
-        self.transform = lambda row: dict(list(zip(self.headers, row)))
+        """
+        Transform each row into a dictionary keyed by column names.
+        """
+        self.transform = lambda row: dict(zip(self.headers, row))
         return self
 
     def as_json(self):
-        self.transform = lambda row: to_json(dict(list(zip(self.headers, row))))
+        """
+        Transform each row into JSON (string).
+        """
+        self.transform = lambda row: to_json(dict(zip(self.headers, row)))
         return self
 
     def as_named_tuple(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_list(self):
+        """
+        Transform each row into a list of values.
+        """
         self.transform = lambda row: list(row)
         return self
 
     def as_tuple(self):
+        """
+        Transform each row into a tuple of values.
+        """
         self.transform = lambda row: row
         return self
 
     def as_simple_list(self, pos=0):
+        """
+        Transform each row into the single value at position `pos`.
+        """
         self.transform = lambda row: row[pos]
         return self
 
     def strings(self, as_strings=True):
+        """
+        Indicate whether retrieved rows should be coerced to string form.
+        """
         self.__as_strings = as_strings
         return self
 
     def scalar(self, default=None):
+        """
+        Return the first column of the first row, or `default` if no rows.
+        """
         if not self._cursor:
             return None
         val = self._cursor.fetchone()
+        # Drain any remaining rows.
         self._cursor.fetchall()
         return val[0] if val else default
 
     def one(self, default=None):
+        """
+        Return the first row or `default` if no rows.
+        """
         try:
-            return next(self)
-        except StopIteration:
-            return default
-        finally:
+            row = next(self)
+            # Drain remaining.
             if self._cursor:
                 self._cursor.fetchall()
+            return row
+        except StopIteration:
+            return default
 
-    def get_table_data(self, headers=True, strings=True):
+    def get_table_data(self, headers=True):
+        """
+        Builds a two-dimensional list: first row is column headers, subsequent rows are data.
+        """
         self.as_list()
         rows = []
         for row in self:
-            rows.append(["" if x is None else str(x) for x in row])
+            row = ["" if x is None else str(x) for x in row]
+            rows.append(row)
         if isinstance(headers, list):
             rows.insert(0, [x.replace("_", " ").title() for x in headers])
         elif headers:
@@ -158,11 +202,12 @@ class Result(object):
         return rows
 
     def enum(self):
+        """
+        Yields each row as (row_index, transformed_row).
+        """
         self.__enumerate = True
         return self
 
-    enumerate = enum
-
     @property
     def sql(self):
         return self.__sql

velocity/db/core/row.py

@@ -1,11 +1,16 @@
 import pprint
 
 
-class Row(object):
+class Row:
+    """
+    Represents a single row in a given table, identified by a primary key or a dictionary of conditions.
+    """
+
     def __init__(self, table, key, lock=None):
         if isinstance(table, str):
-            raise Exception("table parameter of row class must `table` instance")
+            raise Exception("Table parameter must be a `table` instance.")
         self.table = table
+
         if isinstance(key, (dict, Row)):
             pk = {}
             try:
@@ -15,6 +20,7 @@ class Row(object):
                 pk = key
         else:
             pk = {self.key_cols[0]: key}
+
         self.pk = pk
         self.cache = key
         if lock:
@@ -36,12 +42,12 @@ class Row(object):
 
     def __setitem__(self, key, val):
         if key in self.pk:
-            raise Exception("Can't update a primary key, idiot!")
+            raise Exception("Cannot update a primary key.")
         self.table.upsert({key: val}, self.pk)
 
     def __delitem__(self, key):
         if key in self.pk:
-            raise Exception("Can't delete a primary key, idiot!")
+            raise Exception("Cannot delete a primary key.")
         if key not in self:
             return
         self[key] = None
@@ -50,60 +56,64 @@ class Row(object):
         return key.lower() in [x.lower() for x in self.keys()]
 
     def clear(self):
+        """
+        Deletes this row from the database.
+        """
         self.table.delete(where=self.pk)
         return self
 
     def keys(self):
-        return self.table.sys_columns
+        """
+        Returns the column names in the table (including sys_ columns).
+        """
+        return self.table.sys_columns()
 
     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()
         if args:
-            values = []
-            for arg in args:
-                values.append(d[arg])
-            return values
-        else:
-            return list(d.values())
+            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())
 
     def get(self, key, failobj=None):
         data = self[key]
-        if data == None:
+        if data is None:
             return failobj
         return data
 
     def setdefault(self, key, default=None):
         data = self[key]
-        if data == None:
+        if data is None:
             self[key] = default
             return default
         return data
 
-    def update(self, dict=None, **kwds):
+    def update(self, dict_=None, **kwds):
+        """
+        Updates columns in this row.
+        """
         data = {}
-        if dict:
-            data.update(dict)
+        if dict_:
+            data.update(dict_)
         if kwds:
             data.update(kwds)
         if data:
             self.table.upsert(data, self.pk)
         return self
 
-    def iterkeys(self):
-        return list(self.keys())
-
-    def itervalues(self):
-        return list(self.values())
-
-    def iteritems(self):
-        return list(self.items())
-
     def __cmp__(self, other):
-        # zero == same (not less than or greater than 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())
@@ -117,18 +127,18 @@ class Row(object):
         return diff
 
     def __bool__(self):
-        return bool(self.__len__())
+        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.
+        """
         old = self.to_dict()
-        for key in list(old.keys()):
-            if "sys_" in key:
-                old.pop(key)
+        for k in list(old.keys()):
+            if "sys_" in k:
+                old.pop(k)
         return self.table.new(old, lock=lock)
 
-    # ================================================================
-    # This stuff is not implemented
-
     def pop(self):
         raise NotImplementedError
 
@@ -152,9 +162,15 @@ class Row(object):
         raise NotImplementedError
 
     def to_dict(self):
+        """
+        Returns the row as a dictionary via a SELECT on self.pk.
+        """
         return self.table.select(where=self.pk).as_dict().one()
 
     def extract(self, *args):
+        """
+        Returns a dict containing only the specified columns from this row.
+        """
         data = {}
         for key in args:
             if isinstance(key, (tuple, list)):
@@ -165,54 +181,73 @@ class Row(object):
 
     @property
     def key_cols(self):
-        # result = self.execute(*self.sql.primary_keys(self.tablename))
-        # return [x[0] for x in result.as_tuple()]
+        """
+        Returns the primary key columns for the underlying table, defaulting to ['sys_id'] if missing.
+        """
         return ["sys_id"]
 
     def split(self):
+        """
+        Splits data from PK references into (non_sys_data, pk).
+        """
         old = self.to_dict()
-        for key in list(old.keys()):
-            if "sys_" in key:
-                old.pop(key)
+        for k in list(old.keys()):
+            if "sys_" in k:
+                old.pop(k)
         return old, self.pk
 
     @property
     def data(self):
+        """
+        Returns the 'non-sys' data dictionary for this row.
+        """
         return self.split()[0]
 
     def row(self, key, lock=None):
-        tx = self.table.tx
+        """
+        Retrieve a row from a foreign key column if present. E.g. row.row('fk_column').
+        """
         value = self[key]
         if value is None:
             return None
         fk = self.table.foreign_key_info(key)
         if not fk:
             raise Exception(
-                "Column `{}` is not a foreign key in `{}`".format(key, self.table.name)
+                f"Column `{key}` is not a foreign key in `{self.table.name}`"
             )
-        return tx.Row(fk["referenced_table_name"], value, lock=lock)
+        return self.table.tx.Row(fk["referenced_table_name"], value, lock=lock)
 
     def match(self, other):
-        for key in other:
-            if self[key] != other[key]:
+        """
+        Returns True if the columns in 'other' match this row's columns for the same keys.
+        """
+        for k in other:
+            if self[k] != other[k]:
                 return False
         return True
 
     def touch(self):
+        """
+        Update sys_modified to current timestamp.
+        """
         self["sys_modified"] = "@@CURRENT_TIMESTAMP"
         return self
 
     delete = clear
 
     def lock(self):
+        """
+        SELECT ... FOR UPDATE on this row.
+        """
         self.table.select(where=self.pk, lock=True)
         return self
 
     def notBlank(self, key, failobj=None):
+        """
+        Returns the value if it is not blank, else failobj.
+        """
         data = self[key]
-        if not data:
-            return failobj
-        return data
+        return data if data else failobj
 
     getBlank = notBlank
 

velocity/db/core/sequence.py

@@ -1,41 +1,131 @@
-class Sequence(object):
+import psycopg2
+
+
+class Sequence:
+    """
+    Represents a database sequence in PostgreSQL.
+    """
+
     def __init__(self, tx, name, start=1000):
         self.tx = tx
         self.name = name.lower()
         self.sql = tx.engine.sql
         self.start = start
 
-        self.create()
-
     def __str__(self):
-        return """
-    Sequence: %s
-        """ % (
-            self.name
-        )
-
-    def create(self):
-        sql, vals = (
-            "CREATE SEQUENCE IF NOT EXISTS {} START {};".format(self.name, self.start),
-            tuple(),
-        )
+        return f"Sequence: {self.name} (current val: {self.current()})"
+
+    def create(self, start=None):
+        """
+        Creates the sequence if it does not already exist.
+        """
+        val = start if start is not None else self.start
+        sql = f"CREATE SEQUENCE IF NOT EXISTS {self.name} START {val};"
+        vals = ()
         return self.tx.execute(sql, vals)
 
     def next(self):
-        sql, vals = "SELECT nextval('{}');".format(self.name), tuple()
+        """
+        Retrieves the next value in this sequence.
+        """
+        sql = f"SELECT nextval('{self.name}');"
+        vals = ()
         return self.tx.execute(sql, vals).scalar()
 
     def current(self):
-        sql, vals = "SELECT currval('{}');".format(self.name), tuple()
+        """
+        Retrieves the current value of the sequence.
+        """
+        sql = f"SELECT currval('{self.name}');"
+        vals = ()
         return self.tx.execute(sql, vals).scalar()
 
-    def reset(self, start=None):
-        sql, vals = (
-            "ALTER SEQUENCE {} RESTART WITH {};".format(self.name, start or self.start),
-            tuple(),
-        )
+    def safe_current(self):
+        """
+        Returns the current value of the sequence if one has been generated
+        in this session, or None otherwise.
+        """
+        sql = f"SELECT currval('{self.name}');"
+        try:
+            return self.tx.execute(sql, ()).scalar()
+        except psycopg2.ProgrammingError:
+            return None
+
+    def set_value(self, start=None):
+        """
+        Resets the sequence to the given start value (defaults to initial `self.start`).
+        """
+        val = start if start is not None else self.start
+        sql = f"ALTER SEQUENCE {self.name} RESTART WITH {val};"
+        vals = ()
         return self.tx.execute(sql, vals).scalar()
 
+    reset = set_value
+
     def drop(self):
-        sql, vals = "DROP SEQUENCE IF EXISTS {};".format(self.name), tuple()
+        """
+        Drops the sequence if it exists.
+        """
+        sql = f"DROP SEQUENCE IF EXISTS {self.name};"
+        vals = ()
         return self.tx.execute(sql, vals)
+
+    def exists(self):
+        """
+        Checks whether the sequence exists in the database.
+        Returns True if it exists, False otherwise.
+        """
+        sql = f"""
+            SELECT EXISTS (
+                SELECT 1
+                FROM pg_class
+                WHERE relname = '{self.name}'
+                AND relkind = 'S'
+            );
+        """
+        return self.tx.execute(sql, ()).scalar()
+
+    def configure(self, increment=None, minvalue=None, maxvalue=None, cycle=None):
+        """
+        Alter the sequence with the given settings (any of which may be None to skip).
+        """
+        parts = []
+        if increment is not None:
+            parts.append(f"INCREMENT BY {increment}")
+        if minvalue is not None:
+            parts.append(f"MINVALUE {minvalue}")
+        if maxvalue is not None:
+            parts.append(f"MAXVALUE {maxvalue}")
+        if cycle is True:
+            parts.append("CYCLE")
+        elif cycle is False:
+            parts.append("NO CYCLE")
+
+        if not parts:
+            return None  # no-op
+
+        sql = f"ALTER SEQUENCE {self.name} {' '.join(parts)};"
+        return self.tx.execute(sql, ()).scalar()
+
+    def info(self):
+        """
+        Returns a dictionary of metadata about the sequence, or None if it doesn't exist.
+        """
+        sql = f"""
+            SELECT *
+            FROM pg_sequences
+            WHERE schemaname = current_schema()
+            AND sequencename = '{self.name}'
+        """
+        row = self.tx.execute(sql, ()).fetchone()
+        if row is None:
+            return None
+        return dict(row)
+
+    def rename(self, new_name):
+        """
+        Renames this sequence to `new_name`. Updates self.name to the new name.
+        """
+        sql = f"ALTER SEQUENCE {self.name} RENAME TO {new_name.lower()};"
+        self.tx.execute(sql, ())
+        self.name = new_name.lower()