sqlengine-lite 2.2.0__tar.gz → 2.2.1__tar.gz

{sqlengine_lite-2.2.0/src/sqlengine_lite.egg-info → sqlengine_lite-2.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlengine-lite
-Version: 2.2.0
+Version: 2.2.1
 Summary: Cute sqlite3 wrapper for sql tables
 Project-URL: Homepage, https://github.com/suffermuffin/SQL-Engine
 Project-URL: Repository, https://github.com/suffermuffin/SQL-Engine.git
@@ -27,6 +27,7 @@ Dynamic: license-file
   - [Get Item](#get-item)
   - [Custom Types](#custom-types)
   - [Csv Converter](#csv-converter)
+  - [Pandas-like Converter](#pandas-like-converter)
 - [Full Documentation](#full-documentation)
 
 
@@ -127,25 +128,19 @@ More details at [Declaration](https://github.com/suffermuffin/SQL-Engine/blob/ma
 from sqlengine import SqlTableMixin, Primary
 
 # Helper constants for column names
-ID = "ID"
-Name = "Name"
+ID         = "ID"
+Name       = "Name"
 Occupation = "Occupation"
-Salary = "Salary"
+Salary     = "Salary"
 
 
 class Employees(SqlTableMixin):
 
     ID         : Primary[int]
-    Name       : str
+    Name       : str | None
     Occupation : str
     Salary     : float
 
-    # You may overwrite your insert methods for type consistency
-    def insert(self, id : int, name : str, occupation : str, salary : float) -> None:
-        return super().insert(id, name, occupation, salary)
-    
-    def upsert(self, id : int, name : str, occupation : str, salary : float) -> None:
-        return super().upsert(id, name, occupation, salary)
 ```
 
 ## Instantiation
@@ -168,11 +163,16 @@ table = Employees("temp/data.db", force_drop=True)
 table.insert(1, "John Doe", "Software Engineer", 75000.0)
 ```
 
+```py
+# Use kwargs mapping to insert/upsert one row
+
+table.insert(2, salary=80000.0, name="Jane Smith", occupation="Data Scientist")
+```
+
 ```py
 # Bulk insert multiple rows
 
 employees_data = [
-    (2, "Jane Smith", "Data Scientist", 80000.0),
     (3, "Alice Johnson", "Product Manager", 90000.0),
     (4, "Bob Brown", "Project Manager", 78000.0),
     (5, "Charlie Davis", "UI/UX Designer", 65000.0),
@@ -322,10 +322,40 @@ to_csv(table, "temp/table.csv")
 
 ```py
 # Save query result to csv
-
 to_csv(table.select.where.gt(Salary, 70_000), "temp/query.csv")
 ```
 
+```py
+# Stream to csv
+with table.transaction():
+    to_csv(table, "temp/query.csv", stream_batch_size=1000)
+```
+
+## Pandas-like Converter
+
+```py
+# via one shot
+import pandas as pd
+from sqlengine.utils import to_dicts
+
+df = pd.DataFrame(to_dicts(table))
+df.set_index("ID", inplace=True)
+```
+
+```py
+# via generator
+import pandas as pd
+from sqlengine.utils import to_dicts_stream
+
+df = pd.DataFrame(columns=table.columns)
+
+with table.transaction():
+    for batch in to_dicts_stream(table, batch_size=1000):
+        df = pd.concat([df, pd.DataFrame(batch)], axis=0)
+
+df.set_index("ID", inplace=True)
+```
+
 # Full Documentation
 
 For detailed usage, API reference, and advanced examples, see the [full documentation](https://github.com/suffermuffin/SQL-Engine/blob/main/docs/index.md).

{sqlengine_lite-2.2.0 → sqlengine_lite-2.2.1}/README.md

@@ -15,6 +15,7 @@
   - [Get Item](#get-item)
   - [Custom Types](#custom-types)
   - [Csv Converter](#csv-converter)
+  - [Pandas-like Converter](#pandas-like-converter)
 - [Full Documentation](#full-documentation)
 
 
@@ -115,25 +116,19 @@ More details at [Declaration](https://github.com/suffermuffin/SQL-Engine/blob/ma
 from sqlengine import SqlTableMixin, Primary
 
 # Helper constants for column names
-ID = "ID"
-Name = "Name"
+ID         = "ID"
+Name       = "Name"
 Occupation = "Occupation"
-Salary = "Salary"
+Salary     = "Salary"
 
 
 class Employees(SqlTableMixin):
 
     ID         : Primary[int]
-    Name       : str
+    Name       : str | None
     Occupation : str
     Salary     : float
 
-    # You may overwrite your insert methods for type consistency
-    def insert(self, id : int, name : str, occupation : str, salary : float) -> None:
-        return super().insert(id, name, occupation, salary)
-    
-    def upsert(self, id : int, name : str, occupation : str, salary : float) -> None:
-        return super().upsert(id, name, occupation, salary)
 ```
 
 ## Instantiation
@@ -156,11 +151,16 @@ table = Employees("temp/data.db", force_drop=True)
 table.insert(1, "John Doe", "Software Engineer", 75000.0)
 ```
 
+```py
+# Use kwargs mapping to insert/upsert one row
+
+table.insert(2, salary=80000.0, name="Jane Smith", occupation="Data Scientist")
+```
+
 ```py
 # Bulk insert multiple rows
 
 employees_data = [
-    (2, "Jane Smith", "Data Scientist", 80000.0),
     (3, "Alice Johnson", "Product Manager", 90000.0),
     (4, "Bob Brown", "Project Manager", 78000.0),
     (5, "Charlie Davis", "UI/UX Designer", 65000.0),
@@ -310,10 +310,40 @@ to_csv(table, "temp/table.csv")
 
 ```py
 # Save query result to csv
-
 to_csv(table.select.where.gt(Salary, 70_000), "temp/query.csv")
 ```
 
+```py
+# Stream to csv
+with table.transaction():
+    to_csv(table, "temp/query.csv", stream_batch_size=1000)
+```
+
+## Pandas-like Converter
+
+```py
+# via one shot
+import pandas as pd
+from sqlengine.utils import to_dicts
+
+df = pd.DataFrame(to_dicts(table))
+df.set_index("ID", inplace=True)
+```
+
+```py
+# via generator
+import pandas as pd
+from sqlengine.utils import to_dicts_stream
+
+df = pd.DataFrame(columns=table.columns)
+
+with table.transaction():
+    for batch in to_dicts_stream(table, batch_size=1000):
+        df = pd.concat([df, pd.DataFrame(batch)], axis=0)
+
+df.set_index("ID", inplace=True)
+```
+
 # Full Documentation
 
 For detailed usage, API reference, and advanced examples, see the [full documentation](https://github.com/suffermuffin/SQL-Engine/blob/main/docs/index.md).

{sqlengine_lite-2.2.0 → sqlengine_lite-2.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sqlengine-lite"
-version = "2.2.0"
+version = "2.2.1"
 description = "Cute sqlite3 wrapper for sql tables"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -19,7 +19,13 @@ where = ["src"]
 requires = ["setuptools>=61.0"]
 build-backend = "setuptools.build_meta"
 
+[dependency-groups]
+dev = [
+    "black==26.5.1",
+    "pydoc-markdown>=4.8.2",
+]
+
 [project.urls]
 Homepage = "https://github.com/suffermuffin/SQL-Engine"
 Repository = "https://github.com/suffermuffin/SQL-Engine.git"
-Documentation = "https://github.com/suffermuffin/SQL-Engine/blob/main/docs/index.md"
+Documentation = "https://github.com/suffermuffin/SQL-Engine/blob/main/docs/index.md"

sqlengine_lite-2.2.1/src/sqlengine/__init__.py

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

sqlengine_lite-2.2.1/src/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_lite-2.2.0/src/sqlengine/core/connection.py → sqlengine_lite-2.2.1/src/sqlengine/_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,16 @@ 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
 
@@ -172,7 +183,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,7 +195,7 @@ 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()
@@ -194,14 +205,14 @@ class ConnectionManager:
 
     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 +253,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 +261,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_lite-2.2.0/src/sqlengine/core → sqlengine_lite-2.2.1/src/sqlengine/_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"]:
@@ -146,7 +147,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 +207,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,46 +224,52 @@ 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)
     
@@ -275,13 +283,15 @@ 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._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 +303,22 @@ 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._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 +381,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 +400,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_lite-2.2.0/src/sqlengine/core → sqlengine_lite-2.2.1/src/sqlengine/_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_lite-2.2.1/src/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_lite-2.2.0 → sqlengine_lite-2.2.1}/src/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]: