sqlengine-lite 2.1.1__py3-none-any.whl → 2.2.1__py3-none-any.whl

sqlengine/__init__.py

@@ -1,7 +1,11 @@
-from .utils import sqlgen, types
-from .utils.types import Schema
+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"]
+__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/_internal/connection_manager.py

@@ -0,0 +1,266 @@
+import sqlite3
+import logging
+import os
+
+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")
+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 and you will have to
+            create table manually with `create_table()` method inside `transaction()` block.
+        **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
+
+    def __init__(self, database : str, **connection_params) -> None:
+        
+        self.database = database
+        self.connection_params = connection_params
+
+        self._is_managed_transaction = False
+
+    
+    @overload
+    def _fetch(self, query : str, args : SqlRow, 
+               method : Literal["fetchone"]) -> SqlRow: ...
+    @overload
+    def _fetch(self, query : str, args : SqlRow, 
+               method : Literal["fetchall"]) -> list[SqlRow]: ...
+
+    def _fetch(
+            self, 
+            query  : str, 
+            args   : SqlRow = (), 
+            method : Literal["fetchone", "fetchall"] = "fetchall"
+        ) -> SqlRow | list[SqlRow]:
+        
+        logger.debug(f"{self.database}: {query} {args}")
+
+        if self.in_transaction():
+            self._trans_cursor.execute(query, args)
+            return getattr(self._trans_cursor, method)()
+
+        with self.connect() as conn:
+            cursor = conn.cursor()
+            cursor.execute(query, args)
+            return getattr(cursor, method)()
+
+    
+    @overload    
+    def _execute(self, query : str, args : tuple[SqlValue, ...], method : Literal["execute"]) -> None: ...
+    @overload
+    def _execute(self, query : str, args : Sequence[SqlRow], method : Literal["executemany"]) -> None: ...
+    
+    def _execute(
+            self, 
+            query  : str,
+            args   : tuple[SqlValue, ...] | Sequence[SqlRow] = (),
+            method : Literal["execute", "executemany"]       = "execute"
+        ) -> None: 
+        """
+        Shortcut to connect() -> execute[<many>]() -> commit() for single operations. 
+        Can be used in transaction using `transaction()` manager.
+
+        Args:
+            query (str): SQL query to execute on SQLite3 DB
+            *args (Any): Arguments to the execution
+            method (str): "execute" or "executemany"
+        """
+        logger.debug(f"{self.database}: {query} {args}")
+
+        if self.in_transaction():
+            getattr(self._trans_cursor, method)(query, args)
+            return
+        
+        with self.connect() as conn:
+            cursor = conn.cursor()
+            getattr(cursor, method)(query, args)
+            conn.commit()
+
+
+    def execute(self, query : str, *args : SqlValue) -> None:
+        """
+        Shortcut to connect() -> execute() -> commit() for single operations. 
+        Can be used in transaction using `transaction()` manager.
+
+        Args:
+            query (str): SQL query to execute on SQLite3 DB
+            *args (tuple[SqlValue, ...]): Arguments to the execution
+        """
+        return self._execute(query, args, method="execute")
+    
+    
+    def executemany(self, query : str, args : Sequence[SqlRow]) -> None:
+        """
+        Shortcut to connect() -> executemany() -> commit() for single operations. 
+        Can be used in transaction using `transaction()` manager.
+
+        Args:
+            query (str): SQL query to execute on SQLite3 DB
+            args (list[tuple[SqlValue, ...]]): Arguments to the execution
+        """
+        return self._execute(query, args, method="executemany")
+
+
+    def fetchone(self, query : str, *args : SqlValue) -> SqlRow:
+        """
+        Fetch first row based on `query`
+
+        Args:
+            query (str): SQL query
+            *args (tuple[SqlValue, ...]): Arguments to the execution
+
+        Returns:
+            row (SqlRow): Single row
+        """
+        return self._fetch(query, args, method="fetchone")
+    
+
+    def fetchmany(self, query : str, *args : SqlValue, size : int = 1) -> list[SqlRow]:
+        """
+        Fetch first `size` rows based on `query`
+
+        Args:
+            query (str): SQL query
+            *args (tuple[SqlValue, ...]): Arguments to the execution
+            size (str): Number of rows to return
+
+        Returns:
+            rows (list[SqlRow]): list of `size` rows
+        """
+        logger.debug(f"{self.database}: {query} {args}")
+
+        if self.in_transaction():
+            self._trans_cursor.execute(query, args)
+            return self._trans_cursor.fetchmany(size)
+
+        with self.connect() as conn:
+            cursor = conn.cursor()
+            cursor.execute(query, args)
+            return cursor.fetchmany(size)
+    
+
+    def fetchall(self, query : str, *args : SqlValue) -> list[SqlRow]:
+        """
+        Fetch all rows based on `query`
+
+        Args:
+            query (str): SQL query
+            *args (tuple[SqlValue, ...]): Arguments to the execution
+
+        Returns:
+            rows (list[SqlRow]): list of rows
+        """
+        return self._fetch(query, args, method="fetchall")
+
+    
+    def in_transaction(self) -> bool:
+        """ Returns True if instance is in transaction """
+        return hasattr(self, "_trans") and hasattr(self, "_trans_cursor")
+
+
+    def connect(self) -> sqlite3.Connection:
+        """ Shortcut to sqlite3 connection context manager """
+        return sqlite3.connect(self.database, **self.connection_params)
+    
+
+    def open(self) -> None:
+        """ Opens unmanaged transaction """
+        if self.in_transaction():
+            raise NestedTransactionError("Can't re-open existing connection")
+        
+        self._trans = self.connect()
+        self._trans_cursor = self._trans.cursor()
+
+    
+    def close(self) -> None:
+        """ Closes unmanaged transaction """
+        if not self.in_transaction():
+            return
+        
+        if self._is_managed_transaction:
+            raise TransactionError("Can't manually close managed transaction")
+        
+        self._trans_cursor.close()
+        self._trans.close()
+        del(self._trans_cursor)
+        del(self._trans)
+
+
+    def commit(self) -> None:
+        if not self.in_transaction():
+            raise OutsideTransactionError("Can't commit outside transaction mode")
+        
+        self._trans.commit()
+
+
+    def rollback(self) -> None:
+        if not self.in_transaction():
+            raise OutsideTransactionError("Can't rollback outside transaction mode")
+        
+        self._trans.rollback()
+    
+    
+    @contextmanager
+    def transaction(self, autocommit : bool = True):
+        """ 
+        Creates context manager to use class methods in transaction
+
+        Args:
+            autocommit (bool): If `True`, will commit changes at the end of transaction
+        """
+        
+        self.open()
+        self._is_managed_transaction = True
+        logger.debug(f"{self.database}: Transaction started")
+        
+        try:
+            yield
+
+        except Exception as e:
+            logger.error(f"{self.database}: Error while in transaction: {e}")
+            logger.debug(e, exc_info=True)
+            self._trans.rollback()
+            raise e
+        
+        else:
+            if autocommit:
+                self._trans.commit()
+
+        finally:
+            self._is_managed_transaction = False
+            self.close()
+            logger.debug(f"{self.database}: Transaction finished")
+    
+    
+    @property
+    def tx_conn(self) -> sqlite3.Connection:
+        """ Gives access to connection while in transaction """
+        if not self.in_transaction():
+            raise OutsideTransactionError("`tx_conn` is not available outside the transaction mode")
+        return self._trans
+    
+    
+    @property
+    def tx_cursor(self) -> sqlite3.Cursor:
+        """ Gives access to connection cursor while in transaction """
+        if not self.in_transaction():
+            raise OutsideTransactionError("`tx_cursor` is not available outside the transaction mode")
+        return self._trans_cursor
+

