HandySQL 1.0.0__tar.gz

handysql-1.0.0/HandySQL/__init__.py

@@ -0,0 +1,52 @@
+"""
+HandySQL
+=======
+A simple and powerful SQL library for Python.
+
+Supported databases: SQLite · MySQL · PostgreSQL
+
+Quick start
+-----------
+>>> from HandySQL import HandySQL
+>>>
+>>> with HandySQL(db_type="sqlite", database="app.db") as db:
+...     db.quick_table("users", "name", "email")
+...     db.add("users", name="Alice", email="alice@example.com")
+...     users = db.get_all("users")
+
+Public API
+----------
+Classes:
+    HandySQL        – main database interface
+    SQLBuilder     – fluent SQL query builder
+    DatabaseError  – library exception
+
+Functions:
+    create_connection(db_type, **kwargs) -> HandySQL
+    sql_builder(table)                   -> SQLBuilder
+"""
+
+from .sql_easy import (
+    HandySQL,
+    SQLBuilder,
+    DatabaseError,
+    create_connection,
+    sql_builder,
+    MYSQL_AVAILABLE,
+    POSTGRESQL_AVAILABLE,
+)
+
+__all__ = [
+    "HandySQL",
+    "SQLBuilder",
+    "DatabaseError",
+    "create_connection",
+    "sql_builder",
+    "MYSQL_AVAILABLE",
+    "POSTGRESQL_AVAILABLE",
+]
+
+__version__   = "1.0.0"
+__author__    = "HandySQL Team"
+__license__   = "MIT"
+__url__       = "https://github.com/HandySQL/HandySQL"

handysql-1.0.0/HandySQL/builder.py

