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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: sqliter-py
-Version: 0.6.0
+Version: 0.7.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
@@ -60,8 +60,7 @@ Website](https://sqliter.grantramsay.dev)
 > 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.
+> `pickled` first then stored as a BLOB in the database.
 >
 > See the [TODO](TODO.md) for planned features and improvements.
 
@@ -75,6 +74,7 @@ Website](https://sqliter.grantramsay.dev)
 ## Features
 
 - Table creation based on Pydantic models
+- Supports `date` and `datetime` fields. List/Dict/Set fields are planned.
 - Automatic primary key generation
 - User defined indexes on any field
 - Set any field as UNIQUE

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

@@ -32,8 +32,7 @@ Website](https://sqliter.grantramsay.dev)
 > 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.
+> `pickled` first then stored as a BLOB in the database.
 >
 > See the [TODO](TODO.md) for planned features and improvements.
 
@@ -47,6 +46,7 @@ Website](https://sqliter.grantramsay.dev)
 ## Features
 
 - Table creation based on Pydantic models
+- Supports `date` and `datetime` fields. List/Dict/Set fields are planned.
 - Automatic primary key generation
 - User defined indexes on any field
 - Set any field as UNIQUE

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

@@ -3,7 +3,7 @@
 
 [project]
 name = "sqliter-py"
-version = "0.6.0"
+version = "0.7.0"
 description = "Interact with SQLite databases using Python and Pydantic"
 readme = "README.md"
 requires-python = ">=3.9"

{sqliter_py-0.6.0 → sqliter_py-0.7.0}/sqliter/constants.py

@@ -6,8 +6,11 @@ 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 = {
     "__lt": "<",
     "__lte": "<=",
@@ -34,4 +37,6 @@ 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
 }

sqliter_py-0.7.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.6.0 → sqliter_py-0.7.0}/sqliter/model/__init__.py

@@ -5,7 +5,7 @@ models in SQLiter applications, and the Unique class, which is used to
 define unique constraints on model fields.
 """
 
-from .model import BaseDBModel
+from .model import BaseDBModel, SerializableField
 from .unique import Unique
 
-__all__ = ["BaseDBModel", "Unique"]
+__all__ = ["BaseDBModel", "Unique", "SerializableField"]

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

@@ -9,11 +9,13 @@ in SQLiter applications.
 
 from __future__ import annotations
 
+import datetime
 import re
 from typing import (
     Any,
     ClassVar,
     Optional,
+    Protocol,
     TypeVar,
     Union,
     cast,
@@ -23,9 +25,15 @@ from typing import (
 
 from pydantic import BaseModel, ConfigDict, Field
 
+from sqliter.helpers import from_unix_timestamp, to_unix_timestamp
+
 T = TypeVar("T", bound="BaseDBModel")
 
 
+class SerializableField(Protocol):
+    """Protocol for fields that can be serialized or deserialized."""
+
+
 class BaseDBModel(BaseModel):
     """Base model class for SQLiter database models.
 
@@ -38,6 +46,14 @@ 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",
@@ -151,3 +167,50 @@ 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)
+        return value  # Return value as-is for non-datetime 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.
+        """
+        field_type = cls.__annotations__.get(field_name)
+
+        if field_type in (datetime.datetime, datetime.date) and isinstance(
+            value, int
+        ):
+            return from_unix_timestamp(
+                value, field_type, localize=return_local_time
+            )
+        return value  # Return value as-is for non-datetime fields

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

@@ -35,7 +35,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 +609,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

{sqliter_py-0.6.0 → sqliter_py-0.7.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
@@ -51,7 +52,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 +63,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 +75,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 +95,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 +105,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:
@@ -379,11 +433,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 +455,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:
@@ -473,24 +554,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/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")