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

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

@@ -1,14 +1,10 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: sqliter-py
-Version: 0.6.0
+Version: 0.10.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: Changelog, https://github.com/seapagan/sqliter-py/blob/main/CHANGELOG.md
-Project-URL: Repository, https://github.com/seapagan/sqliter-py
+Author: Grant Ramsay
 Author-email: Grant Ramsay <grant@gnramsay.com>
 License-Expression: MIT
-License-File: LICENSE.txt
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -18,12 +14,20 @@ 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: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database :: Front-Ends
 Classifier: Topic :: Software Development
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: inflect==7.0.0 ; extra == 'extras'
 Requires-Python: >=3.9
-Requires-Dist: pydantic>=2.9.0
+Project-URL: Bug Tracker, https://github.com/seapagan/sqliter-py/issues
+Project-URL: Changelog, https://github.com/seapagan/sqliter-py/blob/main/CHANGELOG.md
+Project-URL: Homepage, http://sqliter.grantramsay.dev
+Project-URL: Pull Requests, https://github.com/seapagan/sqliter-py/pulls
+Project-URL: Repository, https://github.com/seapagan/sqliter-py
 Provides-Extra: extras
-Requires-Dist: inflect==7.0.0; extra == 'extras'
 Description-Content-Type: text/markdown
 
 # SQLiter <!-- omit in toc -->
@@ -47,22 +51,16 @@ 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.
 
