Examples
========

This page contains comprehensive examples showing how to use ProllyTree in different scenarios.

Basic Tree Operations
---------------------

Simple Key-Value Store
~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   from prollytree import ProllyTree

   def example_basic_kv_store():
       """Basic key-value store example"""
       tree = ProllyTree()

       # Store user data
       users = {
           "alice": {"name": "Alice Smith", "age": 30},
           "bob": {"name": "Bob Jones", "age": 25},
           "charlie": {"name": "Charlie Brown", "age": 35}
       }

       # Insert users
       import json
       for user_id, user_data in users.items():
           key = f"user:{user_id}".encode('utf-8')
           value = json.dumps(user_data).encode('utf-8')
           tree.insert(key, value)

       # Retrieve a user
       alice_data = tree.find(b"user:alice")
       if alice_data:
           alice = json.loads(alice_data.decode('utf-8'))
           print(f"Alice: {alice['name']}, age {alice['age']}")

       return tree

Working with Different Data Types
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   import json
   import pickle
   from datetime import datetime

   def example_data_types():
       """Examples of storing different data types"""
       tree = ProllyTree()

       # String data
       tree.insert(b"string_key", "Hello, World!".encode('utf-8'))

       # JSON data
       data = {"name": "Alice", "scores": [95, 87, 92]}
       tree.insert(b"json_key", json.dumps(data).encode('utf-8'))

       # Binary data (using pickle)
       complex_data = {
           "timestamp": datetime.now(),
           "nested": {"list": [1, 2, 3], "dict": {"a": 1}}
       }
       tree.insert(b"pickle_key", pickle.dumps(complex_data))

       # Retrieve and decode
       string_val = tree.find(b"string_key").decode('utf-8')
       json_val = json.loads(tree.find(b"json_key").decode('utf-8'))
       pickle_val = pickle.loads(tree.find(b"pickle_key"))

       print(f"String: {string_val}")
       print(f"JSON: {json_val}")
       print(f"Pickle: {pickle_val}")

Versioned Storage Examples
--------------------------

Document Version Control
~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   from prollytree import VersionedKvStore
   import json
   from datetime import datetime

   def example_document_versioning():
       """Example of version controlling documents"""
       store = VersionedKvStore("./document_store")

       # Create initial document
       doc = {
           "title": "My Document",
           "content": "Initial content",
           "author": "Alice",
           "created": datetime.now().isoformat()
       }

       store.insert(b"doc:readme", json.dumps(doc).encode('utf-8'))
       commit1 = store.commit("Initial document creation")
       print(f"Initial commit: {commit1[:8]}")

       # Update document
       doc["content"] = "Updated content with more details"
       doc["modified"] = datetime.now().isoformat()
       store.update(b"doc:readme", json.dumps(doc).encode('utf-8'))
       commit2 = store.commit("Add more content details")
       print(f"Update commit: {commit2[:8]}")

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

       return store

Configuration Management
~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   def example_config_management():
       """Example of managing application configuration with versions"""
       store = VersionedKvStore("./config_store")

       # Production config
       prod_config = {
           "database": {
               "host": "prod-db.example.com",
               "port": 5432,
               "ssl": True
           },
           "api": {
               "rate_limit": 1000,
               "timeout": 30
           }
       }

       store.insert(b"config:production", json.dumps(prod_config).encode('utf-8'))
       store.commit("Initial production configuration")

       # Development config
       dev_config = prod_config.copy()
       dev_config["database"]["host"] = "localhost"
       dev_config["database"]["ssl"] = False
       dev_config["api"]["rate_limit"] = 10000  # Higher for dev

       store.insert(b"config:development", json.dumps(dev_config).encode('utf-8'))
       store.commit("Add development configuration")

       # Update production config
       prod_config["api"]["rate_limit"] = 2000  # Increase rate limit
       store.update(b"config:production", json.dumps(prod_config).encode('utf-8'))
       store.commit("Increase production rate limit")

       # Retrieve current configs
       current_prod = json.loads(store.get(b"config:production").decode('utf-8'))
       print(f"Production rate limit: {current_prod['api']['rate_limit']}")

       return store

SQL Query Examples
------------------

.. code-block:: python

   from prollytree import ProllySQLStore

   def example_sql_analytics():
       """Example using SQL for data analytics"""
       sql_store = ProllySQLStore("./analytics_store")

       # Create tables
       sql_store.execute("""
           CREATE TABLE users (
               id INTEGER,
               name TEXT,
               email TEXT,
               signup_date TEXT,
               plan TEXT
           )
       """)

       sql_store.execute("""
           CREATE TABLE events (
               id INTEGER,
               user_id INTEGER,
               event_type TEXT,
               timestamp TEXT,
               metadata TEXT
           )
       """)

       # Insert sample data
       users_data = [
           (1, 'Alice Smith', 'alice@example.com', '2023-01-15', 'premium'),
           (2, 'Bob Jones', 'bob@example.com', '2023-02-01', 'basic'),
           (3, 'Charlie Brown', 'charlie@example.com', '2023-02-15', 'premium'),
       ]

       for user in users_data:
           sql_store.execute(
               "INSERT INTO users (id, name, email, signup_date, plan) VALUES (?, ?, ?, ?, ?)",
               user
           )

       # Analytics queries
       print("=== User Analytics ===")

       # Premium users
       premium_users = sql_store.execute(
           "SELECT name, email FROM users WHERE plan = 'premium'"
       )
       print(f"Premium users: {len(premium_users)}")
       for user in premium_users:
           print(f"  - {user[0]} ({user[1]})")

       return sql_store

