docs: add uv usage instructions for local development

Add comprehensive uv documentation for Python bindings development
across all documentation files. uv is a fast Python package installer
and resolver written in Rust, providing significantly faster package
management than traditional pip.

Changes:
- README.md: Add Development section with uv quick start
- python/README.md: Add uv as recommended method with detailed instructions
- CLAUDE.md: Update Python bindings section with uv workflow
- Update outdated evaluate_logic references in examples

Benefits of using uv:
- 10-100x faster package installation
- Better dependency resolution
- Built-in virtualenv management
- Seamless drop-in replacement for pip

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: aepfli

CLAUDE.md

@@ -68,7 +68,7 @@ cargo clippy -- -D warnings
 
 ```
 src/
-├── lib.rs              # Main entry point, WASM exports (evaluate_logic, update_state, evaluate)
+├── lib.rs              # Main entry point, WASM exports (update_state, evaluate)
 ├── evaluation.rs       # Core flag evaluation logic, context enrichment ($flagd properties)
 ├── memory.rs           # WASM memory management (alloc/dealloc, pointer packing)
 ├── storage/            # Thread-local flag state storage
@@ -311,7 +311,7 @@ In addition to WASM integration, this project provides **native Python bindings*
 ```
 python/
 ├── src/
-│   └── lib.rs           # PyO3 bindings (evaluate_logic, FlagEvaluator class)
+│   └── lib.rs           # PyO3 bindings (FlagEvaluator class)
 ├── tests/               # Python test suite (pytest)
 ├── examples/            # Usage examples
 ├── benchmarks/          # Performance benchmarks
@@ -322,6 +322,30 @@ python/
 
 ### Building Python Bindings
 
+**Recommended: Using uv (faster)**
+
+```bash
+# Install uv
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Set up development environment
+cd python
+uv venv
+source .venv/bin/activate
+uv pip install maturin pytest
+
+# Build and install locally
+maturin develop
+
+# Run tests
+pytest tests/ -v
+
+# Build wheels for distribution
+maturin build --release
+```
+
+**Alternative: Using pip**
+
 ```bash
 # Install maturin
 pip install maturin
@@ -342,10 +366,14 @@ maturin build --release
 **API Design**: Pythonic dictionaries instead of JSON strings:
 ```python
 # PyO3 API (native)
-result = evaluate_logic({"==": [1, 1]}, {})
+evaluator = FlagEvaluator()
+evaluator.update_state({"flags": {"myFlag": {...}}})
+result = evaluator.evaluate("myFlag", {})
 
 # vs WASM API (for comparison)
-result_json = evaluate_logic_wasm(json.dumps(rule), json.dumps(data))
+config_json = json.dumps({"flags": {"myFlag": {...}}})
+update_state_wasm(config_json)
+result_json = evaluate_wasm("myFlag", "{}")
 result = json.loads(result_json)
 ```
 

README.md

@@ -184,6 +184,23 @@ print(enabled)  # True
 - 🔧 Native Python exceptions
 - 💾 Efficient memory usage
 
+**Development:**
+
+For local development, we recommend using [uv](https://github.com/astral-sh/uv) for faster package management:
+
+```bash
+# Install uv
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Set up development environment
+cd python
+uv venv
+source .venv/bin/activate
+uv pip install maturin pytest
+maturin develop
+pytest tests/ -v
+```
+
 See [python/README.md](python/README.md) for complete documentation.
 
 ### Python with Wasmtime (Alternative)

python/README.md

@@ -158,12 +158,47 @@ See [benchmarks/bench_vs_wasm.py](benchmarks/bench_vs_wasm.py) for detailed comp
 
 ### Building from Source
 
+#### Recommended: Using uv (faster)
+
+[uv](https://github.com/astral-sh/uv) is a fast Python package installer and resolver written in Rust.
+
 ```bash
-# Install maturin
-pip install maturin
+# Install uv (if not already installed)
+curl -LsSf https://astral.sh/uv/install.sh | sh
 
-# Build and install locally
+# Create virtual environment
 cd python
+uv venv
+
+# Activate virtual environment
+source .venv/bin/activate  # On Unix/macOS
+# .venv\Scripts\activate   # On Windows
+
+# Install dependencies and build package
+uv pip install maturin pytest
+
+# Build and install the package in development mode
+maturin develop
+
+# Run tests
+pytest tests/ -v
+```
+
+#### Alternative: Using pip
+
+```bash
+# Create virtual environment
+cd python
+python -m venv .venv
+
+# Activate virtual environment
+source .venv/bin/activate  # On Unix/macOS
+# .venv\Scripts\activate   # On Windows
+
+# Install dependencies
+pip install maturin pytest
+
+# Build and install locally
 maturin develop
 
 # Run tests
@@ -173,6 +208,11 @@ pytest tests/ -v
 ### Running Tests
 
 ```bash
+# With uv (from python directory)
+uv pip install pytest
+pytest tests/ -v
+
+# With pip (from repository root)
 pip install pytest
 pytest python/tests/ -v
 ```