databasesupasafe 1.0.0__py3-none-any.whl

databasesupasafe-1.0.0.dist-info/METADATA

@@ -0,0 +1,251 @@
+Metadata-Version: 2.4
+Name: databasesupasafe
+Version: 1.0.0
+Summary: A lightweight Python package for managing SQLite, PostgreSQL, and MySQL databases.
+Home-page: https://github.com/yourname/dbhandler
+Author: dbhandler contributors
+Author-email: you@example.com
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+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: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: api-feature
+Provides-Extra: postgresql
+Requires-Dist: psycopg2-binary>=2.9; extra == "postgresql"
+Provides-Extra: mysql
+Requires-Dist: mysql-connector-python>=8.0; extra == "mysql"
+Provides-Extra: all
+Requires-Dist: psycopg2-binary>=2.9; extra == "all"
+Requires-Dist: mysql-connector-python>=8.0; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: isort; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# dbhandler
+
+A lightweight Python package for managing **SQLite**, **PostgreSQL**, and **MySQL** databases — with a fluent query builder and an ORM-style model layer.
+
+---
+
+## Installation
+
+```bash
+# SQLite only (no extra dependencies)
+pip install .
+
+# With PostgreSQL support
+pip install ".[postgresql]"
+
+# With MySQL support
+pip install ".[mysql]"
+
+# Everything
+pip install ".[all]"
+
+# Development tools
+pip install ".[dev]"
+```
+
+---
+
+## Quick Start
+
+### DBHandler — direct SQL
+
+```python
+from dbhandler import DBHandler
+
+# SQLite (in-memory)
+with DBHandler("sqlite", database=":memory:") as db:
+    db.execute("""
+        CREATE TABLE users (
+            id    INTEGER PRIMARY KEY AUTOINCREMENT,
+            name  TEXT NOT NULL,
+            email TEXT NOT NULL UNIQUE,
+            age   INTEGER DEFAULT 0
+        )
+    """)
+
+    # Insert a single row
+    db.insert("users", {"name": "Alice", "email": "alice@example.com", "age": 30})
+
+    # Insert many rows
+    db.insert_many("users", [
+        {"name": "Bob",   "email": "bob@example.com",   "age": 25},
+        {"name": "Carol", "email": "carol@example.com", "age": 35},
+    ])
+
+    # Select with a WHERE clause
+    adults = db.select("users", where="age >= ?", params=(30,), order_by="name ASC")
+    for user in adults:
+        print(user["name"], user["age"])
+
+    # Update
+    db.update("users", {"age": 31}, where="name = ?", where_params=("Alice",))
+
+    # Delete
+    db.delete("users", where="name = ?", params=("Bob",))
+
+    # Raw fetch
+    row = db.fetchone("SELECT * FROM users WHERE email = ?", ("alice@example.com",))
+    print(row)
+```
+
+### PostgreSQL / MySQL
+
+```python
+db = DBHandler(
+    "postgresql",
+    host="localhost",
+    port=5432,
+    database="mydb",
+    user="admin",
+    password="secret",
+)
+db.connect()
+# ... same API as SQLite ...
+db.disconnect()
+```
+
+---
+
+### QueryBuilder — fluent SQL construction
+
+```python
+from dbhandler import DBHandler, QueryBuilder
+
+with DBHandler("sqlite", database="app.db") as db:
+
+    # SELECT
+    sql, params = (
+        QueryBuilder("users")
+        .select("id", "name", "email")
+        .where("age > ?", 18)
+        .order_by("name ASC")
+        .limit(10)
+        .build()
+    )
+    rows = db.fetchall(sql, params)
+
+    # INSERT
+    sql, params = QueryBuilder("users").insert(name="Dave", email="d@d.com", age=22).build()
+    db.execute(sql, params)
+
+    # UPDATE
+    sql, params = (
+        QueryBuilder("users")
+        .update(email="dave@new.com")
+        .where("name = ?", "Dave")
+        .build()
+    )
+    db.execute(sql, params)
+
+    # DELETE
+    sql, params = QueryBuilder("users").delete().where("id = ?", 99).build()
+    db.execute(sql, params)
+
+    db.commit()
+```
+
+---
+
+### BaseModel — ORM-style interface
+
+```python
+from dbhandler import DBHandler, BaseModel
+from dbhandler.models import Field
+
+class User(BaseModel):
+    __table__ = "users"
+
+    id    = Field(int, primary_key=True)
+    name  = Field(str, nullable=False)
+    email = Field(str, nullable=False, unique=True)
+    age   = Field(int, default=0)
+
+db = DBHandler("sqlite", database="app.db")
+db.connect()
+
+User.__db__ = db
+User.create_table()
+
+# Create
+alice = User(name="Alice", email="alice@example.com", age=30)
+alice.save()
+
+# Read
+all_users = User.all()
+alice     = User.get(id=1)
+adults    = User.filter("age >= ?", (18,))
+total     = User.count()
+
+# Update
+alice.age = 31
+alice.save()
+
+# Delete
+alice.delete()
+
+db.disconnect()
+```
+
+---
+
+### Transactions
+
+```python
+with DBHandler("sqlite", database="app.db") as db:
+    with db.transaction():
+        db.insert("orders", {"user_id": 1, "total": 99.99})
+        db.insert("order_items", {"order_id": 1, "product_id": 42, "qty": 2})
+    # committed automatically; rolled back on any exception
+```
+
+---
+
+## Schema Utilities
+
+```python
+db.table_exists("users")       # → True / False
+db.get_tables()                # → ["users", "orders", ...]
+db.get_columns("users")        # → [{"name": "id", "type": "INTEGER", ...}, ...]
+```
+
+---
+
+## Running Tests
+
+```bash
+pip install ".[dev]"
+pytest tests/ -v --cov=dbhandler
+```
+
+---
+
+## License
+
+MIT