@@ -0,0 +1,269 @@
+"""
+easysql.builder
+===============
+Fluent SQL query builder.
+
+Usage
+-----
+>>> from easysql import sql_builder
+>>>
+>>> q = (sql_builder("users")
+...         .select(["name", "email"])
+...         .where("age > ?", 18)
+...         .order_by("name")
+...         .limit(10))
+>>> sql, params = q.build()
+"""
+
+from typing import Any, List, Tuple, Union
+from .exceptions import DatabaseError
+
+
+class SQLBuilder:
+    """
+    Fluent builder for SELECT / INSERT / UPDATE / DELETE statements.
+
+    Every method returns ``self``, so calls can be chained::
+
+        builder = (SQLBuilder("users")
+                    .select("*")
+                    .where("age > ?", 18)
+                    .order_by("name", "ASC")
+                    .limit(10))
+        sql, params = builder.build()
+    """
+
+    def __init__(self, table: str = None):
+        self.table          = table
+        self._select        = "*"
+        self._where         = []
+        self._where_params  = []
+        self._order_by      = None
+        self._limit         = None
+        self._offset        = None
+        self._join          = []
+        self._set_values    = {}
+        self._insert_values = []
+        self._operation     = None
+        self._group_by      = None
+        self._having        = None
+        self._distinct      = False
+
+    # ------------------------------------------------------------------ #
+    #  SELECT helpers
+    # ------------------------------------------------------------------ #
+
+    def select(self, columns: Union[str, List[str]] = "*") -> "SQLBuilder":
+        """Set the SELECT column list."""
+        self._operation = "SELECT"
+        self._select = ", ".join(columns) if isinstance(columns, list) else columns
+        return self
+
+    def distinct(self) -> "SQLBuilder":
+        """Add the DISTINCT keyword."""
+        self._distinct = True
+        return self
+
+    # ------------------------------------------------------------------ #
+    #  WHERE / AND / OR
+    # ------------------------------------------------------------------ #
+
+    def where(self, condition: str, *params) -> "SQLBuilder":
+        """
+        Add a WHERE condition.
+        Automatically prepends AND when a condition already exists.
+        """
+        if self._where:
+            self._where.append(f"AND {condition}")
+        else:
+            self._where.append(condition)
+        self._where_params.extend(params)
+        return self
+
+    def and_where(self, condition: str, *params) -> "SQLBuilder":
+        """Explicitly add an AND condition (alias for where())."""
+        return self.where(condition, *params)
+
+    def or_where(self, condition: str, *params) -> "SQLBuilder":
+        """Add an OR condition."""
+        if self._where:
+            self._where.append(f"OR {condition}")
+        else:
+            self._where.append(condition)
+        self._where_params.extend(params)
+        return self
+
+    def where_in(self, column: str, values: List[Any]) -> "SQLBuilder":
+        """Add a WHERE … IN (…) condition."""
+        placeholders = ", ".join("?" for _ in values)
+        self._where.append(
+            f"AND {column} IN ({placeholders})" if self._where
+            else f"{column} IN ({placeholders})"
+        )
+        self._where_params.extend(values)
+        return self
+
+    def where_between(self, column: str, start: Any, end: Any) -> "SQLBuilder":
+        """Add a WHERE … BETWEEN … AND … condition."""
+        prefix = "AND " if self._where else ""
+        self._where.append(f"{prefix}{column} BETWEEN ? AND ?")
+        self._where_params.extend([start, end])
+        return self
+
+    def where_like(self, column: str, pattern: str) -> "SQLBuilder":
+        """Add a WHERE … LIKE … condition."""
+        prefix = "AND " if self._where else ""
+        self._where.append(f"{prefix}{column} LIKE ?")
+        self._where_params.append(pattern)
+        return self
+
+    def where_null(self, column: str, is_null: bool = True) -> "SQLBuilder":
+        """Add WHERE … IS NULL or IS NOT NULL."""
+        prefix = "AND " if self._where else ""
+        qualifier = "IS NULL" if is_null else "IS NOT NULL"
+        self._where.append(f"{prefix}{column} {qualifier}")
+        return self
+
+    # ------------------------------------------------------------------ #
+    #  Ordering / grouping / paging
+    # ------------------------------------------------------------------ #
+
+    def order_by(self, column: str, direction: str = "ASC") -> "SQLBuilder":
+        """Set ORDER BY clause."""
+        self._order_by = f"{column} {direction}".strip()
+        return self
+
+    def group_by(self, columns: Union[str, List[str]]) -> "SQLBuilder":
+        """Set GROUP BY clause."""
+        self._group_by = ", ".join(columns) if isinstance(columns, list) else columns
+        return self
+
+    def having(self, condition: str) -> "SQLBuilder":
+        """Set HAVING clause."""
+        self._having = condition
+        return self
+
+    def limit(self, n: int) -> "SQLBuilder":
+        """Set LIMIT."""
+        self._limit = n
+        return self
+
+    def offset(self, n: int) -> "SQLBuilder":
+        """Set OFFSET."""
+        self._offset = n
+        return self
+
+    # ------------------------------------------------------------------ #
+    #  JOINs
+    # ------------------------------------------------------------------ #
+
+    def join(self, table: str, on: str, join_type: str = "INNER") -> "SQLBuilder":
+        """Add a JOIN clause."""
+        self._join.append(f"{join_type} JOIN {table} ON {on}")
+        return self
+
+    def left_join(self, table: str, on: str) -> "SQLBuilder":
+        """Shorthand for LEFT JOIN."""
+        return self.join(table, on, "LEFT")
+
+    def right_join(self, table: str, on: str) -> "SQLBuilder":
+        """Shorthand for RIGHT JOIN."""
+        return self.join(table, on, "RIGHT")
+
+    # ------------------------------------------------------------------ #
+    #  DML starters
+    # ------------------------------------------------------------------ #
+
+    def insert(self, table: str) -> "SQLBuilder":
+        """Start an INSERT statement."""
+        self._operation = "INSERT"
+        self.table = table
+        return self
+
+    def values(self, **kwargs) -> "SQLBuilder":
+        """Provide a row dict for INSERT."""
+        self._insert_values.append(kwargs)
+        return self
+
+    def update(self, table: str) -> "SQLBuilder":
+        """Start an UPDATE statement."""
+        self._operation = "UPDATE"
+        self.table = table
+        return self
+
+    def set(self, **kwargs) -> "SQLBuilder":
+        """Provide SET values for UPDATE."""
+        self._set_values.update(kwargs)
+        return self
+
+    def delete(self, table: str) -> "SQLBuilder":
+        """Start a DELETE statement."""
+        self._operation = "DELETE"
+        self.table = table
+        return self
+
+    # ------------------------------------------------------------------ #
+    #  Build
+    # ------------------------------------------------------------------ #
+
+    def build(self) -> Tuple[str, List[Any]]:
+        """
+        Compile the builder into ``(sql_string, params_list)``.
+
+        Raises
+        ------
+        DatabaseError
+            If no operation has been set, or required data is missing.
+        """
+        if not self._operation:
+            raise DatabaseError("No SQL operation has been set")
+
+        sql, params = "", []
+
+        if self._operation == "SELECT":
+            kw  = "DISTINCT " if self._distinct else ""
+            sql = f"SELECT {kw}{self._select} FROM {self.table}"
+            if self._join:
+                sql += " " + " ".join(self._join)
+            if self._where:
+                sql += " WHERE " + " ".join(self._where)
+                params.extend(self._where_params)
+            if self._group_by:
+                sql += f" GROUP BY {self._group_by}"
+            if self._having:
+                sql += f" HAVING {self._having}"
+            if self._order_by:
+                sql += f" ORDER BY {self._order_by}"
+            if self._limit is not None:
+                sql += " LIMIT ?"
+                params.append(self._limit)
+            if self._offset is not None:
+                sql += " OFFSET ?"
+                params.append(self._offset)
+
+        elif self._operation == "UPDATE":
+            if not self._set_values:
+                raise DatabaseError("No values provided for UPDATE")
+            set_clause = ", ".join(f"{k} = ?" for k in self._set_values)
+            sql = f"UPDATE {self.table} SET {set_clause}"
+            params.extend(self._set_values.values())
+            if self._where:
+                sql += " WHERE " + " ".join(self._where)
+                params.extend(self._where_params)
+
+        elif self._operation == "INSERT":
+            if not self._insert_values:
+                raise DatabaseError("No values provided for INSERT")
+            cols = list(self._insert_values[0].keys())
+            ph   = ", ".join("?" for _ in cols)
+            rows_ph = ", ".join(f"({ph})" for _ in self._insert_values)
+            sql = f"INSERT INTO {self.table} ({', '.join(cols)}) VALUES {rows_ph}"
+            params = [v for row in self._insert_values for v in (row[c] for c in cols)]
+
+        elif self._operation == "DELETE":
+            sql = f"DELETE FROM {self.table}"
+            if self._where:
+                sql += " WHERE " + " ".join(self._where)
+                params.extend(self._where_params)
+
+        return sql, params