-Full documentation is available on the [Documentation
-Website](https://sqliter.grantramsay.dev)
+Full documentation is available on the [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 - 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. 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.
 
 - [Features](#features)
@@ -75,6 +73,9 @@ Website](https://sqliter.grantramsay.dev)
 ## Features
 
 - Table creation based on Pydantic models
+- Supports `date` and `datetime` fields
+- Support for complex data types (`list`, `dict`, `set`, `tuple`) stored as
+  BLOBs
 - Automatic primary key generation
 - User defined indexes on any field
 - Set any field as UNIQUE
@@ -159,12 +160,16 @@ for user in results:
 new_user.age = 31
 db.update(new_user)
 
-# Delete a record
+# Delete a record by primary key
 db.delete(User, new_user.pk)
+
+# Delete all records returned from a query:
+delete_count = db.select(User).filter(age__gt=30).delete()
 ```
 
-See the [Usage](https://sqliter.grantramsay.dev/usage) section of the documentation
-for more detailed information on how to use SQLiter, and advanced features.
+See the [Guide](https://sqliter.grantramsay.dev/guide/guide/) section of the
+documentation for more detailed information on how to use SQLiter, and advanced
+features.
 
 ## Contributing
 
@@ -180,7 +185,7 @@ which you can read in the [CODE_OF_CONDUCT](CODE_OF_CONDUCT.md) file.
 This project is licensed under the MIT License.
 
 ```pre
-Copyright (c) 2024 Grant Ramsay
+Copyright (c) 2024-2025 Grant Ramsay
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{sqliter_py-0.6.0 → sqliter_py-0.10.0}/README.md

@@ -19,22 +19,16 @@ 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.
 
-Full documentation is available on the [Documentation
-Website](https://sqliter.grantramsay.dev)
+Full documentation is available on the [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 - 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. 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.
 
 - [Features](#features)
@@ -47,6 +41,9 @@ Website](https://sqliter.grantramsay.dev)
 ## Features
 
 - Table creation based on Pydantic models
+- Supports `date` and `datetime` fields
+- Support for complex data types (`list`, `dict`, `set`, `tuple`) stored as
+  BLOBs
 - Automatic primary key generation
 - User defined indexes on any field
 - Set any field as UNIQUE
@@ -131,12 +128,16 @@ for user in results:
 new_user.age = 31
 db.update(new_user)
 
-# Delete a record
+# Delete a record by primary key
 db.delete(User, new_user.pk)
+
+# Delete all records returned from a query:
+delete_count = db.select(User).filter(age__gt=30).delete()
 ```
 
-See the [Usage](https://sqliter.grantramsay.dev/usage) section of the documentation
-for more detailed information on how to use SQLiter, and advanced features.
+See the [Guide](https://sqliter.grantramsay.dev/guide/guide/) section of the
+documentation for more detailed information on how to use SQLiter, and advanced
+features.
 
 ## Contributing
 
@@ -152,7 +153,7 @@ which you can read in the [CODE_OF_CONDUCT](CODE_OF_CONDUCT.md) file.
 This project is licensed under the MIT License.
 
 ```pre
-Copyright (c) 2024 Grant Ramsay
+Copyright (c) 2024-2025 Grant Ramsay
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{sqliter_py-0.6.0 → sqliter_py-0.10.0}/pyproject.toml

@@ -3,13 +3,13 @@
 
 [project]
 name = "sqliter-py"
-version = "0.6.0"
+version = "0.10.0"
 description = "Interact with SQLite databases using Python and Pydantic"
 readme = "README.md"
 requires-python = ">=3.9"
 license = "MIT"
 authors = [{ name = "Grant Ramsay", email = "grant@gnramsay.com" }]
-dependencies = ["pydantic>=2.9.0"]
+dependencies = ["pydantic>=2.12.5"]
 
 classifiers = [
   "Development Status :: 4 - Beta",
@@ -21,6 +21,9 @@ classifiers = [
   "Programming Language :: Python :: 3.10",
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Database :: Front-Ends",
   "Topic :: Software Development",
   "Topic :: Software Development :: Libraries :: Python Modules",
 ]
@@ -29,27 +32,25 @@ classifiers = [
 extras = ["inflect==7.0.0"]
 
 [project.urls]
-# "HomeHage" = "https://xxxxxx"
+"Homepage" = "http://sqliter.grantramsay.dev"
 "Pull Requests" = "https://github.com/seapagan/sqliter-py/pulls"
 "Bug Tracker" = "https://github.com/seapagan/sqliter-py/issues"
 "Changelog" = "https://github.com/seapagan/sqliter-py/blob/main/CHANGELOG.md"
 "Repository" = "https://github.com/seapagan/sqliter-py"
 
 [build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
+requires = ["uv_build>=0.9.9,<0.10.0"]
+build-backend = "uv_build"
 
-[tool.hatch.build.targets.sdist]
-packages = ["sqliter"]
+[tool.uv.build-backend]
+module-name = "sqliter"
+module-root = ""
 
-[tool.hatch.build.targets.wheel]
-packages = ["sqliter"]
-
-[tool.uv]
-dev-dependencies = [
+[dependency-groups]
+dev = [
   "mock>=5.1.0",
   "mypy>=1.11.2",
-  "pytest>=8.3.2",
+  "pytest>=8.3.2,<9.0",
   "pytest-mock>=3.14.0",
   "ruff>=0.6.4",
   "pytest-sugar>=1.0.0",
@@ -100,12 +101,11 @@ changelog.help = "Generate a changelog"
 line-length = 80
 lint.select = ["ALL"] # we are being very strict!
 lint.ignore = [
-  "ANN101",
-  "ANN102",
   "PGH003",
   "FBT002",
   "FBT003",
   "B006",
+  "S301",   # in this library we use 'pickle' for saving and loading list etc
 ] # These rules are too strict even for us 😝
 lint.extend-ignore = [
   "COM812",
@@ -148,6 +148,7 @@ 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.6.0 → sqliter_py-0.10.0}/sqliter/constants.py

@@ -6,6 +6,8 @@ operators and data types, which are crucial for translating between
 Pydantic models and SQLite database operations.
 """
 
+import datetime
+
 # A dictionary mapping SQLiter filter operators to their corresponding SQL
 # operators.
 OPERATOR_MAPPING = {
@@ -34,4 +36,10 @@ SQLITE_TYPE_MAPPING = {
     str: "TEXT",
     bool: "INTEGER",  # SQLite stores booleans as integers (0 or 1)
     bytes: "BLOB",
+    datetime.datetime: "INTEGER",  # Store as Unix timestamp
+    datetime.date: "INTEGER",  # Store as Unix timestamp
+    list: "BLOB",
+    dict: "BLOB",
+    set: "BLOB",
+    tuple: "BLOB",
 }

sqliter_py-0.10.0/sqliter/helpers.py

@@ -0,0 +1,100 @@
+"""Utility functions for SQLiter internal operations.
+
+This module provides helper functions used across the SQLiter library,
+primarily for type inference and mapping between Python and SQLite
+data types. These utilities support the core functionality of model
+to database schema translation.
+"""
+
+from __future__ import annotations
+
+import datetime
+from typing import Union
+
+from sqliter.constants import SQLITE_TYPE_MAPPING
+
+
+def infer_sqlite_type(field_type: Union[type, None]) -> str:
+    """Infer the SQLite column type based on the Python type.
+
+    This function maps Python types to their corresponding SQLite column
+    types. It's used when creating database tables to ensure that the
+    correct SQLite types are used for each field.
+
+    Args:
+        field_type: The Python type of the field, or None.
+
+    Returns:
+        A string representing the corresponding SQLite column type.
+
+    Note:
+        If the input type is None or not recognized, it defaults to 'TEXT'.
+    """
+    # If field_type is None, default to TEXT
+    if field_type is None:
+        return "TEXT"
+
+    # Map the simplified type to an SQLite type
+    return SQLITE_TYPE_MAPPING.get(field_type, "TEXT")
+
+
+def to_unix_timestamp(value: datetime.date | datetime.datetime) -> int:
+    """Convert datetime or date to a Unix timestamp in UTC.
+
+    Args:
+        value: The datetime or date object to convert.
+
+    Returns:
+        An integer Unix timestamp.
+
+    Raises:
+        TypeError: If the value is not a datetime or date object.
+    """
+    if isinstance(value, datetime.datetime):
+        # If no timezone is provided, assume local time and convert to UTC
+        if value.tzinfo is None:
+            value = value.astimezone()  # Convert to user's local timezone
+        # Convert to UTC before storing
+        value = value.astimezone(datetime.timezone.utc)
+        return int(value.timestamp())
+    if isinstance(value, datetime.date):
+        # Convert date to datetime at midnight in UTC
+        dt = datetime.datetime.combine(
+            value, datetime.time(0, 0), tzinfo=datetime.timezone.utc
+        )
+        return int(dt.timestamp())
+
+    err_msg = "Expected datetime or date object."
+    raise TypeError(err_msg)
+
+
+def from_unix_timestamp(
+    value: int, to_type: type, *, localize: bool = True
+) -> datetime.date | datetime.datetime:
+    """Convert a Unix timestamp to datetime or date, optionally to local time.
+
+    Args:
+        value: The Unix timestamp as an integer.
+        to_type: The expected output type, either datetime or date.
+        localize: If True, convert the datetime to the user's local timezone.
+
+    Returns:
+        The corresponding datetime or date object.
+
+    Raises:
+        TypeError: If to_type is not datetime or date.
+    """
+    if to_type is datetime.datetime:
+        # Convert the Unix timestamp to UTC datetime
+        dt = datetime.datetime.fromtimestamp(value, tz=datetime.timezone.utc)
+        # Convert to local time if requested
+        return dt.astimezone() if localize else dt
+    if to_type is datetime.date:
+        # Convert to UTC datetime first
+        dt = datetime.datetime.fromtimestamp(value, tz=datetime.timezone.utc)
+        # Convert to local time if requested, then return the date part
+        dt_local = dt.astimezone() if localize else dt
+        return dt_local.date()  # Extract the date part
+
+    err_msg = "Expected datetime or date type."
+    raise TypeError(err_msg)

sqliter_py-0.10.0/sqliter/model/__init__.py

@@ -0,0 +1,37 @@
+"""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, and the unique function, which is used to
+define unique constraints on model fields.
+"""
+
+import warnings
+from typing import Any
+
+from typing_extensions import deprecated
+
+from .model import BaseDBModel, SerializableField
+from .unique import unique
+
+
+@deprecated("Use 'unique' instead. Will be removed in a future version.")
+def Unique(default: Any = ..., **kwargs: Any) -> Any:  # noqa: ANN401, N802
+    """Deprecated: Use 'unique' instead. Will be removed in a future version.
+
+    Args:
+        default: The default value for the field.
+        **kwargs: Additional keyword arguments to pass to Field.
+
+    Returns:
+        A Field with unique metadata attached.
+    """
+    warnings.warn(
+        "Unique is deprecated and will be removed in a future version. "
+        "Use 'unique' instead.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return unique(default=default, **kwargs)
+
+
+__all__ = ["BaseDBModel", "SerializableField", "Unique", "unique"]

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

@@ -9,12 +9,14 @@ in SQLiter applications.
 
 from __future__ import annotations
 
+import datetime
+import pickle
 import re
 from typing import (
     Any,
     ClassVar,
     Optional,
-    TypeVar,
+    Protocol,
     Union,
     cast,
     get_args,
@@ -22,8 +24,13 @@ from typing import (
 )
 
 from pydantic import BaseModel, ConfigDict, Field
+from typing_extensions import Self
 
-T = TypeVar("T", bound="BaseDBModel")
+from sqliter.helpers import from_unix_timestamp, to_unix_timestamp
+
+
+class SerializableField(Protocol):
+    """Protocol for fields that can be serialized or deserialized."""
 
 
 class BaseDBModel(BaseModel):
@@ -38,11 +45,19 @@ class BaseDBModel(BaseModel):
     """
 
     pk: int = Field(0, description="The mandatory primary key of the table.")
+    created_at: int = Field(
+        default=0,
+        description="Unix timestamp when the record was created.",
+    )
+    updated_at: int = Field(
+        default=0,
+        description="Unix timestamp when the record was last updated.",
+    )
 
     model_config = ConfigDict(
         extra="ignore",
         populate_by_name=True,
-        validate_assignment=False,
+        validate_assignment=True,
         from_attributes=True,
     )
 
@@ -70,7 +85,7 @@ class BaseDBModel(BaseModel):
         unique_indexes: ClassVar[list[Union[str, tuple[str]]]] = []
 
     @classmethod
-    def model_validate_partial(cls: type[T], obj: dict[str, Any]) -> T:
+    def model_validate_partial(cls, obj: dict[str, Any]) -> Self:
         """Validate and create a model instance from partial data.
 
         This method allows for the creation of a model instance even when
@@ -106,7 +121,7 @@ class BaseDBModel(BaseModel):
                 else:
                     converted_obj[field_name] = field_type(value)
 
-        return cast(T, cls.model_construct(**converted_obj))
+        return cast("Self", cls.model_construct(**converted_obj))
 
     @classmethod
     def get_table_name(cls) -> str:
@@ -130,7 +145,7 @@ class BaseDBModel(BaseModel):
 
         # Pluralize the table name
         try:
-            import inflect
+            import inflect  # noqa: PLC0415
 
             p = inflect.engine()
             return p.plural(snake_case_name)
@@ -151,3 +166,71 @@ class BaseDBModel(BaseModel):
     def should_create_pk(cls) -> bool:
         """Returns True since the primary key is always created."""
         return True
+
+    @classmethod
+    def serialize_field(cls, value: SerializableField) -> SerializableField:
+        """Serialize datetime or date fields to Unix timestamp.
+
+        Args:
+            field_name: The name of the field.
+            value: The value of the field.
+
+        Returns:
+            An integer Unix timestamp if the field is a datetime or date.
+        """
+        if isinstance(value, (datetime.datetime, datetime.date)):
+            return to_unix_timestamp(value)
+        if isinstance(value, (list, dict, set, tuple)):
+            return pickle.dumps(value)
+        return value  # Return value as-is for other fields
+
+    # Deserialization after fetching from the database
+
+    @classmethod
+    def deserialize_field(
+        cls,
+        field_name: str,
+        value: SerializableField,
+        *,
+        return_local_time: bool,
+    ) -> object:
+        """Deserialize fields from Unix timestamp to datetime or date.
+
+        Args:
+            field_name: The name of the field being deserialized.
+            value: The Unix timestamp value fetched from the database.
+            return_local_time: Flag to control whether the datetime is localized
+                to the user's timezone.
+
+        Returns:
+            A datetime or date object if the field type is datetime or date,
+            otherwise returns the value as-is.
+        """
+        if value is None:
+            return None
+
+        # Get field type if it exists in model_fields
+        field_info = cls.model_fields.get(field_name)
+        if field_info is None:
+            # If field doesn't exist in model, return value as-is
+            return value
+
+        field_type = field_info.annotation
+
+        if (
+            isinstance(field_type, type)
+            and issubclass(field_type, (datetime.datetime, datetime.date))
+            and isinstance(value, int)
+        ):
+            return from_unix_timestamp(
+                value, field_type, localize=return_local_time
+            )
+
+        origin_type = get_origin(field_type) or field_type
+        if origin_type in (list, dict, set, tuple) and isinstance(value, bytes):
+            try:
+                return pickle.loads(value)
+            except pickle.UnpicklingError:
+                return value
+
+        return value

sqliter_py-0.10.0/sqliter/model/unique.py

@@ -0,0 +1,28 @@
+"""Define a custom field type for unique constraints in SQLiter."""
+
+from typing import Any
+
+from pydantic import Field
+
+
+def unique(default: Any = ..., **kwargs: Any) -> Any:  # noqa: ANN401
+    """A custom field type for unique constraints in SQLiter.
+
+    Args:
+        default: The default value for the field.
+        **kwargs: Additional keyword arguments to pass to Field.
+
+    Returns:
+        A Field with unique metadata attached.
+    """
+    # Extract any existing json_schema_extra from kwargs
+    existing_extra = kwargs.pop("json_schema_extra", {})
+
+    # Ensure it's a dict
+    if not isinstance(existing_extra, dict):
+        existing_extra = {}
+
+    # Add our unique marker to json_schema_extra
+    existing_extra["unique"] = True
+
+    return Field(default=default, json_schema_extra=existing_extra, **kwargs)

{sqliter_py-0.6.0 → sqliter_py-0.10.0}/sqliter/query/query.py

@@ -28,6 +28,7 @@ from sqliter.exceptions import (
     InvalidFilterError,
     InvalidOffsetError,
     InvalidOrderError,
+    RecordDeletionError,
     RecordFetchError,
 )
 
@@ -35,7 +36,7 @@ if TYPE_CHECKING:  # pragma: no cover
     from pydantic.fields import FieldInfo
 
     from sqliter import SqliterDB
-    from sqliter.model import BaseDBModel
+    from sqliter.model import BaseDBModel, SerializableField
 
 # Define a type alias for the possible value types
 FilterValue = Union[
@@ -609,14 +610,32 @@ class QueryBuilder:
             An instance of the model class populated with the row data.
         """
         if self._fields:
-            return self.model_class.model_validate_partial(
-                {field: row[idx] for idx, field in enumerate(self._fields)}
-            )
-        return self.model_class(
-            **{
-                field: row[idx]
-                for idx, field in enumerate(self.model_class.model_fields)
+            data = {
+                field: self._deserialize(field, row[idx])
+                for idx, field in enumerate(self._fields)
             }
+            return self.model_class.model_validate_partial(data)
+
+        data = {
+            field: self._deserialize(field, row[idx])
+            for idx, field in enumerate(self.model_class.model_fields)
+        }
+        return self.model_class(**data)
+
+    def _deserialize(
+        self, field_name: str, value: SerializableField
+    ) -> SerializableField:
+        """Deserialize a field value if needed.
+
+        Args:
+            field_name: Name of the field being deserialized.
+            value: Value from the database.
+
+        Returns:
+            The deserialized value.
+        """
+        return self.model_class.deserialize_field(
+            field_name, value, return_local_time=self.db.return_local_time
         )
 
     @overload
@@ -710,3 +729,34 @@ class QueryBuilder:
             True if at least one result exists, False otherwise.
         """
         return self.count() > 0
+
+    def delete(self) -> int:
+        """Delete records that match the current query conditions.
+
+        Returns:
+            The number of records deleted.
+
+        Raises:
+            RecordDeletionError: If there's an error deleting the records.
+        """
+        sql = f'DELETE FROM "{self.table_name}"'  # noqa: S608 # nosec
+
+        # Build the WHERE clause with special handling for None (NULL in SQL)
+        values, where_clause = self._parse_filter()
+
+        if self.filters:
+            sql += f" WHERE {where_clause}"
+
+        # Print the raw SQL and values if debug is enabled
+        if self.db.debug:
+            self.db._log_sql(sql, values)  # noqa: SLF001
+
+        try:
+            with self.db.connect() as conn:
+                cursor = conn.cursor()
+                cursor.execute(sql, values)
+                deleted_count = cursor.rowcount
+                self.db._maybe_commit()  # noqa: SLF001
+                return deleted_count
+        except sqlite3.Error as exc:
+            raise RecordDeletionError(self.table_name) from exc

{sqliter_py-0.6.0 → sqliter_py-0.10.0}/sqliter/sqliter.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 
 import logging
 import sqlite3
+import time
 from typing import TYPE_CHECKING, Any, Optional, TypeVar, Union
 
 from typing_extensions import Self
@@ -27,7 +28,6 @@ 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
@@ -51,7 +51,9 @@ class SqliterDB:
         logger (Optional[logging.Logger]): Custom logger for debug output.
     """
 
-    def __init__(
+    MEMORY_DB = ":memory:"
+
+    def __init__(  # noqa: PLR0913
         self,
         db_filename: Optional[str] = None,
         *,
@@ -60,6 +62,7 @@ class SqliterDB:
         debug: bool = False,
         logger: Optional[logging.Logger] = None,
         reset: bool = False,
+        return_local_time: bool = True,
     ) -> None:
         """Initialize a new SqliterDB instance.
 
@@ -71,12 +74,13 @@ class SqliterDB:
             logger: Custom logger for debug output.
             reset: Whether to reset the database on initialization. This will
                 basically drop all existing tables.
+            return_local_time: Whether to return local time for datetime fields.
 
         Raises:
             ValueError: If no filename is provided for a non-memory database.
         """
         if memory:
-            self.db_filename = ":memory:"
+            self.db_filename = self.MEMORY_DB
         elif db_filename:
             self.db_filename = db_filename
         else:
@@ -90,6 +94,7 @@ class SqliterDB:
         self.logger = logger
         self.conn: Optional[sqlite3.Connection] = None
         self.reset = reset
+        self.return_local_time = return_local_time
 
         self._in_transaction = False
 
@@ -99,6 +104,54 @@ class SqliterDB:
         if self.reset:
             self._reset_database()
 
+    @property
+    def filename(self) -> Optional[str]:
+        """Returns the filename of the current database or None if in-memory."""
+        return None if self.db_filename == self.MEMORY_DB else self.db_filename
+
+    @property
+    def is_memory(self) -> bool:
+        """Returns True if the database is in-memory."""
+        return self.db_filename == self.MEMORY_DB
+
+    @property
+    def is_autocommit(self) -> bool:
+        """Returns True if auto-commit is enabled."""
+        return self.auto_commit
+
+    @property
+    def is_connected(self) -> bool:
+        """Returns True if the database is connected, False otherwise."""
+        return self.conn is not None
+
+    @property
+    def table_names(self) -> list[str]:
+        """Returns a list of all table names in the database.
+
+        Temporarily connects to the database if not connected and restores
+        the connection state afterward.
+        """
+        was_connected = self.is_connected
+        if not was_connected:
+            self.connect()
+
+        if self.conn is None:
+            err_msg = "Failed to establish a database connection."
+            raise DatabaseConnectionError(err_msg)
+
+        cursor = self.conn.cursor()
+        cursor.execute(
+            "SELECT name FROM sqlite_master WHERE type='table' "
+            "AND name NOT LIKE 'sqlite_%';"
+        )
+        tables = [row[0] for row in cursor.fetchall()]
+
+        # Restore the connection state
+        if not was_connected:
+            self.close()
+
+        return tables
+
     def _reset_database(self) -> None:
         """Drop all user-created tables in the database."""
         with self.connect() as conn:
@@ -240,9 +293,16 @@ class SqliterDB:
         for field_name, field_info in model_class.model_fields.items():
             if field_name != primary_key:
                 sqlite_type = infer_sqlite_type(field_info.annotation)
-                unique_constraint = (
-                    "UNIQUE" if isinstance(field_info, Unique) else ""
-                )
+                unique_constraint = ""
+                if (
+                    (
+                        hasattr(field_info, "json_schema_extra")
+                        and field_info.json_schema_extra
+                    )
+                    and isinstance(field_info.json_schema_extra, dict)
+                    and field_info.json_schema_extra.get("unique", False)
+                ):
+                    unique_constraint = "UNIQUE"
                 fields.append(
                     f"{field_name} {sqlite_type} {unique_constraint}".strip()
                 )
@@ -379,11 +439,18 @@ class SqliterDB:
         if not self._in_transaction and self.auto_commit and self.conn:
             self.conn.commit()
 
-    def insert(self, model_instance: T) -> T:
+    def insert(
+        self, model_instance: T, *, timestamp_override: bool = False
+    ) -> T:
         """Insert a new record into the database.
 
         Args:
             model_instance: The instance of the model class to insert.
+            timestamp_override: If True, override the created_at and updated_at
+                timestamps with provided values. Default is False. If the values
+                are not provided, they will be set to the current time as
+                normal. Without this flag, the timestamps will always be set to
+                the current time, even if provided.
 
         Returns:
             The updated model instance with the primary key (pk) set.
@@ -394,8 +461,28 @@ class SqliterDB:
         model_class = type(model_instance)
         table_name = model_class.get_table_name()
 
+        # Always set created_at and updated_at timestamps
+        current_timestamp = int(time.time())
+
+        # Handle the case where timestamp_override is False
+        if not timestamp_override:
+            # Always override both timestamps with the current time
+            model_instance.created_at = current_timestamp
+            model_instance.updated_at = current_timestamp
+        else:
+            # Respect provided values, but set to current time if they are 0
+            if model_instance.created_at == 0:
+                model_instance.created_at = current_timestamp
+            if model_instance.updated_at == 0:
+                model_instance.updated_at = current_timestamp
+
         # Get the data from the model
         data = model_instance.model_dump()
+
+        # Serialize the data
+        for field_name, value in list(data.items()):
+            data[field_name] = model_instance.serialize_field(value)
+
         # 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:
@@ -422,7 +509,13 @@ class SqliterDB:
             raise RecordInsertionError(table_name) from exc
         else:
             data.pop("pk", None)
-            return model_class(pk=cursor.lastrowid, **data)
+            # Deserialize each field before creating the model instance
+            deserialized_data = {}
+            for field_name, value in data.items():
+                deserialized_data[field_name] = model_class.deserialize_field(
+                    field_name, value, return_local_time=self.return_local_time
+                )
+            return model_class(pk=cursor.lastrowid, **deserialized_data)
 
     def get(
         self, model_class: type[BaseDBModel], primary_key_value: int
@@ -459,7 +552,17 @@ class SqliterDB:
                     field: result[idx]
                     for idx, field in enumerate(model_class.model_fields)
                 }
-                return model_class(**result_dict)
+                # Deserialize each field before creating the model instance
+                deserialized_data = {}
+                for field_name, value in result_dict.items():
+                    deserialized_data[field_name] = (
+                        model_class.deserialize_field(
+                            field_name,
+                            value,
+                            return_local_time=self.return_local_time,
+                        )
+                    )
+                return model_class(**deserialized_data)
         except sqlite3.Error as exc:
             raise RecordFetchError(table_name) from exc
         else:
@@ -473,24 +576,27 @@ class SqliterDB:
 
         Raises:
             RecordUpdateError: If there's an error updating the record or if it
-            is not found.
+                is not found.
         """
         model_class = type(model_instance)
         table_name = model_class.get_table_name()
-
         primary_key = model_class.get_primary_key()
 
-        fields = ", ".join(
-            f"{field} = ?"
-            for field in model_class.model_fields
-            if field != primary_key
-        )
-        values = tuple(
-            getattr(model_instance, field)
-            for field in model_class.model_fields
-            if field != primary_key
-        )
-        primary_key_value = getattr(model_instance, primary_key)
+        # Set updated_at timestamp
+        current_timestamp = int(time.time())
+        model_instance.updated_at = current_timestamp
+
+        # Get the data and serialize any datetime/date fields
+        data = model_instance.model_dump()
+        for field_name, value in list(data.items()):
+            data[field_name] = model_instance.serialize_field(value)
+
+        # Remove the primary key from the update data
+        primary_key_value = data.pop(primary_key)
+
+        # Create the SQL using the processed data
+        fields = ", ".join(f"{field} = ?" for field in data)
+        values = tuple(data.values())
 
         update_sql = f"""
             UPDATE {table_name}

sqliter_py-0.6.0/.gitignore

@@ -1,222 +0,0 @@
-# File created using '.gitignore Generator' for Visual Studio Code: https://bit.ly/vscode-gig
-# Created by https://www.toptal.com/developers/gitignore/api/visualstudiocode,linux,python
-# Edit at https://www.toptal.com/developers/gitignore?templates=visualstudiocode,linux,python
-
-### Linux ###
-*~
-
-# temporary files which can be created if a process still has a handle open of a deleted file
-.fuse_hidden*
-
-# KDE directory preferences
-.directory
-
-# Linux trash folder which might appear on any partition or disk
-.Trash-*
-
-# .nfs files are created when an open file is removed but is still being accessed
-.nfs*
-
-### Python ###
-# Byte-compiled / optimized / DLL files
-__pycache__/
-*.py[cod]
-*$py.class
-
-# C extensions
-*.so
-
-# Distribution / packaging
-.Python
-build/
-develop-eggs/
-dist/
-downloads/
-eggs/
-.eggs/
-lib/
-lib64/
-parts/
-sdist/
-var/
-wheels/
-share/python-wheels/
-*.egg-info/
-.installed.cfg
-*.egg
-MANIFEST
-
-# PyInstaller
-#  Usually these files are written by a python script from a template
-#  before PyInstaller builds the exe, so as to inject date/other infos into it.
-*.manifest
-*.spec
-
-# Installer logs
-pip-log.txt
-pip-delete-this-directory.txt
-
-# Unit test / coverage reports
-htmlcov/
-.tox/
-.nox/
-.coverage
-.coverage.*
-.cache
-nosetests.xml
-coverage.xml
-coverage.lcov
-*.cover
-*.py,cover
-.hypothesis/
-.pytest_cache/
-cover/
-
-# Translations
-*.mo
-*.pot
-
-# Django stuff:
-*.log
-local_settings.py
-db.sqlite3
-db.sqlite3-journal
-
-# Flask stuff:
-instance/
-.webassets-cache
-
-# Scrapy stuff:
-.scrapy
-
-# Sphinx documentation
-docs/_build/
-
-# PyBuilder
-.pybuilder/
-target/
-
-# Jupyter Notebook
-.ipynb_checkpoints
-
-# IPython
-profile_default/
-ipython_config.py
-
-# pyenv
-#   For a library or package, you might want to ignore these files since the code is
-#   intended to run in multiple environments; otherwise, check them in:
-# .python-version
-
-# pipenv
-#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
-#   However, in case of collaboration, if having platform-specific dependencies or dependencies
-#   having no cross-platform support, pipenv may install dependencies that don't work, or not
-#   install all needed dependencies.
-#Pipfile.lock
-
-# poetry
-#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
-#   This is especially recommended for binary packages to ensure reproducibility, and is more
-#   commonly ignored for libraries.
-#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
-#poetry.lock
-
-# pdm
-#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
-#pdm.lock
-#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
-#   in version control.
-#   https://pdm.fming.dev/#use-with-ide
-.pdm.toml
-
-# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
-__pypackages__/
-
-# Celery stuff
-celerybeat-schedule
-celerybeat.pid
-
-# SageMath parsed files
-*.sage.py
-
-# Environments
-.env
-.venv
-env/
-venv/
-ENV/
-env.bak/
-venv.bak/
-
-# Spyder project settings
-.spyderproject
-.spyproject
-
-# Rope project settings
-.ropeproject
-
-# mkdocs documentation
-/site
-
-# mypy
-.mypy_cache/
-.dmypy.json
-dmypy.json
-
-# Pyre type checker
-.pyre/
-
-# pytype static type analyzer
-.pytype/
-
-# Cython debug symbols
-cython_debug/
-
-# PyCharm
-#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
-#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
-#  and can be added to the global gitignore or merged into this file.  For a more nuclear
-#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
-#.idea/
-
-### Python Patch ###
-# Poetry local configuration file - https://python-poetry.org/docs/configuration/#local-configuration
-poetry.toml
-
-# ruff
-.ruff_cache/
-
-# LSP config files
-pyrightconfig.json
-
-### VisualStudioCode ###
-.vscode/*
-!.vscode/settings.json
-!.vscode/tasks.json
-!.vscode/launch.json
-!.vscode/extensions.json
-!.vscode/*.code-snippets
-
-# Local History for Visual Studio Code
-.history/
-
-# Built Visual Studio Code Extensions
-*.vsix
-
-### VisualStudioCode Patch ###
-# Ignore all local history of files
-.history
-.ionide
-
-# End of https://www.toptal.com/developers/gitignore/api/visualstudiocode,linux,python
-
-# Custom rules (everything added below won't be overriden by 'Generate .gitignore File' if you use 'Update' option)
-
-.python-version
-*.db
-.vscode
-.changelog_generator.toml
-repopack-output.xml
-.envrc
-demo-db

sqliter_py-0.6.0/LICENSE.txt

@@ -1,20 +0,0 @@
-The MIT License (MIT)
-Copyright (c) 2024 Grant Ramsay
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
-DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
-OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
-OR OTHER DEALINGS IN THE SOFTWARE.

sqliter_py-0.6.0/sqliter/helpers.py

@@ -1,35 +0,0 @@
-"""Utility functions for SQLiter internal operations.
-
-This module provides helper functions used across the SQLiter library,
-primarily for type inference and mapping between Python and SQLite
-data types. These utilities support the core functionality of model
-to database schema translation.
-"""
-
-from typing import Union
-
-from sqliter.constants import SQLITE_TYPE_MAPPING
-
-
-def infer_sqlite_type(field_type: Union[type, None]) -> str:
-    """Infer the SQLite column type based on the Python type.
-
-    This function maps Python types to their corresponding SQLite column
-    types. It's used when creating database tables to ensure that the
-    correct SQLite types are used for each field.
-
-    Args:
-        field_type: The Python type of the field, or None.
-
-    Returns:
-        A string representing the corresponding SQLite column type.
-
-    Note:
-        If the input type is None or not recognized, it defaults to 'TEXT'.
-    """
-    # If field_type is None, default to TEXT
-    if field_type is None:
-        return "TEXT"
-
-    # Map the simplified type to an SQLite type
-    return SQLITE_TYPE_MAPPING.get(field_type, "TEXT")

sqliter_py-0.6.0/sqliter/model/__init__.py

@@ -1,11 +0,0 @@
-"""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, and the Unique class, which is used to
-define unique constraints on model fields.
-"""
-
-from .model import BaseDBModel
-from .unique import Unique
-
-__all__ = ["BaseDBModel", "Unique"]

sqliter_py-0.6.0/sqliter/model/unique.py

@@ -1,19 +0,0 @@
-"""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