Metadata-Version: 2.4
Name: moltres
Version: 0.19.2
Summary: DataFrame API with SQL pushdown execution and real SQL CRUD - the missing layer for SQL in Python
Author-email: Odos Matthews <odosmatthews@gmail.com>
License: MIT License
Project-URL: Homepage, https://github.com/eddiethedean/moltres
Project-URL: Repository, https://github.com/eddiethedean/moltres
Project-URL: Issues, https://github.com/eddiethedean/moltres/issues
Keywords: dataframe,sql,crud,pushdown,etl,data-engineering,sqlalchemy,pandas,polars,spark,database,query-builder
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: SQLAlchemy>=2.0
Requires-Dist: typing-extensions>=4.5
Provides-Extra: polars
Requires-Dist: polars>=1.0; extra == "polars"
Provides-Extra: pandas
Requires-Dist: pandas>=2.1; extra == "pandas"
Provides-Extra: sqlmodel
Requires-Dist: sqlmodel>=0.0.14; extra == "sqlmodel"
Provides-Extra: django
Requires-Dist: django>=3.2; extra == "django"
Provides-Extra: streamlit
Requires-Dist: streamlit>=1.28.0; extra == "streamlit"
Provides-Extra: airflow
Requires-Dist: apache-airflow>=3.0.0; python_version >= "3.10" and extra == "airflow"
Provides-Extra: prefect
Requires-Dist: prefect>=2.0.0; extra == "prefect"
Provides-Extra: dbt
Requires-Dist: dbt-core>=1.5.0; extra == "dbt"
Provides-Extra: async
Requires-Dist: aiofiles>=23.0; extra == "async"
Requires-Dist: greenlet>=3.0.0; extra == "async"
Provides-Extra: async-postgresql
Requires-Dist: aiofiles>=23.0; extra == "async-postgresql"
Requires-Dist: asyncpg>=0.29.0; extra == "async-postgresql"
Requires-Dist: greenlet>=3.0.0; extra == "async-postgresql"
Provides-Extra: async-mysql
Requires-Dist: aiofiles>=23.0; extra == "async-mysql"
Requires-Dist: aiomysql>=0.2.0; extra == "async-mysql"
Requires-Dist: greenlet>=3.0.0; extra == "async-mysql"
Provides-Extra: async-sqlite
Requires-Dist: aiofiles>=23.0; extra == "async-sqlite"
Requires-Dist: aiosqlite>=0.19.0; extra == "async-sqlite"
Requires-Dist: greenlet>=3.0.0; extra == "async-sqlite"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: pytest-green-light>=0.2.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.5; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Requires-Dist: sphinx>=7.0; extra == "dev"
Requires-Dist: sphinx-rtd-theme>=2.0; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: pre-commit>=3.5; extra == "dev"
Requires-Dist: pandas>=2.1; extra == "dev"
Requires-Dist: pandas-stubs>=2.1; extra == "dev"
Requires-Dist: polars>=1.0; extra == "dev"
Requires-Dist: pyarrow>=10.0; extra == "dev"
Requires-Dist: aiofiles>=23.0; extra == "dev"
Requires-Dist: aiosqlite>=0.19.0; extra == "dev"
Requires-Dist: asyncpg>=0.29.0; extra == "dev"
Requires-Dist: greenlet>=3.0.0; extra == "dev"
Requires-Dist: testing.postgresql>=1.3.0; extra == "dev"
Requires-Dist: testing.mysqld>=1.4.0; extra == "dev"
Requires-Dist: psycopg2-binary>=2.9.0; extra == "dev"
Requires-Dist: pymysql>=1.0.0; extra == "dev"
Requires-Dist: duckdb-engine>=0.9.0; extra == "dev"
Requires-Dist: sqlmodel>=0.0.14; extra == "dev"
Requires-Dist: fastapi>=0.100.0; extra == "dev"
Requires-Dist: uvicorn>=0.23.0; extra == "dev"
Requires-Dist: django>=3.2; extra == "dev"
Requires-Dist: streamlit>=1.28.0; extra == "dev"
Requires-Dist: apache-airflow>=3.0.0; python_version >= "3.10" and extra == "dev"
Requires-Dist: prefect>=2.0.0; extra == "dev"
Requires-Dist: dbt-core>=1.5.0; extra == "dev"

# Moltres

<div align="center">