handysql-1.0.0/HandySQL/connection.py

@@ -0,0 +1,196 @@
+"""
+easysql.connection
+==================
+Low-level connection management for SQLite, MySQL, and PostgreSQL.
+"""
+
+import sqlite3
+import logging
+from contextlib import contextmanager
+from typing import Any, List, Tuple, Union
+
+from .exceptions import DatabaseError, ConnectionError
+
+try:
+    import mysql.connector
+    MYSQL_AVAILABLE = True
+except ImportError:
+    MYSQL_AVAILABLE = False
+
+try:
+    import psycopg2
+    POSTGRESQL_AVAILABLE = True
+except ImportError:
+    POSTGRESQL_AVAILABLE = False
+
+logger = logging.getLogger(__name__)
+
+
+class Connection:
+    """
+    Manages a single database connection.
+
+    Parameters
+    ----------
+    db_type : str
+        ``"sqlite"``, ``"mysql"``, or ``"postgresql"``
+    **kwargs
+        Connection parameters (host, user, password, database, port …)
+    """
+
+    _ID_TYPES = {
+        "sqlite":     "INTEGER PRIMARY KEY AUTOINCREMENT",
+        "mysql":      "INT AUTO_INCREMENT PRIMARY KEY",
+        "postgresql": "SERIAL PRIMARY KEY",
+    }
+
+    def __init__(self, db_type: str = "sqlite", **kwargs):
+        self.db_type = db_type.lower()
+        self._conn   = None
+        self._auto_commit = kwargs.pop("auto_commit", True)
+        self._params = kwargs
+
+        if self.db_type == "sqlite":
+            self._db_path = kwargs.get("database", ":memory:")
+        elif self.db_type == "mysql":
+            if not MYSQL_AVAILABLE:
+                raise ConnectionError(
+                    "mysql-connector-python is not installed.\n"
+                    "Run: pip install mysql-connector-python"
+                )
+        elif self.db_type == "postgresql":
+            if not POSTGRESQL_AVAILABLE:
+                raise ConnectionError(
+                    "psycopg2 is not installed.\n"
+                    "Run: pip install psycopg2-binary"
+                )
+        else:
+            raise DatabaseError(
+                f"Unsupported database type: '{db_type}'. "
+                "Choose 'sqlite', 'mysql', or 'postgresql'."
+            )
+
+    # ------------------------------------------------------------------ #
+
+    def open(self):
+        """Open (or return existing) database connection."""
+        if self._conn is not None:
+            return self._conn
+        try:
+            p = self._params
+            if self.db_type == "sqlite":
+                self._conn = sqlite3.connect(self._db_path)
+                self._conn.row_factory = sqlite3.Row
+                logger.info("SQLite connected: %s", self._db_path)
+            elif self.db_type == "mysql":
+                self._conn = mysql.connector.connect(
+                    host=p.get("host", "localhost"),
+                    user=p.get("user", "root"),
+                    password=p.get("password", ""),
+                    database=p.get("database", ""),
+                    port=p.get("port", 3306),
+                )
+                logger.info("MySQL connected: %s", p.get("database"))
+            elif self.db_type == "postgresql":
+                self._conn = psycopg2.connect(
+                    host=p.get("host", "localhost"),
+                    user=p.get("user", "postgres"),
+                    password=p.get("password", ""),
+                    database=p.get("database", ""),
+                    port=p.get("port", 5432),
+                )
+                logger.info("PostgreSQL connected: %s", p.get("database"))
+            return self._conn
+        except Exception as exc:
+            raise ConnectionError(f"Connection failed: {exc}") from exc
+
+    def close(self):
+        """Close the connection if open."""
+        if self._conn:
+            self._conn.close()
+            self._conn = None
+            logger.info("Connection closed")
+
+    def __enter__(self):
+        self.open()
+        return self
+
+    def __exit__(self, *_):
+        self.close()
+
+    # ------------------------------------------------------------------ #
+
+    @contextmanager
+    def cursor(self):
+        """Context manager that yields a cursor and handles commit/rollback."""
+        if self._conn is None:
+            self.open()
+        cur = self._conn.cursor()
+        try:
+            yield cur
+            if self._auto_commit:
+                self._conn.commit()
+        except Exception as exc:
+            self._conn.rollback()
+            logger.error("Rolled back: %s", exc)
+            raise DatabaseError(f"Database operation error: {exc}") from exc
+        finally:
+            cur.close()
+
+    # ------------------------------------------------------------------ #
+
+    def execute(self, sql: str, params: Union[Tuple, List] = None) -> Any:
+        """
+        Run a SQL statement.
+
+        Returns
+        -------
+        list[dict]  for SELECT
+        int         (rowcount) for INSERT / UPDATE / DELETE
+        """
+        with self.cursor() as cur:
+            logger.debug("SQL: %s | params: %s", sql, params)
+            cur.execute(sql, params or ())
+            if sql.strip().upper().startswith("SELECT"):
+                rows = cur.fetchall()
+                if self.db_type == "sqlite":
+                    return [dict(r) for r in rows]
+                cols = [c[0] for c in cur.description]
+                return [dict(zip(cols, r)) for r in rows]
+            return cur.rowcount
+
+    def execute_many(self, sql: str, params_list: List[Tuple]) -> int:
+        """Run a parameterised statement for each item in params_list."""
+        with self.cursor() as cur:
+            cur.executemany(sql, params_list)
+            return cur.rowcount
+
+    # ------------------------------------------------------------------ #
+    #  Transaction helpers
+    # ------------------------------------------------------------------ #
+
+    def begin(self):
+        """Disable auto-commit to start a manual transaction."""
+        if self._conn is None:
+            self.open()
+        self._auto_commit = False
+        logger.info("Transaction started")
+
+    def commit(self):
+        """Commit the current transaction."""
+        if self._conn:
+            self._conn.commit()
+            logger.info("Transaction committed")
+
+    def rollback(self):
+        """Roll back the current transaction."""
+        if self._conn:
+            self._conn.rollback()
+            logger.info("Transaction rolled back")
+
+    # ------------------------------------------------------------------ #
+
+    @property
+    def auto_id_sql(self) -> str:
+        """Return the correct auto-increment primary key definition."""
+        return self._ID_TYPES[self.db_type]

handysql-1.0.0/HandySQL/exceptions.py

@@ -0,0 +1,40 @@
+"""
+easysql.exceptions
+==================
+All exceptions raised by the EasySQL library.
+"""
+
+
+class DatabaseError(Exception):
+    """
+    Raised for any EasySQL / database-level error.
+
+    Examples
+    --------
+    >>> from easysql import DatabaseError
+    >>> try:
+    ...     db.remove("users")          # missing filter
+    ... except DatabaseError as e:
+    ...     print(f"Caught: {e}")
+    """
+    pass
+
+
+class ConnectionError(DatabaseError):
+    """Raised when a connection to the database cannot be established."""
+    pass
+
+
+class TableNotFoundError(DatabaseError):
+    """Raised when an operation targets a table that does not exist."""
+    pass
+
+
+class RecordNotFoundError(DatabaseError):
+    """Raised when a required row is not found (e.g. clone_row with bad ID)."""
+    pass
+
+
+class ValidationError(DatabaseError):
+    """Raised when input data fails a safety check (e.g. empty filter on delete)."""
+    pass