Metadata-Version: 2.4
Name: nendb
Version: 0.1.0
Summary: High-performance Python client for NenDB graph database
Author-email: Nen Team <team@nen.co>
Maintainer-email: Nen Team <team@nen.co>
License: MIT
Project-URL: Homepage, https://github.com/Nen-Co/nendb-python
Project-URL: Documentation, https://docs.nen.co
Project-URL: Repository, https://github.com/Nen-Co/nendb-python.git
Project-URL: Bug Tracker, https://github.com/Nen-Co/nendb-python/issues
Keywords: graph,database,algorithm,bfs,dijkstra,pagerank,zig,high-performance
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28.0
Requires-Dist: urllib3>=1.26.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: flake8>=5.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: isort>=5.10.0; extra == "dev"
Requires-Dist: pre-commit>=2.20.0; extra == "dev"
Requires-Dist: tox>=4.0.0; extra == "dev"
Requires-Dist: types-requests>=2.28.0; extra == "dev"

# NenDB Python Driver

A high-performance Python client for the NenDB graph database, built with Zig under the hood.

## Features

- **High Performance**: Built on top of NenDB's Zig-based HTTP server
- **Python Native**: Familiar Python API for graph operations
- **Graph Algorithms**: BFS, Dijkstra, PageRank, and more
- **Type Safety**: Full type hints and error handling
- **Async Support**: Both synchronous and asynchronous operations

## Architecture

```
┌─────────────────┐    HTTP/JSON    ┌─────────────────┐
│   Python App    │ ──────────────► │  NenDB Server   │
│                 │                 │   (Zig + HTTP)  │
│  nen-python-    │ ◄────────────── │                 │
│     driver      │                 │                 │
└─────────────────┘                 └─────────────────┘
```

The Python driver communicates with NenDB's HTTP server, which is built in Zig for maximum performance. This gives you the best of both worlds: Python's ease of use with Zig's performance.

## Installation

```bash
pip install NenDB
```

## 🚀 Quick Start

### 📦 NenDB Server Installation

Before using the Python driver, you need to have the NenDB server running. Here are the quickest ways to get started:

#### Linux/macOS (Quick Install)
```bash
curl -fsSL https://github.com/Nen-Co/nen-db/releases/latest/download/nen-linux-x86_64.tar.gz | tar -xz
```

#### Windows PowerShell
```powershell
Invoke-WebRequest -Uri "https://github.com/Nen-Co/nen-db/releases/latest/download/nen-windows-x86_64.zip" -OutFile "nen-windows.zip"
Expand-Archive -Path "nen-windows.zip" -DestinationPath "."
```

#### 🐳 Docker (Recommended)
```bash
# Pull and run with HTTP server on port 8080
docker run --rm -p 8080:8080 --name nendb \
  -v $(pwd)/data:/data \
  ghcr.io/nen-co/nendb:latest
```

#### 🧪 Build from Source
```bash
git clone https://github.com/Nen-Co/nen-db.git
cd nen-db
zig build
./zig-out/bin/nendb
```

### ✅ Verify Server is Running
```bash
curl http://localhost:8080/health
# Should return: {"status": "healthy", "service": "nendb", "version": "0.0.1"}
```

### 🚀 Install Python Driver
```bash
pip install NenDB
```

### 💻 Basic Usage Example
```python
from nen_python_driver import NenDBClient

# Connect to NenDB server
client = NenDBClient("http://localhost:8080")

# Check server health
health = client.health()
print(f"Server status: {health['status']}")

# Get graph statistics
stats = client.graph_stats()
print(f"Graph has {stats['nodes']} nodes and {stats['edges']} edges")

# Run BFS algorithm
result = client.bfs(start_node=0, max_depth=3)
print(f"BFS algorithm: {result['status']}")
```

## API Reference

### Client Initialization

```python
client = NenDBClient(
    base_url="http://localhost:8080",  # NenDB server URL
    timeout=30,                        # Request timeout in seconds
    retries=3                          # Number of retries on failure
)
```

### Health & Status

```python
# Check server health
health = client.health()

# Get graph statistics
stats = client.graph_stats()
```

### Graph Algorithms

```python
# Breadth-First Search
bfs_result = client.bfs(
    start_node=0,      # Starting node ID
    max_depth=3,       # Maximum search depth
    filters={}          # Optional node/edge filters
)

# Dijkstra Shortest Path
dijkstra_result = client.dijkstra(
    start_node=0,      # Starting node ID
    end_node=5,        # Target node ID
    weight_property="cost"  # Edge weight property
)

# PageRank
pagerank_result = client.pagerank(
    iterations=100,           # Number of iterations
    damping_factor=0.85,      # Damping factor
    tolerance=1e-6            # Convergence tolerance
)
```

### Error Handling

```python
from nen_python_driver import NenDBError

try:
    result = client.bfs(start_node=0, max_depth=3)
except NenDBError as e:
    print(f"Error: {e}")
    if e.details:
        print(f"Details: {e.details}")
```

## Development

### Running Tests

```bash
# Install development dependencies
pip install -r requirements-dev.txt

# Run tests
pytest tests/

# Run with coverage
pytest --cov=nen_python_driver tests/
```

### Building Documentation

```bash
# Install documentation dependencies
pip install -r requirements-docs.txt

# Build docs
sphinx-build -b html docs/ docs/_build/html
```

## Performance

The Python driver is designed for high performance:

- **Connection Pooling**: Reuses HTTP connections
- **Request Batching**: Batches multiple operations
- **Async Support**: Non-blocking operations
- **Error Recovery**: Automatic retries and fallbacks

## Contributing

1. Fork the repository
2. Create a feature branch
3. Write tests for your changes
4. Ensure all tests pass
5. Submit a pull request

## License

MIT License - see LICENSE file for details.

## Support

- **Issues**: GitHub Issues
- **Documentation**: [docs.nen.co](https://docs.nen.co)
- **Community**: [Discord](https://discord.gg/nen)
