sqlengine-lite 2.2.0__py3-none-any.whl → 2.2.2__py3-none-any.whl

sqlengine/__init__.py

@@ -1,7 +1,11 @@
-from .core import sqlgen, types
-from .core.types import Schema, Primary
+from ._internal import sqlgen
+from ._internal import ConnectionManager
+from ._internal.types import Schema, Primary, register_type
 from .sqltable import SqlTableMixin
 
 __author__  = "suffermuffin"
 
-__all__ = ["types", "sqlgen", "Schema", "SqlTableMixin", "Primary"]
+__all__ = [
+    "sqlgen", "Schema", "SqlTableMixin",
+    "Primary", "ConnectionManager", "register_type"
+]

sqlengine/_internal/__init__.py

@@ -0,0 +1,4 @@
+from .statements import Select, Delete, Update
+from .connection_manager import ConnectionManager
+
+__all__ = ["Select", "Delete", "Update", "ConnectionManager"]

sqlengine/{core/connection.py → _internal/connection_manager.py}

@@ -6,6 +6,7 @@ from typing import overload, Literal, Sequence
 from contextlib import contextmanager
 
 from .types import SqlValue, SqlRow
+from ..exceptions import TransactionError, NestedTransactionError, OutsideTransactionError
 
 
 logger = logging.getLogger("sqlengine")
@@ -14,6 +15,15 @@ logger.setLevel(os.getenv("SQL_ENGINE_LOG_LEVEL", "WARNING").upper())
 
 class ConnectionManager:
 
+    """ 
+    Connection manager for sqlite3 
+    
+    Args:
+
+        database (str): database filename to connect to. If `":memory:"` is passed, then database will be set in memory.
+        **connection_params: Params to create connection with. Reference: https://docs.python.org/3/library/sqlite3.html#sqlite3.connect
+    """
+
     _trans : sqlite3.Connection
     _trans_cursor : sqlite3.Cursor
 
@@ -128,7 +138,7 @@ class ConnectionManager:
         Args:
             query (str): SQL query
             *args (tuple[SqlValue, ...]): Arguments to the execution
-            size (str): Number of rows to return
+            size (int): Number of rows to return
 
         Returns:
             rows (list[SqlRow]): list of `size` rows
@@ -172,7 +182,7 @@ class ConnectionManager:
     def open(self) -> None:
         """ Opens unmanaged transaction """
         if self.in_transaction():
-            raise RuntimeError("Can't re-open existing connection")
+            raise NestedTransactionError("Can't re-open existing connection")
         
         self._trans = self.connect()
         self._trans_cursor = self._trans.cursor()
@@ -184,24 +194,28 @@ class ConnectionManager:
             return
         
         if self._is_managed_transaction:
-            raise RuntimeError("Can't manually close managed transaction")
+            raise TransactionError("Can't manually close managed transaction")
         
-        self._trans_cursor.close()
-        self._trans.close()
-        del(self._trans_cursor)
-        del(self._trans)
+        try:
+            self._trans_cursor.close()
+            self._trans.close()
+        except sqlite3.ProgrammingError as e:
+            raise TransactionError("Can't close connection properly") from e
+        finally:
+            del(self._trans_cursor)
+            del(self._trans)
 
 
     def commit(self) -> None:
         if not self.in_transaction():
-            raise RuntimeError("Can't commit outside transaction mode")
+            raise OutsideTransactionError("Can't commit outside transaction mode")
         
         self._trans.commit()
 
 
     def rollback(self) -> None:
         if not self.in_transaction():
-            raise RuntimeError("Can't rollback outside transaction mode")
+            raise OutsideTransactionError("Can't rollback outside transaction mode")
         
         self._trans.rollback()
     
@@ -242,7 +256,7 @@ class ConnectionManager:
     def tx_conn(self) -> sqlite3.Connection:
         """ Gives access to connection while in transaction """
         if not self.in_transaction():
-            raise RuntimeError("`tx_conn` is not available outside the transaction mode")
+            raise OutsideTransactionError("`tx_conn` is not available outside the transaction mode")
         return self._trans
     
     
