sqliter-py 0.4.0__tar.gz → 0.5.0__tar.gz

{sqliter_py-0.4.0 → sqliter_py-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: sqliter-py
-Version: 0.4.0
+Version: 0.5.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
@@ -52,14 +52,16 @@ Website](https://sqliter.grantramsay.dev)
 
 > [!CAUTION]
 > This project is still in the early stages of development and is lacking some
-> planned functionality. Please use with caution.
+> planned functionality. Please use with caution - Classes and methods may
+> change until a stable release is made. I'll try to keep this to an absolute
+> minimum and the releases and documentation will be very clear about any
+> breaking changes.
 >
 > Also, structures like `list`, `dict`, `set` etc are not supported **at this
 > time** as field types, since SQLite does not have a native column type for
-> these. I will look at implementing these in the future, probably by
-> serializing them to JSON or pickling them and storing in a text field. For
-> now, you can actually do this manually when creating your Model (use `TEXT` or
-> `BLOB` fields), then serialize before saving after and retrieving data.
+> these. This is the **next planned enhancement**. These will need to be
+> `pickled` first then stored as a BLOB in the database . Also support `date`
+> which can be stored as a Unix timestamp in an integer field.
 >
 > See the [TODO](TODO.md) for planned features and improvements.
 
@@ -74,10 +76,11 @@ Website](https://sqliter.grantramsay.dev)
 
 - Table creation based on Pydantic models
 - CRUD operations (Create, Read, Update, Delete)
-- Basic query building with filtering, ordering, and pagination
+- Chained Query building with filtering, ordering, and pagination
 - Transaction support
 - Custom exceptions for better error handling
 - Full type hinting and type checking
+- Detailed documentation and examples
 - No external dependencies other than Pydantic
 - Full test coverage
 - Can optionally output the raw SQL queries being executed for debugging
@@ -142,7 +145,7 @@ db.create_table(User)
 
 # Insert a record
 user = User(name="John Doe", age=30)
-db.insert(user)
+new_user = db.insert(user)
 
 # Query records
 results = db.select(User).filter(name="John Doe").fetch_all()
@@ -150,11 +153,11 @@ for user in results:
     print(f"User: {user.name}, Age: {user.age}")
 
 # Update a record
-user.age = 31
-db.update(user)
+new_user.age = 31
+db.update(new_user)
 
 # Delete a record
-db.delete(User, "John Doe")
+db.delete(User, new_user.pk)
 ```
 
 See the [Usage](https://sqliter.grantramsay.dev/usage) section of the documentation

{sqliter_py-0.4.0 → sqliter_py-0.5.0}/README.md

@@ -24,14 +24,16 @@ Website](https://sqliter.grantramsay.dev)
 
 > [!CAUTION]
 > This project is still in the early stages of development and is lacking some
-> planned functionality. Please use with caution.
+> planned functionality. Please use with caution - Classes and methods may
+> change until a stable release is made. I'll try to keep this to an absolute
+> minimum and the releases and documentation will be very clear about any
+> breaking changes.
 >
 > Also, structures like `list`, `dict`, `set` etc are not supported **at this
 > time** as field types, since SQLite does not have a native column type for
-> these. I will look at implementing these in the future, probably by
-> serializing them to JSON or pickling them and storing in a text field. For
-> now, you can actually do this manually when creating your Model (use `TEXT` or
-> `BLOB` fields), then serialize before saving after and retrieving data.
+> these. This is the **next planned enhancement**. These will need to be
+> `pickled` first then stored as a BLOB in the database . Also support `date`
+> which can be stored as a Unix timestamp in an integer field.
 >
 > See the [TODO](TODO.md) for planned features and improvements.
 
@@ -46,10 +48,11 @@ Website](https://sqliter.grantramsay.dev)
 
 - Table creation based on Pydantic models
 - CRUD operations (Create, Read, Update, Delete)
-- Basic query building with filtering, ordering, and pagination
+- Chained Query building with filtering, ordering, and pagination
 - Transaction support
 - Custom exceptions for better error handling
 - Full type hinting and type checking
+- Detailed documentation and examples
 - No external dependencies other than Pydantic
 - Full test coverage
 - Can optionally output the raw SQL queries being executed for debugging
@@ -114,7 +117,7 @@ db.create_table(User)
 
 # Insert a record
 user = User(name="John Doe", age=30)
-db.insert(user)
+new_user = db.insert(user)
 
 # Query records
 results = db.select(User).filter(name="John Doe").fetch_all()
@@ -122,11 +125,11 @@ for user in results:
     print(f"User: {user.name}, Age: {user.age}")
 
 # Update a record
-user.age = 31
-db.update(user)
+new_user.age = 31
+db.update(new_user)
 
 # Delete a record
-db.delete(User, "John Doe")
+db.delete(User, new_user.pk)
 ```
 
 See the [Usage](https://sqliter.grantramsay.dev/usage) section of the documentation

{sqliter_py-0.4.0 → sqliter_py-0.5.0}/pyproject.toml

@@ -3,7 +3,7 @@
 
 [project]
 name = "sqliter-py"
-version = "0.4.0"
+version = "0.5.0"
 description = "Interact with SQLite databases using Python and Pydantic"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -144,9 +144,10 @@ known-first-party = ["sqliter"]
 keep-runtime-typing = true
 
 [tool.mypy]
+plugins = ["pydantic.mypy"]
+
 python_version = "3.9"
 exclude = ["docs"]
-
 [[tool.mypy.overrides]]
 disable_error_code = ["method-assign", "no-untyped-def", "attr-defined"]
 module = "tests.*"

{sqliter_py-0.4.0 → sqliter_py-0.5.0}/sqliter/exceptions.py

@@ -114,7 +114,7 @@ class RecordUpdateError(SqliterError):
 class RecordNotFoundError(SqliterError):
     """Exception raised when a requested record is not found in the database."""
 
-    message_template = "Failed to find a record for key '{}' "
+    message_template = "Failed to find that record in the table (key '{}') "
 
 
 class RecordFetchError(SqliterError):

{sqliter_py-0.4.0 → sqliter_py-0.5.0}/sqliter/model/model.py

@@ -10,9 +10,9 @@ in SQLiter applications.
 from __future__ import annotations
 
 import re
-from typing import Any, Optional, TypeVar, Union, get_args, get_origin
+from typing import Any, Optional, TypeVar, Union, cast, get_args, get_origin
 
-from pydantic import BaseModel, ConfigDict
+from pydantic import BaseModel, ConfigDict, Field
 
 T = TypeVar("T", bound="BaseDBModel")
 
@@ -28,6 +28,8 @@ class BaseDBModel(BaseModel):
     representing database models.
     """
 
+    pk: int = Field(0, description="The mandatory primary key of the table.")
+
     model_config = ConfigDict(
         extra="ignore",
         populate_by_name=True,
@@ -44,10 +46,6 @@ class BaseDBModel(BaseModel):
             table_name (Optional[str]): The name of the database table.
         """
 
-        create_pk: bool = (
-            True  # Whether to create an auto-increment primary key
-        )
-        primary_key: str = "id"  # Default primary key name
         table_name: Optional[str] = (
             None  # Table name, defaults to class name if not set
         )
@@ -89,7 +87,7 @@ class BaseDBModel(BaseModel):
                 else:
                     converted_obj[field_name] = field_type(value)
 
-        return cls.model_construct(**converted_obj)
+        return cast(T, cls.model_construct(**converted_obj))
 
     @classmethod
     def get_table_name(cls) -> str:
@@ -127,18 +125,10 @@ class BaseDBModel(BaseModel):
 
     @classmethod
     def get_primary_key(cls) -> str:
-        """Get the primary key field name for the model.
-
-        Returns:
-            The name of the primary key field.
-        """
-        return getattr(cls.Meta, "primary_key", "id")
+        """Returns the mandatory primary key, always 'pk'."""
+        return "pk"
 
     @classmethod
     def should_create_pk(cls) -> bool:
-        """Determine if a primary key should be automatically created.
-
-        Returns:
-            True if a primary key should be created, False otherwise.
-        """
-        return getattr(cls.Meta, "create_pk", True)
+        """Returns True since the primary key is always created."""
+        return True

{sqliter_py-0.4.0 → sqliter_py-0.5.0}/sqliter/query/query.py

@@ -129,8 +129,11 @@ class QueryBuilder:
             field_name, operator = self._parse_field_operator(field)
             self._validate_field(field_name, valid_fields)
 
-            handler = self._get_operator_handler(operator)
-            handler(field_name, value, operator)
+            if operator in ["__isnull", "__notnull"]:
+                self._handle_null(field_name, value, operator)
+            else:
+                handler = self._get_operator_handler(operator)
+                handler(field_name, value, operator)
 
         return self
 
@@ -145,6 +148,8 @@ class QueryBuilder:
             The QueryBuilder instance for method chaining.
         """
         if fields:
+            if "pk" not in fields:
+                fields.append("pk")
             self._fields = fields
             self._validate_fields()
         return self
@@ -164,6 +169,9 @@ class QueryBuilder:
                 invalid fields are specified.
         """
         if fields:
+            if "pk" in fields:
+                err = "The primary key 'pk' cannot be excluded."
+                raise ValueError(err)
             all_fields = set(self.model_class.model_fields.keys())
 
             # Check for invalid fields before subtraction
@@ -179,7 +187,7 @@ class QueryBuilder:
             self._fields = list(all_fields - set(fields))
 
             # Explicit check: raise an error if no fields remain
-            if not self._fields:
+            if self._fields == ["pk"]:
                 err = "Exclusion results in no fields being selected."
                 raise ValueError(err)
 
@@ -208,7 +216,7 @@ class QueryBuilder:
             raise ValueError(err)
 
         # Set self._fields to just the single field
-        self._fields = [field]
+        self._fields = [field, "pk"]
         return self
 
     def _get_operator_handler(
@@ -275,7 +283,7 @@ class QueryBuilder:
             self.filters.append((field_name, value, operator))
 
     def _handle_null(
-        self, field_name: str, _: FilterValue, operator: str
+        self, field_name: str, value: Union[str, float, None], operator: str
     ) -> None:
         """Handle IS NULL and IS NOT NULL filter conditions.
 
@@ -283,15 +291,14 @@ class QueryBuilder:
             field_name: The name of the field to filter on. _: Placeholder for
                 unused value parameter.
             operator: The operator string ('__isnull' or '__notnull').
+            value: The value to check for.
 
         This method adds an IS NULL or IS NOT NULL condition to the filters
         list.
         """
-        condition = (
-            f"{field_name} IS NOT NULL"
-            if operator == "__notnull"
-            else f"{field_name} IS NULL"
-        )
+        is_null = operator == "__isnull"
+        check_null = bool(value) if is_null else not bool(value)
+        condition = f"{field_name} IS {'NOT ' if not check_null else ''}NULL"
         self.filters.append((condition, None, operator))
 
     def _handle_in(
@@ -527,6 +534,8 @@ class QueryBuilder:
         if count_only:
             fields = "COUNT(*)"
         elif self._fields:
+            if "pk" not in self._fields:
+                self._fields.append("pk")
             fields = ", ".join(f'"{field}"' for field in self._fields)
         else:
             fields = ", ".join(

{sqliter_py-0.4.0 → sqliter_py-0.5.0}/sqliter/sqliter.py

@@ -10,7 +10,7 @@ from __future__ import annotations
 
 import logging
 import sqlite3
-from typing import TYPE_CHECKING, Any, Optional
+from typing import TYPE_CHECKING, Any, Optional, TypeVar
 
 from typing_extensions import Self
 
@@ -33,6 +33,8 @@ if TYPE_CHECKING:  # pragma: no cover
 
     from sqliter.model.model import BaseDBModel
 
+T = TypeVar("T", bound="BaseDBModel")
+
 
 class SqliterDB:
     """Main class for interacting with SQLite databases.
@@ -223,28 +225,12 @@ class SqliterDB:
         """
         table_name = model_class.get_table_name()
         primary_key = model_class.get_primary_key()
-        create_pk = model_class.should_create_pk()
 
         if force:
             drop_table_sql = f"DROP TABLE IF EXISTS {table_name}"
             self._execute_sql(drop_table_sql)
 
-        fields = []
-
-        # Always add the primary key field first
-        if create_pk:
-            fields.append(f"{primary_key} INTEGER PRIMARY KEY AUTOINCREMENT")
-        else:
-            field_info = model_class.model_fields.get(primary_key)
-            if field_info is not None:
-                sqlite_type = infer_sqlite_type(field_info.annotation)
-                fields.append(f"{primary_key} {sqlite_type} PRIMARY KEY")
-            else:
-                err = (
-                    f"Primary key field '{primary_key}' not found in model "
-                    "fields."
-                )
-                raise ValueError(err)
+        fields = [f'"{primary_key}" INTEGER PRIMARY KEY AUTOINCREMENT']
 
         # Add remaining fields
         for field_name, field_info in model_class.model_fields.items():
@@ -325,19 +311,28 @@ class SqliterDB:
         if self.auto_commit and self.conn:
             self.conn.commit()
 
-    def insert(self, model_instance: BaseDBModel) -> None:
+    def insert(self, model_instance: T) -> T:
         """Insert a new record into the database.
 
         Args:
-            model_instance: An instance of a Pydantic model to be inserted.
+            model_instance: The instance of the model class to insert.
+
+        Returns:
+            The updated model instance with the primary key (pk) set.
 
         Raises:
-            RecordInsertionError: If there's an error inserting the record.
+            RecordInsertionError: If an error occurs during the insertion.
         """
         model_class = type(model_instance)
         table_name = model_class.get_table_name()
 
+        # Get the data from the model
         data = model_instance.model_dump()
+        # remove the primary key field if it exists, otherwise we'll get
+        # TypeErrors as multiple primary keys will exist
+        if data.get("pk", None) == 0:
+            data.pop("pk")
+
         fields = ", ".join(data.keys())
         placeholders = ", ".join(
             ["?" if value is not None else "NULL" for value in data.values()]
@@ -354,11 +349,15 @@ class SqliterDB:
                 cursor = conn.cursor()
                 cursor.execute(insert_sql, values)
                 self._maybe_commit()
+
         except sqlite3.Error as exc:
             raise RecordInsertionError(table_name) from exc
+        else:
+            data.pop("pk", None)
+            return model_class(pk=cursor.lastrowid, **data)
 
     def get(
-        self, model_class: type[BaseDBModel], primary_key_value: str
+        self, model_class: type[BaseDBModel], primary_key_value: int
     ) -> BaseDBModel | None:
         """Retrieve a single record from the database by its primary key.
 
@@ -405,11 +404,12 @@ class SqliterDB:
             model_instance: An instance of a Pydantic model to be updated.
 
         Raises:
-            RecordUpdateError: If there's an error updating the record.
-            RecordNotFoundError: If the record to update is not found.
+            RecordUpdateError: If there's an error updating the record or if it
+            is not found.
         """
         model_class = type(model_instance)
         table_name = model_class.get_table_name()
+
         primary_key = model_class.get_primary_key()
 
         fields = ", ".join(