Metadata-Version: 2.4
Name: quacksql
Version: 0.1.0
Summary: A simple Python wrapper for DuckDB with SQL file module loading
Author-email: "D.C. Hess" <dc.hess@gmail.com>
Maintainer-email: "D.C. Hess" <dc.hess@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/dchess/quacksql
Project-URL: Documentation, https://github.com/dchess/quacksql#readme
Project-URL: Repository, https://github.com/dchess/quacksql.git
Project-URL: Issues, https://github.com/dchess/quacksql/issues
Keywords: duckdb,sql,database,query
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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: Topic :: Database
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: duckdb>=0.9.0
Requires-Dist: pandas
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file

# QuackSQL

A simple Python wrapper for DuckDB that allows you to load and execute SQL queries from files with a clean, Pythonic interface.

## Installation

```bash
pip install quacksql
```

## Quick Start

```python
import quacksql

# Connect to an in-memory database (default)
quacksql.connect()

# Or connect to a file
quacksql.connect('my_database.duckdb')

# Load SQL queries from a directory
quacksql.module('./queries')

# Execute a query (assumes you have a file queries/get_users.sql)
results = quacksql.get_users()

# Get results as a pandas DataFrame
df = quacksql.get_users().df()

# Pass parameters to queries
results = quacksql.get_user_by_id(user_id=123).df()
```

## Features

- **Simple API**: Load SQL files and execute them as Python methods
- **Pandas Integration**: Easy conversion to DataFrames with `.df()`
- **Parameter Support**: Pass parameters to queries using positional or keyword arguments
- **DuckDB Power**: Full access to DuckDB's analytical capabilities

## Usage

### Loading SQL Modules

Place your SQL files in a directory:

```
queries/
├── get_users.sql
├── get_orders.sql
└── update_inventory.sql
```

Load them in Python:

```python
import quacksql

quacksql.connect('mydb.duckdb')
quacksql.module('./queries')

# Now you can call any query as a method
users = quacksql.get_users().df()
orders = quacksql.get_orders().df()
```

### Working with Parameters

SQL file (`queries/get_user.sql`):
```sql
SELECT * FROM users WHERE user_id = ?
```

Python code:
```python
user = quacksql.get_user(123).fetchone()
```

Or with named parameters:
```sql
SELECT * FROM users WHERE name = $name AND age > $min_age
```

```python
users = quacksql.get_users(name='Alice', min_age=25).df()
```

### Query Results

All queries return a `QueryResult` object with multiple methods:

```python
result = quacksql.my_query()

# Get as pandas DataFrame
df = result.df()

# Get all rows as list of tuples
rows = result.fetchall()

# Get first row
first = result.fetchone()

# Get n rows
some = result.fetchmany(10)

# Iterate over results
for row in result:
    print(row)
```

## Requirements

- Python >= 3.8
- DuckDB
- Pandas

## License

MIT License - see LICENSE file for details

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.
