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

sqlengine/__init__.py

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

sqlengine/core/__init__.py

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

sqlengine/core/connection.py

@@ -0,0 +1,255 @@
+import sqlite3
+import logging
+import os
+
+from typing import overload, Literal, Sequence
+from contextlib import contextmanager
+
+from .types import SqlValue, SqlRow
+
+
+logger = logging.getLogger("sqlengine")
+logger.setLevel(os.getenv("SQL_ENGINE_LOG_LEVEL", "WARNING").upper())
+
+
+class ConnectionManager:
+
+    _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 RuntimeError("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 RuntimeError("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 RuntimeError("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")
+        
+        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 RuntimeError("`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 RuntimeError("`tx_cursor` is not available outside the transaction mode")
+        return self._trans_cursor
+

sqlengine/{utils → core}/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 → core}/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 → core}/statements.py

@@ -1,20 +1,16 @@
-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 import ConnectionManager
+
+from .types import SqlValue, SqlRow, Schema
 from .repr  import to_html
 
 
-class Where[T : Statement]:
+class Where[T : "Statement"]:
     """ Where clause build helper """
     
-    
     def __init__(self, statement : T):
         
         self._statement = statement
@@ -146,11 +142,10 @@ 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._tableschema = tableschema
+        self._connection  = connection
         self._where: Where[Self] = Where(self)
 
         self._custom_query : str | None = None
@@ -175,7 +170,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 +204,16 @@ class Statement(ABC):
     
 
 class MutationalStatement(Statement, ABC):
-
     
     def execute(self) -> None:
         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] = []
@@ -260,17 +253,17 @@ class Select(Statement):
 
     def fetchone(self) -> SqlRow:
         query, args = self.build()
-        return self._table.fetchone(query, *args)
+        return self._connection.fetchone(query, *args)
         
 
     def fetchmany(self, size : int = 1) -> list[SqlRow]:
         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]:
         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]:
@@ -286,13 +279,13 @@ class Select(Statement):
             >>>     for batch in table.select.where.gt("Age", 30).then.fetchmany_iterator(1000):
             >>>         process_batch(batch)
         """
-        if not self._table.in_transaction():
+        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")
         
         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):
@@ -302,13 +295,13 @@ class Select(Statement):
     def __iter__(self) -> Generator[SqlRow, None, None]:
         """ Select statement rows iterator """
         
-        if not self._table.in_transaction():
+        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")
         
         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 +323,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,38 +335,45 @@ 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")
         
-        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] = []
 
@@ -391,7 +391,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)
     
     

sqlengine/{utils → core}/types.py

@@ -1,6 +1,6 @@
 import sqlite3
-from typing import Protocol, Self, TypeGuard, TypedDict
-
+from typing import Protocol, Self, TypeGuard, TypedDict, Any
+from types import UnionType
 
 class CustomType(Protocol):
     @classmethod
@@ -24,12 +24,20 @@ class Schema(TypedDict):
     primary   : list[str]
 
 
+class Primary[T]:
+    __slots__ = ()
+
+
 # https://docs.python.org/3/library/sqlite3.html#sqlite-and-python-types
-_TYPES_MAP : dict[type, str] = {
-    int     : "INTEGER",
-    float   : "REAL",
-    str     : "TEXT",
-    bytes   : "BLOB",
+_TYPES_MAP : dict[type | UnionType, str] = {
+    int     : "INTEGER NOT NULL",
+    float   : "REAL NOT NULL",
+    str     : "TEXT NOT NULL",
+    bytes   : "BLOB NOT NULL",
+    None | int   : "INTEGER",
+    None | float : "REAL",
+    None | str   : "TEXT",
+    None | bytes : "BLOB",
 }
 
 
@@ -62,4 +70,35 @@ def pytype_to_sqltype(type_ : type) -> str:
     if type_ not in _TYPES_MAP:
         raise TypeError(f"{type_} is not natively supported by sqlite3")
     
-    return _TYPES_MAP[type_]
+    return _TYPES_MAP[type_]
+
+
+def register_resolve_types(types : list[SqlType | str], **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] = []
+    assert_register_types = False
+
+    for type_ in types:
+        
+        if isinstance(type_, str):
+            resolved.append(type_)
+            continue
+        
+        if is_custom_type(type_):
+            ctname = type_.__name__.upper()
+            
+            register_type(type_, ctname)
+            resolved.append(ctname)
+            
+            if not assert_register_types:
+                assert_register_types = True
+            continue 
+        
+        sql_type = pytype_to_sqltype(type_)
+        resolved.append(sql_type)
+    
+    if assert_register_types and ("detect_types" not in connection_params):
+        connection_params.update(dict(detect_types=sqlite3.PARSE_DECLTYPES))
+
+    return resolved, connection_params

sqlengine/schema.py

@@ -3,7 +3,7 @@ import sqlite3
 from typing import overload
 
 from .sqltable import SqlTableMixin
-from .utils.types import Schema
+from .core.types import Schema
 
 
 def get_database_tablenames(database : str, cursor : sqlite3.Cursor | None = None) -> list[str]: