Metadata-Version: 2.4
Name: datavoxel
Version: 0.2.0
Summary: Type-Safe Modern ORM - Data in 3D
Project-URL: Homepage, https://github.com/jdevsky/datavoxel
Project-URL: Documentation, https://github.com/jdevsky/datavoxel#readme
Project-URL: Repository, https://github.com/jdevsky/datavoxel.git
Project-URL: Bug Tracker, https://github.com/jdevsky/datavoxel/issues
Author-email: Juste Elysée MALANDILA <justech4dev@gmail.com>
License: MIT License
        
        Copyright (c) 2024 Juste Elysée MALANDILA
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: async,database,orm,prisma,sql,sqlalchemy,type-safe
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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
Requires-Python: >=3.8
Requires-Dist: asyncpg>=0.29.0
Requires-Dist: sqlalchemy>=2.0.0
Provides-Extra: dev
Requires-Dist: black>=22.0; extra == 'dev'
Requires-Dist: build>=0.8; extra == 'dev'
Requires-Dist: flake8>=4.0; extra == 'dev'
Requires-Dist: isort>=5.0; extra == 'dev'
Requires-Dist: mypy>=0.950; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: twine>=4.0; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">

```
██████╗  █████╗ ████████╗ █████╗ ██╗   ██╗ ██████╗ ██╗  ██╗███████╗██╗     
██╔══██╗██╔══██╗╚══██╔══╝██╔══██╗██║   ██║██╔═══██╗╚██╗██╔╝██╔════╝██║     
██║  ██║███████║   ██║   ███████║██║   ██║██║   ██║ ╚███╔╝ █████╗  ██║     
██║  ██║██╔══██║   ██║   ██╔══██║╚██╗ ██╔╝██║   ██║ ██╔██╗ ██╔══╝  ██║     
██████╔╝██║  ██║   ██║   ██║  ██║ ╚████╔╝ ╚██████╔╝██╔╝ ██╗███████╗███████╗
╚═════╝ ╚═╝  ╚═╝   ╚═╝   ╚═╝  ╚═╝  ╚═══╝   ╚═════╝ ╚═╝  ╚═╝╚══════╝╚══════╝
```

### 🗄️ *Type-Safe Modern ORM* 🗄️

<p align="center">
  <strong>Data in 3D - Where Database Queries Feel Like Magic</strong>
</p>

