sqliter-py 0.1.0__py3-none-any.whl → 0.1.1__py3-none-any.whl

sqliter/exceptions.py

@@ -0,0 +1,114 @@
+"""Define custom exceptions for the sqliter package."""
+
+import os
+import sys
+import traceback
+
+
+class SqliterError(Exception):
+    """Base class for all exceptions raised by the sqliter package."""
+
+    message_template: str = "An error occurred in the SQLiter package."
+
+    def __init__(self, *args: object) -> None:
+        """Format the message using the provided arguments.
+
+        We also capture (and display) the current exception context and chain
+        any previous exceptions.
+
+        :param args: Arguments to format into the message template
+        """
+        if args:
+            message = self.message_template.format(*args)
+        else:
+            message = (
+                self.message_template.replace("'{}'", "")
+                .replace(":", "")
+                .strip()
+            )
+
+        # Capture the current exception context
+        self.original_exception = sys.exc_info()[1]
+
+        # If there's an active exception, append its information to our message
+        if self.original_exception:
+            original_type = type(self.original_exception).__name__
+            original_module = type(self.original_exception).__module__
+
+            # Get the traceback of the original exception
+            tb = traceback.extract_tb(self.original_exception.__traceback__)
+            if tb:
+                last_frame = tb[-1]
+                file_path = os.path.relpath(last_frame.filename)
+                line_number = last_frame.lineno
+                location = f"{file_path}:{line_number}"
+            else:
+                location = "unknown location"
+
+            message += (
+                f"\n  --> {original_module}.{original_type} "
+                f"from {location}: {self.original_exception}"
+            )
+
+        # Call the parent constructor with our formatted message
+        super().__init__(message)
+
+        # Explicitly chain exceptions if there's an active one
+        if self.original_exception:
+            self.__cause__ = self.original_exception
+
+
+class DatabaseConnectionError(SqliterError):
+    """Raised when the SQLite database connection fails."""
+
+    message_template = "Failed to connect to the database: '{}'"
+
+
+class InvalidOffsetError(SqliterError):
+    """Raised when an invalid offset value (0 or negative) is used."""
+
+    message_template = (
+        "Invalid offset value: '{}'. Offset must be a positive integer."
+    )
+
+
+class TableCreationError(SqliterError):
+    """Raised when a table cannot be created in the database."""
+
+    message_template = "Failed to create the table: '{}'"
+
+
+class RecordInsertionError(SqliterError):
+    """Raised when an error occurs during record insertion."""
+
+    message_template = "Failed to insert record into table: '{}'"
+
+
+class RecordUpdateError(SqliterError):
+    """Raised when an error occurs during record update."""
+
+    message_template = "Failed to update record in table: '{}'"
+
+
+class RecordNotFoundError(SqliterError):
+    """Raised when a record with the specified primary key is not found."""
+
+    message_template = "Failed to find a record for key '{}' "
+
+
+class RecordFetchError(SqliterError):
+    """Raised when an error occurs during record fetching."""
+
+    message_template = "Failed to fetch record from table: '{}'"
+
+
+class RecordDeletionError(SqliterError):
+    """Raised when an error occurs during record deletion."""
+
+    message_template = "Failed to delete record from table: '{}'"
+
+
+class InvalidFilterError(SqliterError):
+    """Raised when an invalid filter field is used in a query."""
+
+    message_template = "Failed to apply filter: invalid field '{}'"

sqliter/query/query.py

@@ -2,11 +2,18 @@
 
 from __future__ import annotations
 
+import sqlite3
 from typing import TYPE_CHECKING, Any, Optional
 
 from typing_extensions import Self
 
-if TYPE_CHECKING:
+from sqliter.exceptions import (
+    InvalidFilterError,
+    InvalidOffsetError,
+    RecordFetchError,
+)
+
+if TYPE_CHECKING:  # pragma: no cover
     from sqliter import SqliterDB
     from sqliter.model import BaseDBModel
 
