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