[![CI](https://github.com/eddiethedean/moltres/actions/workflows/ci.yml/badge.svg)](https://github.com/eddiethedean/moltres/actions/workflows/ci.yml)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://github.com/eddiethedean/moltres)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/eddiethedean/moltres/blob/main/LICENSE)
[![Documentation Status](https://readthedocs.org/projects/moltres/badge/?version=latest)](https://moltres.readthedocs.io/en/latest/?badge=latest)

**The Missing DataFrame Layer for SQL in Python**

**MOLTRES**: **M**odern **O**perations **L**ayer for **T**ransformations, **R**elational **E**xecution, and **S**QL

</div>

---

**Moltres** combines a DataFrame API (like Pandas/Polars), SQL pushdown execution (no data loading into memory), and real SQL CRUD operations (INSERT, UPDATE, DELETE) in one unified interface.

Transform millions of rows using familiar DataFrame operations—all executed directly in SQL without materializing data.

## ✨ Key Features

- 🚀 **PySpark-Style DataFrame API** - Primary API with 98% PySpark compatibility
- 🗄️ **SQL Pushdown Execution** - All operations compile to SQL and run on your database
- ✏️ **Real SQL CRUD** - INSERT, UPDATE, DELETE with DataFrame-style syntax
- 🐼 **Pandas & Polars Interfaces** - Optional pandas/polars-style APIs
- ⚡ **Async Support** - Full async/await support for all operations
- 🔒 **Security First** - Built-in SQL injection prevention
- 🎯 **Framework Integrations** - FastAPI, Django, Streamlit, SQLModel, Pydantic

## 📦 Installation

```bash
pip install moltres

# Optional extras
pip install moltres[async-postgresql]  # Async PostgreSQL
pip install moltres[pandas,polars]     # Pandas/Polars result formats
pip install moltres[sqlmodel]          # SQLModel/Pydantic integration
pip install moltres[streamlit]        # Streamlit integration
```

## 🚀 Quick Start

```python
from moltres import col, connect
from moltres.expressions import functions as F

# Connect to your database
db = connect("sqlite:///example.db")

# DataFrame operations with SQL pushdown (no data loading into memory)
df = (
    db.table("orders")
    .select()
    .join(db.table("customers").select(), on=[col("orders.customer_id") == col("customers.id")])
    .where(col("active") == True)
    .group_by("country")
    .agg(F.sum(col("amount")).alias("total_amount"))
)

# Execute and get results
results = df.collect()  # Returns list of dicts by default
```

### CRUD Operations

```python
from moltres.io.records import Records

# Insert rows
Records.from_list([
    {"id": 1, "name": "Alice", "email": "alice@example.com"},
    {"id": 2, "name": "Bob", "email": "bob@example.com"},
], database=db).insert_into("users")

# Update rows
db.update("users", where=col("active") == 0, set={"active": 1})

# Delete rows
db.delete("users", where=col("email").is_null())
```

## 📖 Documentation

- **[Getting Started Guide](https://moltres.readthedocs.io/en/latest/guides/getting-started.html)** - Step-by-step introduction
- **[Examples Directory](https://moltres.readthedocs.io/en/latest/EXAMPLES.html)** - 29 comprehensive examples
- **[User Guides](https://moltres.readthedocs.io/en/latest/#guides-how-to)** - Complete guides for all features
- **[API Reference](https://moltres.readthedocs.io/en/latest/api/dataframe.html)** - Complete API documentation

### Framework Integrations

- **[FastAPI Integration](https://moltres.readthedocs.io/en/latest/EXAMPLES.html)** - Error handling, dependency injection
- **[Django Integration](https://moltres.readthedocs.io/en/latest/EXAMPLES.html)** - Middleware, template tags, management commands
- **[Streamlit Integration](https://moltres.readthedocs.io/en/latest/EXAMPLES.html)** - Components, caching, query visualization
- **[SQLModel & Pydantic](https://moltres.readthedocs.io/en/latest/guides/sqlmodel-integration.html)** - Type-safe models

## 🛠️ Supported Operations

**DataFrame Operations**: `select()`, `where()`, `join()`, `group_by()`, `agg()`, `order_by()`, `limit()`, `distinct()`, `pivot()`, and more

**130+ Functions**: Mathematical, string, date/time, aggregate, window, array, JSON, and utility functions

**SQL Dialects**: SQLite, PostgreSQL, MySQL, DuckDB, and any SQLAlchemy-supported database

## 🧪 Development

```bash
# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

# Code quality
ruff check . && ruff format . && mypy src
```

## 🤝 Contributing

Contributions are welcome! See [`CONTRIBUTING.md`](https://moltres.readthedocs.io/en/latest/CONTRIBUTING.html) for guidelines.

## 📄 License

MIT License - see [LICENSE](https://github.com/eddiethedean/moltres/blob/main/LICENSE) file for details.

---

<div align="center">

**Made with ❤️ for the Python data community**

[⬆ Back to Top](#moltres)

</div>