@@ -20,52 +27,87 @@ class QueryBuilder:
         self.model_class = model_class
         self.table_name = model_class.get_table_name()  # Use model_class method
         self.filters: list[tuple[str, Any]] = []
+        self._limit: Optional[int] = None
+        self._offset: Optional[int] = None
+        self._order_by: Optional[str] = None
 
     def filter(self, **conditions: str | float | None) -> Self:
         """Add filter conditions to the query."""
+        valid_fields = self.model_class.model_fields
+
         for field, value in conditions.items():
+            if field not in valid_fields:
+                raise InvalidFilterError(field)
             self.filters.append((field, value))
+
+        return self
+
+    def limit(self, limit_value: int) -> Self:
+        """Limit the number of results returned by the query."""
+        self._limit = limit_value
+        return self
+
+    def offset(self, offset_value: int) -> Self:
+        """Set an offset value for the query."""
+        if offset_value <= 0:
+            raise InvalidOffsetError(offset_value)
+        self._offset = offset_value
+
+        if self._limit is None:
+            self._limit = -1
+        return self
+
+    def order(self, order_by_field: str) -> Self:
+        """Order the results by a specific field and optionally direction."""
+        self._order_by = order_by_field
         return self
 
     def _execute_query(
         self,
-        limit: Optional[int] = None,
-        offset: Optional[int] = None,
-        order_by: Optional[str] = None,
         *,
         fetch_one: bool = False,
     ) -> list[tuple[Any, ...]] | Optional[tuple[Any, ...]]:
         """Helper function to execute the query with filters."""
         fields = ", ".join(self.model_class.model_fields)
+
+        # Build the WHERE clause with special handling for None (NULL in SQL)
         where_clause = " AND ".join(
-            [f"{field} = ?" for field, _ in self.filters]
+            [
+                f"{field} IS NULL" if value is None else f"{field} = ?"
+                for field, value in self.filters
+            ]
         )
+
         sql = f"SELECT {fields} FROM {self.table_name}"  # noqa: S608
 
         if self.filters:
             sql += f" WHERE {where_clause}"
 
-        if order_by:
-            sql += f" ORDER BY {order_by}"
+        if self._order_by:
+            sql += f" ORDER BY {self._order_by}"
 
-        if limit is not None:
-            sql += f" LIMIT {limit}"
+        if self._limit is not None:
+            sql += f" LIMIT {self._limit}"
 
-        if offset is not None:
-            sql += f" OFFSET {offset}"
+        if self._offset is not None:
+            sql += f" OFFSET {self._offset}"
 
-        values = [value for _, value in self.filters]
+        # Only include non-None values in the values list
+        values = [value for _, value in self.filters if value is not None]
 
-        with self.db.connect() as conn:
-            cursor = conn.cursor()
-            cursor.execute(sql, values)
-            return cursor.fetchall() if not fetch_one else cursor.fetchone()
+        try:
+            with self.db.connect() as conn:
+                cursor = conn.cursor()
+                cursor.execute(sql, values)
+                return cursor.fetchall() if not fetch_one else cursor.fetchone()
+        except sqlite3.Error as exc:
+            raise RecordFetchError(self.table_name) from exc
 
     def fetch_all(self) -> list[BaseDBModel]:
         """Fetch all results matching the filters."""
         results = self._execute_query()
 