databasesupasafe-1.0.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+dbhandler/__init__.py,sha256=YOIXNiCwtoyfsDXLZBtiWgc7CRIavyrooZdKyHbJ5Pg,513
+dbhandler/core.py,sha256=OwcdXOnem2UInycy8oIu-9cH810ddPYmXKNj9rPLQIk,16816
+dbhandler/exceptions.py,sha256=Q10Lg9V6srkd4HxXYoNG2VwsLiXQD9MRtK48u6U65u0,483
+dbhandler/models.py,sha256=taMHobJpgPJhACV5bTYFaRd-ahA0NPoys7hgspjb_O8,9024
+dbhandler/query.py,sha256=gNOWVX10C3nOnVaRNX5YXkVHiUjNdunfbyxP1CHJD00,7359
+databasesupasafe-1.0.0.dist-info/METADATA,sha256=8NGC_XIHGxhVfDJfHYmJNOqi9-_vg9B7B5ttVidveuQ,6026
+databasesupasafe-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+databasesupasafe-1.0.0.dist-info/top_level.txt,sha256=PH3fZCYCR6JCo3kFrFaT6uKg7Ov7DXxYjeIYAz2vdlk,10
+databasesupasafe-1.0.0.dist-info/RECORD,,

databasesupasafe-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

databasesupasafe-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+dbhandler

dbhandler/__init__.py

@@ -0,0 +1,26 @@
+"""
+dbhandler - A Python package for handling databases with ease.
+Supports SQLite, PostgreSQL, and MySQL.
+"""
+
+from .core import DBHandler
+from .query import QueryBuilder
+from .models import BaseModel
+from .exceptions import (
+    DBHandlerError,
+    ConnectionError,
+    QueryError,
+    ModelError,
+)
+
+__version__ = "1.0.0"
+__author__ = "dbhandler contributors"
+__all__ = [
+    "DBHandler",
+    "QueryBuilder",
+    "BaseModel",
+    "DBHandlerError",
+    "ConnectionError",
+    "QueryError",
+    "ModelError",
+]

dbhandler/core.py