@@ -250,6 +264,6 @@ class ConnectionManager:
     def tx_cursor(self) -> sqlite3.Cursor:
         """ Gives access to connection cursor while in transaction """
         if not self.in_transaction():
-            raise RuntimeError("`tx_cursor` is not available outside the transaction mode")
+            raise OutsideTransactionError("`tx_cursor` is not available outside the transaction mode")
         return self._trans_cursor
 

sqlengine/{core → _internal}/statements.py

@@ -2,10 +2,11 @@ from typing import Sequence, Literal, Generator, Self
 from abc    import ABC, abstractmethod
 
 from . import sqlgen as sql
-from .connection import ConnectionManager
+from .connection_manager import ConnectionManager
 
 from .types import SqlValue, SqlRow, Schema
 from .repr  import to_html
+from ..exceptions import SqlEngineError, OutsideTransactionError
 
 
 class Where[T : "Statement"]:
@@ -31,39 +32,46 @@ class Where[T : "Statement"]:
 
     
     def op(self, column : str, value : SqlValue, operator : str) -> Self:
+        """ Adds operator to the where clause """
         self._clause.append(f"{column} {operator} ?")
         self._args.append(value)
         return self
 
     
     def join(self, lop : str = "AND") -> Self:
-        """ Joins previous expression via logical operator `lop` """
+        """ Join previous expression via logical operator `lop` """
         joined = f" {lop} ".join(self._clause)
         self._clause = [f"({joined})"]
         return self
 
     
     def eq(self, column : str, value : SqlValue) -> Self:
+        """ Add `column = value` to the where clause """
         return self.op(column, value, "=")
 
     
     def neq(self, column : str, value : SqlValue) -> Self:
+        """ Add `column != value` to the where clause """
         return self.op(column, value, "!=")
     
     
     def gt(self, column : str, value : SqlValue) -> Self:
+        """ Add `column > value` to the where clause """
         return self.op(column, value, ">")
     
     
     def gte(self, column : str, value : SqlValue) -> Self:
+        """ Add `column >= value` to the where clause """
         return self.op(column, value, ">=")
     
     
     def lt(self, column : str, value : SqlValue) -> Self:
+        """ Add `column < value` to the where clause """
         return self.op(column, value, "<")
     
     
     def lte(self, column : str, value : SqlValue) -> Self:
+        """ Add `column <= value` to the where clause """
         return self.op(column, value, "<=")
     
     
@@ -76,12 +84,13 @@ class Where[T : "Statement"]:
     
     
     def is_null(self, column : str) -> Self:
+        """ Add `column IS NULL` to the where clause """
         self._clause.append(f"{column} IS NULL")
         return self
     
     
     def inverted(self) -> Self:
-        """ Invert last where clause with NOT """
+        """ Invert previous where clauses with `NOT` """
         self._clause[-1] = f"NOT ({self._clause[-1]})"
         return self
     
@@ -127,14 +136,16 @@ class Where[T : "Statement"]:
         return self._statement.__repr__()
 
     
+    def __iter__(self):
+        if not isinstance(self._statement, Select):
+            raise SqlEngineError("Can iterate only over `Select` statements")
+        return iter(self._statement)
+    
+
     def _repr_html_(self) -> str | None:
         if isinstance(self._statement, Select):
             return self._statement._repr_html_()
         return None
-    
-    
-    def __len__(self) -> int:
-        return len(self._args)
 
 
 class Statement(ABC):
@@ -146,7 +157,7 @@ class Statement(ABC):
 
         self._tableschema = tableschema
         self._connection  = connection
-        self._where: Where[Self] = Where(self)
+        self._where = Where(self)
 
         self._custom_query : str | None = None
         self._custom_args  : tuple[SqlValue, ...] = ()
@@ -206,6 +217,7 @@ class Statement(ABC):
 class MutationalStatement(Statement, ABC):
     
     def execute(self) -> None:
+        """ Execute built statement """
         query, args = self.build()
         self._connection.execute(query, *args)
 
@@ -222,66 +234,74 @@ class Select(Statement):
 
 
     def __call__(self, *columns : str) -> Self:
+        """ Shortcut to columns selector """
         return self.columns(*columns)
     
 
     def columns(self, *columns : str) -> Self:
-        """ Column selector """
+        """ Columns selector """
         self._columns.extend(columns)
         return self
     
     
     def aggregate(self, by : Literal['COUNT', 'SUM', 'AVG', 'MIN', 'MAX']) -> Self:
-        
+        """ Aggregate by provided method """
         if self._aggregate:
-            raise ValueError("Can't aggregate columns multiple times")
+            raise SqlEngineError("Can't aggregate columns multiple times")
         
         self._aggregate = by
         return self
 
     
     def order_by(self, column : str, ascending : bool = True) -> Self:
+        """ Orders returned rows by provided column """
         order = "ASC" if ascending else "DESC"
         self._order_by.append(f"{column} {order}")
         return self
     
 
     def limit(self, n : int) -> Self:
+        """ Limit number of returned rows """
         self._limit = n
         return self
     
 
     def fetchone(self) -> SqlRow:
+        """ Fetch first row """
         query, args = self.build()
         return self._connection.fetchone(query, *args)
         
 
     def fetchmany(self, size : int = 1) -> list[SqlRow]:
+        """ Fetch first `size` rows """
         query, args = self.build()
         return self._connection.fetchmany(query, *args, size=size)
 
     
     def fetchall(self) -> list[SqlRow]:
+        """ Fetch all rows """
         query, args = self.build()
         return self._connection.fetchall(query, *args)
     
 
     def fetchmany_iterator(self, batch_size: int) -> Generator[list[SqlRow], None, None]:
         """
-        Yields all rows in batches, each batch in its own transaction.
+        Yields all rows in batches within a single transaction.
         
         Args:
             batch_size (int): Size of each batch
 
-        Examples:
+        Example:
 
-            >>> with table.transaction():
-            >>>     for batch in table.select.where.gt("Age", 30).then.fetchmany_iterator(1000):
-            >>>         process_batch(batch)
+        ```python
+        with table.transaction():
+            for batch in table.select.where.gt("Age", 30).then.fetchmany_iterator(1000):
+                process_batch(batch)
+        ```
         """
         if not self._connection.in_transaction():
-            raise RuntimeError("To use the `fetchall_iterator()` method you have \
-                    to keep open the transaction of the table with `transaction()` manager")
+            raise OutsideTransactionError("To use the `fetchall_iterator()` method you have "
+                    "to keep open the transaction of the table")
         
         query, exec_args = self.build()
 
@@ -293,11 +313,21 @@ class Select(Statement):
 
     
     def __iter__(self) -> Generator[SqlRow, None, None]:
-        """ Select statement rows iterator """
+        """ 
+        Select statement rows iterator
+
+        Example:
+        
+        ```python
+        with table.transaction():
+            for row in table.select.where.gt("Age", 30):
+                process_row(row)
+        ```
+        """
         
         if not self._connection.in_transaction():
-            raise RuntimeError("To use the __iter__ method you have \
-                to keep open the transaction of the table with `transaction()` manager")
+            raise OutsideTransactionError("To use the `__iter__` method you have "
+                "to keep open the transaction of the table")
         
         query, exec_args = self.build()
         
@@ -360,7 +390,7 @@ class Delete(MutationalStatement):
     def _build(self, where_clause : str, *args : SqlValue) -> tuple[str, tuple[SqlValue, ...]]:
         
         if not where_clause:
-            raise ValueError("Delete statement must have a where clause")
+            raise SqlEngineError("Delete statement must have a where clause")
         
         query = sql.delete_rows(self._tableschema["tablename"], where_clause)
         return query, args
@@ -379,6 +409,7 @@ class Update(MutationalStatement):
 
     
     def __call__(self, column : str, value : SqlValue) -> Self:
+        """ Shortcut to set value to a column """
         return self.set(column, value)
 
 

sqlengine/{core → _internal}/types.py