Performance Examples
--------------------

.. code-block:: python

   def example_batch_operations():
       """Example showing efficient batch operations"""
       tree = ProllyTree()

       # Generate test data
       import time

       # Single inserts (slower)
       start_time = time.time()
       for i in range(1000):
           key = f"single:{i:04d}".encode('utf-8')
           value = f"value_{i}".encode('utf-8')
           tree.insert(key, value)
       single_time = time.time() - start_time

       # Batch insert (faster)
       start_time = time.time()
       batch_data = []
       for i in range(1000):
           key = f"batch:{i:04d}".encode('utf-8')
           value = f"value_{i}".encode('utf-8')
           batch_data.append((key, value))

       tree.insert_batch(batch_data)
       batch_time = time.time() - start_time

       print(f"Single inserts: {single_time:.3f}s")
       print(f"Batch insert: {batch_time:.3f}s")
       print(f"Speedup: {single_time/batch_time:.1f}x")

       return tree

Branch Merging and Conflict Resolution
---------------------------------------

.. code-block:: python

   from prollytree import VersionedKvStore, ConflictResolution, MergeConflict
   import tempfile
   import os
   import subprocess

   def example_merge_operations():
       """Comprehensive example of branch merging with conflict resolution"""

       # Create temporary directory for the example
       with tempfile.TemporaryDirectory() as tmpdir:
           # Initialize git repository
           subprocess.run(['git', 'init'], cwd=tmpdir, check=True, capture_output=True)
           subprocess.run(['git', 'config', 'user.name', 'Example'], cwd=tmpdir, check=True, capture_output=True)
           subprocess.run(['git', 'config', 'user.email', 'example@test.com'], cwd=tmpdir, check=True, capture_output=True)

           # Create data subdirectory
           data_dir = os.path.join(tmpdir, 'data')
           os.makedirs(data_dir)

           store = VersionedKvStore(data_dir)

           print("=== Basic Merge Without Conflicts ===")

           # Initial data
           store.insert(b"users:alice", b"Alice Smith")
           store.insert(b"users:bob", b"Bob Jones")
           store.insert(b"config:theme", b"light")
           store.commit("Initial data")

           # Create feature branch
           store.create_branch("add-user-feature")

           # Changes on feature branch
           store.insert(b"users:charlie", b"Charlie Brown")
           store.update(b"config:theme", b"dark")
           store.commit("Add Charlie and dark theme")

           # Switch back to main and make different changes
           store.checkout("main")
           store.insert(b"users:diana", b"Diana Prince")
           store.commit("Add Diana")

           # Merge feature branch
           merge_commit = store.merge("add-user-feature", ConflictResolution.TakeSource)
           print(f"Merge successful: {merge_commit[:8]}")

           # Show final state
           print("Final users:")
           for key in [b"users:alice", b"users:bob", b"users:charlie", b"users:diana"]:
               value = store.get(key)
               if value:
                   print(f"  {key.decode()}: {value.decode()}")

           print(f"Theme: {store.get(b'config:theme').decode()}")

           print("\\n=== Conflict Detection ===")

           # Create another scenario with conflicts
           store.create_branch("conflicting-feature")
           store.update(b"config:theme", b"blue")
           store.commit("Change theme to blue")

           store.checkout("main")
           store.update(b"config:theme", b"red")
           store.commit("Change theme to red")

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

           print("\\n=== Conflict Resolution Strategies ===")

           # Demonstrate different resolution strategies
           strategies = [
               ("IgnoreAll", ConflictResolution.IgnoreAll),
               ("TakeSource", ConflictResolution.TakeSource),
               ("TakeDestination", ConflictResolution.TakeDestination)
           ]

           for name, strategy in strategies:
               # Create test branch for each strategy
               branch_name = f"test-{name.lower()}"
               store.checkout("main")
               store.create_branch(branch_name)

               store.update(b"config:theme", b"feature-theme")
               store.commit(f"Feature theme on {branch_name}")

               store.checkout("main")

               # Apply merge with strategy
               merge_commit = store.merge(branch_name, strategy)
               final_theme = store.get(b"config:theme").decode()
               print(f"{name:15} -> Theme: {final_theme}")

               # Reset main for next test
               store.checkout("main")

Running Examples
----------------

.. code-block:: python

   if __name__ == "__main__":
       # Run examples
       print("=== Basic Key-Value Store ===")
       example_basic_kv_store()

       print("\\n=== Data Types ===")
       example_data_types()

       print("\\n=== Document Versioning ===")
       example_document_versioning()

       print("\\n=== SQL Analytics ===")
       example_sql_analytics()

       print("\\n=== Branch Merging ===")
       example_merge_operations()

       print("\\n=== Performance ===")
       example_batch_operations()