[![PyPI version](https://img.shields.io/pypi/v/datavoxel?color=blue&style=for-the-badge)](https://pypi.org/project/datavoxel/)
[![Python Versions](https://img.shields.io/pypi/pyversions/datavoxel?style=for-the-badge)](https://pypi.org/project/datavoxel/)
[![License](https://img.shields.io/badge/License-MIT-green.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
[![Downloads](https://img.shields.io/pypi/dm/datavoxel?style=for-the-badge&color=orange)](https://pepy.tech/project/datavoxel)

[![Type Checked](https://img.shields.io/badge/type%20checked-mypy-blue?style=for-the-badge)](http://mypy-lang.org/)
[![Async Ready](https://img.shields.io/badge/async-ready-brightgreen?style=for-the-badge)]()
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg?style=for-the-badge)](https://github.com/psf/black)

<p align="center">
  <a href="#-quick-start">Quick Start</a> •
  <a href="#-features">Features</a> •
  <a href="#-examples">Examples</a> •
  <a href="#-documentation">Documentation</a>
</p>

![Separator](https://user-images.githubusercontent.com/74038190/212284100-561aa473-3905-4a80-b561-0d28506553ee.gif)

</div>

## 🌟 What is DATAVOXEL?

**DATAVOXEL** is a revolutionary ORM that thinks in **3 dimensions**: **Type Safety**, **Developer Experience**, and **Performance**. Built on SQLAlchemy but with a modern twist, it makes database operations feel **natural** and **intuitive**.

```python
from datavoxel import Model, Query

class User(Model):
    __table__ = "users"
    
    id: int
    name: str
    email: str
    created_at: datetime

# Type-safe queries with IDE autocomplete!
users = Query(User).where(User.age > 18).order_by(User.name).limit(10).all()
# 🎯 Your IDE knows exactly what type 'users' is!
```

---

## ✨ Key Features

<table>
<tr>
<td width="50%">

### 🎯 Type Safety
- ✅ **Full Type Hints** - IDE autocomplete everywhere
- 🔍 **Mypy Compatible** - Catch errors before runtime
- 📝 **IntelliSense** - See available fields instantly
- 🛡️ **Compile-Time Checks** - No more typos

</td>
<td width="50%">

### ⚡ Performance
- 🚀 **Async First** - Built for async/await
- 🔄 **Connection Pooling** - Reuse connections
- 💾 **Query Caching** - Automatic optimization
- 📊 **Lazy Loading** - Load data when needed

</td>
</tr>
<tr>
<td width="50%">

### 🎨 Developer Experience
- 💡 **Intuitive API** - Reads like English
- 🔗 **Method Chaining** - Build queries naturally
- 🏗️ **Auto Migrations** - Schema changes made easy
- 📚 **Rich Documentation** - Examples for everything

</td>
<td width="50%">

### 🏗️ Production Ready
- ✅ **Battle Tested** - Built on SQLAlchemy
- 🔒 **SQL Injection Safe** - Parameterized queries
- 🌍 **Multi-DB Support** - Postgres, MySQL, SQLite
- 📈 **Scalable** - From MVP to millions of rows

</td>
</tr>
</table>

---

## 📦 Installation

```bash
# Basic installation (SQLite support)
pip install datavoxel

# With PostgreSQL support
pip install datavoxel[postgres]

# With MySQL support  
pip install datavoxel[mysql]

# With all database drivers
pip install datavoxel[all]
```

---

## 🎯 Quick Start

### Define Your Models

```python
from datavoxel import Model
from datetime import datetime
from typing import Optional

class User(Model):
    __table__ = "users"
    __database__ = "myapp"
    
    id: int
    username: str
    email: str
    is_active: bool = True
    created_at: datetime = datetime.now()
    bio: Optional[str] = None
```

### Simple CRUD Operations

```python
# Create
user = User(username="john_doe", email="john@example.com")
await user.save()

# Read
user = await User.get(id=1)
users = await User.filter(is_active=True).all()

# Update
user.email = "newemail@example.com"
await user.save()

# Delete
await user.delete()
```

### Advanced Queries

```python
from datavoxel import Query, Q

# Complex WHERE clauses
active_users = await Query(User).where(
    (User.is_active == True) & 
    (User.created_at > datetime(2024, 1, 1))
).all()

# Joins
class Post(Model):
    __table__ = "posts"
    user_id: int
    title: str
    content: str

posts_with_users = await Query(Post).join(
    User, Post.user_id == User.id
).select(Post.title, User.username).all()

# Aggregations
from datavoxel import Count, Avg

user_count = await Query(User).aggregate(Count(User.id))
avg_age = await Query(User).aggregate(Avg(User.age))
```

---

## 🏗️ Architecture

```mermaid
graph TB
    A[Your Application] --> B[DATAVOXEL ORM]
    
    B --> C{Query Builder}
    B --> D{Model Manager}
    B --> E{Migration Engine}
    
    C --> F[Type Checker]
    C --> G[SQL Generator]
    
    D --> H[CRUD Operations]
    D --> I[Relationships]
    
    E --> J[Schema Diff]
    E --> K[Auto Migrate]
    
    F --> L[SQLAlchemy Core]
    G --> L
    H --> L
    I --> L
    J --> L
    K --> L
    
    L --> M{Database Driver}
    M --> N[PostgreSQL]
    M --> O[MySQL]
    M --> P[SQLite]
    
    style B fill:#2196F3
    style L fill:#4CAF50
```

---

## 🔥 Advanced Features

### Relationships

```python
class Author(Model):
    __table__ = "authors"
    id: int
    name: str

class Book(Model):
    __table__ = "books"
    id: int
    title: str
    author_id: int
    
    # Define relationship
    author = Relation(Author, foreign_key="author_id")

# Use relationships
book = await Book.get(id=1)
author = await book.author  # Automatically fetches author
print(f"{book.title} by {author.name}")
```

### Transactions

```python
from datavoxel import transaction

async with transaction():
    user = User(username="alice")
    await user.save()
    
    post = Post(title="First Post", user_id=user.id)
    await post.save()
    
    # Both saved or both rolled back together!
```

### Query Optimization

```python
# Eager loading (N+1 query prevention)
books = await Query(Book).prefetch(Book.author).all()
# Only 2 queries instead of N+1!

# Select only needed fields
users = await Query(User).only(User.id, User.username).all()
# Smaller result set = faster queries

# Bulk operations
await User.bulk_create([
    User(username="user1", email="user1@example.com"),
    User(username="user2", email="user2@example.com"),
])
```

### Custom Queries

```python
# Raw SQL when needed
results = await Query.raw("""
    SELECT users.name, COUNT(posts.id) as post_count
    FROM users
    LEFT JOIN posts ON users.id = posts.user_id
    GROUP BY users.id
    HAVING post_count > 10
""")
```

---

## 📊 Comparison with Other ORMs

| Feature | DATAVOXEL | SQLAlchemy | Django ORM | Peewee | Tortoise |
|---------|-----------|------------|------------|--------|----------|
| Type Safety | ✅ Full | ⚠️ Partial | ❌ No | ❌ No | ⚠️ Partial |
| Async Support | ✅ Native | ✅ Yes | ⚠️ Limited | ❌ No | ✅ Yes |
| Learning Curve | 🟢 Easy | 🔴 Hard | 🟢 Easy | 🟢 Easy | 🟡 Medium |
| Auto Migrations | ✅ Built-in | ⚠️ Alembic | ✅ Yes | ❌ No | ✅ Yes |
| IDE Support | ⚡⚡⚡⚡⚡ | ⚡⚡ | ⚡⚡ | ⚡⚡ | ⚡⚡⚡ |
| Performance | ⚡⚡⚡⚡ | ⚡⚡⚡⚡⚡ | ⚡⚡⚡ | ⚡⚡⚡⚡ | ⚡⚡⚡⚡ |

---

## 🎨 Real-World Examples

### FastAPI Integration

```python
from fastapi import FastAPI, Depends
from datavoxel import Model, Query

app = FastAPI()

class User(Model):
    __table__ = "users"
    id: int
    username: str
    email: str

@app.get("/users/{user_id}")
async def get_user(user_id: int):
    user = await User.get(id=user_id)
    return user.dict()  # Automatic serialization!

@app.get("/users")
async def list_users(skip: int = 0, limit: int = 10):
    users = await Query(User).offset(skip).limit(limit).all()
    return [user.dict() for user in users]
```

### Data Pipeline

```python
from datavoxel import Model, transaction
import asyncio

class RawData(Model):
    __table__ = "raw_data"
    id: int
    data: str

class ProcessedData(Model):
    __table__ = "processed_data"
    id: int
    result: str

async def process_data():
    raw_items = await Query(RawData).filter(processed=False).all()
    
    async with transaction():
        for item in raw_items:
            # Process data
            result = transform(item.data)
            
            # Save result
            processed = ProcessedData(result=result)
            await processed.save()
            
            # Mark as processed
            item.processed = True
            await item.save()
```

### Multi-Tenant App

```python
from datavoxel import Model, set_schema

class Tenant(Model):
    __table__ = "tenants"
    id: int
    schema_name: str

class User(Model):
    __table__ = "users"
    __schema_bound__ = True  # Uses current schema
    id: int
    name: str

async def get_tenant_users(tenant_id: int):
    tenant = await Tenant.get(id=tenant_id)
    
    # Switch to tenant schema
    set_schema(tenant.schema_name)
    
    # Query tenant-specific data
    users = await Query(User).all()
    return users
```

---

## 📚 Documentation

- 📖 [Full API Reference](https://datavoxel.readthedocs.io)
- 🚀 [Quick Start Guide](https://datavoxel.readthedocs.io/quickstart)
- 🎓 [Tutorial](https://datavoxel.readthedocs.io/tutorial)
- 🏗️ [Migrations Guide](https://datavoxel.readthedocs.io/migrations)
- 🎯 [Best Practices](https://datavoxel.readthedocs.io/best-practices)

---

## 🗺️ Roadmap

### ✅ Version 0.1.0 (Current)
- [x] Type-safe models
- [x] Basic CRUD operations
- [x] Query builder
- [x] Async support

### 🚧 Version 0.2.0 (Coming Soon)
- [ ] Auto migrations
- [ ] Relationship support
- [ ] Connection pooling
- [ ] Query caching

### 🔮 Version 0.3.0 (Planned)
- [ ] Advanced relationships (M2M, polymorphic)
- [ ] Full-text search
- [ ] Database sharding
- [ ] Performance monitoring
- [ ] GraphQL integration

---

## 🤝 Contributing

Contributions welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

---

## 📜 License

MIT License - see [LICENSE](LICENSE) file for details.

---

## 👤 Author

<div align="center">

### **Juste Elysée MALANDILA**

[![LinkedIn](https://img.shields.io/badge/LinkedIn-0077B5?style=for-the-badge&logo=linkedin&logoColor=white)](https://linkedin.com/in/juste-elysee-malandila)
[![Email](https://img.shields.io/badge/Email-D14836?style=for-the-badge&logo=gmail&logoColor=white)](mailto:justech4dev@gmail.com)
[![GitHub](https://img.shields.io/badge/GitHub-100000?style=for-the-badge&logo=github&logoColor=white)](https://github.com/jdevsky)

*"Making databases feel like magic."* 🗄️

</div>

---

<div align="center">

### Made with ❤️ by [Juste Elysée MALANDILA](https://linkedin.com/in/juste-elysee-malandila)

**DATAVOXEL** - *Data in 3D* 🗄️

![Footer](https://capsule-render.vercel.app/api?type=waving&color=gradient&height=100&section=footer)

</div>