-        if results is None:
+        if not results:
             return []
 
         return [
@@ -92,7 +134,8 @@ class QueryBuilder:
 
     def fetch_first(self) -> BaseDBModel | None:
         """Fetch the first result of the query."""
-        result = self._execute_query(limit=1)
+        self._limit = 1
+        result = self._execute_query()
         if not result:
             return None
         return self.model_class(
@@ -103,9 +146,10 @@ class QueryBuilder:
         )
 
     def fetch_last(self) -> BaseDBModel | None:
-        """Fetch the last result of the query (based on the primary key)."""
-        primary_key = self.model_class.get_primary_key()
-        result = self._execute_query(limit=1, order_by=f"{primary_key} DESC")
+        """Fetch the last result of the query (based on the insertion order)."""
+        self._limit = 1
+        self._order_by = "rowid DESC"
+        result = self._execute_query()
         if not result:
             return None
         return self.model_class(

sqliter/sqliter.py

@@ -7,9 +7,18 @@ from typing import TYPE_CHECKING, Optional
 
 from typing_extensions import Self
 
+from sqliter.exceptions import (
+    DatabaseConnectionError,
+    RecordDeletionError,
+    RecordFetchError,
+    RecordInsertionError,
+    RecordNotFoundError,
+    RecordUpdateError,
+    TableCreationError,
+)
 from sqliter.query.query import QueryBuilder
 
-if TYPE_CHECKING:
+if TYPE_CHECKING:  # pragma: no cover
     from types import TracebackType
 
     from sqliter.model.model import BaseDBModel
@@ -27,7 +36,10 @@ class SqliterDB:
     def connect(self) -> sqlite3.Connection:
         """Create or return a connection to the SQLite database."""
         if not self.conn:
-            self.conn = sqlite3.connect(self.db_filename)
+            try:
+                self.conn = sqlite3.connect(self.db_filename)
+            except sqlite3.Error as exc:
+                raise DatabaseConnectionError(self.db_filename) from exc
         return self.conn
 
     def create_table(self, model_class: type[BaseDBModel]) -> None:
@@ -43,7 +55,7 @@ class SqliterDB:
         if create_id:
             create_table_sql = f"""
                 CREATE TABLE IF NOT EXISTS {table_name} (
-                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    {primary_key} INTEGER PRIMARY KEY AUTOINCREMENT,
                     {fields}
                 )
             """
@@ -55,10 +67,13 @@ class SqliterDB:
                 )
             """
 
-        with self.connect() as conn:
-            cursor = conn.cursor()
-            cursor.execute(create_table_sql)
-            conn.commit()
+        try:
+            with self.connect() as conn:
+                cursor = conn.cursor()
+                cursor.execute(create_table_sql)
+                conn.commit()
+        except sqlite3.Error as exc:
+            raise TableCreationError(table_name) from exc
 
     def _maybe_commit(self, conn: sqlite3.Connection) -> None:
         """Commit changes if auto_commit is True."""
@@ -77,14 +92,17 @@ class SqliterDB:
         )
 
         insert_sql = f"""
-        INSERT OR REPLACE INTO {table_name} ({fields})
+        INSERT INTO {table_name} ({fields})
         VALUES ({placeholders})
     """  # noqa: S608
 
-        with self.connect() as conn:
-            cursor = conn.cursor()
-            cursor.execute(insert_sql, values)
-            self._maybe_commit(conn)
+        try:
+            with self.connect() as conn:
+                cursor = conn.cursor()
+                cursor.execute(insert_sql, values)
+                self._maybe_commit(conn)
+        except sqlite3.Error as exc:
+            raise RecordInsertionError(table_name) from exc
 
     def get(
         self, model_class: type[BaseDBModel], primary_key_value: str
@@ -99,18 +117,22 @@ class SqliterDB:
             SELECT {fields} FROM {table_name} WHERE {primary_key} = ?
         """  # noqa: S608
 
-        with self.connect() as conn:
-            cursor = conn.cursor()
-            cursor.execute(select_sql, (primary_key_value,))
-            result = cursor.fetchone()
-
-        if result:
-            result_dict = {
-                field: result[idx]
-                for idx, field in enumerate(model_class.model_fields)
-            }
-            return model_class(**result_dict)
-        return None
+        try:
+            with self.connect() as conn:
+                cursor = conn.cursor()
+                cursor.execute(select_sql, (primary_key_value,))
+                result = cursor.fetchone()
+
+            if result:
+                result_dict = {
+                    field: result[idx]
+                    for idx, field in enumerate(model_class.model_fields)
+                }
+                return model_class(**result_dict)
+        except sqlite3.Error as exc:
+            raise RecordFetchError(table_name) from exc
+        else:
+            return None
 
     def update(self, model_instance: BaseDBModel) -> None:
         """Update an existing record using the Pydantic model."""
@@ -131,13 +153,24 @@ class SqliterDB:
         primary_key_value = getattr(model_instance, primary_key)
 
         update_sql = f"""
-            UPDATE {table_name} SET {fields} WHERE {primary_key} = ?
+            UPDATE {table_name}
+            SET {fields}
+            WHERE {primary_key} = ?
         """  # noqa: S608
 
-        with self.connect() as conn:
-            cursor = conn.cursor()
-            cursor.execute(update_sql, (*values, primary_key_value))
-            self._maybe_commit(conn)
+        try:
+            with self.connect() as conn:
+                cursor = conn.cursor()
+                cursor.execute(update_sql, (*values, primary_key_value))
+
+                # Check if any rows were updated
+                if cursor.rowcount == 0:
+                    raise RecordNotFoundError(primary_key_value)
+
+                self._maybe_commit(conn)
+
+        except sqlite3.Error as exc:
+            raise RecordUpdateError(table_name) from exc
 
     def delete(
         self, model_class: type[BaseDBModel], primary_key_value: str
@@ -150,10 +183,16 @@ class SqliterDB:
             DELETE FROM {table_name} WHERE {primary_key} = ?
         """  # noqa: S608
 
-        with self.connect() as conn:
-            cursor = conn.cursor()
-            cursor.execute(delete_sql, (primary_key_value,))
-            self._maybe_commit(conn)
+        try:
+            with self.connect() as conn:
+                cursor = conn.cursor()
+                cursor.execute(delete_sql, (primary_key_value,))
+
+                if cursor.rowcount == 0:
+                    raise RecordNotFoundError(primary_key_value)
+                self._maybe_commit(conn)
+        except sqlite3.Error as exc:
+            raise RecordDeletionError(table_name) from exc
 
     def select(self, model_class: type[BaseDBModel]) -> QueryBuilder:
         """Start a query for the given model."""
@@ -173,7 +212,12 @@ class SqliterDB:
     ) -> None:
         """Exit the runtime context and close the connection."""
         if self.conn:
-            if not self.auto_commit:
-                self.conn.commit()
-            self.conn.close()
-            self.conn = None
+            try:
+                if exc_type:
+                    # Roll back the transaction if there was an exception
+                    self.conn.rollback()
+                self._maybe_commit(self.conn)
+            finally:
+                # Close the connection and reset the instance variable
+                self.conn.close()
+                self.conn = None

sqliter_py-0.1.1.dist-info/METADATA

@@ -0,0 +1,204 @@
+Metadata-Version: 2.3
+Name: sqliter-py
+Version: 0.1.1
+Summary: Interact with SQLite databases using Python and Pydantic
+Project-URL: Pull Requests, https://github.com/seapagan/sqliter-py/pulls
+Project-URL: Bug Tracker, https://github.com/seapagan/sqliter-py/issues
+Project-URL: Repository, https://github.com/seapagan/sqliter-py
+Author-email: Grant Ramsay <grant@gnramsay.com>
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: pydantic>=2.9.0
+Description-Content-Type: text/markdown
+
+# SQLiter
+
+<!-- ![PyPI - Version](https://img.shields.io/pypi/v/sqliter-py) -->
+[![Test Suite](https://github.com/seapagan/sqliter-py/actions/workflows/testing.yml/badge.svg)](https://github.com/seapagan/sqliter-py/actions/workflows/testing.yml)
+[![Linting](https://github.com/seapagan/sqliter-py/actions/workflows/linting.yml/badge.svg)](https://github.com/seapagan/sqliter-py/actions/workflows/linting.yml)
+[![Type Checking](https://github.com/seapagan/sqliter-py/actions/workflows/mypy.yml/badge.svg)](https://github.com/seapagan/sqliter-py/actions/workflows/mypy.yml)
+<!-- ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/sqliter-py) -->
+
+SQLiter is a lightweight Object-Relational Mapping (ORM) library for SQLite
+databases in Python. It provides a simplified interface for interacting with
+SQLite databases using Pydantic models.
+
+It does not aim to be a full-fledged ORM like SQLAlchemy, but rather a simple
+and easy-to-use library for basic database operations, especially for small
+projects. It is NOT asynchronous and does not support complex queries (at this
+time).
+
+The ideal use case is more for Python CLI tools that need to store data in a
+database-like format without needing to learn SQL or use a full ORM.
+
+> [!NOTE]
+> This project is still in the early stages of development and is lacking some
+> planned functionality. Please use with caution.
+>
+> See the [TODO](TODO.md) for planned features and improvements.
+
+## Features
+
+- Table creation based on Pydantic models
+- CRUD operations (Create, Read, Update, Delete)
+- Basic query building with filtering, ordering, and pagination
+- Transaction support
+- Custom exceptions for better error handling
+
+## Installation
+
+You can install SQLiter using pip:
+
+```bash
+pip install sqliter-py
+```
+
+## Quick Start
+
+Here's a quick example of how to use SQLiter:
+
+```python
+from sqliter import SqliterDB
+from sqliter.model import BaseDBModel
+
+# Define your model
+class User(BaseDBModel):
+    name: str
+    age: int
+
+    class Meta:
+        table_name = "users"
+
+# Create a database connection
+db = SqliterDB("example.db", auto_commit=True)
+
+# Create the table
+db.create_table(User)
+
+# Insert a record
+user = User(name="John Doe", age=30)
+db.insert(user)
+
+# Query records
+results = db.select(User).filter(name="John Doe").fetch_all()
+for user in results:
+    print(f"User: {user.name}, Age: {user.age}")
+
+# Update a record
+user.age = 31
+db.update(user)
+
+# Delete a record
+db.delete(User, "John Doe")
+```
+
+## Detailed Usage
+
+### Defining Models
+
+Models in SQLiter are based on Pydantic's `BaseModel`. You can define your
+models like this:
+
+```python
+from sqliter.model import BaseDBModel
+
+class User(BaseDBModel):
+    name: str
+    age: int
+    email: str
+
+    class Meta:
+        table_name = "users"
+        primary_key = "name"  # Default is "id"
+        create_id = False  # Set to True to auto-create an ID field
+```
+
+### Database Operations
+
+#### Creating a Connection
+
+```python
+from sqliter import SqliterDB
+
+db = SqliterDB("your_database.db", auto_commit=True)
+```
+
+#### Creating Tables
+
+```python
+db.create_table(User)
+```
+
+#### Inserting Records
+
+```python
+user = User(name="Jane Doe", age=25, email="jane@example.com")
+db.insert(user)
+```
+
+#### Querying Records
+
+```python
+# Fetch all users
+all_users = db.select(User).fetch_all()
+
+# Filter users
+young_users = db.select(User).filter(age=25).fetch_all()
+
+# Order users
+ordered_users = db.select(User).order("age DESC").fetch_all()
+
+# Limit and offset
+paginated_users = db.select(User).limit(10).offset(20).fetch_all()
+```
+
+Note: The filtering in SQLiter is basic and supports exact matches. Complex
+queries like `age__lt` are not supported in the current implementation.
+
+#### Updating Records
+
+```python
+user.age = 26
+db.update(user)
+```
+
+#### Deleting Records
+
+```python
+db.delete(User, "Jane Doe")
+```
+
+### Transactions
+
+SQLiter supports transactions using Python's context manager:
+
+```python
+with db:
+    db.insert(User(name="Alice", age=30, email="alice@example.com"))
+    db.insert(User(name="Bob", age=35, email="bob@example.com"))
+    # If an exception occurs, the transaction will be rolled back
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the MIT License.
+
+## Acknowledgements
+
+SQLiter was initially developed as an experiment using ChatGPT, with subsequent
+manual refinements and improvements.

sqliter_py-0.1.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+sqliter/__init__.py,sha256=L8R0uvCbbbACwaI5xtd3khtvpNhlPRgHJAaYZvqjzig,134
+sqliter/exceptions.py,sha256=5NO9DwHMVKrDZP908G63J5-ANBJDCwbBkXL7h_Bit2Q,3610
+sqliter/sqliter.py,sha256=R69oNusPEg0Q_zRPFetS9VUUCT5pjatXnUr3Tv6yzjE,7494
+sqliter/model/__init__.py,sha256=Ovpkbyx2-T6Oee0qFNgUBBc2M0uwK-cdG0pigG3mkd8,179
+sqliter/model/model.py,sha256=t1w38om37gma1gRk01Z_9II0h4g-l734ijN_8M1SYoY,1247
+sqliter/query/__init__.py,sha256=BluNMJpuoo2PsYN-bL7fXlEc02O_8LgOMsvCmyv04ao,125
+sqliter/query/query.py,sha256=BRKCdMBOlbcIU5CUxRyKBF4aFT2AboUPu7UwbJ1s5hs,5793
+sqliter_py-0.1.1.dist-info/METADATA,sha256=ehe8KZXc08ftvn2i6FGiw3Qe8jK6QsqApDoDQm9p0XE,5477
+sqliter_py-0.1.1.dist-info/WHEEL,sha256=1yFddiXMmvYK7QYTqtRNtX66WJ0Mz8PYEiEUoOUUxRY,87
+sqliter_py-0.1.1.dist-info/RECORD,,

sqliter_py-0.1.0.dist-info/METADATA

@@ -1,30 +0,0 @@
-Metadata-Version: 2.3
-Name: sqliter-py
-Version: 0.1.0
-Summary: Interact with SQLite databases using Python and Pydantic
-Project-URL: Pull Requests, https://github.com/seapagan/sqliter-py/pulls
-Project-URL: Bug Tracker, https://github.com/seapagan/sqliter-py/issues
-Project-URL: Repository, https://github.com/seapagan/sqliter-py
-Author-email: Grant Ramsay <grant@gnramsay.com>
-License-Expression: MIT
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Topic :: Software Development
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: >=3.9
-Requires-Dist: pydantic>=2.9.0
-Description-Content-Type: text/markdown
-
-# SQLiter
-
-An SQLite wrapper in Python using Pydantic and written primarily using ChatGPT,
-as an experiment in how viable it is to write working code using a LLM.
-
-The code was then cleaned up, typed and linted by hand.

sqliter_py-0.1.0.dist-info/RECORD

@@ -1,9 +0,0 @@
-sqliter/__init__.py,sha256=L8R0uvCbbbACwaI5xtd3khtvpNhlPRgHJAaYZvqjzig,134
-sqliter/sqliter.py,sha256=FxWtYnjnfM2Tp1lc1b1AfrGia-G0IdSopZ2bSa-lPuo,5944
-sqliter/model/__init__.py,sha256=Ovpkbyx2-T6Oee0qFNgUBBc2M0uwK-cdG0pigG3mkd8,179
-sqliter/model/model.py,sha256=t1w38om37gma1gRk01Z_9II0h4g-l734ijN_8M1SYoY,1247
-sqliter/query/__init__.py,sha256=BluNMJpuoo2PsYN-bL7fXlEc02O_8LgOMsvCmyv04ao,125
-sqliter/query/query.py,sha256=8wV5GJwQVFesnW60Qe9XCiOwEZI3Wvk-8WNM0ANsT_M,4442
-sqliter_py-0.1.0.dist-info/METADATA,sha256=R_IogiSpgnGC54Mftva2w5EIa-JnGH-R8NuE5_LDhRo,1267
-sqliter_py-0.1.0.dist-info/WHEEL,sha256=1yFddiXMmvYK7QYTqtRNtX66WJ0Mz8PYEiEUoOUUxRY,87
-sqliter_py-0.1.0.dist-info/RECORD,,