sqliter-py 0.3.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

sqliter/sqliter.py

@@ -1,9 +1,16 @@
-"""This is the main module for the sqliter package."""
+"""Core module for SQLiter, providing the main database interaction class.
+
+This module defines the SqliterDB class, which serves as the primary
+interface for all database operations in SQLiter. It handles connection
+management, table creation, and CRUD operations, bridging the gap between
+Pydantic models and SQLite database interactions.
+"""
 
 from __future__ import annotations
 
+import logging
 import sqlite3
-from typing import TYPE_CHECKING, Optional
+from typing import TYPE_CHECKING, Any, Optional, TypeVar
 
 from typing_extensions import Self
 
@@ -14,8 +21,11 @@ from sqliter.exceptions import (
     RecordInsertionError,
     RecordNotFoundError,
     RecordUpdateError,
+    SqlExecutionError,
     TableCreationError,
+    TableDeletionError,
 )
+from sqliter.helpers import infer_sqlite_type
 from sqliter.query.query import QueryBuilder
 
 if TYPE_CHECKING:  # pragma: no cover
@@ -23,9 +33,21 @@ if TYPE_CHECKING:  # pragma: no cover
 
     from sqliter.model.model import BaseDBModel
 
+T = TypeVar("T", bound="BaseDBModel")
+
 
 class SqliterDB:
-    """Class to manage SQLite database interactions."""
+    """Main class for interacting with SQLite databases.
+
+    This class provides methods for connecting to a SQLite database,
+    creating tables, and performing CRUD operations.
+
+    Arguements:
+        db_filename (str): The filename of the SQLite database.
+        auto_commit (bool): Whether to automatically commit transactions.
+        debug (bool): Whether to enable debug logging.
+        logger (Optional[logging.Logger]): Custom logger for debug output.
+    """
 
     def __init__(
         self,
@@ -33,8 +55,24 @@ class SqliterDB:
         *,
         memory: bool = False,
         auto_commit: bool = True,
+        debug: bool = False,
+        logger: Optional[logging.Logger] = None,
+        reset: bool = False,
     ) -> None:
-        """Initialize the class and options."""
+        """Initialize a new SqliterDB instance.
+
+        Args:
+            db_filename: The filename of the SQLite database.
+            memory: If True, create an in-memory database.
+            auto_commit: Whether to automatically commit transactions.
+            debug: Whether to enable debug logging.
+            logger: Custom logger for debug output.
+            reset: Whether to reset the database on initialization. This will
+                basically drop all existing tables.
+
+        Raises:
+            ValueError: If no filename is provided for a non-memory database.
+        """
         if memory:
             self.db_filename = ":memory:"
         elif db_filename:
@@ -46,10 +84,98 @@ class SqliterDB:
             )
             raise ValueError(err)
         self.auto_commit = auto_commit
+        self.debug = debug
+        self.logger = logger
         self.conn: Optional[sqlite3.Connection] = None
+        self.reset = reset
+
+        if self.debug:
+            self._setup_logger()
+
+        if self.reset:
+            self._reset_database()
+
+    def _reset_database(self) -> None:
+        """Drop all user-created tables in the database."""
+        with self.connect() as conn:
+            cursor = conn.cursor()
+
+            # Get all table names, excluding SQLite system tables
+            cursor.execute(
+                "SELECT name FROM sqlite_master WHERE type='table' "
+                "AND name NOT LIKE 'sqlite_%';"
+            )
+            tables = cursor.fetchall()
+
+            # Drop each user-created table
+            for table in tables:
+                cursor.execute(f"DROP TABLE IF EXISTS {table[0]}")
+
+            conn.commit()
+
+        if self.debug and self.logger:
+            self.logger.debug(
+                "Database reset: %s user-created tables dropped.", len(tables)
+            )
+
+    def _setup_logger(self) -> None:
+        """Set up the logger for debug output.
+
+        This method configures a logger for the SqliterDB instance, either
+        using an existing logger or creating a new one specifically for
+        SQLiter.
+        """
+        # Check if the root logger is already configured
+        root_logger = logging.getLogger()
+
+        if root_logger.hasHandlers():
+            # If the root logger has handlers, use it without modifying the root
+            # configuration
+            self.logger = root_logger.getChild("sqliter")
+        else:
+            # If no root logger is configured, set up a new logger specific to
+            # SqliterDB
+            self.logger = logging.getLogger("sqliter")
+
+            handler = logging.StreamHandler()  # Output to console
+            formatter = logging.Formatter(
+                "%(levelname)-8s%(message)s"
+            )  # Custom format
+            handler.setFormatter(formatter)
+            self.logger.addHandler(handler)
+
+            self.logger.setLevel(logging.DEBUG)
+            self.logger.propagate = False
+
+    def _log_sql(self, sql: str, values: list[Any]) -> None:
+        """Log the SQL query and its values if debug mode is enabled.
+
+        The values are inserted into the SQL query string to replace the
+        placeholders.
+
+        Args:
+            sql: The SQL query string.
+            values: The list of values to be inserted into the query.
+        """
+        if self.debug and self.logger:
+            formatted_sql = sql
+            for value in values:
+                if isinstance(value, str):
+                    formatted_sql = formatted_sql.replace("?", f"'{value}'", 1)
+                else:
+                    formatted_sql = formatted_sql.replace("?", str(value), 1)
+
+            self.logger.debug("Executing SQL: %s", formatted_sql)
 
     def connect(self) -> sqlite3.Connection:
-        """Create or return a connection to the SQLite database."""
+        """Establish a connection to the SQLite database.
+
+        Returns:
+            The SQLite connection object.
+
+        Raises:
+            DatabaseConnectionError: If unable to connect to the database.
+        """
         if not self.conn:
             try:
                 self.conn = sqlite3.connect(self.db_filename)
@@ -58,41 +184,72 @@ class SqliterDB:
         return self.conn
 
     def close(self) -> None:
-        """Close the connection to the SQLite database."""
+        """Close the database connection.
+
+        This method commits any pending changes if auto_commit is True,
+        then closes the connection. If the connection is already closed or does
+        not exist, this method silently does nothing.
+        """
         if self.conn:
             self._maybe_commit()
             self.conn.close()
             self.conn = None
 
     def commit(self) -> None:
-        """Commit any pending transactions."""
+        """Commit the current transaction.
+
+        This method explicitly commits any pending changes to the database.
+        """
         if self.conn:
             self.conn.commit()
 
-    def create_table(self, model_class: type[BaseDBModel]) -> None:
-        """Create a table based on the Pydantic model."""
+    def create_table(
+        self,
+        model_class: type[BaseDBModel],
+        *,
+        exists_ok: bool = True,
+        force: bool = False,
+    ) -> None:
+        """Create a table in the database based on the given model class.
+
+        Args:
+            model_class: The Pydantic model class representing the table.
+            exists_ok: If True, do not raise an error if the table already
+                exists. Default is True which is the original behavior.
+            force: If True, drop the table if it exists before creating.
+                Defaults to False.
+
+        Raises:
+            TableCreationError: If there's an error creating the table.
+            ValueError: If the primary key field is not found in the model.
+        """
         table_name = model_class.get_table_name()
         primary_key = model_class.get_primary_key()
-        create_pk = model_class.should_create_pk()
 
-        fields = ", ".join(
-            f"{field_name} TEXT" for field_name in model_class.model_fields
+        if force:
+            drop_table_sql = f"DROP TABLE IF EXISTS {table_name}"
+            self._execute_sql(drop_table_sql)
+
+        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}")
+
+        create_str = (
+            "CREATE TABLE IF NOT EXISTS" if exists_ok else "CREATE TABLE"
         )
 
-        if create_pk:
-            create_table_sql = f"""
-                CREATE TABLE IF NOT EXISTS {table_name} (
-                    {primary_key} INTEGER PRIMARY KEY AUTOINCREMENT,
-                    {fields}
-                )
-            """
-        else:
-            create_table_sql = f"""
-                CREATE TABLE IF NOT EXISTS {table_name} (
-                    {fields},
-                    PRIMARY KEY ({primary_key})
-                )
-            """
+        create_table_sql = f"""
+        {create_str} {table_name} (
+            {", ".join(fields)}
+        )
+        """
+
+        if self.debug:
+            self._log_sql(create_table_sql, [])
 
         try:
             with self.connect() as conn:
@@ -102,17 +259,80 @@ class SqliterDB:
         except sqlite3.Error as exc:
             raise TableCreationError(table_name) from exc
 
