rustybase 0.1.1

Official Python SDK for RustyBase Database

RustyBase Python SDK 🐍

The official Python client for RustyBase, a high-performance, embedded-friendly database system with a MongoDB-like API.

---

📚 Table of Contents

• Installation
• Quick Start
• Client Configuration
• Authentication
• CRUD Operations
  • Insert
  • Find & Query
  • Update
  • Delete
• Filtering & Operators
• Aggregation Framework
• Async Support
• Admin Operations
• Error Handling

---

📦 Installation

pip install rustybase

🚀 Quick Start

from rustybase import RustyBaseClient

# 1. Connect
client = RustyBaseClient(connection_string="rustybase://admin:password@localhost:3000/mydb")

# 2. Authenticate
client.login()

# 3. Get Collection
users = client.db("mydb").collection("users")

# 4. Insert Data
users.insert_one({"name": "Alice", "role": "engineer", "age": 28})

# 5. Find Data
alice = users.find_one({"name": "Alice"})
print(f"Found user: {alice}")

---

🛠 Client Configuration

You can initialize the client using a connection string or individual parameters.

Connection String (Recommended)

client = RustyBaseClient(
    connection_string="rustybase://username:password@host:port/database?authSource=admin"
)

Individual Parameters

client = RustyBaseClient(
    host="127.0.0.1",
    port=3000,
    username="admin",
    password="password",
    database="default",
    timeout=30.0,
    use_signing=False  # Enable HMAC request signing for extra security
)

Parameter	Type	Default	Description
connection_string	str	None	URI formatted connection string.
use_signing	bool	False	If True, adds X-RB-Signature headers to requests.
timeout	float	30.0	Request timeout in seconds.
request_callback	Callable	None	Optional callback (fn(method, url, payload, response)) for logging.

---

🔐 Authentication

RustyBase uses JWT authentication. You must login before performing operations. The SDK handles automatic token refreshing for you.

# Authenticate and obtain tokens
client.login()

# ... perform operations ...

# Tokens are auto-refreshed on 401 errors.

---

💾 CRUD Operations

Insert

Insert One

doc = {"name": "Bob", "tags": ["developer", "python"]}
result = users.insert_one(doc)
# result: {"inserted_count": 1, "inserted_ids": [...]}

Insert Many

docs = [
    {"name": "Charlie", "age": 25},
    {"name": "Dana", "age": 30}
]
users.insert_many(docs)

Find & Query

The find method is powerful and supports filtering, projection, sorting, implementation, and pagination.

results = users.find(
    filter={"age": {"$gt": 25}},   # Query criteria
    projection={"name": 1},        # Fields to include (1) or exclude (0)
    sort={"age": -1},              # 1 for Ascending, -1 for Descending
    limit=10,                      # Max documents to return
    skip=0,                        # Documents to skip
    auto_indexing=True             # Allow ad-hoc indexing for performance
)

Find One Helper to return a single document or None.

user = users.find_one({"_id": "some_id"})

Update

Updates a single document matching the filter.

users.update_one(
    filter={"name": "Alice"},
    update={"$set": {"active": True}, "$inc": {"age": 1}},
    upsert=True  # Create if it doesn't exist
)

Delete

Removes a document matching the filter.

users.delete_one({"name": "Charlie"})

---

🔍 Filtering & Operators

RustyBase supports a rich set of MongoDB-compatible query operators.

Comparison Operators

Operator	Description	Example
$eq	Matches values that are equal to a specified value.	{"age": {"$eq": 20}} or {"age": 20}
$gt	Matches values that are greater than a specified value.	{"age": {"$gt": 20}}
$gte	Matches values that are greater than or equal to a specified value.	{"age": {"$gte": 20}}
$lt	Matches values that are less than a specified value.	{"age": {"$lt": 20}}
$lte	Matches values that are less than or equal to a specified value.	{"age": {"$lte": 20}}
$ne	Matches all values that are not equal to a specified value.	{"age": {"$ne": 20}}
$in	Matches any of the values specified in an array.	{"status": {"$in": ["active", "pending"]}}
$nin	Matches none of the values specified in an array.	{"status": {"$nin": ["banned", "deleted"]}}

Logical Operators

Operator	Description	Example
$and	Joins query clauses with a logical AND.	{"$and": [{"price": {"$ne": 1.99}}, {"price": {"$exists": true}}]}
$or	Joins query clauses with a logical OR.	{"$or": [{"qty": {"$lt": 20}}, {"price": 10}]}
$not	Inverts the effect of a query expression.	{"price": {"$not": {"$gt": 1.99}}}
$nor	Joins query clauses with a logical NOR.	{"$nor": [{"price": 1.99}, {"sale": true}]}

Element Operators

Operator	Description	Example
$exists	Matches documents that have the specified field.	{"qty": {"$exists": true}}
$type	Selects documents if a field is of the specified type.	{"price": {"$type": "number"}}

---

📊 Aggregation Framework

Perform complex data analysis using aggregation pipelines.

pipeline = [
    # Stage 1: Filter documents
    {"$match": {"status": "active"}},

    # Stage 2: Group by a field and calculate metrics
    {"$group": {
        "_id": "$department",
        "total_salary": {"$sum": "$salary"},
        "avg_age": {"$avg": "$age"}
    }},

    # Stage 3: Sort the results
    {"$sort": {"total_salary": -1}}
]

results = users.aggregate(pipeline)

Supported Aggregation Stages

• $match: Filters the documents.
• $group: Groups input documents by the specified _id.
• $sort: Sorts the documents.
• $project: Reshapes each document in the stream (include/exclude fields).
• $limit: Limits the number of documents.
• $skip: Skips the specified number of documents.
• $unwind: Deconstructs an array field from the input documents.
• $count: Counts the number of documents.

Accumulators (for $group)

• $sum, $avg, $min, $max, $first, $last, $push, $addToSet.

---

⚡ Async Support

The SDK includes a full Asynchronous Client built on httpx.AsyncClient. It mirrors the synchronous API perfectly, but all network methods are awaitable.

import asyncio
from rustybase import AsyncRustyBaseClient

async def main():
    client = AsyncRustyBaseClient(connection_string="...")
    await client.login()

    db = client.db("test")
    users = db.collection("users")

    # Awaitable methods
    await users.insert_one({"name": "Async User"})
    docs = await users.find({"name": "Async User"})
    print(docs)

    await client.close()

asyncio.run(main())

---

🛡 Admin Operations

Manage databases and users programmatically.

# Create a new database
client.create_database("new_db")

# List all databases
dbs = client.list_databases()

# Create a new user
client.create_user("new_user", "secure_password", "new_db", roles=["readWrite"])

# Wipe all data (Danger!)
# client.wipe_all_data()

---

⚠️ Error Handling

The SDK raises specific exceptions for different failure scenarios. All exceptions inherit from RustyBaseError.

from rustybase import AuthenticationError, ConnectionError, RequestError

try:
    client.login()
except AuthenticationError:
    print("Check your username/password!")
except ConnectionError:
    print("Is the server running?")
except RequestError as e:
    print(f"API Error: {e}")

---

License

This SDK is available under the MIT License.