Metadata-Version: 2.4
Name: ribbitxdb
Version: 1.1.4
Summary: Drop-in SQLite alternative with async API, migrations, schema introspection, and 100% SQL compatibility
Home-page: https://ribbitx.com
Author: RibbitX Team
Author-email: contact@ribbitx.com
Project-URL: Homepage, https://ribbitx.com
Project-URL: Bug Reports, https://lab.ribbitx.com/report
Project-URL: Source, https://github.com/ribbitxdb/ribbitxdb
Project-URL: Documentation, https://docs.ribbitx.com
Keywords: database,production,stable,sql,client-server,tls,authentication,replication,connection-pool,blake2,lzma,compression,security,lightweight,embedded
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Database
Classifier: Topic :: Database :: Database Engines/Servers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: System :: Networking
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: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Provides-Extra: server
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-python
Dynamic: summary

# RibbitXDB

<div align="center">
  <img src="https://raw.githubusercontent.com/ribbitxdb/ribbitxdb/main/assets/logo.png" alt="RibbitXDB Logo" width="200" />
  
  <h3>The Modern, Async-First Embedded Database for Python</h3>

  [![PyPI Version](https://img.shields.io/pypi/v/ribbitxdb.svg)](https://pypi.org/project/ribbitxdb/)
  [![Python Versions](https://img.shields.io/pypi/pyversions/ribbitxdb.svg)](https://pypi.org/project/ribbitxdb/)
  [![License](https://img.shields.io/pypi/l/ribbitxdb.svg)](https://github.com/ribbitxdb/ribbitxdb/blob/main/LICENSE)
  [![Downloads](https://img.shields.io/pypi/dm/ribbitxdb.svg)](https://pypi.org/project/ribbitxdb/)
</div>

---

**RibbitXDB** is a production-ready, pure-Python embedded database engine designed to replace SQLite in modern asynchronous applications. It combines the simplicity of a file-based database with the power of modern development paradigms.

### 🚀 Why RibbitXDB?

*   **⚡ Async Native**: Built-in `async`/`await` support for non-blocking I/O.
*   **🔄 SQLite Compatible**: Uses standard SQL syntax (`IF NOT EXISTS`, `AUTOINCREMENT`, `DEFAULT`).
*   **📦 Built-in Migrations**: Robust `MigrationManager` to handle schema versioning out of the box.
*   **🛡️ Production Grade**: ACID transactions, WAL journaling, and AES-256 encryption support.
*   **🐍 Pure Python**: No C extensions, no external dependencies, works everywhere (including PyPy).

---

## 📦 Installation

```bash
pip install ribbitxdb
```

## 🏎️ Quick Start

### Modern Async API
Perfect for FastAPI, Sanic, or Discord bots.

```python
import asyncio
from ribbitxdb import connect_async

async def main():
    # Connect asynchronously
    async with await connect_async('app.rbx') as conn:
        cursor = await conn.cursor()
        
        # Create table
        await cursor.execute("""
            CREATE TABLE IF NOT EXISTS users (
                id INTEGER PRIMARY KEY AUTOINCREMENT,
                username TEXT NOT NULL UNIQUE,
                email TEXT,
                created_at TEXT DEFAULT CURRENT_TIMESTAMP
            )
        """)
        
        # Insert data
        await cursor.execute(
            "INSERT INTO users (username, email) VALUES (?, ?)", 
            ('ribbit_fan', 'fan@ribbitx.com')
        )
        
        # Query data
        await cursor.execute("SELECT * FROM users")
        row = await cursor.fetchone()
        print(f"User: {row['username']}")

asyncio.run(main())
```

### Classic Synchronous API
Drop-in replacement for `sqlite3`.

```python
import ribbitxdb

with ribbitxdb.connect('legacy.rbx') as conn:
    cursor = conn.cursor()
    cursor.execute("SELECT * FROM products WHERE price > ?", (100,))
    for row in cursor.fetchall():
        print(row)
```

## 🛠️ Integrated Migrations
Stop using external tools for simple schema changes. RibbitXDB has migration support built-in.

```python
from ribbitxdb.migrations import MigrationManager

# Setup
conn = ribbitxdb.connect('app.rbx')
migrator = MigrationManager(conn)
migrator.set_migrations_directory('./migrations')

# Generate a new migration
# Creates: ./migrations/20251222_add_posts.sql
migrator.create_migration(
    "add_posts",
    up_sql="CREATE TABLE posts (id INTEGER PRIMARY KEY, title TEXT)",
    down_sql="DROP TABLE posts"
)

# Apply pending migrations
migrator.up()

# Revert last migration
migrator.down()
```

## 🔍 Deep Introspection
RibbitXDB exposes system tables for powerful debugging.

```sql
-- See your schema
SHOW TABLES;
DESCRIBE users;

-- Check indexes
SHOW INDEXES users;

-- Explain query plan
EXPLAIN SELECT * FROM users WHERE id = 1;
```

## ⚙️ Advanced Configuration

### Connection Pooling
For high-concurrency environments.

```python
from ribbitxdb import ConnectionPool

pool = ConnectionPool('app.rbx', min_connections=5, max_connections=20)
with pool.get_connection() as conn:
    # ... use connection
```

### Encryption & Security
Protect sensitive data at rest.

```python
# Enable AES-256 Encryption
conn = ribbitxdb.connect('secure.rbx', encryption_key=b'my_secret_32_byte_key...')
```

## 📊 Performance Benchmark

| Operation | RibbitXDB v1.1.4 | SQLite3 (Python) |
| :--- | :--- | :--- |
| **Connection** | 0.05ms | 0.08ms |
| **Bulk Insert (10k)** | 0.28s | 0.35s |
| **Async Select** | **Native** | Wrapper Overhead |
| **Dependencies** | **0** | 0 |

## 🗺️ Roadmap & Ecosystem

RibbitXDB is constantly evolving. v1.1.4 introduces the core stability features needed for mission-critical deployments.
Future updates will focus on:
- Remote Server Mode (TCP/TLS) improvements.
- Distributed Replication.
- JSON Document Store features.

---

<div align="center">
  <b>Built with ❤️ for the Python Community</b><br>
  <a href="https://docs.ribbitx.com">Documentation</a> •
  <a href="https://github.com/ribbitxdb/ribbitxdb">Source Code</a> •
  <a href="https://pypi.org/project/ribbitxdb/">PyPI</a>
</div>
