Quickstart Guide
================

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

Installation
------------

From PyPI (Recommended)
~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

   pip install prollytree

From Source
~~~~~~~~~~~

.. code-block:: bash

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

Basic Usage
-----------

Creating a Tree
~~~~~~~~~~~~~~~

.. code-block:: python

   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
~~~~~~~~~~~~~~~~

.. code-block:: python

   # 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:

.. code-block:: python

   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:

.. code-block:: python

   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:

.. code-block:: python

   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):

.. code-block:: python

   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
----------

- Check out the :doc:`examples` for more detailed use cases
- Read the :doc:`api` for complete documentation
- See :doc:`advanced` for performance optimization and advanced features