SQLitey 0.1.0__tar.gz → 0.1.1__tar.gz

sqlitey-0.1.1/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: SQLitey
+Version: 0.1.1
+Summary: Useful wrapper around SQLite
+License: The MIT License (MIT)
+        
+        Copyright (c) 2025 Matthieu Petiteau
+        
+        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.
+License-File: LICENSE
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# SQLitey
+
+SQLitey is a lightweight and flexible wrapper around SQLite, designed to streamline database access using configuration files, SQL templates, and custom row factories.
+
+Key Features:
+- Configuration-driven setup for database paths and SQL templates
+- Support for SQL template files to keep queries organized
+- Customizable row factories (e.g., return rows as namedtuples)
+- Support for both templated and raw SQL queries
+- Optional config usage for quick, one-off database access
+
+## Installation
+
+```
+pip install sqlitey
+```
+
+## Quick Start
+
+```python
+from sqlitey import Db, Sql
+
+with Db("mydb.sqlite") as db:
+    db.commit(Sql.raw("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)"))
+    db.commit(Sql.raw("INSERT INTO users (name) VALUES (?)"), ("Alice",))
+    user = db.fetchone(Sql.raw("SELECT * FROM users WHERE id = ?"), (1,))
+    print(user)  # (1, 'Alice')
+```
+
+## Usage
+
+### Row Factories
+
+Return rows as dictionaries or namedtuples instead of tuples:
+
+```python
+from sqlitey import Db, Sql, dict_factory, namedtuple_factory
+
+with Db("mydb.sqlite", row_factory=dict_factory) as db:
+    user = db.fetchone(Sql.raw("SELECT * FROM users WHERE id = ?"), (1,))
+    print(user["name"])  # 'Alice'
+
+with Db("mydb.sqlite", row_factory=namedtuple_factory) as db:
+    user = db.fetchone(Sql.raw("SELECT * FROM users WHERE id = ?"), (1,))
+    print(user.name)  # 'Alice'
+```
+
+### SQL Templates
+
+Keep SQL queries in separate files for better organization:
+
+```python
+from pathlib import Path
+from sqlitey import Db, DbPathConfig, Sql
+
+config = DbPathConfig(
+    database=Path("mydb.sqlite"),
+    sql_templates_dir=Path("sql/"),
+)
+
+with Db.from_config(config) as db:
+    # Loads query from sql/get_user_by_id.sql
+    user = db.fetchone(Sql.template("get_user_by_id.sql"), (1,))
+```
+
+Or specify the template path directly:
+
+```python
+with Db("mydb.sqlite") as db:
+    sql = Sql.template("get_user_by_id.sql", path=Path("sql/"))
+    user = db.fetchone(sql, (1,))
+```
+
+### Autocommit Mode
+
+Disable transaction management for auto-committing each statement:
+
+```python
+with Db("mydb.sqlite", autocommit=True) as db:
+    db.execute(Sql.raw("UPDATE users SET name = ? WHERE id = ?"), ("Bob", 1))
+```
+
+### Batch Operations
+
+Execute multiple parameter sets or run SQL scripts:
+
+```python
+with Db("mydb.sqlite", autocommit=True) as db:
+    # Execute same query with multiple parameter sets
+    users = [("Alice",), ("Bob",), ("Charlie",)]
+    db.executemany(Sql.raw("INSERT INTO users (name) VALUES (?)"), users)
+
+    # Execute multiple statements as a script
+    db.executescript(Sql.raw("""
+        DELETE FROM users WHERE id = 1;
+        UPDATE users SET name = 'Robert' WHERE name = 'Bob';
+    """))
+```
+
+## API Reference
+
+### Sql
+
+| Method | Description |
+|--------|-------------|
+| `Sql.raw(query)` | Create a Sql instance from an inline query string |
+| `Sql.template(filename, path=None)` | Create a Sql instance from a template file |
+
+### Db
+
+| Method | Description |
+|--------|-------------|
+| `Db(path, row_factory=None, sql_templates_dir=None, autocommit=False)` | Create a database connection |
+| `Db.from_config(config, **kwargs)` | Create from a `DbPathConfig` |
+| `execute(sql, *args)` | Execute a query and return the cursor |
+| `executemany(sql, *args)` | Execute a query against multiple parameter sets |
+| `executescript(sql)` | Execute multiple statements as a script |
+| `fetchone(sql, *args)` | Execute and return the first row |
+| `fetchall(sql, *args)` | Execute and return all rows |
+| `commit(sql, *args)` | Execute and commit the transaction |
+
+### Row Factories
+
+| Factory | Description |
+|---------|-------------|
+| `dict_factory` | Return rows as dictionaries |
+| `namedtuple_factory` | Return rows as namedtuples |
+
+## More Examples
+
+See the [test suite](https://github.com/smallwat3r/sqlitey/blob/main/tests/test_sqlitey.py) for more examples.

sqlitey-0.1.1/README.md

@@ -0,0 +1,131 @@
+# SQLitey
+
+SQLitey is a lightweight and flexible wrapper around SQLite, designed to streamline database access using configuration files, SQL templates, and custom row factories.
+
+Key Features:
+- Configuration-driven setup for database paths and SQL templates
+- Support for SQL template files to keep queries organized
+- Customizable row factories (e.g., return rows as namedtuples)
+- Support for both templated and raw SQL queries
+- Optional config usage for quick, one-off database access
+
+## Installation
+
+```
+pip install sqlitey
+```
+
+## Quick Start
+
+```python
+from sqlitey import Db, Sql
+
+with Db("mydb.sqlite") as db:
+    db.commit(Sql.raw("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)"))
+    db.commit(Sql.raw("INSERT INTO users (name) VALUES (?)"), ("Alice",))
+    user = db.fetchone(Sql.raw("SELECT * FROM users WHERE id = ?"), (1,))
+    print(user)  # (1, 'Alice')
+```
+
+## Usage
+
+### Row Factories
+
+Return rows as dictionaries or namedtuples instead of tuples:
+
+```python
+from sqlitey import Db, Sql, dict_factory, namedtuple_factory
+
+with Db("mydb.sqlite", row_factory=dict_factory) as db:
+    user = db.fetchone(Sql.raw("SELECT * FROM users WHERE id = ?"), (1,))
+    print(user["name"])  # 'Alice'
+
+with Db("mydb.sqlite", row_factory=namedtuple_factory) as db:
+    user = db.fetchone(Sql.raw("SELECT * FROM users WHERE id = ?"), (1,))
+    print(user.name)  # 'Alice'
+```
+
+### SQL Templates
+
+Keep SQL queries in separate files for better organization:
+
+```python
+from pathlib import Path
+from sqlitey import Db, DbPathConfig, Sql
+
+config = DbPathConfig(
+    database=Path("mydb.sqlite"),
+    sql_templates_dir=Path("sql/"),
+)
+
+with Db.from_config(config) as db:
+    # Loads query from sql/get_user_by_id.sql
+    user = db.fetchone(Sql.template("get_user_by_id.sql"), (1,))
+```
+
+Or specify the template path directly:
+
+```python
+with Db("mydb.sqlite") as db:
+    sql = Sql.template("get_user_by_id.sql", path=Path("sql/"))
+    user = db.fetchone(sql, (1,))
+```
+
+### Autocommit Mode
+
+Disable transaction management for auto-committing each statement:
+
+```python
+with Db("mydb.sqlite", autocommit=True) as db:
+    db.execute(Sql.raw("UPDATE users SET name = ? WHERE id = ?"), ("Bob", 1))
+```
+
+### Batch Operations
+
+Execute multiple parameter sets or run SQL scripts:
+
+```python
+with Db("mydb.sqlite", autocommit=True) as db:
+    # Execute same query with multiple parameter sets
+    users = [("Alice",), ("Bob",), ("Charlie",)]
+    db.executemany(Sql.raw("INSERT INTO users (name) VALUES (?)"), users)
+
+    # Execute multiple statements as a script
+    db.executescript(Sql.raw("""
+        DELETE FROM users WHERE id = 1;
+        UPDATE users SET name = 'Robert' WHERE name = 'Bob';
+    """))
+```
+
+## API Reference
+
+### Sql
+
+| Method | Description |
+|--------|-------------|
+| `Sql.raw(query)` | Create a Sql instance from an inline query string |
+| `Sql.template(filename, path=None)` | Create a Sql instance from a template file |
+
+### Db
+
+| Method | Description |
+|--------|-------------|
+| `Db(path, row_factory=None, sql_templates_dir=None, autocommit=False)` | Create a database connection |
+| `Db.from_config(config, **kwargs)` | Create from a `DbPathConfig` |
+| `execute(sql, *args)` | Execute a query and return the cursor |
+| `executemany(sql, *args)` | Execute a query against multiple parameter sets |
+| `executescript(sql)` | Execute multiple statements as a script |
+| `fetchone(sql, *args)` | Execute and return the first row |
+| `fetchall(sql, *args)` | Execute and return all rows |
+| `commit(sql, *args)` | Execute and commit the transaction |
+
+### Row Factories
+
+| Factory | Description |
+|---------|-------------|
+| `dict_factory` | Return rows as dictionaries |
+| `namedtuple_factory` | Return rows as namedtuples |
+
+## More Examples
+
+See the [test suite](https://github.com/smallwat3r/sqlitey/blob/main/tests/test_sqlitey.py) for more examples.

{sqlitey-0.1.0 → sqlitey-0.1.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "SQLitey"
-version = "0.1.0"
+version = "0.1.1"
 description = "Useful wrapper around SQLite"
 readme = "README.md"
 license = { file="LICENSE" }

sqlitey-0.1.1/sqlitey/__init__.py

@@ -0,0 +1,330 @@
+"""Sqlitey - A lightweight SQLite wrapper with SQL injection protection.
+
+This module provides a safe interface for SQLite database operations by
+enforcing the use of the Sql class for all queries, preventing direct
+string-based SQL execution.
+
+Example:
+    >>> from sqlitey import Db, Sql
+    >>> with Db("mydb.sqlite") as db:
+    ...     users = db.fetchall(Sql.raw("SELECT * FROM users"))
+"""
+
+import sqlite3
+from collections import namedtuple
+from dataclasses import dataclass
+from functools import lru_cache, wraps
+from pathlib import Path
+from typing import Any, Callable, Self, TypeAlias
+
+__all__ = [
+    "Db",
+    "DbPathConfig",
+    "Sql",
+    "dict_factory",
+    "namedtuple_factory",
+    "RowFactory",
+    "SqlRow",
+]
+
+
+@dataclass(frozen=True)
+class DbPathConfig:
+    """Configuration for database and SQL template paths.
+
+    Attributes:
+        database: Path to the SQLite database file.
+        sql_templates_dir: Optional directory containing SQL template files.
+    """
+
+    database: Path
+    sql_templates_dir: Path | None = None
+
+
+@lru_cache(maxsize=128)
+def _read_sql_template(filename: str, template_path: Path) -> str:
+    """Read and cache SQL template files.
+
+    Raises:
+        FileNotFoundError: If the template file does not exist.
+        ValueError: If the filename attempts path traversal.
+    """
+    # Validate filename to prevent path traversal
+    if ".." in filename or filename.startswith("/"):
+        raise ValueError(f"Invalid template filename: {filename}")
+
+    file_path = template_path / filename
+    # Ensure resolved path is within template directory
+    try:
+        file_path.resolve().relative_to(template_path.resolve())
+    except ValueError:
+        raise ValueError(f"Template path traversal detected: {filename}") from None
+
+    try:
+        return file_path.read_text().strip()
+    except FileNotFoundError:
+        raise FileNotFoundError(
+            f"SQL template not found: {filename} in {template_path}"
+        ) from None
+
+
+class Sql:
+    """Represents a SQL query, either inline or from a template file.
+
+    Use the class methods `raw()` or `template()` to create instances.
+    Direct instantiation is discouraged.
+
+    Example:
+        >>> sql = Sql.raw("SELECT * FROM users WHERE id = ?")
+        >>> sql = Sql.template("get_users.sql")
+    """
+
+    def __init__(self, query_loader: Callable, **kwargs) -> None:
+        self._query_loader = query_loader
+        self._is_templated = False
+        self._store = kwargs
+
+    @property
+    def has_template_path(self) -> bool:
+        """Return True if this is a template with a configured path."""
+        return bool(self._is_templated and self._store.get("template_path"))
+
+    def set_template_path(self, template_path: Path) -> None:
+        """Set the template directory path for deferred template resolution."""
+        if self._is_templated:
+            self._store["template_path"] = template_path
+
+    def load_query(self) -> str:
+        """Load and return the SQL query string.
+
+        Raises:
+            ValueError: If this is a template without a configured path.
+        """
+        if self._is_templated and not self.has_template_path:
+            raise ValueError("No template path configured")
+        return self._query_loader(**self._store)
+
+    @classmethod
+    def raw(cls, query: str) -> Self:
+        """Create a Sql instance from an inline query string.
+
+        Args:
+            query: The SQL query string.
+
+        Returns:
+            A Sql instance wrapping the query.
+        """
+        return cls(lambda: query)
+
+    @classmethod
+    def template(cls, filename: str, *, path: Path | None = None) -> Self:
+        """Create a Sql instance from a template file.
+
+        The template path can be provided directly or deferred to be set
+        later via the Db configuration.
+
+        Args:
+            filename: Name of the SQL template file.
+            path: Optional directory containing the template file.
+
+        Returns:
+            A Sql instance that loads from the template file.
+        """
+        instance = cls(_read_sql_template, template_path=path, filename=filename)
+        instance._is_templated = True
+        return instance
+
+
+#: Type alias for database row data returned by queries.
+SqlRow: TypeAlias = tuple[Any, ...] | dict[str, Any] | Any
+
+#: Type alias for row factory functions that transform raw rows.
+RowFactory: TypeAlias = Callable[[sqlite3.Cursor, sqlite3.Row], SqlRow]
+
+
+def dict_factory(cursor: sqlite3.Cursor, row: sqlite3.Row) -> dict[str, Any]:
+    """Row factory that returns rows as dictionaries.
+
+    Example:
+        >>> with Db("mydb.sqlite", row_factory=dict_factory) as db:
+        ...     user = db.fetchone(Sql.raw("SELECT id, name FROM users"))
+        ...     print(user["name"])
+    """
+    return {col[0]: row[idx] for idx, col in enumerate(cursor.description)}
+
+
+@lru_cache(maxsize=128)
+def _make_row_class(fields: tuple[str, ...]) -> type[tuple[Any, ...]]:
+    """Create and cache a namedtuple class for the given field names."""
+    return namedtuple("Row", fields)
+
+
+def namedtuple_factory(cursor: sqlite3.Cursor, row: sqlite3.Row) -> tuple[Any, ...]:
+    """Row factory that returns rows as namedtuples.
+
+    Example:
+        >>> with Db("mydb.sqlite", row_factory=namedtuple_factory) as db:
+        ...     user = db.fetchone(Sql.raw("SELECT id, name FROM users"))
+        ...     print(user.name)
+    """
+    fields = tuple(col[0] for col in cursor.description)
+    return _make_row_class(fields)(*row)
+
+
+_HOOKED_METHODS = frozenset({"execute", "executemany", "executescript"})
+
+
+class _SafeCursor:
+    """Cursor proxy that blocks direct access to execute methods.
+
+    This prevents bypassing the Sql class by calling cursor.execute() directly.
+    All other cursor attributes are proxied through to the underlying cursor.
+    """
+
+    __slots__ = ("__cursor",)
+
+    def __init__(self, cursor: sqlite3.Cursor) -> None:
+        object.__setattr__(self, "_SafeCursor__cursor", cursor)
+
+    def __getattr__(self, name: str) -> Any:
+        if name in _HOOKED_METHODS:
+            raise AttributeError(f"Cannot access {name} from cursor directly")
+        return getattr(self.__cursor, name)
+
+
+class Db:
+    """SQLite database wrapper with SQL injection protection.
+
+    All queries must be wrapped in a Sql object, preventing direct string
+    execution. Supports both inline queries and SQL template files.
+
+    Args:
+        *args: Positional arguments passed to sqlite3.connect().
+        row_factory: Optional factory function to transform result rows.
+        sql_templates_dir: Optional directory for SQL template files.
+        autocommit: If True, disable transaction management.
+        **kwargs: Keyword arguments passed to sqlite3.connect().
+
+    Example:
+        >>> with Db("mydb.sqlite", row_factory=dict_factory) as db:
+        ...     db.commit(Sql.raw("INSERT INTO users (name) VALUES (?)"), ("Alice",))
+        ...     users = db.fetchall(Sql.raw("SELECT * FROM users"))
+    """
+
+    def __init__(
+        self,
+        *args,
+        row_factory: RowFactory | None = None,
+        sql_templates_dir: Path | None = None,
+        autocommit: bool = False,
+        **kwargs,
+    ) -> None:
+        if autocommit:
+            kwargs["isolation_level"] = None
+        self.conn = sqlite3.connect(*args, **kwargs)
+        if row_factory:
+            self.conn.row_factory = row_factory
+        self._cursor = _SafeCursor(self.conn.cursor())
+        self._sql_templates_dir = sql_templates_dir
+        self._method_cache: dict[str, Callable] = {}
+
+    @classmethod
+    def from_config(cls, config: DbPathConfig, **kwargs) -> Self:
+        """Create a Db instance from a DbPathConfig.
+
+        Args:
+            config: Database path configuration.
+            **kwargs: Additional arguments passed to the constructor.
+        """
+        return cls(
+            config.database,
+            sql_templates_dir=config.sql_templates_dir,
+            **kwargs,
+        )
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        try:
+            self.conn.close()
+        except Exception:
+            # Suppress close errors to avoid masking the original exception
+            if exc_type is None:
+                raise
+
+    def _pre_execute_hook(self, sql: Sql) -> None:
+        """Set deferred template path from config if not already set."""
+        if not sql.has_template_path and self._sql_templates_dir:
+            sql.set_template_path(self._sql_templates_dir)
+
+    def __getattribute__(self, name: str) -> Any:
+        attr = super().__getattribute__(name)
+        # inject hook before running sensitive methods
+        if name in _HOOKED_METHODS:
+            # Cache wrapper functions to avoid creating new ones on each access
+            cache = super().__getattribute__("_method_cache")
+            if name not in cache:
+
+                @wraps(attr)
+                def wrapper(*args, **kwargs):
+                    self._pre_execute_hook(args[0])
+                    return attr(*args, **kwargs)
+
+                cache[name] = wrapper
+            return cache[name]
+        return attr
+
+    def execute(self, sql: Sql, *args) -> sqlite3.Cursor:
+        """Execute a SQL query and return the cursor.
+
+        Args:
+            sql: The Sql object containing the query.
+            *args: Parameters to bind to the query.
+        """
+        return self._cursor._SafeCursor__cursor.execute(sql.load_query(), *args)
+
+    def executemany(self, sql: Sql, *args) -> sqlite3.Cursor:
+        """Execute a SQL query against multiple parameter sets.
+
+        Args:
+            sql: The Sql object containing the query.
+            *args: Sequence of parameter sets.
+        """
+        return self._cursor._SafeCursor__cursor.executemany(sql.load_query(), *args)
+
+    def executescript(self, sql: Sql) -> sqlite3.Cursor:
+        """Execute multiple SQL statements as a script.
+
+        Args:
+            sql: The Sql object containing the script.
+        """
+        return self._cursor._SafeCursor__cursor.executescript(sql.load_query())
+
+    def fetchone(self, sql: Sql, *args) -> SqlRow | None:
+        """Execute a query and return the first result row, or None.
+
+        Args:
+            sql: The Sql object containing the query.
+            *args: Parameters to bind to the query.
+        """
+        return self.execute(sql, *args).fetchone()
+
+    def fetchall(self, sql: Sql, *args) -> list[SqlRow]:
+        """Execute a query and return all result rows.
+
+        Args:
+            sql: The Sql object containing the query.
+            *args: Parameters to bind to the query.
+        """
+        return self.execute(sql, *args).fetchall()
+
+    def commit(self, sql: Sql, *args) -> None:
+        """Execute a query and commit the transaction.
+
+        Args:
+            sql: The Sql object containing the query.
+            *args: Parameters to bind to the query.
+        """
+        self.execute(sql, *args)
+        self.conn.commit()

{sqlitey-0.1.0 → sqlitey-0.1.1}/tests/test_sqlitey.py

@@ -1,4 +1,12 @@
-import re
+"""Tests for the sqlitey module.
+
+This module tests the core functionality of sqlitey including:
+- Sql class (raw and template queries)
+- Db class (execute, fetch, commit operations)
+- Row factories (dict and namedtuple)
+- Security features (cursor protection, path traversal prevention)
+"""
+
 import sqlite3
 from pathlib import Path
 from sqlite3.dbapi2 import OperationalError
@@ -11,6 +19,12 @@ from sqlitey import Db, DbPathConfig, Sql, dict_factory, namedtuple_factory
 
 @fixture
 def temp_db_path():
+    """Create a temporary SQLite database with test data.
+
+    Yields a path to a database containing a 'users' table with two rows:
+    - (1, 'Alice')
+    - (2, 'John')
+    """
     with NamedTemporaryFile(suffix=".db", delete=True) as tmp:
         db_path = Path(tmp.name)
         conn = sqlite3.connect(db_path)
@@ -23,6 +37,7 @@ def temp_db_path():
 
 @fixture
 def config(temp_db_path):
+    """Create a DbPathConfig with the temp database and test SQL templates."""
     return DbPathConfig(
         database=temp_db_path,
         sql_templates_dir=Path(__file__).resolve().parent / "sql"
@@ -123,9 +138,9 @@ def test_access_cursor_execute(config):
     """Test accessing cursor.execute() is forbidden."""
     with Db.from_config(config) as db:
         with raises(AttributeError, match="Cannot access execute from cursor directly"):
-            db.cursor.execute(Sql.raw("SELECT 1;"))
+            db._cursor.execute(Sql.raw("SELECT 1;"))
         # however we should be able to access other attributes
-        assert db.cursor.rowcount == -1
+        assert db._cursor.rowcount == -1
 
 
 def test_db_autocommit_behaviour(config):
@@ -178,3 +193,38 @@ def test_executemany(config):
         results = db.fetchall(Sql.raw("SELECT name FROM users"))
     assert "Alicia" in str(results)
     assert "Bobby" in str(results)
+
+
+def test_template_path_traversal_dotdot():
+    """Test path traversal with .. is blocked."""
+    sql = Sql.template("../etc/passwd", path=Path(__file__).resolve().parent / "sql")
+    with raises(ValueError, match="Invalid template filename"):
+        sql.load_query()
+
+
+def test_template_path_traversal_absolute():
+    """Test path traversal with absolute path is blocked."""
+    sql = Sql.template("/etc/passwd", path=Path(__file__).resolve().parent / "sql")
+    with raises(ValueError, match="Invalid template filename"):
+        sql.load_query()
+
+
+def test_template_file_not_found():
+    """Test loading a template that doesn't exist."""
+    sql = Sql.template("nonexistent.sql", path=Path(__file__).resolve().parent / "sql")
+    with raises(FileNotFoundError, match="SQL template not found"):
+        sql.load_query()
+
+
+def test_access_cursor_executemany(config):
+    """Test accessing cursor.executemany() is forbidden."""
+    with Db.from_config(config) as db:
+        with raises(AttributeError, match="Cannot access executemany from cursor directly"):
+            db._cursor.executemany(Sql.raw("SELECT 1;"), [])
+
+
+def test_access_cursor_executescript(config):
+    """Test accessing cursor.executescript() is forbidden."""
+    with Db.from_config(config) as db:
+        with raises(AttributeError, match="Cannot access executescript from cursor directly"):
+            db._cursor.executescript(Sql.raw("SELECT 1;"))

sqlitey-0.1.0/PKG-INFO

@@ -1,87 +0,0 @@
-Metadata-Version: 2.4
-Name: SQLitey
-Version: 0.1.0
-Summary: Useful wrapper around SQLite
-License: The MIT License (MIT)
-        
-        Copyright (c) 2025 Matthieu Petiteau
-        
-        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.
-License-File: LICENSE
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-
-# SQLitey
-
-SQLitey is a lightweight and flexible wrapper around SQLite, designed to streamline database access using configuration files, SQL templates, and custom row factories.
-
-Key Features:
-- Configuration-driven setup for database paths and SQL templates
-- Support for SQL template files to keep queries organized
-- Customizable row factories (e.g., return rows as namedtuples)
-- Support for both templated and raw SQL queries
-- Optional config usage for quick, one-off database access
-
-## Exampe usage
-
-### Using a Config File
-
-Define a configuration with the database path and the directory for SQL templates:
-
-``` python
-from pathlib import Path
-from sqlitey import Db, DbPathConfig, Sql, namedtuple_factory
-
-dir = Path(__file__).resolve().parent
-config = DbPathConfig(
-    database=dir / "db.sqlite3",
-    sql_templates_dir=dir / "sql"
-)
-
-with Db.from_config(config, row_factory=namedtuple_factory) as db:
-    result = db.fetchone(Sql.template("get_user_by_id.sql"), (3,))
-    print(result.id, result.name)
-```
-
-### Executing Raw SQL
-
-You can also use raw SQL directly:
-
-``` python
-with Db.from_config(config, timeout=15) as db:
-    db.commit(Sql.raw("INSERT INTO users VALUES (10, 'John');"))
-```
-
-### Without a Config File
-
-Skip the config and use the database path directly:
-
-``` python
-with Db("db.sqlite3", autocommit=True) as db:
-    db.execute(Sql.raw("UPDATE users SET name = 'Johnny' WHERE id = 10;"))
-
-with Db("db.sqlite3") as db:
-    sql = Sql.template("get_user_by_id.sql", path=Path(__file__).resolve().parent / "sql")
-    result = db.fetchone(sql, (3,))
-```
-
-### More examples
-
-See more examples in [tests](./tests/test_sqlight.py)

sqlitey-0.1.0/README.md

@@ -1,57 +0,0 @@
-# SQLitey
-
-SQLitey is a lightweight and flexible wrapper around SQLite, designed to streamline database access using configuration files, SQL templates, and custom row factories.
-
-Key Features:
-- Configuration-driven setup for database paths and SQL templates
-- Support for SQL template files to keep queries organized
-- Customizable row factories (e.g., return rows as namedtuples)
-- Support for both templated and raw SQL queries
-- Optional config usage for quick, one-off database access
-
-## Exampe usage
-
-### Using a Config File
-
-Define a configuration with the database path and the directory for SQL templates:
-
-``` python
-from pathlib import Path
-from sqlitey import Db, DbPathConfig, Sql, namedtuple_factory
-
-dir = Path(__file__).resolve().parent
-config = DbPathConfig(
-    database=dir / "db.sqlite3",
-    sql_templates_dir=dir / "sql"
-)
-
-with Db.from_config(config, row_factory=namedtuple_factory) as db:
-    result = db.fetchone(Sql.template("get_user_by_id.sql"), (3,))
-    print(result.id, result.name)
-```
-
-### Executing Raw SQL
-
-You can also use raw SQL directly:
-
-``` python
-with Db.from_config(config, timeout=15) as db:
-    db.commit(Sql.raw("INSERT INTO users VALUES (10, 'John');"))
-```
-
-### Without a Config File
-
-Skip the config and use the database path directly:
-
-``` python
-with Db("db.sqlite3", autocommit=True) as db:
-    db.execute(Sql.raw("UPDATE users SET name = 'Johnny' WHERE id = 10;"))
-
-with Db("db.sqlite3") as db:
-    sql = Sql.template("get_user_by_id.sql", path=Path(__file__).resolve().parent / "sql")
-    result = db.fetchone(sql, (3,))
-```
-
-### More examples
-
-See more examples in [tests](./tests/test_sqlight.py)

sqlitey-0.1.0/sqlitey/__init__.py

@@ -1,154 +0,0 @@
-import sqlite3
-from collections import namedtuple
-from dataclasses import dataclass
-from functools import lru_cache
-from pathlib import Path
-from typing import Any, Callable, Self, TypeAlias
-
-
-@dataclass(frozen=True)
-class DbPathConfig:
-    """Database path configurations."""
-
-    # database filepath
-    database: Path
-    # directory storing sql templates
-    sql_templates_dir: Path | None = None
-
-
-@lru_cache
-def _read_sql_template(filename: str, template_path: Path) -> str:
-    return (template_path / filename).read_text().strip()
-
-
-class Sql:
-    """Represent a SQL query."""
-
-    _is_templated = False
-
-    def __init__(self, query_loader: Callable, **kwargs) -> None:
-        self._query_loader = query_loader
-        self._store = kwargs
-
-    @property
-    def has_template_path(self) -> bool:
-        return bool(self._is_templated and self._store.get("template_path"))
-
-    def set_template_path(self, template_path: Path) -> None:
-        if self._is_templated:
-            self._store["template_path"] = template_path
-
-    def load_query(self) -> str:
-        if self._is_templated and not self.has_template_path:
-            raise ValueError("No template path configured")
-        return self._query_loader(**self._store)
-
-    @classmethod
-    def raw(cls, query: str) -> Self:
-        return cls(lambda *args, **kwargs: query)
-
-    @classmethod
-    def template(cls, filename: str, *, path: Path | None = None) -> Self:
-        # path is optional so we can defer setting at a later time, in order to
-        # derive its value from a config for example.
-        cls_ = cls(_read_sql_template, template_path=path, filename=filename)
-        cls_._is_templated = True
-        return cls_
-
-
-SqlRow: TypeAlias = Any
-RowFactory: TypeAlias = Callable[[sqlite3.Cursor, sqlite3.Row], SqlRow]
-
-
-def dict_factory(cursor: sqlite3.Cursor, row: sqlite3.Row) -> SqlRow:
-    return {col[0]: row[idx] for idx, col in enumerate(cursor.description)}
-
-
-def namedtuple_factory(cursor: sqlite3.Cursor, row: sqlite3.Row) -> SqlRow:
-    Row = namedtuple("Row", [str(col[0]) for col in cursor.description])  # type: ignore
-    return Row(*row)
-
-
-_HOOKED_METHODS = ("execute", "executemany", "executescript")
-
-
-class _SafeCursor:
-    """Proxy to protect `cursor.execute` to be accessed directly."""
-
-    def __init__(self, safe_cursor: sqlite3.Cursor) -> None:
-        self._safe_cursor = safe_cursor
-
-    def __getattr__(self, name: str) -> Any:
-        if name in _HOOKED_METHODS:
-            raise AttributeError(f"Cannot access {name} from cursor directly")
-        return getattr(self._safe_cursor, name)
-
-
-class Db:
-    """SQLite wrapper class."""
-
-    def __init__(
-        self,
-        *args,
-        row_factory: RowFactory | None = None,
-        sql_templates_dir: Path | None = None,
-        autocommit: bool = False,
-        **kwargs,
-    ) -> None:
-        if autocommit:
-            kwargs["isolation_level"] = None
-        self.conn = sqlite3.connect(*args, **kwargs)
-        if row_factory:
-            self.conn.row_factory = row_factory
-        self.cursor = _SafeCursor(self.conn.cursor())
-        self._sql_templates_dir = sql_templates_dir
-
-    @classmethod
-    def from_config(cls, config: DbPathConfig, **kwargs) -> Self:
-        return cls(
-            config.database,
-            sql_templates_dir=config.sql_templates_dir,
-            **kwargs,
-        )
-
-    def __enter__(self) -> Self:
-        return self
-
-    def __exit__(self, *args, **kwargs) -> None:
-        self.conn.close()
-
-    def _pre_execute_hook(self, sql: Sql) -> None:
-        if not sql.has_template_path and self._sql_templates_dir:
-            # path is deferred, lets set it from the config
-            sql.set_template_path(self._sql_templates_dir)
-
-    def __getattribute__(self, name: str) -> Any:
-        attr = super().__getattribute__(name)
-        # inject hook before running sensitive methods
-        if name in _HOOKED_METHODS:
-
-            def wrapper(*args, **kwargs):
-                self._pre_execute_hook(args[0])
-                return attr(*args, **kwargs)
-
-            return wrapper
-        return attr
-
-    def execute(self, sql: Sql, *args) -> SqlRow:
-        return self.cursor._safe_cursor.execute(sql.load_query(), *args)
-
-    def executemany(self, sql: Sql, *args) -> SqlRow:
-        return self.cursor._safe_cursor.executemany(sql.load_query(), *args)
-
-    def executescript(self, sql: Sql) -> SqlRow:
-        return self.cursor._safe_cursor.executescript(sql.load_query())
-
-    def fetchone(self, sql: Sql, *args) -> SqlRow:
-        return self.execute(sql, *args).fetchone()
-
-    def fetchall(self, sql: Sql, *args) -> list[SqlRow]:
-        return self.execute(sql, *args).fetchall()
-
-    def commit(self, sql: Sql, *args) -> None:
-        self.execute(sql, *args)
-        self.conn.commit()