SQLitey 0.1.0__tar.gz

sqlitey-0.1.0/.github/workflows/ci.yaml

@@ -0,0 +1,22 @@
+name: CI
+on: [push, pull_request]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: pip install uv && uv sync --inexact
+    - name: Lint with Ruff
+      run: python -m uv run ruff check sqlitey
+    - name: Run Mypy
+      run: python -m uv run mypy sqlitey
+    - name: Test suite
+      run: python -m uv run pytest --cov=sqlitey tests

sqlitey-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+*.DS_Store
+.coverage
+.venv/
+build/
+dist/
+.mypy_cache/

sqlitey-0.1.0/.python-version

@@ -0,0 +1 @@
+3.11

sqlitey-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+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.

sqlitey-0.1.0/Makefile

@@ -0,0 +1,47 @@
+SRC = sqlitey
+
+.PHONY: help
+help:  ## Show this help menu
+	@echo "Usage: make [TARGET ...]"
+	@echo ""
+	@grep --no-filename -E '^[a-zA-Z_%-]+:.*?## .*$$' $(MAKEFILE_LIST) | \
+		awk 'BEGIN {FS = ":.*?## "}; {printf "%-25s %s\n", $$1, $$2}'
+
+VENV           = .venv
+VENV_PYTHON    = $(VENV)/bin/python
+SYSTEM_PYTHON  = $(shell which python3.13)
+PYTHON         = $(wildcard $(VENV_PYTHON))
+
+$(VENV_PYTHON):
+	rm -rf $(VENV)
+	$(SYSTEM_PYTHON) -m venv $(VENV)
+
+.PHONY: venv
+venv: $(VENV_PYTHON)  ## Create a Python virtual environment
+
+.PHONY: deps
+deps: venv ## Install requirements in virtual environment
+	$(PYTHON) -m ensurepip
+	$(PYTHON) -m pip install uv
+	$(PYTHON) -m uv sync --inexact
+
+.PHONY: tests
+tests:  ## Run unit tests
+	$(PYTHON) -m uv run pytest --cov=$(SRC) --cov-report term-missing tests
+
+.PHONY: mypy
+mypy:  ## Run mypy
+	$(PYTHON) -m uv run mypy $(SRC)
+
+.PHONY: ruff
+ruff:  ## Run ruff
+	$(PYTHON) -m uv run ruff check $(SRC)
+
+.PHONY: black
+black:  ## Run black
+	$(PYTHON) -m uv run black $(SRC)
+
+.PHONY: release
+release:  ## Release to PyPI
+	$(PYTHON) -m build
+	$(PYTHON) -m twine upload dist/*

sqlitey-0.1.0/PKG-INFO

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

@@ -0,0 +1,57 @@
+# 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/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "SQLitey"
+version = "0.1.0"
+description = "Useful wrapper around SQLite"
+readme = "README.md"
+license = { file="LICENSE" }
+requires-python = ">=3.11"
+dependencies = []
+
+[dependency-groups]
+dev = [
+    "black>=25.1.0",
+    "build>=1.2.2.post1",
+    "mypy>=1.16.0",
+    "pytest>=8.3.5",
+    "pytest-cov>=6.1.1",
+    "ruff>=0.11.11",
+    "twine>=6.1.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

sqlitey-0.1.0/sqlitey/__init__.py

@@ -0,0 +1,154 @@
+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()

sqlitey-0.1.0/tests/sql/test.sql

@@ -0,0 +1 @@
+SELECT 1;

sqlitey-0.1.0/tests/test_sqlitey.py

@@ -0,0 +1,180 @@
+import re
+import sqlite3
+from pathlib import Path
+from sqlite3.dbapi2 import OperationalError
+from tempfile import NamedTemporaryFile
+
+from pytest import fixture, raises
+
+from sqlitey import Db, DbPathConfig, Sql, dict_factory, namedtuple_factory
+
+
+@fixture
+def temp_db_path():
+    with NamedTemporaryFile(suffix=".db", delete=True) as tmp:
+        db_path = Path(tmp.name)
+        conn = sqlite3.connect(db_path)
+        conn.execute("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)")
+        conn.execute("INSERT INTO users VALUES (1, 'Alice'), (2, 'John')")
+        conn.commit()
+        conn.close()
+        yield db_path
+
+
+@fixture
+def config(temp_db_path):
+    return DbPathConfig(
+        database=temp_db_path,
+        sql_templates_dir=Path(__file__).resolve().parent / "sql"
+    )
+
+
+def test_raw_sql():
+    """Test loading raw SQL."""
+    sql = Sql.raw("SELECT 1")
+    assert sql.load_query() == "SELECT 1"
+
+
+def test_template_sql_no_path_config():
+    """Test loading a template without a path."""
+    sql = Sql.template("test.sql")
+    with raises(ValueError, match="No template path configured"):
+        sql.load_query()
+
+
+def test_template_sql():
+    """Test loading a template."""
+    sql = Sql.template("test.sql", path=Path(__file__).resolve().parent / "sql")
+    assert sql.load_query() == "SELECT 1;"
+
+
+def test_db_fetchone(config):
+    """Test using fetchone."""
+    sql = Sql.raw("SELECT id, name FROM users WHERE id = ?")
+    with Db.from_config(config) as db:
+        result = db.fetchone(sql, (1,))
+    assert result == (1, "Alice")
+
+
+def test_db_fetchone_dict_factory(config):
+    """Test using fetchone and the dict factory."""
+    sql = Sql.raw("SELECT id, name FROM users WHERE id = ?")
+    with Db.from_config(config, row_factory=dict_factory) as db:
+        result = db.fetchone(sql, (1,))
+    assert result == {"id": 1, "name": "Alice"}
+
+
+def test_db_fetchone_namedtuple_factory(config):
+    """Test using fetchone and the namedtuple factory."""
+    sql = Sql.raw("SELECT id, name FROM users WHERE id = ?")
+    with Db.from_config(config, row_factory=namedtuple_factory) as db:
+        result = db.fetchone(sql, (1,))
+    assert result.id == 1
+    assert result.name == "Alice"
+
+
+def test_db_fetchall(config):
+    """Test using fetchall."""
+    sql = Sql.raw("SELECT id, name FROM users")
+    with Db.from_config(config) as db:
+        results = db.fetchall(sql)
+    assert results == [(1, "Alice"), (2, "John")]
+
+
+def test_db_fetchall_dict_factory(config):
+    """Test using fetchall and the dict factory."""
+    sql = Sql.raw("SELECT id, name FROM users")
+    with Db.from_config(config, row_factory=dict_factory) as db:
+        results = db.fetchall(sql)
+    assert results == [{"id": 1, "name": "Alice"}, {"id": 2, "name": "John"}]
+
+
+def test_db_fetchall_namedtuple_factory(config):
+    """Test using fetchall and the namedtuple factory."""
+    sql = Sql.raw("SELECT id, name FROM users")
+    with Db.from_config(config, row_factory=namedtuple_factory) as db:
+        results = db.fetchall(sql)
+    assert results[0].id == 1
+    assert results[0].name == "Alice"
+    assert results[1].id == 2
+    assert results[1].name == "John"
+
+
+def test_db_commit(config):
+    """Test using commit."""
+    with Db.from_config(config, row_factory=namedtuple_factory) as db:
+        db.commit(Sql.raw("INSERT INTO users VALUES (3, 'Kate')"))
+        result = db.fetchone(Sql.raw("SELECT COUNT(id) as total FROM users"))
+    assert result.total == 3
+
+
+def test_db_context_manager_rollback(config):
+    """Test rolling back in context manager."""
+    with raises(OperationalError):
+        with Db.from_config(config) as db:
+            db.execute(Sql.raw("INSERT INTO users VALUES (3, 'Kate')"))
+            db.execute(Sql.raw("SYNTAX ERROR;"))  # raise
+    with Db.from_config(config) as db:
+        result = db.fetchone(Sql.raw("SELECT id FROM users WHERE id = 3"))
+    assert result is None
+
+
+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;"))
+        # however we should be able to access other attributes
+        assert db.cursor.rowcount == -1
+
+
+def test_db_autocommit_behaviour(config):
+    """Test autocommit works as expected in context manager."""
+    with raises(OperationalError):
+        with Db.from_config(config, autocommit=True) as db:
+            db.execute(Sql.raw("INSERT INTO users VALUES (3, 'Kate')"))
+            db.execute(Sql.raw("SYNTAX ERROR"))  # raise
+    with Db.from_config(config) as db:
+        result = db.fetchone(Sql.raw("SELECT id FROM users WHERE id = 3"))
+    assert result == (3,)
+
+
+def test_db_undefer_template_path(temp_db_path):
+    """Test setting template path not using a config."""
+    sql = Sql.template("test.sql", path=Path(__file__).resolve().parent / "sql")
+    with Db(temp_db_path) as db:
+        result = db.fetchone(sql)
+    assert result == (1,)
+
+
+def test_db_defer_template_path(config):
+    """Test setting template path from a config."""
+    with Db.from_config(config) as db:
+        result = db.fetchone(Sql.template("test.sql"))
+    assert result == (1,)
+
+
+def test_executescript(config):
+    """Test using executescript."""
+    with Db.from_config(config) as db:
+        db.executescript(
+            Sql.raw(
+                "INSERT INTO users VALUES (3, 'Kate');"
+                "INSERT INTO users VALUES (4, 'Johny');"
+            )
+        )
+        result = db.fetchone(Sql.raw("SELECT COUNT(id) as total FROM users"))
+    assert result == (4,)
+
+
+def test_executemany(config):
+    """Test using executemany."""
+    updates = [
+        ('Alicia', 1),
+        ('Bobby', 2),
+    ]
+    with Db.from_config(config, autocommit=True) as db:
+        db.executemany(Sql.raw("UPDATE users SET name = ? WHERE id = ?"), updates)
+        results = db.fetchall(Sql.raw("SELECT name FROM users"))
+    assert "Alicia" in str(results)
+    assert "Bobby" in str(results)