@@ -0,0 +1,486 @@
+"""
+dbhandler.core - Core DBHandler class for managing database connections.
+Supports SQLite, PostgreSQL (via psycopg2), and MySQL (via mysql-connector-python).
+"""
+
+import sqlite3
+import logging
+from contextlib import contextmanager
+from typing import Any, Dict, List, Optional, Tuple, Union
+
+from .exceptions import ConnectionError, QueryError
+
+logger = logging.getLogger(__name__)
+
+
+class DBHandler:
+    """
+    A unified interface for interacting with SQLite, PostgreSQL, and MySQL databases.
+
+    Usage (SQLite):
+        db = DBHandler("sqlite", database="mydb.sqlite3")
+        db.connect()
+        db.execute("CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)")
+        db.disconnect()
+
+    Usage (PostgreSQL):
+        db = DBHandler("postgresql", host="localhost", port=5432,
+                       database="mydb", user="admin", password="secret")
+        db.connect()
+
+    Usage (MySQL):
+        db = DBHandler("mysql", host="localhost", port=3306,
+                       database="mydb", user="admin", password="secret")
+        db.connect()
+
+    Context manager support:
+        with DBHandler("sqlite", database=":memory:") as db:
+            db.execute("SELECT 1")
+    """
+
+    SUPPORTED_BACKENDS = ("sqlite", "postgresql", "mysql")
+
+    def __init__(
+        self,
+        backend: str,
+        *,
+        database: str = ":memory:",
+        host: str = "localhost",
+        port: Optional[int] = None,
+        user: Optional[str] = None,
+        password: Optional[str] = None,
+        **kwargs: Any,
+    ):
+        """
+        Initialize the DBHandler.
+
+        Args:
+            backend:    One of 'sqlite', 'postgresql', or 'mysql'.
+            database:   Database name / file path.
+            host:       Hostname (PostgreSQL / MySQL only).
+            port:       Port number (defaults: PostgreSQL=5432, MySQL=3306).
+            user:       Username (PostgreSQL / MySQL only).
+            password:   Password (PostgreSQL / MySQL only).
+            **kwargs:   Additional driver-specific keyword arguments.
+        """
+        backend = backend.lower()
+        if backend not in self.SUPPORTED_BACKENDS:
+            raise ValueError(
+                f"Unsupported backend '{backend}'. "
+                f"Choose from: {', '.join(self.SUPPORTED_BACKENDS)}"
+            )
+
+        self.backend = backend
+        self.database = database
+        self.host = host
+        self.port = port
+        self.user = user
+        self.password = password
+        self.extra = kwargs
+
+        self._conn = None
+        self._cursor = None
+
+    # ------------------------------------------------------------------
+    # Connection management
+    # ------------------------------------------------------------------
+
+    def connect(self) -> None:
+        """Open the database connection."""
+        try:
+            if self.backend == "sqlite":
+                self._conn = sqlite3.connect(self.database)
+                self._conn.row_factory = sqlite3.Row
+
+            elif self.backend == "postgresql":
+                try:
+                    import psycopg2
+                    import psycopg2.extras
+                except ImportError:
+                    raise ConnectionError(
+                        "psycopg2 is required for PostgreSQL support. "
+                        "Install it with: pip install psycopg2-binary"
+                    )
+                self._conn = psycopg2.connect(
+                    host=self.host,
+                    port=self.port or 5432,
+                    dbname=self.database,
+                    user=self.user,
+                    password=self.password,
+                    **self.extra,
+                )
+                self._conn.autocommit = False
+
+            elif self.backend == "mysql":
+                try:
+                    import mysql.connector
+                except ImportError:
+                    raise ConnectionError(
+                        "mysql-connector-python is required for MySQL support. "
+                        "Install it with: pip install mysql-connector-python"
+                    )
+                self._conn = mysql.connector.connect(
+                    host=self.host,
+                    port=self.port or 3306,
+                    database=self.database,
+                    user=self.user,
+                    password=self.password,
+                    **self.extra,
+                )
+
+            self._cursor = self._conn.cursor()
+            logger.info("Connected to %s database '%s'.", self.backend, self.database)
+
+        except Exception as exc:
+            raise ConnectionError(f"Failed to connect: {exc}") from exc
+
+    def disconnect(self) -> None:
+        """Close the database connection."""
+        if self._cursor:
+            self._cursor.close()
+            self._cursor = None
+        if self._conn:
+            self._conn.close()
+            self._conn = None
+            logger.info("Disconnected from %s database '%s'.", self.backend, self.database)
+
+    def is_connected(self) -> bool:
+        """Return True if the connection is active."""
+        return self._conn is not None
+
+    # ------------------------------------------------------------------
+    # Context manager
+    # ------------------------------------------------------------------
+
+    def __enter__(self) -> "DBHandler":
+        self.connect()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        if exc_type is None:
+            self.commit()
+        else:
+            self.rollback()
+        self.disconnect()
+
+    # ------------------------------------------------------------------
+    # Transaction helpers
+    # ------------------------------------------------------------------
+
+    def commit(self) -> None:
+        """Commit the current transaction."""
+        self._require_connection()
+        self._conn.commit()
+
+    def rollback(self) -> None:
+        """Roll back the current transaction."""
+        self._require_connection()
+        self._conn.rollback()
+
+    @contextmanager
+    def transaction(self):
+        """
+        Context manager for explicit transactions.
+
+        Example:
+            with db.transaction():
+                db.execute("INSERT INTO users (name) VALUES (?)", ("Alice",))
+                db.execute("INSERT INTO users (name) VALUES (?)", ("Bob",))
+        """
+        self._require_connection()
+        try:
+            yield self
+            self.commit()
+        except Exception:
+            self.rollback()
+            raise
+
+    # ------------------------------------------------------------------
+    # Query execution
+    # ------------------------------------------------------------------
+
+    def execute(
+        self,
+        sql: str,
+        params: Optional[Union[Tuple, Dict]] = None,
+    ) -> Any:
+        """
+        Execute a single SQL statement.
+
+        Args:
+            sql:    The SQL statement to run.
+            params: Optional bind parameters (tuple or dict).
+
+        Returns:
+            The cursor object after execution.
+        """
+        self._require_connection()
+        try:
+            if params:
+                self._cursor.execute(sql, params)
+            else:
+                self._cursor.execute(sql)
+            logger.debug("Executed: %s | params=%s", sql.strip(), params)
+            return self._cursor
+        except Exception as exc:
+            raise QueryError(f"Query failed: {exc}\nSQL: {sql}") from exc
+
+    def executemany(
+        self,
+        sql: str,
+        params_seq: List[Union[Tuple, Dict]],
+    ) -> Any:
+        """
+        Execute a statement against a sequence of parameter sets.
+
+        Args:
+            sql:        The SQL statement template.
+            params_seq: A list of tuples or dicts to bind.
+        """
+        self._require_connection()
+        try:
+            self._cursor.executemany(sql, params_seq)
+            logger.debug("Executemany: %s | %d rows", sql.strip(), len(params_seq))
+            return self._cursor
+        except Exception as exc:
+            raise QueryError(f"Executemany failed: {exc}\nSQL: {sql}") from exc
+
+    # ------------------------------------------------------------------
+    # Fetch helpers
+    # ------------------------------------------------------------------
+
+    def fetchone(
+        self,
+        sql: str,
+        params: Optional[Union[Tuple, Dict]] = None,
+    ) -> Optional[Dict[str, Any]]:
+        """Execute *sql* and return the first row as a dict, or None."""
+        cursor = self.execute(sql, params)
+        row = cursor.fetchone()
+        return self._row_to_dict(row) if row else None
+
+    def fetchall(
+        self,
+        sql: str,
+        params: Optional[Union[Tuple, Dict]] = None,
+    ) -> List[Dict[str, Any]]:
+        """Execute *sql* and return all rows as a list of dicts."""
+        cursor = self.execute(sql, params)
+        rows = cursor.fetchall()
+        return [self._row_to_dict(r) for r in rows]
+
+    def fetchmany(
+        self,
+        sql: str,
+        size: int = 100,
+        params: Optional[Union[Tuple, Dict]] = None,
+    ) -> List[Dict[str, Any]]:
+        """Execute *sql* and return up to *size* rows as a list of dicts."""
+        cursor = self.execute(sql, params)
+        rows = cursor.fetchmany(size)
+        return [self._row_to_dict(r) for r in rows]
+
+    # ------------------------------------------------------------------
+    # CRUD shortcuts
+    # ------------------------------------------------------------------
+
+    def insert(self, table: str, data: Dict[str, Any]) -> int:
+        """
+        Insert a single row and return the last inserted row id.
+
+        Args:
+            table: Target table name.
+            data:  Column → value mapping.
+
+        Returns:
+            The last inserted row ID.
+        """
+        cols = ", ".join(data.keys())
+        placeholders = self._placeholders(len(data))
+        sql = f"INSERT INTO {table} ({cols}) VALUES ({placeholders})"
+        self.execute(sql, tuple(data.values()))
+        return self._cursor.lastrowid
+
+    def insert_many(self, table: str, rows: List[Dict[str, Any]]) -> None:
+        """Insert multiple rows efficiently using executemany."""
+        if not rows:
+            return
+        cols = ", ".join(rows[0].keys())
+        placeholders = self._placeholders(len(rows[0]))
+        sql = f"INSERT INTO {table} ({cols}) VALUES ({placeholders})"
+        self.executemany(sql, [tuple(r.values()) for r in rows])
+
+    def select(
+        self,
+        table: str,
+        *,
+        columns: Union[str, List[str]] = "*",
+        where: Optional[str] = None,
+        params: Optional[Union[Tuple, Dict]] = None,
+        order_by: Optional[str] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+    ) -> List[Dict[str, Any]]:
+        """
+        Build and execute a SELECT statement.
+
+        Args:
+            table:    Source table name.
+            columns:  Column(s) to select (default '*').
+            where:    Optional WHERE clause (e.g. "age > ?").
+            params:   Bind parameters for the WHERE clause.
+            order_by: Optional ORDER BY clause.
+            limit:    Row limit.
+            offset:   Row offset.
+
+        Returns:
+            A list of row dicts.
+        """
+        if isinstance(columns, list):
+            columns = ", ".join(columns)
+
+        sql = f"SELECT {columns} FROM {table}"
+        if where:
+            sql += f" WHERE {where}"
+        if order_by:
+            sql += f" ORDER BY {order_by}"
+        if limit is not None:
+            sql += f" LIMIT {int(limit)}"
+        if offset is not None:
+            sql += f" OFFSET {int(offset)}"
+
+        return self.fetchall(sql, params)
+
+    def update(
+        self,
+        table: str,
+        data: Dict[str, Any],
+        where: str,
+        where_params: Optional[Union[Tuple, Dict]] = None,
+    ) -> int:
+        """
+        Update rows in *table* and return the number of affected rows.
+
+        Args:
+            table:        Target table name.
+            data:         Column → new-value mapping.
+            where:        WHERE clause (required to prevent accidental mass updates).
+            where_params: Bind parameters for the WHERE clause.
+        """
+        set_clause = ", ".join(
+            f"{col} = {self._single_placeholder()}" for col in data.keys()
+        )
+        sql = f"UPDATE {table} SET {set_clause} WHERE {where}"
+        params: tuple = tuple(data.values())
+        if where_params:
+            params += tuple(where_params) if not isinstance(where_params, dict) else ()
+        self.execute(sql, params)
+        return self._cursor.rowcount
+
+    def delete(
+        self,
+        table: str,
+        where: str,
+        params: Optional[Union[Tuple, Dict]] = None,
+    ) -> int:
+        """
+        Delete rows from *table* and return the number of affected rows.
+
+        Args:
+            table:  Target table name.
+            where:  WHERE clause (required).
+            params: Bind parameters.
+        """
+        sql = f"DELETE FROM {table} WHERE {where}"
+        self.execute(sql, params)
+        return self._cursor.rowcount
+
+    # ------------------------------------------------------------------
+    # Schema helpers
+    # ------------------------------------------------------------------
+
+    def table_exists(self, table: str) -> bool:
+        """Return True if *table* exists in the database."""
+        if self.backend == "sqlite":
+            row = self.fetchone(
+                "SELECT 1 FROM sqlite_master WHERE type='table' AND name=?",
+                (table,),
+            )
+        elif self.backend == "postgresql":
+            row = self.fetchone(
+                "SELECT 1 FROM information_schema.tables WHERE table_name=%s",
+                (table,),
+            )
+        else:  # mysql
+            row = self.fetchone(
+                "SELECT 1 FROM information_schema.tables WHERE table_name=%s AND table_schema=DATABASE()",
+                (table,),
+            )
+        return row is not None
+
+    def get_tables(self) -> List[str]:
+        """Return a list of all table names in the database."""
+        if self.backend == "sqlite":
+            rows = self.fetchall(
+                "SELECT name FROM sqlite_master WHERE type='table' ORDER BY name"
+            )
+            return [r["name"] for r in rows]
+        elif self.backend == "postgresql":
+            rows = self.fetchall(
+                "SELECT table_name FROM information_schema.tables "
+                "WHERE table_schema='public' ORDER BY table_name"
+            )
+            return [r["table_name"] for r in rows]
+        else:  # mysql
+            rows = self.fetchall("SHOW TABLES")
+            return [list(r.values())[0] for r in rows]
+
+    def get_columns(self, table: str) -> List[Dict[str, Any]]:
+        """Return column info for the given table."""
+        if self.backend == "sqlite":
+            return self.fetchall(f"PRAGMA table_info({table})")
+        elif self.backend == "postgresql":
+            return self.fetchall(
+                "SELECT column_name, data_type, is_nullable "
+                "FROM information_schema.columns WHERE table_name=%s",
+                (table,),
+            )
+        else:  # mysql
+            return self.fetchall(
+                "SELECT COLUMN_NAME, DATA_TYPE, IS_NULLABLE "
+                "FROM information_schema.columns WHERE table_name=%s AND table_schema=DATABASE()",
+                (table,),
+            )
+
+    # ------------------------------------------------------------------
+    # Internals
+    # ------------------------------------------------------------------
+
+    def _require_connection(self) -> None:
+        if self._conn is None:
+            raise ConnectionError("Not connected. Call connect() first.")
+
+    def _placeholders(self, n: int) -> str:
+        """Return comma-separated placeholders for n values."""
+        ph = self._single_placeholder()
+        return ", ".join([ph] * n)
+
+    def _single_placeholder(self) -> str:
+        return "?" if self.backend == "sqlite" else "%s"
+
+    def _row_to_dict(self, row: Any) -> Dict[str, Any]:
+        """Convert a database row to a plain dict."""
+        if row is None:
+            return {}
+        if isinstance(row, sqlite3.Row):
+            return dict(row)
+        if hasattr(row, "_asdict"):  # psycopg2 RealDictRow / namedtuple
+            return dict(row._asdict())
+        if hasattr(self._cursor, "description") and self._cursor.description:
+            keys = [d[0] for d in self._cursor.description]
+            return dict(zip(keys, row))
+        return dict(row)
+
+    def __repr__(self) -> str:
+        status = "connected" if self.is_connected() else "disconnected"
+        return f"<DBHandler backend={self.backend!r} database={self.database!r} [{status}]>"

