Metadata-Version: 2.1
Name: dbx-py
Version: 0.0.3b0
Summary: Python bindings for DBX high-performance database
Author: DBX Contributors
License: MIT
Project-URL: Homepage, https://github.com/bytelogiccore-spec/DBX
Project-URL: Repository, https://github.com/bytelogiccore-spec/DBX
Project-URL: Documentation, https://bytelogiccore-spec.github.io/DBX/
Keywords: database,embedded,key-value,storage
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
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 :: Rust
Classifier: Topic :: Database
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# dbx-py

[![PyPI](https://img.shields.io/pypi/v/dbx-py.svg)](https://pypi.org/project/dbx-py/)
[![License](https://img.shields.io/badge/license-MIT%20OR%20Commercial-green.svg)](LICENSE)
[![Guide](https://img.shields.io/badge/guide-GitHub%20Pages-blue)](https://bytelogiccore-spec.github.io/DBX/english/packages/python)

Python bindings for the DBX high-performance embedded database.

## Installation

### From Source

```bash
cd bindings/python
pip install -e .
```

This will automatically build the Rust FFI library and install the Python package.

## Quick Start

```python
from dbx_py import Database

# Open an in-memory database
db = Database.open_in_memory()

# Or open a file-based database
# db = Database("my_database.db")

# Insert data
db.insert("users", b"user:1", b"Alice")
db.insert("users", b"user:2", b"Bob")

# Get data
value = db.get("users", b"user:1")
print(value.decode('utf-8'))  # Output: Alice

# Count rows
count = db.count("users")
print(f"Total users: {count}")  # Output: Total users: 2

# Delete data
db.delete("users", b"user:2")

# Flush to disk
db.flush()

# Close database
db.close()
```

## Context Manager Support

```python
with Database("my_database.db") as db:
    db.insert("users", b"user:1", b"Alice")
    value = db.get("users", b"user:1")
    print(value.decode('utf-8'))
# Database is automatically closed
```

## API Reference

### `Database(path: str)`

Open a database at the specified path.

**Parameters:**
- `path` (str): Path to the database file

**Returns:**
- `Database`: Database instance

### `Database.open_in_memory() -> Database`

Open an in-memory database.

**Returns:**
- `Database`: Database instance

### `insert(table: str, key: bytes, value: bytes) -> None`

Insert a key-value pair into a table.

**Parameters:**
- `table` (str): Table name
- `key` (bytes): Key data
- `value` (bytes): Value data

**Raises:**
- `RuntimeError`: If insertion fails

### `get(table: str, key: bytes) -> Optional[bytes]`

Get a value by key from a table.

**Parameters:**
- `table` (str): Table name
- `key` (bytes): Key data

**Returns:**
- `bytes` or `None`: Value data if found, None otherwise

**Raises:**
- `RuntimeError`: If operation fails

### `delete(table: str, key: bytes) -> None`

Delete a key from a table.

**Parameters:**
- `table` (str): Table name
- `key` (bytes): Key data

**Raises:**
- `RuntimeError`: If deletion fails

### `count(table: str) -> int`

Count rows in a table.

**Parameters:**
- `table` (str): Table name

**Returns:**
- `int`: Number of rows

**Raises:**
- `RuntimeError`: If operation fails

### `flush() -> None`

Flush database to disk.

**Raises:**
- `RuntimeError`: If flush fails

### `close() -> None`

Close the database and free resources.

## Examples

See the `examples/` directory for more examples:
- `basic_crud.py`: Basic CRUD operations

## Requirements

- Python 3.8+
- Rust toolchain (for building from source)

## License

Dual-licensed under:
- **MIT License** — for open-source projects
- **Commercial License** — for proprietary/commercial use

See [LICENSE](https://github.com/bytelogiccore-spec/DBX/blob/main/LICENSE) for details.

For commercial licensing inquiries, contact: [ByteLogicCore](https://github.com/bytelogiccore-spec)
