python-etcd3-async 0.1.0__tar.gz

python_etcd3_async-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+etcdrpc/*_pb2.py
+etcdrpc/*_pb2_grpc.py
+etcdrpc/*_pb2.pyi
+.trae/documents/*
+.pytest_cache/
+.ruff_cache/
+htmlcov/
+# Virtual environments
+.venv
+/site

python_etcd3_async-0.1.0/.pylintrc

@@ -0,0 +1,29 @@
+# Pylint configuration file
+
+[MASTER]
+
+# Specify a score threshold to be exceeded before program exits with error.
+score=no
+
+
+[MESSAGES CONTROL]
+
+# Disable specific messages
+#disable=all
+#enable=unused-import,unused-variable
+; disable=C0302,R0902,R0913,R0917,C0116,W0212,R0914,R0904,R0903,E0202,W0718
+
+
+[BASIC]
+
+# Maximum line length.
+max-line-length=100
+
+
+[TYPECHECK]
+
+# List of module names for which member attributes should not be checked
+# (useful for modules/projects where namespaces are manipulated during runtime
+# and thus existing member attributes cannot be deduced by static analysis).
+# It supports qualified module names, as well as Unix pattern matching.
+ignored-modules=etcdrpc

python_etcd3_async-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

python_etcd3_async-0.1.0/AGENTS.md

@@ -0,0 +1,138 @@
+# AGENTS.md - python-etcd3-async
+
+AI coding agent guidelines for the python-etcd3-async project.
+
+## Project Overview
+- **Name**: python-etcd3-async
+- **Python**: 3.12+
+- **Package Manager**: uv
+- **License**: Apache 2.0
+
+## Build & Development Commands
+
+### Setup
+```bash
+uv sync                    # Install dependencies
+uv sync --extra dev        # Install with dev dependencies
+uv pip install -e .        # Editable install
+```
+
+### Testing (requires ETCD_ENDPOINT)
+```bash
+ETCD_ENDPOINT=192.168.31.15:12379 uv run pytest
+ETCD_ENDPOINT=192.168.31.15:12379 uv run pytest tests/test_async_client.py::TestAsyncClient::test_client_init -v
+ETCD_ENDPOINT=192.168.31.15:12379 uv run pytest --cov=etcd3 --cov=etcdrpc
+```
+
+### Linting
+```bash
+uv run ruff check etcd3/ etcdrpc/        # Check
+uv run ruff format etcd3/ etcdrpc/       # Format
+pylint etcd3/                    # Static/ etcdrpc analysis
+```
+
+### Other
+```bash
+uv run python gen_protos.py  # Regenerate protobuf
+uv run mkdocs serve          # Serve docs
+```
+
+## Code Style
+
+### Formatting
+- **Max line length**: 100 characters
+- **Formatter**: ruff
+- Follow PEP 8
+
+### Naming
+- Classes: `PascalCase` (e.g., `AsyncEtcd3Client`)
+- Functions/Methods: `snake_case` (e.g., `async_client()`, `get_prefix()`)
+- Constants: `UPPER_CASE` (e.g., `FILTER_PUT`)
+- Private: `_leading_underscore` (e.g., `_get_channel()`)
+
+### Imports (3 groups, sorted)
+1. Standard library
+2. Third-party (grpc, etcdrpc, pytest)
+3. Internal modules
+
+### Type Hints
+- Use type hints for all parameters and returns
+- Use `Optional[]` for nullable types, `Literal[]` for enums
+
+### Docstrings
+- Google-style
+- Document all public methods/classes
+- Include type info
+
+### Error Handling
+- Use custom exceptions from `etcd3/exceptions.py`:
+  - `Etcd3Exception` (base), `ConnectionFailedError`, `ConnectionTimeoutError`
+  - `RevisionCompactedError`, `LockReleaseError`, `BatchOperationError`
+- Decorators: `_handle_errors`, `_async_handle_errors`
+
+## Architecture
+
+### Dual Client Design
+- **Sync**: `Etcd3Client`, `MultiEndpointEtcd3Client` in `etcd3/client.py`
+- **Async**: `AsyncEtcd3Client`, `AsyncMultiEndpointEtcd3Client` in `etcd3/async_client.py`
+- Factory: `async_client()` function
+
+### Extension Pattern (`etcd3/async_client_extensions.py`)
+- `AsyncKVOperations`, `AsyncLeaseOperations`, `AsyncLockOperations`
+- `AsyncClusterOperations`, `AsyncMaintenanceOperations`, `AsyncWatchOperations`
+
+### Load Balancing
+- `LoadBalancerStrategy` enum: `PRIORITY`, `ROUND_ROBIN`, `RANDOM`, `STICKY`
+
+## Observability (Environment Variables)
+
+All prefixed with `ETCD_OBS_`:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ETCD_OBS_AUTO_INIT` | true | Auto-init on client create |
+| `ETCD_OBS_LOG_LEVEL` | INFO | DEBUG/INFO/WARNING/ERROR |
+| `ETCD_OBS_LOG_FORMAT` | text | text/json/colored |
+| `ETCD_OBS_LOG_SAMPLE_RATE` | 1.0 | 0.0-1.0 |
+| `ETCD_OBS_LOG_SAMPLE_STRATEGY` | always | always/rate/dynamic/level_based |
+| `ETCD_OBS_TRACING_ENABLED` | true | Enable OpenTelemetry |
+| `ETCD_OBS_TRACING_SERVICE_NAME` | etcd3-client | Service name |
+| `ETCD_OBS_TRACING_SAMPLE_RATE` | 1.0 | Trace sampling |
+| `ETCD_OBS_OTLP_ENDPOINT` | - | OTLP collector endpoint |
+| `ETCD_OBS_PROMETHEUS_ENABLED` | false | Enable Prometheus |
+
+## Testing
+- Tests require `ETCD_ENDPOINT` env var
+- Unit tests: no etcd needed
+- Integration tests: require running etcd server
+- Test files: `tests/test_*.py`
+
+## Common Patterns
+```python
+# Async client (auto-initializes observability)
+from etcd3 import async_client
+etcd = await async_client(host='localhost', port=2379)
+
+# Sync client
+from etcd3 import client
+etcd = client(host='localhost', port=2379)
+
+# Manual observability config
+from etcd3 import ObservabilityConfig, configure_from_env
+config = configure_from_env()
+config.apply()
+
+# Context tracking
+from etcd3 import get_request_context
+async with etcd.context(operation="batch_put", source="worker_1"):
+    await etcd.kv.batch_put(items)
+```
+
+## Security
+- TLS, username/password, token-based auth supported
+- Never commit credentials
+
+## References
+- [python-etcd3](https://github.com/kragniz/python-etcd3)
+- [Go etcd client v3](https://pkg.go.dev/go.etcd.io/etcd/client/v3)
+- [etcd docs](https://etcd.io/docs/)

python_etcd3_async-0.1.0/CLAUDE.md

@@ -0,0 +1,257 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+python-etcd3-async is an async Python client library for the etcd v3 API using `grpc.aio`. It provides both synchronous and asynchronous clients with full support for etcd operations including key-value operations, leases, locks, watches, transactions, and cluster management.
+
+## Commands
+
+### Development Setup
+```bash
+# Install dependencies
+uv sync
+
+# Install dev dependencies
+uv sync --extra dev
+
+# Run Python commands
+uv run python <script.py>
+
+# Install package in dev mode
+uv pip install -e .
+```
+
+### Testing
+```bash
+# Run all tests (requires ETCD_ENDPOINT environment variable)
+ETCD_ENDPOINT=192.168.31.15:12379 uv run pytest
+
+# Run a single test file
+ETCD_ENDPOINT=192.168.31.15:12379 uv run pytest tests/test_async_client.py
+
+# Run a specific test method
+ETCD_ENDPOINT=192.168.31.15:12379 uv run pytest tests/test_locks.py::TestAsyncLock::test_lock_acquire -v
+
+# Run with coverage
+ETCD_ENDPOINT=192.168.31.15:12379 uv run pytest --cov=etcd3 --cov=etcdrpc
+
+# Run with verbose output
+ETCD_ENDPOINT=192.168.31.15:12379 uv run pytest -v
+```
+
+### Linting & Formatting
+```bash
+# Check with ruff
+uv run ruff check etcd3/ etcdrpc/
+
+# Format with ruff
+uv run ruff format etcd3/ etcdrpc/
+
+# Run pylint
+pylint etcd3/ etcdrpc/
+```
+
+### Protobuf Generation
+```bash
+# Protobuf files are auto-generated during build via hatchling hook
+# To manually regenerate:
+uv run python gen_protos.py
+```
+
+### Environment Variables
+| Variable | Description |
+|----------|-------------|
+| `ETCD3_LOG_LEVEL` | Set logging level (DEBUG, INFO, WARNING, ERROR) |
+| `ETCD_ENDPOINT` | etcd server address for testing (e.g., 192.168.31.15:12379) |
+
+## Project Rules
+
+1. Use `uv` for Python environment management, `hatchling` as build tool
+2. Use `uv run python` to execute Python commands
+3. Follow PEP8规范, use `pylint` for static analysis
+4. Use `pytest` and `pytest-asyncio` for sync and async tests
+5. Use context7 MCP to query official documentation
+
+## Architecture
+
+### Core Client Classes
+
+**Sync client (`etcd3/client.py`):**
+- `MultiEndpointEtcd3Client` - Base class with multiple endpoints and failover support
+- `Etcd3Client` - Single endpoint client, inherits from `MultiEndpointEtcd3Client`
+- `Endpoint` - Single etcd cluster endpoint with gRPC channel
+
+**Async client (`etcd3/async_client.py`):**
+- `AsyncMultiEndpointEtcd3Client` - Main async client with failover support
+- `AsyncEtcd3Client` - Alias for backward compatibility
+- `async_client()` - Factory function
+
+### Configuration Classes
+
+**`RangeRequestConfig`** - Dataclass for range query options (limit, revision, sort_order, etc.)
+
+**`ClientConfig`** / **`AsyncClientConfig`** - Client connection configuration (host, port, timeout, TLS, auth)
+
+**`AsyncMultiEndpointConfig`** - Multi-endpoint failover configuration
+
+### Async Operation Extensions (`etcd3/async_client_extensions.py`)
+
+Operation classes that wrap async functionality with error handling decorators:
+- `AsyncKVOperations` - Key-value CRUD operations
+- `AsyncLeaseOperations` - Lease creation, revocation, refresh
+- `AsyncLockOperations` - Distributed lock operations
+- `AsyncClusterOperations` - Cluster operations
+- `AsyncMaintenanceOperations` - Maintenance operations
+- `AsyncWatchOperations` - Watch operations
+
+### Async Managers (`etcd3/async_managers.py`)
+
+- `AsyncWatchManager` - Watch operations with callbacks and prefixes
+- `AsyncClusterManager` - Cluster membership operations
+- `AsyncMaintenanceManager` - Status, defragmentation, alarms, snapshots
+
+### Endpoint Pattern
+
+**`etcd3/endpoint.py`** - Base endpoint with shared logic:
+- `BaseEndpoint` - Common endpoint functionality (fail state, health check)
+
+**`etcd3/async_endpoint.py`** (async `AsyncEndpoint` class):
+- Async gRPC channel with `is_healthy()` and `rebuild_channel()`
+
+**`etcd3/client.py`** (sync `Endpoint` class):
+- Sync gRPC channel with `is_healthy()` and `rebuild_channel()`
+
+### Shared Components
+
+**`etcd3/shared.py`:**
+- `Transactions` - Transaction operation builders
+- `KVMetadata` - Key-value metadata wrapper
+- `Status`, `Alarm` - Status information classes
+- `EtcdTokenCallCredentials` - Authentication credentials
+- `RequestBuilder` - gRPC request builder utility
+- `_handle_errors` / `_async_handle_errors` - Error handling decorators
+- `_make_sync_handle_generator_errors_with_tracing` - Generator error decorator with `propagate_errors` support
+
+**`etcd3/trace.py`:** Request tracing and monitoring utilities
+
+**`etcd3/monitor.py` / `etcd3/async_monitor.py`:** Request monitoring decorators
+
+**`etcd3/exceptions.py`:** Exception classes (`Etcd3Exception` and subclasses)
+
+**`etcd3/utils.py`:** Key encoding, prefix ranges, lease conversion utilities, filter constants, load balancer strategies
+
+**`etcd3/transactions.py`:** Transaction comparison and operation classes
+
+**`etcd3/async_client_extensions.py`:**
+- `get_request_context()` / `set_request_context()` - Context variable utilities for request tracking
+- `AsyncKVOperations` - KV operations with `batch_put()`, `batch_delete()`, `put_many()` methods
+
+**`etcd3/async_client.py`:**
+- `client.context()` - Context manager for request tracking with `asyncio.Semaphore` concurrency control
+
+**`etcd3/leases.py`:** `Lease` and `AsyncLease` classes
+
+**`etcd3/locks.py`:** `Lock` and `AsyncLock` classes
+
+**`etcd3/events.py`:** Watch event classes
+
+**`etcd3/watch.py`** / **`etcd3/async_watch.py`:** Watch builder and iterator implementations
+
+**`etcd3/members.py`:** `Member` class for cluster representation
+
+### Protobuf Layer (`etcdrpc/`)
+
+Generated gRPC/Python bindings from etcd proto files:
+- `rpc_pb2.py`, `rpc_pb2_grpc.py` - Main RPC definitions
+- `kv_pb2.py`, `kv_pb2_grpc.py` - Key-value service
+- `auth_pb2.py`, `auth_pb2_grpc.py` - Authentication service
+
+Compiled during build via `gen_protos.py` (hatchling build hook).
+
+### Examples (`examples/`)
+
+| File | Description |
+|------|-------------|
+| `leader_election.py` | Async leader election with lease-based lock |
+| `leader_election_sync.py` | Sync version using threading |
+| `service_registration.py` | Async service registration with auto-renewal |
+| `service_registration_sync.py` | Sync version using threads |
+| `service_discovery.py` | Async service discovery with watch callbacks |
+| `service_discovery_sync.py` | Sync version using polling |
+
+## Key Design Patterns
+
+1. **Dual sync/async implementations:** Same API for sync (`client.py`) and async (`async_client.py`)
+
+2. **Error handling decorators:**
+   - `_handle_errors` / `_async_handle_errors` - Standard error handling
+   - `_sync_handle_keepalive_errors` / `_async_handle_keepalive_errors` - Lease keepalive with `propagate_errors=True`
+
+3. **Endpoint failover:** `MultiEndpointEtcd3Client` tracks failed endpoints with retry on `failover=True`
+
+4. **Load balancing:** Multiple strategies supported via `LoadBalancerStrategy`:
+   - `PRIORITY` (default): Keep current endpoint if healthy, failover on failure
+   - `ROUND_ROBIN`: Cycle through endpoints sequentially
+   - `RANDOM`: Random endpoint selection
+   - `STICKY`: Maintain connection to the same endpoint
+
+5. **Auto-reconnection:** Async has `_get_channel()`, sync has matching implementation with health check
+
+6. **Lazy authentication:** Async uses `_init_auth()` with `asyncio.Lock()`, sync initializes in `__init__`
+
+7. **Watch pattern:** Iterator + cancel function returns for both sync and async
+
+8. **Request context tracking:** Use `client.context()` to track operations across async tasks:
+   ```python
+   async with etcd.context(operation="batch_put", source="worker_1"):
+       await etcd.kv.batch_put(items)
+   ctx = get_request_context()  # Get context in callbacks
+   ```
+
+## Common Operations
+
+```python
+# KV Operations
+client.get(key), client.put(key, value), client.delete(key)
+client.get_prefix(prefix), client.get_range(start, end), client.get_all()
+
+# Batch Operations (async only)
+await client.kv.batch_put([('/key1', 'value1'), ('/key2', 'value2')])
+await client.kv.batch_delete(['/key1', '/key2'])
+await client.kv.put_many({'/key1': 'value1', '/key2': 'value2'})
+
+# Watch with filters (only receive PUT events)
+from etcd3 import FILTER_DELETE
+events, cancel = await client.watch('/key', filters=[FILTER_DELETE])
+
+# Leases
+lease = client.lease(ttl)
+async for response in lease.refresh(): pass
+lease.revoke()
+
+# Locks
+lock = client.lock('/name', ttl=ttl)
+await lock.acquire() / lock.release()
+# or use context manager
+
+# Watches
+events_iter, cancel = client.watch(key)
+async for event in events_iter: pass
+cancel()
+
+# Transactions
+client.transaction(
+    compare=[client.transactions.value('/key') == 'expected'],
+    success=[client.transactions.put('/key', 'new')],
+    failure=[]
+)
+
+# Cluster
+members = client.members()
+client.add_member(urls), client.remove_member(id), client.update_member(id, urls)
+
+# Maintenance
+client.status(), client.compact(revision), client.defragment()
+```