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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: sqliter-py
-Version: 0.4.0
+Version: 0.6.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.
 
@@ -73,11 +75,15 @@ Website](https://sqliter.grantramsay.dev)
 ## Features
 
 - Table creation based on Pydantic models
+- Automatic primary key generation
+- User defined indexes on any field
+- Set any field as UNIQUE
 - 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
@@ -95,16 +101,16 @@ virtual environments (`uv` is used for developing this project and in the CI):
 uv add sqliter-py
 ```
 
-With `pip`:
+With `Poetry`:
 
 ```bash
-pip install sqliter-py
+poetry add sqliter-py
 ```
 
-Or with `Poetry`:
+Or with `pip`:
 
 ```bash
-poetry add sqliter-py
+pip install sqliter-py
 ```
 
 ### Optional Dependencies
@@ -113,9 +119,9 @@ Currently by default, the only external dependency is Pydantic. However, there
 are some optional dependencies that can be installed to enable additional
 features:
 
-- `inflect`: For pluralizing table names (if not specified). This just offers a
-  more-advanced pluralization than the default method used. In most cases you
-  will not need this.
+- `inflect`: For pluralizing the auto-generated table names (if not explicitly
+  set in the Model) This just offers a more-advanced pluralization than the
+  default method used. In most cases you will not need this.
 
 See [Installing Optional
 Dependencies](https://sqliter.grantramsay.dev/installation#optional-dependencies)
@@ -142,7 +148,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 +156,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.6.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.
 
@@ -45,11 +47,15 @@ Website](https://sqliter.grantramsay.dev)
 ## Features
 
 - Table creation based on Pydantic models
+- Automatic primary key generation
+- User defined indexes on any field
+- Set any field as UNIQUE
 - 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
@@ -67,16 +73,16 @@ virtual environments (`uv` is used for developing this project and in the CI):
 uv add sqliter-py
 ```
 
-With `pip`:
+With `Poetry`:
 
 ```bash
-pip install sqliter-py
+poetry add sqliter-py
 ```
 
-Or with `Poetry`:
+Or with `pip`:
 
 ```bash
-poetry add sqliter-py
+pip install sqliter-py
 ```
 
 ### Optional Dependencies
@@ -85,9 +91,9 @@ Currently by default, the only external dependency is Pydantic. However, there
 are some optional dependencies that can be installed to enable additional
 features:
 
-- `inflect`: For pluralizing table names (if not specified). This just offers a
-  more-advanced pluralization than the default method used. In most cases you
-  will not need this.
+- `inflect`: For pluralizing the auto-generated table names (if not explicitly
+  set in the Model) This just offers a more-advanced pluralization than the
+  default method used. In most cases you will not need this.
 
 See [Installing Optional
 Dependencies](https://sqliter.grantramsay.dev/installation#optional-dependencies)
@@ -114,7 +120,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 +128,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.6.0}/pyproject.toml

@@ -3,7 +3,7 @@
 
 [project]
 name = "sqliter-py"
-version = "0.4.0"
+version = "0.6.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.6.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):
@@ -145,3 +145,24 @@ class SqlExecutionError(SqliterError):
     """Raised when an SQL execution fails."""
 
     message_template = "Failed to execute SQL: '{}'"
+
+
+class InvalidIndexError(SqliterError):
+    """Exception raised when an invalid index field is specified.
+
+    This error is triggered if one or more fields specified for an index
+    do not exist in the model's fields.
+
+    Attributes:
+        invalid_fields (list[str]): The list of fields that were invalid.
+        model_class (str): The name of the model where the error occurred.
+    """
+
+    message_template = "Invalid fields for indexing in model '{}': {}"
+
+    def __init__(self, invalid_fields: list[str], model_class: str) -> None:
+        """Tidy up the error message by joining the invalid fields."""
+        # Join invalid fields into a comma-separated string
+        invalid_fields_str = ", ".join(invalid_fields)
+        # Pass the formatted message to the parent class
+        super().__init__(model_class, invalid_fields_str)

{sqliter_py-0.4.0 → sqliter_py-0.6.0}/sqliter/model/__init__.py

@@ -1,9 +1,11 @@
 """This module provides the base model class for SQLiter database models.
 
 It exports the BaseDBModel class, which is used to define database
-models in SQLiter applications.
+models in SQLiter applications, and the Unique class, which is used to
+define unique constraints on model fields.
 """
 
 from .model import BaseDBModel
+from .unique import Unique
 
-__all__ = ["BaseDBModel"]
+__all__ = ["BaseDBModel", "Unique"]

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

@@ -10,9 +10,18 @@ in SQLiter applications.
 from __future__ import annotations
 
 import re
-from typing import Any, Optional, TypeVar, Union, get_args, get_origin
-
-from pydantic import BaseModel, ConfigDict
+from typing import (
+    Any,
+    ClassVar,
+    Optional,
+    TypeVar,
+    Union,
+    cast,
+    get_args,
+    get_origin,
+)
+
+from pydantic import BaseModel, ConfigDict, Field
 
 T = TypeVar("T", bound="BaseDBModel")
 
@@ -28,6 +37,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,
@@ -39,18 +50,24 @@ class BaseDBModel(BaseModel):
         """Metadata class for configuring database-specific attributes.
 
         Attributes:
-            create_pk (bool): Whether to create a primary key field.
-            primary_key (str): The name of the primary key field.
-            table_name (Optional[str]): The name of the database table.
+            table_name (Optional[str]): The name of the database table. If not
+                specified, the table name will be inferred from the model class
+                name and converted to snake_case.
+            indexes (ClassVar[list[Union[str, tuple[str]]]]): A list of fields
+                or tuples of fields for which regular (non-unique) indexes
+                should be created. Indexes improve query performance on these
+                fields.
+            unique_indexes (ClassVar[list[Union[str, tuple[str]]]]): A list of
+                fields or tuples of fields for which unique indexes should be
+                created. Unique indexes enforce that all values in these fields
+                are distinct across the 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
         )
+        indexes: ClassVar[list[Union[str, tuple[str]]]] = []
+        unique_indexes: ClassVar[list[Union[str, tuple[str]]]] = []
 
     @classmethod
     def model_validate_partial(cls: type[T], obj: dict[str, Any]) -> T:
@@ -89,7 +106,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 +144,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.6.0/sqliter/model/unique.py

@@ -0,0 +1,19 @@
+"""Define a custom field type for unique constraints in SQLiter."""
+
+from typing import Any
+
+from pydantic.fields import FieldInfo
+
+
+class Unique(FieldInfo):
+    """A custom field type for unique constraints in SQLiter."""
+
+    def __init__(self, default: Any = ..., **kwargs: Any) -> None:  # noqa: ANN401
+        """Initialize a Unique field.
+
+        Args:
+            default: The default value for the field.
+            **kwargs: Additional keyword arguments to pass to FieldInfo.
+        """
+        super().__init__(default=default, **kwargs)
+        self.unique = True

{sqliter_py-0.4.0 → sqliter_py-0.6.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.6.0}/sqliter/sqliter.py

@@ -10,12 +10,13 @@ from __future__ import annotations
 
 import logging
 import sqlite3
-from typing import TYPE_CHECKING, Any, Optional
+from typing import TYPE_CHECKING, Any, Optional, TypeVar, Union
 
 from typing_extensions import Self
 
 from sqliter.exceptions import (
     DatabaseConnectionError,
+    InvalidIndexError,
     RecordDeletionError,
     RecordFetchError,
     RecordInsertionError,
@@ -26,6 +27,7 @@ from sqliter.exceptions import (
     TableDeletionError,
 )
 from sqliter.helpers import infer_sqlite_type
+from sqliter.model.unique import Unique
 from sqliter.query.query import QueryBuilder
 
 if TYPE_CHECKING:  # pragma: no cover
@@ -33,6 +35,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.
@@ -87,6 +91,8 @@ class SqliterDB:
         self.conn: Optional[sqlite3.Connection] = None
         self.reset = reset
 
+        self._in_transaction = False
+
         if self.debug:
             self._setup_logger()
 
@@ -223,34 +229,23 @@ 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():
             if field_name != primary_key:
                 sqlite_type = infer_sqlite_type(field_info.annotation)
-                fields.append(f"{field_name} {sqlite_type}")
+                unique_constraint = (
+                    "UNIQUE" if isinstance(field_info, Unique) else ""
+                )
+                fields.append(
+                    f"{field_name} {sqlite_type} {unique_constraint}".strip()
+                )
 
         create_str = (
             "CREATE TABLE IF NOT EXISTS" if exists_ok else "CREATE TABLE"
@@ -273,6 +268,65 @@ class SqliterDB:
         except sqlite3.Error as exc:
             raise TableCreationError(table_name) from exc
 
+        # Create regular indexes
+        if hasattr(model_class.Meta, "indexes"):
+            self._create_indexes(
+                model_class, model_class.Meta.indexes, unique=False
+            )
+
+        # Create unique indexes
+        if hasattr(model_class.Meta, "unique_indexes"):
+            self._create_indexes(
+                model_class, model_class.Meta.unique_indexes, unique=True
+            )
+
+    def _create_indexes(
+        self,
+        model_class: type[BaseDBModel],
+        indexes: list[Union[str, tuple[str]]],
+        *,
+        unique: bool = False,
+    ) -> None:
+        """Helper method to create regular or unique indexes.
+
+        Args:
+            model_class: The model class defining the table.
+            indexes: List of fields or tuples of fields to create indexes for.
+            unique: If True, creates UNIQUE indexes; otherwise, creates regular
+                indexes.
+
+        Raises:
+            InvalidIndexError: If any fields specified for indexing do not exist
+                in the model.
+        """
+        valid_fields = set(
+            model_class.model_fields.keys()
+        )  # Get valid fields from the model
+
+        for index in indexes:
+            # Handle multiple fields in tuple form
+            fields = list(index) if isinstance(index, tuple) else [index]
+
+            # Check if all fields exist in the model
+            invalid_fields = [
+                field for field in fields if field not in valid_fields
+            ]
+            if invalid_fields:
+                raise InvalidIndexError(invalid_fields, model_class.__name__)
+
+            # Build the SQL string
+            index_name = "_".join(fields)
+            index_postfix = "_unique" if unique else ""
+            index_type = " UNIQUE " if unique else " "
+
+            create_index_sql = (
+                f"CREATE{index_type}INDEX IF NOT EXISTS "
+                f"idx_{model_class.get_table_name()}"
+                f"_{index_name}{index_postfix} "
+                f"ON {model_class.get_table_name()} ({', '.join(fields)})"
+            )
+            self._execute_sql(create_index_sql)
+
     def _execute_sql(self, sql: str) -> None:
         """Execute an SQL statement.
 
@@ -322,22 +376,31 @@ class SqliterDB:
         This method is called after operations that modify the database,
         committing changes only if auto_commit is set to True.
         """
-        if self.auto_commit and self.conn:
+        if not self._in_transaction and 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 +417,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 +472,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(
@@ -515,6 +583,7 @@ class SqliterDB:
 
         """
         self.connect()
+        self._in_transaction = True
         return self
 
     def __exit__(
@@ -552,3 +621,4 @@ class SqliterDB:
                 # Close the connection and reset the instance variable
                 self.conn.close()
                 self.conn = None
+                self._in_transaction = False