sqlengine-lite 2.1.0__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/core/repr.py

@@ -0,0 +1,52 @@
+from html import escape
+from typing import Sequence
+
+from .types import SqlRow
+
+
+def to_html(tablename : str, columns : list[str], repr_rows : Sequence[SqlRow], limit : int = 25) -> str:
+
+    tablestyle     = "<table style=\"border-collapse: collapse; font-size: 14px;\">"
+    tablenamestyle = "<caption style=\"font-size: 18px; font-weight: bold;\">{}</caption>"
+    colstyle       = "<td style=\"border: 1px solid #555; text-align: center;\">{}</td>"
+    cellstyle      = "<td style=\"border: 1px solid #000; text-align: center;\">{}</td>"
+    morestyle      = "<td colspan=\"{}\" style=\"text-align:center;color:#888;font-style:italic;padding:8px;\">... more rows ...</td>"
+    
+    cols      = [colstyle.format(escape(col)) for col in columns]
+    tablename = tablenamestyle.format(escape(tablename))
+    more      = morestyle.format(len(columns))
+
+    html = [
+        tablestyle,
+        tablename,
+            "<thead>",
+                "<tr>",
+                    *cols,
+                "</tr>",
+            "</thead>",
+        "<tbody>",
+    ]
+
+    for row in repr_rows[:limit]:
+        values = [cellstyle.format(escape(str(val))) for val in row]
+        
+        html.extend([
+            "<tr>",
+                *values,
+            "</tr>"
+        ])
+    
+    if len(repr_rows) > limit:
+        html.extend([
+        "<tr>",
+            more,
+        "</tr>"
+      ])
+    
+    html.extend([
+        "</tbody>",
+        "</table>",
+    ])
+
+    return "".join(html)
+

sqlengine/core/sqlgen.py

@@ -0,0 +1,109 @@
+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])
+    return f'({items_str})' if brackets else items_str
+
+
+def create_table(
+        tablename: str,
+        columns  : list[str],
+        types    : list[str],
+        primary  : list[str]
+    ) -> str:
+
+    columns_types = format_list([
+        f'{col} {dtype}' for col, dtype 
+        in zip(columns, types)], brackets=False)
+    
+    primary_keys = format_list(primary)
+    
+    return (
+        f"CREATE TABLE IF NOT EXISTS {tablename} "
+        f"({columns_types}, PRIMARY KEY {primary_keys});"
+    )
+
+
+def drop_table(tablename : str) -> str:
+    return f"DROP TABLE IF EXISTS {tablename}"
+
+
+def values_placeholder(n_values : int) -> str:
+    """ Creates placeholder `(?, ?, ?, ...)` with "?" `n_values` times """
+    return format_list(['?']*n_values)
+
+
+def bulk_placeholder(n_values : int, n_rows : int) -> str:
+    """ Creates placeholders `(?, ?, ..), (?, ?, ..), ...` for each row """
+    place_holder = values_placeholder(n_values)
+    return format_list([place_holder]*n_rows, False)
+
+
+def insert(tablename : str, columns : list[str], values : str) -> str:
+    """ Creates insert query """
+    return f"INSERT INTO {tablename} {format_list(columns)} VALUES {values};"
+
+
+def insert_row(tablename : str, columns : list[str]) -> str:
+    """ Creates insert query for 1 row """
+    n_values = len(columns)
+    placeholder = values_placeholder(n_values)
+    return insert(tablename, columns, placeholder)
+
+
+def insert_many(tablename : str, columns : list[str], n_rows : int) -> str:
+    """ Creates insert query for multiple rows """
+    n_values = len(columns)
+    placeholder = bulk_placeholder(n_values, n_rows)
+    return insert(tablename, columns, placeholder)
+
+
+def delete_rows(tablename : str, where_clause : str) -> str:
+    return f"DELETE FROM {tablename} WHERE {where_clause};"
+
+
+def select(
+      tablename   : str,
+      columns     : str | list[str]  = "*",
+      where_clause: str | None       = None,
+      order_by    : str | None       = None,
+      limit       : int | str | None = None
+    ) -> str: 
+    """ Creates select query """
+    
+    _columns = columns if isinstance(columns, str) else format_list(columns, False)
+    
+    query  = f"SELECT {_columns} FROM {tablename}"
+    query += f" WHERE {where_clause}" if where_clause else ""
+    query += f" ORDER BY {order_by}"  if order_by     else ""
+    query += f" LIMIT {limit}"        if limit        else ""
+    query += ";"
+
+    return query
+
+
+def upsert(tablename : str, columns : list[str], primary_key : list[str]) -> str:
+    """
+    Creates query to upsert (update or insert) row based on `primary_key`
+
+    Args:
+        tablename (str): name of the table in db
+        columns (list[str]): list of table columns
+        primary_key (list[str]): list of primary keys
+    """
+    placeholder  = values_placeholder(len(columns))
+    non_primary  = set(columns) - set(primary_key)
+    updated_list = [f"{col}=excluded.{col}" for col in non_primary]
+    
+    columns_str = format_list(columns)
+    updated_str = format_list(updated_list, False)
+    primary_str = format_list(primary_key)
+
+    query = (
+        f"INSERT INTO {tablename} {columns_str} VALUES {placeholder} "
+        f"ON CONFLICT {primary_str} "
+        f"DO UPDATE SET {updated_str};"
+    )
+    return query