sqlengine/{utils → _internal}/repr.py

@@ -1,12 +1,5 @@
-from __future__ import annotations
 from html import escape
-from typing import Sequence, TYPE_CHECKING
-
-import csv
-
-if TYPE_CHECKING:
-    from .statements import Select, Where
-    from ..sqltable  import SqlTableMixin
+from typing import Sequence
 
 from .types import SqlRow
 
@@ -57,25 +50,3 @@ def to_html(tablename : str, columns : list[str], repr_rows : Sequence[SqlRow],
 
     return "".join(html)
 
-
-def to_csv(builder : Select | Where[Select] | SqlTableMixin, path : str) -> None:
-    
-    from ..sqltable  import SqlTableMixin
-    from .statements import Where
-
-    match builder:
-        case Where():
-            builder = builder.then
-        case SqlTableMixin():
-            builder = builder.select
-
-    if builder._aggregate:
-        raise AssertionError("Aggregated queries are not supported")
-    
-    columns   = builder._table.columns if len(builder._columns) == 0 or "*" in builder._columns else builder._columns
-    repr_rows = builder.fetchall()
-
-    with open(path, 'w', newline='') as file:
-        writer = csv.writer(file)
-        writer.writerow(columns)
-        writer.writerows(repr_rows)

sqlengine/{utils → _internal}/sqlgen.py

@@ -4,9 +4,7 @@ from typing import Sequence
 def format_list(items : Sequence | set, brackets : bool = True) -> str:
     """ Formats list into `(item1, item2, ...)` format """
     items_str = ', '.join([str(i) for i in items])
-    if not brackets: 
-        return items_str
-    return f'({items_str})'
+    return f'({items_str})' if brackets else items_str
 
 
 def create_table(
@@ -40,7 +38,7 @@ def values_placeholder(n_values : int) -> str:
 def bulk_placeholder(n_values : int, n_rows : int) -> str:
     """ Creates placeholders `(?, ?, ..), (?, ?, ..), ...` for each row """
     place_holder = values_placeholder(n_values)
-    return f"{format_list([place_holder]*n_rows, False)}"
+    return format_list([place_holder]*n_rows, False)
 
 
 def insert(tablename : str, columns : list[str], values : str) -> str:

sqlengine/{utils → _internal}/statements.py

@@ -1,20 +1,17 @@
-from __future__ import annotations
-from typing     import Sequence, Literal, Generator, Self, TYPE_CHECKING
-from abc        import ABC, abstractmethod
-
-if TYPE_CHECKING:
-    from .statements import Statement 
-    from ..sqltable  import SqlTableMixin
+from typing import Sequence, Literal, Generator, Self
+from abc    import ABC, abstractmethod
 
 from . import sqlgen as sql
-from .types import SqlValue, SqlRow
+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]:
+class Where[T : "Statement"]:
     """ Where clause build helper """
     
-    
     def __init__(self, statement : T):
         
         self._statement = statement
@@ -146,12 +143,11 @@ class Statement(ABC):
     Statement object that helps you build queries and execute them
     """
 
-    __command__ : Literal["SELECT", "INSERT", "UPDATE", "DELETE"]
+    def __init__(self, connection : ConnectionManager, tableschema : Schema) -> None:
 
-    def __init__(self, table : SqlTableMixin) -> None:
-
-        self._table = table
-        self._where: Where[Self] = Where(self)
+        self._tableschema = tableschema
+        self._connection  = connection
+        self._where = Where(self)
 
         self._custom_query : str | None = None
         self._custom_args  : tuple[SqlValue, ...] = ()
@@ -175,7 +171,7 @@ class Statement(ABC):
     
 
     def reset(self) -> None:
-        """ Resets statement to reuse object """
+        """ Reset statement to reuse the object """
         self._where.reset()
         self._custom_query = None
         self._custom_args = ()
@@ -209,18 +205,17 @@ class Statement(ABC):
     
 
 class MutationalStatement(Statement, ABC):
-
     
     def execute(self) -> None:
+        """ Execute built statement """
         query, args = self.build()
-        self._table.execute(query, *args)
+        self._connection.execute(query, *args)
 
 
 class Select(Statement):
 
-
-    def __init__(self, table : SqlTableMixin) -> None:
-        super().__init__(table)
+    def __init__(self, connection : ConnectionManager, tableschema : Schema) -> None:
+        super().__init__(connection, tableschema)
         
         self._columns   : list[str] = []
         self._order_by  : list[str] = []
@@ -229,48 +224,54 @@ 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._table.fetchone(query, *args)
+        return self._connection.fetchone(query, *args)
         
 
     def fetchmany(self, size : int = 1) -> list[SqlRow]:
+        """ Fetch first `size` rows """
         query, args = self.build()
-        return self._table.fetchmany(query, *args, size=size)
+        return self._connection.fetchmany(query, *args, size=size)
 
     
     def fetchall(self) -> list[SqlRow]:
+        """ Fetch all rows """
         query, args = self.build()
-        return self._table.fetchall(query, *args)
+        return self._connection.fetchall(query, *args)
     
 
     def fetchmany_iterator(self, batch_size: int) -> Generator[list[SqlRow], None, None]:
@@ -282,17 +283,19 @@ class Select(Statement):
 
         Examples:
 
-            >>> 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._table.in_transaction():
-            raise RuntimeError("To use the `fetchall_iterator()` method you have \
-                    to keep open the transaction of the table with `transaction()` manager")
+        if not self._connection.in_transaction():
+            raise OutsideTransactionError("To use the `fetchall_iterator()` method you have \
+                    to keep open the transaction of the table")
         
         query, exec_args = self.build()
 
-        iter_cursor = self._table.tx_conn.cursor()
+        iter_cursor = self._connection.tx_conn.cursor()
         iter_cursor.execute(query, exec_args)
 
         while batch := iter_cursor.fetchmany(batch_size):
@@ -300,15 +303,26 @@ class Select(Statement):
 
     
     def __iter__(self) -> Generator[SqlRow, None, None]:
-        """ Select statement rows iterator """
+        """ 
+        Select statement rows iterator
+
+        Examples:
+        
+        ```python
+        with table.transaction():
+            # here `then` is used to link back to the `select` instance from `where` object
+            for row in table.select.where.gt("Age", 30).then: 
+                process_row(row)
+        ```
+        """
         
-        if not self._table.in_transaction():
-            raise RuntimeError("To use the __iter__ method you have \
-                to keep open the transaction of the table with `transaction()` manager")
+        if not self._connection.in_transaction():
+            raise OutsideTransactionError("To use the __iter__ method you have \
+                to keep open the transaction of the table")
         
         query, exec_args = self.build()
         
-        iter_cursor = self._table.tx_conn.cursor()
+        iter_cursor = self._connection.tx_conn.cursor()
         iter_cursor.execute(query, exec_args)
 
         while row := iter_cursor.fetchone(): 
@@ -330,7 +344,7 @@ class Select(Statement):
         else:
             limit = None
         
-        query = sql.select(self._table.tablename, columns, where_clause, order, limit)
+        query = sql.select(self._tableschema["tablename"], columns, where_clause, order, limit)
         
         return query, args
     
@@ -342,43 +356,51 @@ class Select(Statement):
         self._limit     = None
 
 
+    def _resolve_columns(self) -> list[str]:
+        return (
+            self._tableschema["columns"] 
+            if len(self._columns) == 0 or "*" in self._columns 
+            else self._columns
+        )
+
+
     def _repr_html_(self) -> str | None:
         
         if self._aggregate:
             return None
         
         limit     = 26
-        columns   = self._table.columns if len(self._columns) == 0 or "*" in self._columns else self._columns
+        columns   = self._resolve_columns()
         repr_rows = self.fetchmany(limit)
 
-        return to_html(self._table.tablename, columns, repr_rows, limit=limit-1)
+        return to_html(self._tableschema["tablename"], columns, repr_rows, limit=limit-1)
     
 
 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._table.tablename, where_clause)
+        query = sql.delete_rows(self._tableschema["tablename"], where_clause)
         return query, args
     
+    
     def _reset(self) -> None:
         pass
     
 
 class Update(MutationalStatement):
 
-
-    def __init__(self, table : SqlTableMixin) -> None:
-        super().__init__(table)
+    def __init__(self, connection : ConnectionManager, tableschema : Schema) -> None:
+        super().__init__(connection, tableschema)
         self._set_clauses : list[str] = []
         self._set_args    : list[SqlValue] = []
 
     
     def __call__(self, column : str, value : SqlValue) -> Self:
+        """ Shortcut to set value to a column """
         return self.set(column, value)
 
 
@@ -391,7 +413,7 @@ class Update(MutationalStatement):
 
     def _build(self, where_clause : str, *args : SqlValue) -> tuple[str, tuple[SqlValue, ...]]:
         set_clause = sql.format_list(self._set_clauses, brackets=False)
-        query = f"UPDATE {self._table.tablename} SET {set_clause} WHERE {where_clause};"
+        query = f"UPDATE {self._tableschema["tablename"]} SET {set_clause} WHERE {where_clause};"
         return query, (*self._set_args, *args)