SQLitey 0.1.0__py3-none-any.whl

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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,5 @@
+sqlitey/__init__.py,sha256=8plqNkh0YMvN9_dJ8FM8OcYy-vDfam88liZbLuJVUNI,4813
+sqlitey-0.1.0.dist-info/METADATA,sha256=Rkpn1xIX_iEMm996L3UNBgOGHDCjMiQySYbX4u_C_3Q,3092
+sqlitey-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+sqlitey-0.1.0.dist-info/licenses/LICENSE,sha256=0u06wIiVg9FooZGOF0fBibfyDmYSxRORrErXYN9xb5s,1084
+sqlitey-0.1.0.dist-info/RECORD,,

sqlitey-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

sqlitey-0.1.0.dist-info/licenses/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.