+    def _execute_sql(self, sql: str) -> None:
+        """Execute an SQL statement.
+
+        Args:
+            sql: The SQL statement to execute.
+
+        Raises:
+            SqlExecutionError: If the SQL execution fails.
+        """
+        if self.debug:
+            self._log_sql(sql, [])
+
+        try:
+            with self.connect() as conn:
+                cursor = conn.cursor()
+                cursor.execute(sql)
+                conn.commit()
+        except (sqlite3.Error, sqlite3.Warning) as exc:
+            raise SqlExecutionError(sql) from exc
+
+    def drop_table(self, model_class: type[BaseDBModel]) -> None:
+        """Drop the table associated with the given model class.
+
+        Args:
+            model_class: The model class for which to drop the table.
+
+        Raises:
+            TableDeletionError: If there's an error dropping the table.
+        """
+        table_name = model_class.get_table_name()
+        drop_table_sql = f"DROP TABLE IF EXISTS {table_name}"
+
+        if self.debug:
+            self._log_sql(drop_table_sql, [])
+
+        try:
+            with self.connect() as conn:
+                cursor = conn.cursor()
+                cursor.execute(drop_table_sql)
+                self.commit()
+        except sqlite3.Error as exc:
+            raise TableDeletionError(table_name) from exc
+
     def _maybe_commit(self) -> None:
-        """Commit changes if auto_commit is True."""
+        """Commit changes if auto_commit is enabled.
+
+        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:
             self.conn.commit()
 
-    def insert(self, model_instance: BaseDBModel) -> None:
-        """Insert a new record into the table defined by the Pydantic model."""
+    def insert(self, model_instance: T) -> T:
+        """Insert a new record into the database.
+
+        Args:
+            model_instance: The instance of the model class to insert.
+
+        Returns:
+            The updated model instance with the primary key (pk) set.
+
+        Raises:
+            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()]
@@ -129,13 +349,28 @@ 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 record by its PK and return a Pydantic instance."""
+        """Retrieve a single record from the database by its primary key.
+
+        Args:
+            model_class: The Pydantic model class representing the table.
+            primary_key_value: The value of the primary key to look up.
+
+        Returns:
+            An instance of the model class if found, None otherwise.
+
+        Raises:
+            RecordFetchError: If there's an error fetching the record.
+        """
         table_name = model_class.get_table_name()
         primary_key = model_class.get_primary_key()
 
@@ -163,9 +398,18 @@ class SqliterDB:
             return None
 
     def update(self, model_instance: BaseDBModel) -> None:
-        """Update an existing record using the Pydantic model."""
+        """Update an existing record in the database.
+
+        Args:
+            model_instance: An instance of a Pydantic model to be updated.
+
+        Raises:
+            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(
@@ -203,7 +447,17 @@ class SqliterDB:
     def delete(
         self, model_class: type[BaseDBModel], primary_key_value: str
     ) -> None:
-        """Delete a record by its primary key."""
+        """Delete a record from the database by its primary key.
+
+        Args:
+            model_class: The Pydantic model class representing the table.
+            primary_key_value: The value of the primary key of the record to
+                delete.
+
+        Raises:
+            RecordDeletionError: If there's an error deleting the record.
+            RecordNotFoundError: If the record to delete is not found.
+        """
         table_name = model_class.get_table_name()
         primary_key = model_class.get_primary_key()
 
@@ -228,18 +482,15 @@ class SqliterDB:
         fields: Optional[list[str]] = None,
         exclude: Optional[list[str]] = None,
     ) -> QueryBuilder:
-        """Start a query for the given model.
+        """Create a QueryBuilder instance for selecting records.
 
         Args:
-            model_class: The model class to query.
-            fields: Optional list of field names to select. If None, all fields
-                are selected.
-            exclude: Optional list of field names to exclude from the query
-                output.
+            model_class: The Pydantic model class representing the table.
+            fields: Optional list of fields to include in the query.
+            exclude: Optional list of fields to exclude from the query.
 
         Returns:
-            QueryBuilder: An instance of QueryBuilder for the given model and
-            fields.
+            A QueryBuilder instance for further query construction.
         """
         query_builder = QueryBuilder(self, model_class, fields)
 
@@ -251,7 +502,18 @@ class SqliterDB:
 
     # --- Context manager methods ---
     def __enter__(self) -> Self:
-        """Enter the runtime context for the 'with' statement."""
+        """Enter the runtime context for the SqliterDB instance.
+
+        This method is called when entering a 'with' statement. It ensures
+        that a database connection is established.
+
+        Note that this method should never be called explicitly, but will be
+        called by the 'with' statement when entering the context.
+
+        Returns:
+            The SqliterDB instance.
+
+        """
         self.connect()
         return self
 
@@ -261,7 +523,24 @@ class SqliterDB:
         exc_value: Optional[BaseException],
         traceback: Optional[TracebackType],
     ) -> None:
-        """Exit the runtime context and close the connection."""
+        """Exit the runtime context for the SqliterDB instance.
+
+        This method is called when exiting a 'with' statement. It handles
+        committing or rolling back transactions based on whether an exception
+        occurred, and closes the database connection.
+
+        Args:
+            exc_type: The type of the exception that caused the context to be
+                exited, or None if no exception was raised.
+            exc_value: The instance of the exception that caused the context
+                to be exited, or None if no exception was raised.
+            traceback: A traceback object encoding the stack trace, or None
+                if no exception was raised.
+
+        Note that this method should never be called explicitly, but will be
+        called by the 'with' statement when exiting the context.
+
+        """
         if self.conn:
             try:
                 if exc_type:

sqliter_py-0.5.0.dist-info/METADATA

@@ -0,0 +1,199 @@
+Metadata-Version: 2.3
+Name: sqliter-py
+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
+Project-URL: Changelog, https://github.com/seapagan/sqliter-py/blob/main/CHANGELOG.md
+Project-URL: Repository, https://github.com/seapagan/sqliter-py
+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
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: pydantic>=2.9.0
+Provides-Extra: extras
+Requires-Dist: inflect==7.0.0; extra == 'extras'
+Description-Content-Type: text/markdown
+
+# SQLiter <!-- omit in toc -->
+
+[![PyPI version](https://badge.fury.io/py/sqliter-py.svg)](https://badge.fury.io/py/sqliter-py)
+[![Test Suite](https://github.com/seapagan/sqliter-py/actions/workflows/testing.yml/badge.svg)](https://github.com/seapagan/sqliter-py/actions/workflows/testing.yml)
+[![Linting](https://github.com/seapagan/sqliter-py/actions/workflows/linting.yml/badge.svg)](https://github.com/seapagan/sqliter-py/actions/workflows/linting.yml)
+[![Type Checking](https://github.com/seapagan/sqliter-py/actions/workflows/mypy.yml/badge.svg)](https://github.com/seapagan/sqliter-py/actions/workflows/mypy.yml)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/sqliter-py)
+
+SQLiter is a lightweight Object-Relational Mapping (ORM) library for SQLite
+databases in Python. It provides a simplified interface for interacting with
+SQLite databases using Pydantic models. The only external run-time dependency
+is Pydantic itself.
+
+It does not aim to be a full-fledged ORM like SQLAlchemy, but rather a simple
+and easy-to-use library for basic database operations, especially for small
+projects. It is NOT asynchronous and does not support complex queries (at this
+time).
+
+The ideal use case is more for Python CLI tools that need to store data in a
+database-like format without needing to learn SQL or use a full ORM.
+
+Full documentation is available on the [Documentation
+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)
+- [Installation](#installation)
+  - [Optional Dependencies](#optional-dependencies)
+- [Quick Start](#quick-start)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Features
+
+- Table creation based on Pydantic models
+- CRUD operations (Create, Read, Update, Delete)
+- 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
+  purposes.
+
+## Installation
+
+You can install SQLiter using whichever method you prefer or is compatible with
+your project setup.
+
+With `uv` which is rapidly becoming my favorite tool for managing projects and
+virtual environments (`uv` is used for developing this project and in the CI):
+
+```bash
+uv add sqliter-py
+```
+
+With `pip`:
+
+```bash
+pip install sqliter-py
+```
+
+Or with `Poetry`:
+
+```bash
+poetry add sqliter-py
+```
+
+### Optional Dependencies
+
+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.
+
+See [Installing Optional
+Dependencies](https://sqliter.grantramsay.dev/installation#optional-dependencies)
+for more information.
+
+## Quick Start
+
+Here's a quick example of how to use SQLiter:
+
+```python
+from sqliter import SqliterDB
+from sqliter.model import BaseDBModel
+
+# Define your model
+class User(BaseDBModel):
+    name: str
+    age: int
+
+# Create a database connection
+db = SqliterDB("example.db")
+
+# Create the table
+db.create_table(User)
+
+# Insert a record
+user = User(name="John Doe", age=30)
+new_user = db.insert(user)
+
+# Query records
+results = db.select(User).filter(name="John Doe").fetch_all()
+for user in results:
+    print(f"User: {user.name}, Age: {user.age}")
+
+# Update a record
+new_user.age = 31
+db.update(new_user)
+
+# Delete a record
+db.delete(User, new_user.pk)
+```
+
+See the [Usage](https://sqliter.grantramsay.dev/usage) section of the documentation
+for more detailed information on how to use SQLiter, and advanced features.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+See the [CONTRIBUTING](CONTRIBUTING.md) guide for more information.
+
+Please note that this project is released with a Contributor Code of Conduct,
+which you can read in the [CODE_OF_CONDUCT](CODE_OF_CONDUCT.md) file.
+
+## License
+
+This project is licensed under the MIT License.
+
+```pre
+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.
+```