dbhandler/exceptions.py

@@ -0,0 +1,23 @@
+"""
+dbhandler.exceptions - Custom exception classes.
+"""
+
+
+class DBHandlerError(Exception):
+    """Base exception for all dbhandler errors."""
+
+
+class ConnectionError(DBHandlerError):
+    """Raised when a database connection fails."""
+
+
+class QueryError(DBHandlerError):
+    """Raised when a query fails to execute."""
+
+
+class ModelError(DBHandlerError):
+    """Raised when a model operation fails."""
+
+
+class MigrationError(DBHandlerError):
+    """Raised when a migration fails."""

dbhandler/models.py

@@ -0,0 +1,285 @@
+"""
+dbhandler.models - Lightweight ORM-style BaseModel.
+"""
+
+from __future__ import annotations
+
+from typing import Any, ClassVar, Dict, List, Optional, TYPE_CHECKING
+
+from .exceptions import ModelError
+
+if TYPE_CHECKING:
+    from .core import DBHandler
+
+
+class ModelMeta(type):
+    """Metaclass that collects declared fields."""
+
+    def __new__(mcs, name, bases, namespace):
+        fields = {}
+        for key, val in list(namespace.items()):
+            if isinstance(val, Field):
+                fields[key] = val
+        namespace["_fields"] = fields
+        cls = super().__new__(mcs, name, bases, namespace)
+        return cls
+
+
+class Field:
+    """
+    Descriptor representing a database column.
+
+    Example:
+        class User(BaseModel):
+            __table__ = "users"
+            name  = Field(str, nullable=False)
+            email = Field(str, nullable=False, unique=True)
+            age   = Field(int, default=0)
+    """
+
+    _TYPE_MAP = {
+        int:   "INTEGER",
+        float: "REAL",
+        str:   "TEXT",
+        bool:  "INTEGER",
+        bytes: "BLOB",
+    }
+
+    def __init__(
+        self,
+        type_: type = str,
+        *,
+        nullable: bool = True,
+        default: Any = None,
+        unique: bool = False,
+        primary_key: bool = False,
+    ):
+        self.type_ = type_
+        self.nullable = nullable
+        self.default = default
+        self.unique = unique
+        self.primary_key = primary_key
+        self.name: Optional[str] = None  # set by BaseModel.__init_subclass__
+
+    def sql_type(self) -> str:
+        return self._TYPE_MAP.get(self.type_, "TEXT")
+
+    def column_def(self) -> str:
+        parts = [self.name, self.sql_type()]
+        if self.primary_key:
+            parts.append("PRIMARY KEY AUTOINCREMENT")
+        else:
+            if not self.nullable:
+                parts.append("NOT NULL")
+            if self.unique:
+                parts.append("UNIQUE")
+            if self.default is not None:
+                parts.append(f"DEFAULT {self.default!r}")
+        return " ".join(parts)
+
+    def __set_name__(self, owner, name):
+        self.name = name
+
+    def __get__(self, obj, objtype=None):
+        if obj is None:
+            return self
+        return obj.__dict__.get(self.name, self.default)
+
+    def __set__(self, obj, value):
+        obj.__dict__[self.name] = value
+
+
+class BaseModel(metaclass=ModelMeta):
+    """
+    Lightweight ORM-style base class.
+
+    Subclass this to define a table model:
+
+        class User(BaseModel):
+            __table__ = "users"
+            __db__: DBHandler = None  # set at runtime
+
+            id    = Field(int, primary_key=True)
+            name  = Field(str, nullable=False)
+            email = Field(str, nullable=False, unique=True)
+            age   = Field(int, default=0)
+
+        # Bind database connection
+        User.__db__ = db
+
+        # Create the table
+        User.create_table()
+
+        # Insert
+        user = User(name="Alice", email="alice@example.com", age=30)
+        user.save()
+
+        # Query
+        users = User.all()
+        alice = User.get(id=1)
+
+        # Update
+        alice.age = 31
+        alice.save()
+
+        # Delete
+        alice.delete()
+    """
+
+    __table__: ClassVar[str] = ""
+    __db__: ClassVar[Optional["DBHandler"]] = None
+    _fields: ClassVar[Dict[str, Field]] = {}
+
+    def __init__(self, **kwargs: Any):
+        self._pk_value: Optional[Any] = None
+        for name, field in self.__class__._fields.items():
+            value = kwargs.pop(name, field.default)
+            setattr(self, name, value)
+        if kwargs:
+            raise ModelError(f"Unknown fields: {', '.join(kwargs)}")
+
+    # ------------------------------------------------------------------
+    # Class-level helpers
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def _db(cls) -> "DBHandler":
+        if cls.__db__ is None:
+            raise ModelError(
+                f"No database bound to {cls.__name__}. Set {cls.__name__}.__db__ = db."
+            )
+        return cls.__db__
+
+    @classmethod
+    def _pk_field(cls) -> Optional[str]:
+        for name, field in cls._fields.items():
+            if field.primary_key:
+                return name
+        return None
+
+    @classmethod
+    def _non_pk_fields(cls) -> Dict[str, Field]:
+        return {n: f for n, f in cls._fields.items() if not f.primary_key}
+
+    # ------------------------------------------------------------------
+    # Schema
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def create_table(cls, if_not_exists: bool = True) -> None:
+        """Create the table in the database based on declared fields."""
+        modifier = "IF NOT EXISTS " if if_not_exists else ""
+        col_defs = [f.column_def() for f in cls._fields.values()]
+        sql = f"CREATE TABLE {modifier}{cls.__table__} ({', '.join(col_defs)})"
+        cls._db().execute(sql)
+        cls._db().commit()
+
+    @classmethod
+    def drop_table(cls, if_exists: bool = True) -> None:
+        """Drop the table from the database."""
+        modifier = "IF EXISTS " if if_exists else ""
+        cls._db().execute(f"DROP TABLE {modifier}{cls.__table__}")
+        cls._db().commit()
+
+    # ------------------------------------------------------------------
+    # CRUD
+    # ------------------------------------------------------------------
+
+    def save(self) -> None:
+        """Insert or update this instance in the database."""
+        pk = self.__class__._pk_field()
+        data = {
+            name: getattr(self, name)
+            for name, field in self.__class__._non_pk_fields().items()
+        }
+        db = self.__class__._db()
+
+        if pk and getattr(self, pk) is not None:
+            # UPDATE
+            pk_val = getattr(self, pk)
+            ph = db._single_placeholder()
+            db.update(
+                self.__class__.__table__,
+                data,
+                where=f"{pk} = {ph}",
+                where_params=(pk_val,),
+            )
+        else:
+            # INSERT
+            row_id = db.insert(self.__class__.__table__, data)
+            if pk:
+                setattr(self, pk, row_id)
+        db.commit()
+
+    def delete(self) -> None:
+        """Delete this instance from the database."""
+        pk = self.__class__._pk_field()
+        if pk is None:
+            raise ModelError("Cannot delete: no primary key defined.")
+        pk_val = getattr(self, pk)
+        if pk_val is None:
+            raise ModelError("Cannot delete: primary key value is None.")
+        db = self.__class__._db()
+        ph = db._single_placeholder()
+        db.delete(self.__class__.__table__, where=f"{pk} = {ph}", params=(pk_val,))
+        db.commit()
+
+    @classmethod
+    def get(cls, **kwargs: Any) -> Optional["BaseModel"]:
+        """Return the first matching row as a model instance, or None."""
+        db = cls._db()
+        ph = db._single_placeholder()
+        where = " AND ".join(f"{k} = {ph}" for k in kwargs)
+        params = tuple(kwargs.values())
+        row = db.fetchone(f"SELECT * FROM {cls.__table__} WHERE {where}", params)
+        return cls._from_row(row) if row else None
+
+    @classmethod
+    def all(cls) -> List["BaseModel"]:
+        """Return all rows as a list of model instances."""
+        rows = cls._db().fetchall(f"SELECT * FROM {cls.__table__}")
+        return [cls._from_row(r) for r in rows]
+
+    @classmethod
+    def filter(cls, where: str, params: tuple = ()) -> List["BaseModel"]:
+        """
+        Return filtered rows as model instances.
+
+        Example:
+            adults = User.filter("age >= ?", (18,))
+        """
+        rows = cls._db().fetchall(
+            f"SELECT * FROM {cls.__table__} WHERE {where}", params
+        )
+        return [cls._from_row(r) for r in rows]
+
+    @classmethod
+    def count(cls, where: Optional[str] = None, params: tuple = ()) -> int:
+        """Return the number of rows matching an optional WHERE clause."""
+        sql = f"SELECT COUNT(*) AS n FROM {cls.__table__}"
+        if where:
+            sql += f" WHERE {where}"
+        row = cls._db().fetchone(sql, params or None)
+        return int(row["n"]) if row else 0
+
+    # ------------------------------------------------------------------
+    # Internals
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def _from_row(cls, row: Dict[str, Any]) -> "BaseModel":
+        instance = cls.__new__(cls)
+        instance._pk_value = None
+        for name, field in cls._fields.items():
+            setattr(instance, name, row.get(name, field.default))
+        return instance
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Return the model instance as a plain dictionary."""
+        return {name: getattr(self, name) for name in self.__class__._fields}
+
+    def __repr__(self) -> str:
+        fields = ", ".join(
+            f"{k}={v!r}" for k, v in self.to_dict().items()
+        )
+        return f"<{self.__class__.__name__} {fields}>"

dbhandler/query.py

@@ -0,0 +1,216 @@
+"""
+dbhandler.query - Fluent QueryBuilder for constructing SQL statements.
+"""
+
+from typing import Any, Dict, List, Optional, Tuple, Union
+
+
+class QueryBuilder:
+    """
+    Fluent SQL query builder.
+
+    Example:
+        qb = QueryBuilder("users")
+        sql, params = (
+            qb.select("id", "name", "email")
+              .where("age > ?", 18)
+              .where("active = ?", 1)
+              .order_by("name ASC")
+              .limit(10)
+              .offset(0)
+              .build()
+        )
+        rows = db.fetchall(sql, params)
+
+    INSERT example:
+        sql, params = QueryBuilder("users").insert(name="Alice", age=30).build()
+        db.execute(sql, params)
+
+    UPDATE example:
+        sql, params = (
+            QueryBuilder("users")
+            .update(name="Alice Smith")
+            .where("id = ?", 1)
+            .build()
+        )
+        db.execute(sql, params)
+
+    DELETE example:
+        sql, params = QueryBuilder("users").delete().where("id = ?", 5).build()
+        db.execute(sql, params)
+    """
+
+    def __init__(self, table: str):
+        self._table = table
+        self._operation: Optional[str] = None  # SELECT | INSERT | UPDATE | DELETE
+        self._columns: List[str] = []
+        self._where_clauses: List[str] = []
+        self._where_params: List[Any] = []
+        self._order: Optional[str] = None
+        self._limit_val: Optional[int] = None
+        self._offset_val: Optional[int] = None
+        self._data: Dict[str, Any] = {}
+        self._join_clauses: List[str] = []
+
+    # ------------------------------------------------------------------
+    # Operation starters
+    # ------------------------------------------------------------------
+
+    def select(self, *columns: str) -> "QueryBuilder":
+        """Set to SELECT mode. Pass column names or use default '*'."""
+        self._operation = "SELECT"
+        self._columns = list(columns) if columns else ["*"]
+        return self
+
+    def insert(self, **data: Any) -> "QueryBuilder":
+        """Set to INSERT mode with the given column=value pairs."""
+        self._operation = "INSERT"
+        self._data = data
+        return self
+
+    def update(self, **data: Any) -> "QueryBuilder":
+        """Set to UPDATE mode with the given column=value pairs."""
+        self._operation = "UPDATE"
+        self._data = data
+        return self
+
+    def delete(self) -> "QueryBuilder":
+        """Set to DELETE mode."""
+        self._operation = "DELETE"
+        return self
+
+    # ------------------------------------------------------------------
+    # Clauses
+    # ------------------------------------------------------------------
+
+    def where(self, clause: str, *params: Any) -> "QueryBuilder":
+        """
+        Add a WHERE condition (ANDed with previous conditions).
+
+        Example:
+            .where("age > ?", 18)
+            .where("name = ?", "Alice")
+        """
+        self._where_clauses.append(clause)
+        self._where_params.extend(params)
+        return self
+
+    def join(self, join_clause: str) -> "QueryBuilder":
+        """
+        Add a raw JOIN clause.
+
+        Example:
+            .join("INNER JOIN orders ON orders.user_id = users.id")
+        """
+        self._join_clauses.append(join_clause)
+        return self
+
+    def order_by(self, clause: str) -> "QueryBuilder":
+        """
+        Set the ORDER BY clause.
+
+        Example:
+            .order_by("created_at DESC")
+        """
+        self._order = clause
+        return self
+
+    def limit(self, n: int) -> "QueryBuilder":
+        """Set the LIMIT clause."""
+        self._limit_val = int(n)
+        return self
+
+    def offset(self, n: int) -> "QueryBuilder":
+        """Set the OFFSET clause."""
+        self._offset_val = int(n)
+        return self
+
+    # ------------------------------------------------------------------
+    # Build
+    # ------------------------------------------------------------------
+
+    def build(self, placeholder: str = "?") -> Tuple[str, tuple]:
+        """
+        Compile the query into a (sql, params) tuple.
+
+        Args:
+            placeholder: The parameter placeholder style ('?' for SQLite,
+                         '%s' for PostgreSQL/MySQL).
+
+        Returns:
+            A (sql_string, params_tuple) pair ready for cursor.execute().
+        """
+        if self._operation is None:
+            raise ValueError(
+                "No operation set. Call .select(), .insert(), .update(), or .delete() first."
+            )
+
+        if self._operation == "SELECT":
+            return self._build_select(placeholder)
+        if self._operation == "INSERT":
+            return self._build_insert(placeholder)
+        if self._operation == "UPDATE":
+            return self._build_update(placeholder)
+        if self._operation == "DELETE":
+            return self._build_delete(placeholder)
+
+        raise ValueError(f"Unknown operation: {self._operation}")
+
+    # ------------------------------------------------------------------
+    # Internal builders
+    # ------------------------------------------------------------------
+
+    def _ph(self, placeholder: str, n: int = 1) -> List[str]:
+        return [placeholder] * n
+
+    def _where_sql(self, placeholder: str) -> Tuple[str, list]:
+        if not self._where_clauses:
+            return "", []
+        # Replace '?' with the target placeholder
+        clauses = [c.replace("?", placeholder) for c in self._where_clauses]
+        return " WHERE " + " AND ".join(clauses), list(self._where_params)
+
+    def _build_select(self, ph: str) -> Tuple[str, tuple]:
+        cols = ", ".join(self._columns)
+        sql = f"SELECT {cols} FROM {self._table}"
+        for j in self._join_clauses:
+            sql += f" {j}"
+        where_sql, where_params = self._where_sql(ph)
+        sql += where_sql
+        if self._order:
+            sql += f" ORDER BY {self._order}"
+        if self._limit_val is not None:
+            sql += f" LIMIT {self._limit_val}"
+        if self._offset_val is not None:
+            sql += f" OFFSET {self._offset_val}"
+        return sql, tuple(where_params)
+
+    def _build_insert(self, ph: str) -> Tuple[str, tuple]:
+        if not self._data:
+            raise ValueError("No data provided for INSERT.")
+        cols = ", ".join(self._data.keys())
+        placeholders = ", ".join([ph] * len(self._data))
+        sql = f"INSERT INTO {self._table} ({cols}) VALUES ({placeholders})"
+        return sql, tuple(self._data.values())
+
+    def _build_update(self, ph: str) -> Tuple[str, tuple]:
+        if not self._data:
+            raise ValueError("No data provided for UPDATE.")
+        set_clause = ", ".join(f"{col} = {ph}" for col in self._data.keys())
+        sql = f"UPDATE {self._table} SET {set_clause}"
+        where_sql, where_params = self._where_sql(ph)
+        sql += where_sql
+        return sql, tuple(self._data.values()) + tuple(where_params)
+
+    def _build_delete(self, ph: str) -> Tuple[str, tuple]:
+        sql = f"DELETE FROM {self._table}"
+        where_sql, where_params = self._where_sql(ph)
+        sql += where_sql
+        return sql, tuple(where_params)
+
+    def __repr__(self) -> str:
+        try:
+            sql, params = self.build()
+            return f"<QueryBuilder sql={sql!r} params={params!r}>"
+        except ValueError:
+            return f"<QueryBuilder table={self._table!r} op={self._operation!r}>"