@@ -12,15 +12,16 @@ class CustomType(Protocol):
         ...
 
 
-type SqlValue = str | int | float | bytes | None | CustomType
-type SqlRow   = tuple[SqlValue, ...]
-type SqlType  = type[str | int | float | bytes | CustomType]
+type SqlValue   = str | int | float | bytes | None | CustomType
+type SqlRow     = tuple[SqlValue, ...]
+type SqlType    = type[str | int | float | bytes | CustomType]
+type ColumnType = SqlType | str | UnionType
 
 
 class Schema(TypedDict):
     tablename : str
     columns   : list[str]
-    types     : list[SqlType | str]
+    types     : list[ColumnType]
     primary   : list[str]
 
 
@@ -41,7 +42,7 @@ _TYPES_MAP : dict[type | UnionType, str] = {
 }
 
 
-def is_custom_type(type_: SqlType) -> TypeGuard[type[CustomType]]:
+def is_custom_type(type_: SqlType | UnionType) -> TypeGuard[type[CustomType]]:
     return (
         type_ not in (str, int, float, bytes)
         and isinstance(type_, type)
@@ -52,7 +53,7 @@ def is_custom_type(type_: SqlType) -> TypeGuard[type[CustomType]]:
 
 def register_type(cls : type[CustomType], type_name : str | None = None) -> None:
     """ 
-    Register custom type to be able to store it in tables 
+    Register custom type into sqlite3 to be able to store it in tables
     
     Args:
         cls (CustomType): Class that implements `from_sql(cls, sql : bytes) -> Self` and `
@@ -65,7 +66,7 @@ def register_type(cls : type[CustomType], type_name : str | None = None) -> None
     sqlite3.register_converter(type_name, cls.from_sql)
 
 
-def pytype_to_sqltype(type_ : type) -> str:
+def pytype_to_sqltype(type_ : type | UnionType) -> str:
     """ Converts python type to sql type """
     if type_ not in _TYPES_MAP:
         raise TypeError(f"{type_} is not natively supported by sqlite3")
@@ -73,7 +74,7 @@ def pytype_to_sqltype(type_ : type) -> str:
     return _TYPES_MAP[type_]
 
 
-def register_resolve_types(types : list[SqlType | str], **connection_params) -> tuple[list[str], dict[str, Any]]:
+def register_resolve_types(types : list[ColumnType], **connection_params) -> tuple[list[str], dict[str, Any]]:
     """ Converts py types to sql types, registers custom types, resolves type names, updates connection params """
 
     resolved : list[str] = []

sqlengine/exceptions.py

@@ -0,0 +1,20 @@
+
+class SqlEngineError(Exception):
+    """ Errors linked to sqlengine module """
+    pass
+
+class TransactionError(SqlEngineError):
+    """ Errors within transactions """
+    pass
+
+class OutsideTransactionError(TransactionError):
+    """ Errors of prohibited outside tranasctions operations """
+    pass
+
+class NestedTransactionError(TransactionError):
+    """ Errors of nested transaction operations """
+    pass
+
+class TableDeclarationError(SqlEngineError):
+    """ Errors of table declaration """
+    pass

sqlengine/schema.py

@@ -3,7 +3,7 @@ import sqlite3
 from typing import overload
 
 from .sqltable import SqlTableMixin
-from .core.types import Schema
+from ._internal.types import Schema
 
 
 def get_database_tablenames(database : str, cursor : sqlite3.Cursor | None = None) -> list[str]:
@@ -62,15 +62,9 @@ def get_database_schemas(database : str) -> list[Schema]:
         cursor = conn.cursor()
         names  = get_database_tablenames(database, cursor)
         
-        schemas : list[Schema] = []
+        schemas = (get_table_schema(database, table_name, cursor) for table_name in names)
         
-        for tablename in names:
-            schema = get_table_schema(database, tablename, cursor)
-            
-            if schema:
-                schemas.append(schema)
-
-    return schemas
+    return [sh for sh in schemas if sh]
 
 
 def table_from_schema(database : str, schema : Schema, **kwargs) -> SqlTableMixin: