tubox-client 1.0.0

Official Python client for Tubox Database

Tubox Client

The Next-Gen Python Client for Tubox Database

Features • Quick Start • Architecture • Examples • Documentation

---

Tubox Client is a high-performance, production-ready Python library designed to interact with the Tubox database. Built with a philosophy of "Simple by default, powerful when needed," it offers both a developer-friendly synchronous API and a high-throughput asynchronous core.

🚀 Features at a Glance

🔌 Seamless Connectivity

Automatic connection pooling, health checks, and smart retries ensure your application stays connected even in unstable network conditions.

⚡ Async Native

Built on asyncio from the ground up. Perfect for modern web frameworks like FastAPI, Quart, or Tornado to handle thousands of concurrent requests.

🔒 ACID Transactions

Full support for multi-document transactions using a familiar, MongoDB-style session API.

🛡️ Robust & Secure

Enterprise-grade security with session-based authentication and comprehensive error handling patterns.

📦 Installation

pip install tubox-client

🏎️ Quick Start

Get up and running in seconds.

Synchronous (Standard)

Perfect for scripts, data analysis, and standard web apps (Django, Flask).

from tubox_client import TuboxClient

# 1. Connect
with TuboxClient("localhost", 7188, "admin", "password") as client:
    db = client["my_app"]
    users = db["users"]
    
    # 2. Insert
    users.insert_one({"name": "Alice", "role": "developer"})
    
    # 3. Query
    for user in users.find({"role": "developer"}).documents:
        print(f"Found developer: {user['name']}")

Asynchronous (High Performance)

Built for speed.

import asyncio
from tubox_client import TuboxAPIClient

async def main():
    client = TuboxAPIClient("localhost", 7188)
    await client.connect()
    await client.authenticate("admin", "password")
    
    await client["my_app"]["logs"].insert_one({"event": "login"})
    
    await client.close()

asyncio.run(main())

🏗️ Architecture

Tubox Client is built on a layered architecture to separate concerns and ensure reliability.

The Sync Wrapper manages a dedicated event loop to bridge standard Python code with the Async Core, which handles the heavy lifting of connection management and protocol serialization.

For a deep dive, see ARCHITECTURE.md.

💡 Examples

We have a comprehensive suite of examples to cover every use case:

Category	Example Script	Description
Basics	basic_usage.py	CRUD operations and basic connectivity.
Async	async_usage.py	Native async/await patterns.
ACID	transactions.py	Multi-document transactions with rollback.
Config	advanced_config.py	Tuning pools, timeouts, and logging.
Robustness	error_handling.py	Retry logic for rate limits and outages.
Metrics	monitoring.py	Inspecting client and server health.
Queries	advanced_querying.py	Pagination, sorting, and projections.

📚 Documentation

Full documentation is available at https://tubox.cloud/.

📜 License

This project is licensed under the MIT License.