commitdb 2.2.1__tar.gz

commitdb-2.2.1/PKG-INFO

@@ -0,0 +1,277 @@
+Metadata-Version: 2.4
+Name: commitdb
+Version: 2.2.1
+Summary: Python driver for CommitDB SQL Server
+Author: CommitDB Contributors
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/nickyhof/CommitDB
+Project-URL: Documentation, https://github.com/nickyhof/CommitDB#readme
+Project-URL: Repository, https://github.com/nickyhof/CommitDB
+Keywords: database,sql,git,commitdb
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Provides-Extra: ibis
+Requires-Dist: ibis-framework>=9.0; extra == "ibis"
+Requires-Dist: pandas>=2.0; extra == "ibis"
+
+# CommitDB Python Driver
+
+[![PyPI version](https://badge.fury.io/py/commitdb.svg)](https://badge.fury.io/py/commitdb)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+
+Python client for CommitDB - a Git-backed SQL database engine.
+
+**[📚 Full Documentation](https://nickyhof.github.io/CommitDB/python-driver/)**
+
+> ⚠️ **Experimental Project** - This is a hobby project and should not be used in any production environment.
+
+## Installation
+
+```bash
+pip install commitdb
+```
+
+## Quick Start
+
+### Remote Mode (connect to server)
+
+```python
+from commitdb import CommitDB
+
+with CommitDB('localhost', 3306) as db:
+    db.execute('CREATE DATABASE mydb')
+    db.execute('CREATE TABLE mydb.users (id INT PRIMARY KEY, name STRING)')
+    db.execute("INSERT INTO mydb.users VALUES (1, 'Alice')")
+    
+    result = db.query('SELECT * FROM mydb.users')
+    for row in result:
+        print(f"{row['id']}: {row['name']}")
+```
+
+### Embedded Mode (no server required)
+
+```python
+from commitdb import CommitDBLocal
+
+with CommitDBLocal() as db:  # In-memory
+    db.execute('CREATE DATABASE mydb')
+    db.execute('CREATE TABLE mydb.users (id INT PRIMARY KEY, name STRING)')
+    
+with CommitDBLocal('/path/to/data') as db:  # File-based (persistent)
+    db.execute('CREATE DATABASE mydb')
+```
+
+### Ibis Mode (pandas DataFrame support)
+
+```bash
+pip install commitdb[ibis]
+```
+
+```python
+import ibis
+
+con = ibis.commitdb.connect('localhost', 3306, database='mydb')
+
+# Or use URL-based connection:
+con = ibis.connect('commitdb://localhost:3306/mydb')
+
+# Query with Ibis expressions
+users = con.table('users')
+result = users.filter(users.age > 30).select('name', 'city').execute()  # → pandas DataFrame
+print(result)
+
+# Insert from DataFrame
+import pandas as pd
+df = pd.DataFrame({'id': [1, 2], 'name': ['Alice', 'Bob']})
+con.insert('users', df)
+```
+
+---
+
+## API Reference
+
+### CommitDB (Remote)
+
+```python
+CommitDB(host='localhost', port=3306, use_ssl=False, ssl_verify=True, 
+         ssl_ca_cert=None, jwt_token=None)
+```
+
+| Method | Description |
+|--------|-------------|
+| `connect(timeout=10.0)` | Connect to server |
+| `close()` | Close connection |
+| `execute(sql)` | Execute SQL (INSERT, UPDATE, CREATE, etc.) |
+| `query(sql)` | Execute SELECT, returns QueryResult |
+| `authenticate_jwt(token)` | Authenticate with JWT |
+
+### CommitDBLocal (Embedded)
+
+```python
+CommitDBLocal(path=None, lib_path=None)
+```
+
+- `path` - Directory for persistence (`None` = in-memory)
+- `lib_path` - Path to `libcommitdb` shared library
+
+| Method | Description |
+|--------|-------------|
+| `open()` / `close()` | Open/close database |
+| `execute(sql)` | Execute SQL |
+| `query(sql)` | Execute SELECT |
+
+### QueryResult
+
+```python
+result = db.query('SELECT * FROM mydb.users')
+result.columns  # ['id', 'name']
+len(result)     # Row count
+result[0]       # {'id': '1', 'name': 'Alice'}
+
+for row in result:
+    print(row)
+```
+
+### Error Handling
+
+```python
+from commitdb import CommitDB, CommitDBError
+
+try:
+    with CommitDB('localhost', 3306) as db:
+        db.execute('SELECT * FROM nonexistent.table')
+except CommitDBError as e:
+    print(f"Database error: {e}")
+```
+
+---
+
+## Security
+
+### SSL/TLS Encryption
+
+```python
+# Production (with certificate verification)
+db = CommitDB('localhost', 3306, use_ssl=True, ssl_ca_cert='cert.pem')
+
+# Development (skip verification)
+db = CommitDB('localhost', 3306, use_ssl=True, ssl_verify=False)
+```
+
+### JWT Authentication
+
+```python
+# Auto-authenticate on connect
+db = CommitDB('localhost', 3306, jwt_token='eyJhbG...')
+db.connect()
+print(f"Authenticated as: {db.identity}")
+
+# Or authenticate after connect
+db.connect()
+db.authenticate_jwt('eyJhbG...')
+```
+
+---
+
+## Version Control
+
+### Branching & Merging
+
+```python
+with CommitDBLocal() as db:
+    db.execute('CREATE DATABASE mydb')
+    db.execute('CREATE TABLE mydb.users (id INT, name STRING)')
+    db.execute("INSERT INTO mydb.users VALUES (1, 'Alice')")
+    
+    # Create and switch to branch
+    db.execute('CREATE BRANCH feature')
+    db.execute('CHECKOUT feature')
+    
+    # Make changes (isolated to this branch)
+    db.execute("INSERT INTO mydb.users VALUES (2, 'Bob')")
+    
+    # Switch back and merge
+    db.execute('CHECKOUT master')
+    db.execute('MERGE feature')
+```
+
+**Branch Commands:**
+
+| Command | Description |
+|---------|-------------|
+| `CREATE BRANCH name` | Create new branch |
+| `CHECKOUT name` | Switch to branch |
+| `MERGE name` | Merge branch (auto-resolve) |
+| `MERGE name WITH MANUAL RESOLUTION` | Merge with manual conflict resolution |
+| `SHOW BRANCHES` | List branches |
+| `SHOW MERGE CONFLICTS` | View pending conflicts |
+| `RESOLVE CONFLICT path USING HEAD\|SOURCE` | Resolve conflict |
+| `COMMIT MERGE` / `ABORT MERGE` | Finalize or cancel merge |
+
+### Remote Sync (Git)
+
+```python
+# Add remote
+db.execute("CREATE REMOTE origin 'https://github.com/user/repo.git'")
+
+# Push/Pull with authentication
+db.execute("PUSH WITH TOKEN 'ghp_xxxxxxxxxxxx'")
+db.execute("PUSH WITH SSH KEY '/path/to/id_rsa'")
+db.execute("PULL FROM origin")
+```
+
+---
+
+## Bulk Import/Export
+
+### Local Files
+
+```python
+# Export to CSV
+db.execute("COPY INTO '/path/to/users.csv' FROM mydb.users WITH (HEADER = TRUE)")
+
+# Import from CSV
+db.execute("COPY INTO mydb.users FROM '/path/to/users.csv' WITH (HEADER = TRUE)")
+```
+
+### S3 & HTTPS
+
+```python
+# Import from HTTPS
+db.execute("COPY INTO mydb.users FROM 'https://example.com/data.csv'")
+
+# Import from S3 (uses AWS env vars)
+db.execute("COPY INTO mydb.users FROM 's3://bucket/users.csv'")
+
+# Import from S3 with explicit credentials
+db.execute("""
+    COPY INTO mydb.users FROM 's3://bucket/users.csv' WITH (
+        AWS_KEY = 'AKIAIOSFODNN7EXAMPLE',
+        AWS_SECRET = 'your-secret-key',
+        AWS_REGION = 'us-east-1'
+    )
+""")
+
+# Export to S3
+db.execute("COPY INTO 's3://bucket/export.csv' FROM mydb.users WITH (HEADER = TRUE)")
+```
+
+---
+
+## Building the Shared Library
+
+For embedded mode, if the library isn't bundled:
+
+```bash
+# From CommitDB root
+make lib  # Creates lib/libcommitdb.dylib (macOS) or .so (Linux)
+```

commitdb-2.2.1/README.md

@@ -0,0 +1,252 @@
+# CommitDB Python Driver
+
+[![PyPI version](https://badge.fury.io/py/commitdb.svg)](https://badge.fury.io/py/commitdb)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+
+Python client for CommitDB - a Git-backed SQL database engine.
+
+**[📚 Full Documentation](https://nickyhof.github.io/CommitDB/python-driver/)**
+
+> ⚠️ **Experimental Project** - This is a hobby project and should not be used in any production environment.
+
+## Installation
+
+```bash
+pip install commitdb
+```
+
+## Quick Start
+
+### Remote Mode (connect to server)
+
+```python
+from commitdb import CommitDB
+
+with CommitDB('localhost', 3306) as db:
+    db.execute('CREATE DATABASE mydb')
+    db.execute('CREATE TABLE mydb.users (id INT PRIMARY KEY, name STRING)')
+    db.execute("INSERT INTO mydb.users VALUES (1, 'Alice')")
+    
+    result = db.query('SELECT * FROM mydb.users')
+    for row in result:
+        print(f"{row['id']}: {row['name']}")
+```
+
+### Embedded Mode (no server required)
+
+```python
+from commitdb import CommitDBLocal
+
+with CommitDBLocal() as db:  # In-memory
+    db.execute('CREATE DATABASE mydb')
+    db.execute('CREATE TABLE mydb.users (id INT PRIMARY KEY, name STRING)')
+    
+with CommitDBLocal('/path/to/data') as db:  # File-based (persistent)
+    db.execute('CREATE DATABASE mydb')
+```
+
+### Ibis Mode (pandas DataFrame support)
+
+```bash
+pip install commitdb[ibis]
+```
+
+```python
+import ibis
+
+con = ibis.commitdb.connect('localhost', 3306, database='mydb')
+
+# Or use URL-based connection:
+con = ibis.connect('commitdb://localhost:3306/mydb')
+
+# Query with Ibis expressions
+users = con.table('users')
+result = users.filter(users.age > 30).select('name', 'city').execute()  # → pandas DataFrame
+print(result)
+
+# Insert from DataFrame
+import pandas as pd
+df = pd.DataFrame({'id': [1, 2], 'name': ['Alice', 'Bob']})
+con.insert('users', df)
+```
+
+---
+
+## API Reference
+
+### CommitDB (Remote)
+
+```python
+CommitDB(host='localhost', port=3306, use_ssl=False, ssl_verify=True, 
+         ssl_ca_cert=None, jwt_token=None)
+```
+
+| Method | Description |
+|--------|-------------|
+| `connect(timeout=10.0)` | Connect to server |
+| `close()` | Close connection |
+| `execute(sql)` | Execute SQL (INSERT, UPDATE, CREATE, etc.) |
+| `query(sql)` | Execute SELECT, returns QueryResult |
+| `authenticate_jwt(token)` | Authenticate with JWT |
+
+### CommitDBLocal (Embedded)
+
+```python
+CommitDBLocal(path=None, lib_path=None)
+```
+
+- `path` - Directory for persistence (`None` = in-memory)
+- `lib_path` - Path to `libcommitdb` shared library
+
+| Method | Description |
+|--------|-------------|
+| `open()` / `close()` | Open/close database |
+| `execute(sql)` | Execute SQL |
+| `query(sql)` | Execute SELECT |
+
+### QueryResult
+
+```python
+result = db.query('SELECT * FROM mydb.users')
+result.columns  # ['id', 'name']
+len(result)     # Row count
+result[0]       # {'id': '1', 'name': 'Alice'}
+
+for row in result:
+    print(row)
+```
+
+### Error Handling
+
+```python
+from commitdb import CommitDB, CommitDBError
+
+try:
+    with CommitDB('localhost', 3306) as db:
+        db.execute('SELECT * FROM nonexistent.table')
+except CommitDBError as e:
+    print(f"Database error: {e}")
+```
+
+---
+
+## Security
+
+### SSL/TLS Encryption
+
+```python
+# Production (with certificate verification)
+db = CommitDB('localhost', 3306, use_ssl=True, ssl_ca_cert='cert.pem')
+
+# Development (skip verification)
+db = CommitDB('localhost', 3306, use_ssl=True, ssl_verify=False)
+```
+
+### JWT Authentication
+
+```python
+# Auto-authenticate on connect
+db = CommitDB('localhost', 3306, jwt_token='eyJhbG...')
+db.connect()
+print(f"Authenticated as: {db.identity}")
+
+# Or authenticate after connect
+db.connect()
+db.authenticate_jwt('eyJhbG...')
+```
+
+---
+
+## Version Control
+
+### Branching & Merging
+
+```python
+with CommitDBLocal() as db:
+    db.execute('CREATE DATABASE mydb')
+    db.execute('CREATE TABLE mydb.users (id INT, name STRING)')
+    db.execute("INSERT INTO mydb.users VALUES (1, 'Alice')")
+    
+    # Create and switch to branch
+    db.execute('CREATE BRANCH feature')
+    db.execute('CHECKOUT feature')
+    
+    # Make changes (isolated to this branch)
+    db.execute("INSERT INTO mydb.users VALUES (2, 'Bob')")
+    
+    # Switch back and merge
+    db.execute('CHECKOUT master')
+    db.execute('MERGE feature')
+```
+
+**Branch Commands:**
+
+| Command | Description |
+|---------|-------------|
+| `CREATE BRANCH name` | Create new branch |
+| `CHECKOUT name` | Switch to branch |
+| `MERGE name` | Merge branch (auto-resolve) |
+| `MERGE name WITH MANUAL RESOLUTION` | Merge with manual conflict resolution |
+| `SHOW BRANCHES` | List branches |
+| `SHOW MERGE CONFLICTS` | View pending conflicts |
+| `RESOLVE CONFLICT path USING HEAD\|SOURCE` | Resolve conflict |
+| `COMMIT MERGE` / `ABORT MERGE` | Finalize or cancel merge |
+
+### Remote Sync (Git)
+
+```python
+# Add remote
+db.execute("CREATE REMOTE origin 'https://github.com/user/repo.git'")
+
+# Push/Pull with authentication
+db.execute("PUSH WITH TOKEN 'ghp_xxxxxxxxxxxx'")
+db.execute("PUSH WITH SSH KEY '/path/to/id_rsa'")
+db.execute("PULL FROM origin")
+```
+
+---
+
+## Bulk Import/Export
+
+### Local Files
+
+```python
+# Export to CSV
+db.execute("COPY INTO '/path/to/users.csv' FROM mydb.users WITH (HEADER = TRUE)")
+
+# Import from CSV
+db.execute("COPY INTO mydb.users FROM '/path/to/users.csv' WITH (HEADER = TRUE)")
+```
+
+### S3 & HTTPS
+
+```python
+# Import from HTTPS
+db.execute("COPY INTO mydb.users FROM 'https://example.com/data.csv'")
+
+# Import from S3 (uses AWS env vars)
+db.execute("COPY INTO mydb.users FROM 's3://bucket/users.csv'")
+
+# Import from S3 with explicit credentials
+db.execute("""
+    COPY INTO mydb.users FROM 's3://bucket/users.csv' WITH (
+        AWS_KEY = 'AKIAIOSFODNN7EXAMPLE',
+        AWS_SECRET = 'your-secret-key',
+        AWS_REGION = 'us-east-1'
+    )
+""")
+
+# Export to S3
+db.execute("COPY INTO 's3://bucket/export.csv' FROM mydb.users WITH (HEADER = TRUE)")
+```
+
+---
+
+## Building the Shared Library
+
+For embedded mode, if the library isn't bundled:
+
+```bash
+# From CommitDB root
+make lib  # Creates lib/libcommitdb.dylib (macOS) or .so (Linux)
+```

commitdb-2.2.1/commitdb/__init__.py

@@ -0,0 +1,43 @@
+"""
+CommitDB Python Driver
+
+A Python client for connecting to CommitDB SQL Server.
+
+Usage:
+    from commitdb import CommitDB
+
+    db = CommitDB('localhost', 3306)
+    db.connect()
+
+    # Create database and table
+    db.execute('CREATE DATABASE mydb')
+    db.execute('CREATE TABLE mydb.users (id INT PRIMARY KEY, name STRING)')
+
+    # Insert data
+    db.execute("INSERT INTO mydb.users (id, name) VALUES (1, 'Alice')")
+
+    # Query data
+    result = db.query('SELECT * FROM mydb.users')
+    for row in result:
+        print(row)
+
+    db.close()
+
+Embedded mode (requires libcommitdb):
+    from commitdb import CommitDBLocal
+
+    with CommitDBLocal('/path/to/data') as db:
+        db.execute('CREATE DATABASE mydb')
+"""
+
+from importlib.metadata import version, PackageNotFoundError
+
+from .client import CommitDB, CommitDBLocal, QueryResult, CommitResult, CommitDBError
+
+try:
+    __version__ = version("commitdb")
+except PackageNotFoundError:
+    __version__ = "0.0.0"  # Fallback for development/editable installs
+
+__all__ = ['CommitDB', 'CommitDBLocal', 'QueryResult', 'CommitResult', 'CommitDBError', '__version__']
+

commitdb-2.2.1/commitdb/binding.py

@@ -0,0 +1,135 @@
+"""
+Python ctypes bindings for libcommitdb shared library.
+"""
+
+import ctypes
+import json
+import os
+import platform
+from pathlib import Path
+from typing import Optional
+
+
+def _find_library() -> Optional[str]:
+    """Find the libcommitdb shared library."""
+    system = platform.system()
+    
+    if system == 'Darwin':
+        lib_names = ['libcommitdb.dylib', 'libcommitdb-darwin-arm64.dylib', 'libcommitdb-darwin-amd64.dylib']
+    elif system == 'Linux':
+        lib_names = ['libcommitdb.so', 'libcommitdb-linux-amd64.so', 'libcommitdb-linux-arm64.so']
+    elif system == 'Windows':
+        lib_names = ['libcommitdb.dll']
+    else:
+        lib_names = ['libcommitdb.so', 'libcommitdb.dylib']
+    
+    # Search paths
+    search_paths = [
+        Path(__file__).parent / 'lib',  # Package lib directory (for pip installed)
+        Path(__file__).parent,  # Same directory as this file
+        Path(__file__).parent.parent / 'lib',  # drivers/python/lib
+        Path(__file__).parent.parent.parent.parent / 'lib',  # CommitDB/lib
+        Path.cwd() / 'lib',  # ./lib
+        Path.cwd(),  # Current directory
+    ]
+    
+    for path in search_paths:
+        for lib_name in lib_names:
+            lib_path = path / lib_name
+            if lib_path.exists():
+                return str(lib_path)
+    
+    return None
+
+
+class CommitDBBinding:
+    """Low-level ctypes bindings for libcommitdb."""
+    
+    _lib: Optional[ctypes.CDLL] = None
+    _lib_path: Optional[str] = None
+    
+    @classmethod
+    def load(cls, lib_path: Optional[str] = None) -> 'CommitDBBinding':
+        """Load the shared library."""
+        if lib_path is None:
+            lib_path = _find_library()
+        
+        if lib_path is None:
+            raise RuntimeError(
+                "Could not find libcommitdb shared library. "
+                "Build it with: make lib"
+            )
+        
+        cls._lib_path = lib_path
+        cls._lib = ctypes.CDLL(lib_path)
+        
+        # Define function signatures
+        cls._lib.commitdb_open_memory.argtypes = []
+        cls._lib.commitdb_open_memory.restype = ctypes.c_int
+        
+        cls._lib.commitdb_open_file.argtypes = [ctypes.c_char_p]
+        cls._lib.commitdb_open_file.restype = ctypes.c_int
+        
+        cls._lib.commitdb_close.argtypes = [ctypes.c_int]
+        cls._lib.commitdb_close.restype = None
+        
+        # Use c_void_p for the result pointer to avoid automatic conversion
+        cls._lib.commitdb_execute.argtypes = [ctypes.c_int, ctypes.c_char_p]
+        cls._lib.commitdb_execute.restype = ctypes.c_void_p
+        
+        cls._lib.commitdb_free.argtypes = [ctypes.c_void_p]
+        cls._lib.commitdb_free.restype = None
+        
+        return cls()
+    
+    @classmethod
+    def is_loaded(cls) -> bool:
+        """Check if the library is loaded."""
+        return cls._lib is not None
+    
+    @classmethod
+    def open_memory(cls) -> int:
+        """Open an in-memory database."""
+        if not cls.is_loaded():
+            cls.load()
+        handle = cls._lib.commitdb_open_memory()
+        if handle < 0:
+            raise RuntimeError("Failed to open in-memory database")
+        return handle
+    
+    @classmethod
+    def open_file(cls, path: str) -> int:
+        """Open a file-based database."""
+        if not cls.is_loaded():
+            cls.load()
+        handle = cls._lib.commitdb_open_file(path.encode('utf-8'))
+        if handle < 0:
+            raise RuntimeError(f"Failed to open database at {path}")
+        return handle
+    
+    @classmethod
+    def close(cls, handle: int) -> None:
+        """Close a database handle."""
+        if cls.is_loaded():
+            cls._lib.commitdb_close(handle)
+    
+    @classmethod
+    def execute(cls, handle: int, query: str) -> dict:
+        """Execute a query and return the JSON response."""
+        if not cls.is_loaded():
+            raise RuntimeError("Library not loaded")
+        
+        result_ptr = cls._lib.commitdb_execute(handle, query.encode('utf-8'))
+        if result_ptr is None or result_ptr == 0:
+            raise RuntimeError("Query execution failed")
+        
+        try:
+            # Cast void pointer to char pointer and read the string
+            result_str = ctypes.cast(result_ptr, ctypes.c_char_p).value
+            if result_str is None:
+                raise RuntimeError("Empty response from query")
+            result_json = result_str.decode('utf-8')
+            return json.loads(result_json)
+        finally:
+            # Free the allocated memory using the void pointer
+            cls._lib.commitdb_free(result_ptr)