Quickstart Guide

This guide will help you get started with ProllyTree Python bindings quickly.

Installation

From Source

git clone https://github.com/zhangfengcdt/prollytree
cd prollytree
./python/build_python.sh --all-features --install

Basic Usage

Creating a Tree

from prollytree import ProllyTree, TreeConfig

# Create with default settings
tree = ProllyTree()

# Or with custom configuration
config = TreeConfig(base=4, modulus=64)
tree = ProllyTree(config=config)

# Use file storage instead of memory
tree = ProllyTree(storage_type="file", path="/path/to/data")

Basic Operations

# Insert data
tree.insert(b"hello", b"world")
tree.insert(b"foo", b"bar")

# Find data
value = tree.find(b"hello")
print(value)  # b"world"

# Update existing key
tree.update(b"hello", b"updated world")

# Delete a key
tree.delete(b"foo")

# Batch operations for efficiency
items = [(b"key1", b"value1"), (b"key2", b"value2")]
tree.insert_batch(items)

Working with Text

ProllyTree operates on bytes, but you can easily work with strings:

def str_to_bytes(s):
    return s.encode('utf-8')

def bytes_to_str(b):
    return b.decode('utf-8') if b else None

# Insert string data
tree.insert(str_to_bytes("name"), str_to_bytes("Alice"))

# Retrieve string data
value = tree.find(str_to_bytes("name"))
name = bytes_to_str(value)
print(name)  # "Alice"

Versioned Storage

ProllyTree provides Git-like versioned storage:

from prollytree import VersionedKvStore

# Create a versioned store
store = VersionedKvStore("/path/to/store")

# Insert data
store.insert(b"user:123", b"Alice")
store.insert(b"user:456", b"Bob")

# Commit changes
commit_id = store.commit("Add initial users")

# Update data
store.update(b"user:123", b"Alice Smith")
commit_id2 = store.commit("Update Alice's name")

# View history
commits = store.log()
for commit in commits:
    print(f"{commit['id'][:8]} - {commit['message']}")

Branch Operations & Merging

ProllyTree supports Git-like branching and merging with conflict resolution:

from prollytree import VersionedKvStore, ConflictResolution

store = VersionedKvStore("/path/to/store")

# Set up initial data
store.insert(b"config:theme", b"light")
store.insert(b"config:lang", b"en")
store.commit("Initial configuration")

# Create and switch to feature branch
store.create_branch("feature-dark-mode")

# Make changes on feature branch
store.update(b"config:theme", b"dark")
store.insert(b"config:animations", b"enabled")
store.commit("Add dark mode and animations")

# Switch back to main branch
store.checkout("main")

# Make different changes on main
store.update(b"config:lang", b"fr")
store.commit("Change language to French")

# Merge feature branch with conflict resolution
try:
    # Attempt merge, taking source values on conflicts
    merge_commit = store.merge("feature-dark-mode", ConflictResolution.TakeSource)
    print(f"Merge successful: {merge_commit[:8]}")
except Exception as e:
    print(f"Merge failed: {e}")

# Check for conflicts without applying merge
success, conflicts = store.try_merge("feature-dark-mode")
if not success:
    print(f"Found {len(conflicts)} conflicts:")
    for conflict in conflicts:
        print(f"  Key: {conflict.key}")
        print(f"    Source: {conflict.source_value}")
        print(f"    Destination: {conflict.destination_value}")

SQL Queries

Query your data using SQL (requires building with SQL feature):

from prollytree import ProllySQLStore

# Create SQL store
sql_store = ProllySQLStore("/path/to/sql_store")

# Create tables and insert data
sql_store.execute("""
    CREATE TABLE users (
        id INTEGER,
        name TEXT,
        email TEXT
    )
""")

sql_store.execute("""
    INSERT INTO users (id, name, email) VALUES
    (1, 'Alice', 'alice@example.com'),
    (2, 'Bob', 'bob@example.com')
""")

# Query data
results = sql_store.execute("SELECT * FROM users WHERE name = 'Alice'")
print(results)

Next Steps