python-etcd3-async 0.1.0__tar.gz → 0.1.5__tar.gz

{python_etcd3_async-0.1.0 → python_etcd3_async-0.1.5}/AGENTS.md

@@ -22,6 +22,8 @@ uv pip install -e .        # Editable install
 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
+ETCD_ENDPOINT=192.168.31.15:12379 uv run pytest tests/ -v -k "test_name"  # Run tests matching pattern
+ETCD_ENDPOINT=192.168.31.15:12379 uv run pytest tests/ --ignore=tests/test_integration.py  # Skip integration tests
 ```
 
 ### Linting
@@ -43,32 +45,46 @@ uv run mkdocs serve          # Serve docs
 - **Max line length**: 100 characters
 - **Formatter**: ruff
 - Follow PEP 8
+- 4 spaces for indentation (no tabs)
+- Trailing commas for multi-line structures
+- Single blank line between top-level definitions
 
 ### 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()`)
+- Protected: `_leading_underscore` for internal use
+- Type variables: `PascalCase` (e.g., `T`, `TKey`, `TValue`)
 
 ### Imports (3 groups, sorted)
-1. Standard library
-2. Third-party (grpc, etcdrpc, pytest)
-3. Internal modules
+1. Standard library (`asyncio`, `functools`, `typing`, etc.)
+2. Third-party (`grpc`, `etcdrpc`, `pytest`)
+3. Internal modules (`etcd3.*`, `etcdrpc.*`)
+- Use absolute imports within package
+- Sort alphabetically within groups
 
 ### Type Hints
 - Use type hints for all parameters and returns
 - Use `Optional[]` for nullable types, `Literal[]` for enums
+- Use `|` syntax for unions (e.g., `str | bytes`)
+- Use `X | None` over `Optional[X]`
+- Generics: `list[int]`, `dict[str, Any]` over `List[int]`, `Dict[str, Any]`
 
 ### Docstrings
 - Google-style
 - Document all public methods/classes
-- Include type info
+- Include type info in params and returns
+- First line should be a concise summary
+- Use `:raises:` for exceptions that may be raised
 
 ### Error Handling
 - Use custom exceptions from `etcd3/exceptions.py`:
   - `Etcd3Exception` (base), `ConnectionFailedError`, `ConnectionTimeoutError`
   - `RevisionCompactedError`, `LockReleaseError`, `BatchOperationError`
 - Decorators: `_handle_errors`, `_async_handle_errors`
+- Never catch broad `Exception` unless re-raising
+- Always include context in error messages
 
 ## Architecture
 
@@ -84,6 +100,24 @@ uv run mkdocs serve          # Serve docs
 ### Load Balancing
 - `LoadBalancerStrategy` enum: `PRIORITY`, `ROUND_ROBIN`, `RANDOM`, `STICKY`
 
+### Package Structure
+```
+etcd3/
+  __init__.py           # Public exports (client, async_client, exceptions, etc.)
+  async_client.py       # AsyncEtcd3Client (main async client)
+  client.py             # Etcd3Client (sync client)
+  async_client_extensions.py  # Operation mixins
+  async_endpoint.py     # AsyncEndpoint (single endpoint handler)
+  async_managers.py     # Watch, Cluster, Maintenance managers
+  exceptions.py         # Custom exceptions
+  transactions.py       # Transaction support
+  utils.py              # Utility functions
+  log.py                # Logging utilities
+  shared.py             # Shared code between sync/async
+etcdrpc/                # Generated protobuf/gRPC code
+tests/                  # Test files
+```
+
 ## Observability (Environment Variables)
 
 All prefixed with `ETCD_OBS_`:

{python_etcd3_async-0.1.0 → python_etcd3_async-0.1.5}/CLAUDE.md

@@ -26,7 +26,7 @@ uv pip install -e .
 ### Testing
 ```bash
 # Run all tests (requires ETCD_ENDPOINT environment variable)
-ETCD_ENDPOINT=192.168.31.15:12379 uv run pytest
+ETCD_ENDPOINT=127.0.0.1:2379 uv run pytest
 
 # Run a single test file
 ETCD_ENDPOINT=192.168.31.15:12379 uv run pytest tests/test_async_client.py
@@ -63,8 +63,11 @@ 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) |
+| `ETCD_OBS_LOG_LEVEL` | Logging level (DEBUG, INFO, WARNING, ERROR) |
+| `ETCD_OBS_LOG_FORMAT` | Log format (text, json, colored) |
+| `ETCD_OBS_TRACING_ENABLED` | Enable OpenTelemetry tracing |
+| `ETCD_OBS_PROMETHEUS_ENABLED` | Enable Prometheus metrics |
 
 ## Project Rules
 
@@ -78,23 +81,26 @@ uv run python gen_protos.py
 
 ### 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
+**Sync client modules:**
+- `etcd3/single_client.py` - `Etcd3Client` - Single endpoint client, inherits from `MultiEndpointEtcd3Client`
+- `etcd3/multi_client.py` - `MultiEndpointEtcd3Client` - Base class with multiple endpoints and failover support, `Endpoint` - Single etcd cluster endpoint with gRPC channel
+- `etcd3/client.py` - Compatibility shim (re-exports from the above modules)
 
-**Async client (`etcd3/async_client.py`):**
-- `AsyncMultiEndpointEtcd3Client` - Main async client with failover support
-- `AsyncEtcd3Client` - Alias for backward compatibility
-- `async_client()` - Factory function
+**Async client modules:**
+- `etcd3/async_single_client.py` - `AsyncEtcd3Client` - Single endpoint async client
+- `etcd3/async_multi_client.py` - `AsyncMultiEndpointEtcd3Client` - Main async client with failover support, `AsyncEndpoint` - Single etcd cluster endpoint with async gRPC channel
+- `etcd3/async_client.py` - Compatibility shim (re-exports from the above modules)
 
 ### Configuration Classes
 
-**`RangeRequestConfig`** - Dataclass for range query options (limit, revision, sort_order, etc.)
+**`etcd3/config.py`:**
+- `RangeRequestConfig` - Dataclass for range query options (limit, revision, sort_order, etc.)
+- `ClientConfig` - Client connection configuration (host, port, timeout, TLS, auth)
+- `MultiEndpointConfig` - Multi-endpoint failover configuration
 
-**`ClientConfig`** / **`AsyncClientConfig`** - Client connection configuration (host, port, timeout, TLS, auth)
-
-**`AsyncMultiEndpointConfig`** - Multi-endpoint failover configuration
+**`etcd3/async_config.py`:**
+- `AsyncClientConfig` - Async client connection configuration
+- `AsyncMultiEndpointConfig` - Async multi-endpoint failover configuration
 
 ### Async Operation Extensions (`etcd3/async_client_extensions.py`)
 
@@ -117,12 +123,14 @@ Operation classes that wrap async functionality with error handling decorators:
 **`etcd3/endpoint.py`** - Base endpoint with shared logic:
 - `BaseEndpoint` - Common endpoint functionality (fail state, health check)
 
-**`etcd3/async_endpoint.py`** (async `AsyncEndpoint` class):
+**`etcd3/async_endpoint.py`** - Async `AsyncEndpoint` class:
 - Async gRPC channel with `is_healthy()` and `rebuild_channel()`
 
-**`etcd3/client.py`** (sync `Endpoint` class):
+**`etcd3/multi_client.py`** - Sync `Endpoint` class:
 - Sync gRPC channel with `is_healthy()` and `rebuild_channel()`
 
+**`etcd3/async_multi_client.py`** - Async `AsyncEndpoint` class (re-exported from async_endpoint)
+
 ### Shared Components
 
 **`etcd3/shared.py`:**
@@ -131,8 +139,12 @@ Operation classes that wrap async functionality with error handling decorators:
 - `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/errors.py`:**
+- `create_sync_error_handlers()` - Factory for sync error handling decorators
+- `create_async_error_handlers()` - Factory for async error handling decorators
+- `_make_sync_handle_errors_with_tracing` - Sync error handler with tracing
+- `_make_async_handle_errors_with_tracing` - Async error handler with tracing
 
 **`etcd3/trace.py`:** Request tracing and monitoring utilities
 
@@ -181,12 +193,45 @@ Compiled during build via `gen_protos.py` (hatchling build hook).
 | `service_discovery.py` | Async service discovery with watch callbacks |
 | `service_discovery_sync.py` | Sync version using polling |
 
+### Observability Utilities
+
+**Logging:**
+- `get_logger(name)` - Get a logger instance
+- `set_log_level(level)` - Set global log level
+
+**Tracing:**
+- `get_tracer()` - Get OpenTelemetry tracer
+- `create_span(name, attributes)` - Create a tracing span
+- `is_tracing_available()` - Check if tracing is enabled
+
+**Prometheus Metrics:**
+- `get_exporter()` - Get Prometheus exporter instance
+- `is_prometheus_available()` - Check if Prometheus is available
+
+**Configuration:**
+```python
+from etcd3 import ObservabilityConfig, configure_from_env, auto_init
+
+# Configure programmatically
+config = ObservabilityConfig(
+    tracing_enabled=True,
+    log_format="json",
+    log_level="INFO",
+    prometheus_enabled=True,
+)
+config.apply()
+
+# Or from environment variables
+configure_from_env()
+auto_init()  # Auto-initialize at import time
+```
+
 ## Key Design Patterns
 
-1. **Dual sync/async implementations:** Same API for sync (`client.py`) and async (`async_client.py`)
+1. **Dual sync/async implementations:** Same API for sync and async clients (client modules in `single_client.py` / `async_single_client.py`, with shims for backward compatibility)
 
 2. **Error handling decorators:**
-   - `_handle_errors` / `_async_handle_errors` - Standard error handling
+   - Error handlers are created via `create_sync_error_handlers()` and `create_async_error_handlers()` factories from `errors.py`
    - `_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`

python_etcd3_async-0.1.0/README.md → python_etcd3_async-0.1.5/PKG-INFO

@@ -1,3 +1,13 @@
+Metadata-Version: 2.5
+Name: python-etcd3-async
+Version: 0.1.5
+Summary: etcd3 async sdk
+Requires-Python: <4,>=3.12
+Requires-Dist: grpcio==1.76.0
+Requires-Dist: prometheus-client>=0.24.1
+Requires-Dist: protobuf==6.31.1
+Description-Content-Type: text/markdown
+
 # python-etcd3-async
 
 [中文文档](./README_CN.md) | English
@@ -15,6 +25,7 @@ Python async client for the etcd API v3, supporting both synchronous and asynchr
 - **Keepalive error propagation**: Lease keepalive errors are properly propagated for connection loss detection
 - **Endpoint failover**: Built-in support for multiple endpoints with automatic failover
 - **Context manager**: Clean resource management for both sync and async
+- **Observability**: Structured logging, OpenTelemetry tracing, and Prometheus metrics
 
 ## Quick Start
 
@@ -284,11 +295,50 @@ client = await async_client(
 )
 ```
 
-## Environment Variables
+## Observability
 
-| Variable | Description |
-|----------|-------------|
-| `ETCD3_LOG_LEVEL` | Set logging level (DEBUG, INFO, WARNING, ERROR) |
+### Configure via Environment
+
+```bash
+export ETCD_OBS_LOG_LEVEL=DEBUG
+export ETCD_OBS_LOG_FORMAT=json
+export ETCD_OBS_TRACING_ENABLED=true
+export ETCD_OBS_PROMETHEUS_ENABLED=true
+```
+
+### Configure Programmatically
+
+```python
+from etcd3 import ObservabilityConfig
+
+config = ObservabilityConfig(
+    tracing_enabled=True,
+    log_format="json",
+    log_level="INFO",
+    prometheus_enabled=True,
+)
+config.apply()
+```
+
+### Access Metrics
+
+```python
+from etcd3.exporters.prometheus import get_exporter
+
+exporter = get_exporter()
+if exporter:
+    print(exporter.metrics().decode())
+```
+
+## API Reference
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ETCD_OBS_LOG_LEVEL` | INFO | Logging level (DEBUG, INFO, WARNING, ERROR) |
+| `ETCD_OBS_LOG_FORMAT` | text | Log format (text, json, colored) |
+| `ETCD_OBS_TRACING_ENABLED` | true | Enable OpenTelemetry tracing |
+| `ETCD_OBS_TRACING_SERVICE_NAME` | etcd3-client | Service name for tracing |
+| `ETCD_OBS_PROMETHEUS_ENABLED` | false | Enable Prometheus metrics export |
 
 ## API Reference
 

python_etcd3_async-0.1.0/PKG-INFO → python_etcd3_async-0.1.5/README.md

@@ -1,13 +1,3 @@
-Metadata-Version: 2.4
-Name: python-etcd3-async
-Version: 0.1.0
-Summary: etcd3 async sdk
-Requires-Python: <4,>=3.12
-Requires-Dist: grpcio==1.76.0
-Requires-Dist: prometheus-client>=0.24.1
-Requires-Dist: protobuf==6.31.1
-Description-Content-Type: text/markdown
-
 # python-etcd3-async
 
 [中文文档](./README_CN.md) | English
@@ -25,6 +15,7 @@ Python async client for the etcd API v3, supporting both synchronous and asynchr
 - **Keepalive error propagation**: Lease keepalive errors are properly propagated for connection loss detection
 - **Endpoint failover**: Built-in support for multiple endpoints with automatic failover
 - **Context manager**: Clean resource management for both sync and async
+- **Observability**: Structured logging, OpenTelemetry tracing, and Prometheus metrics
 
 ## Quick Start
 
@@ -294,11 +285,50 @@ client = await async_client(
 )
 ```
 
-## Environment Variables
+## Observability
 
-| Variable | Description |
-|----------|-------------|
-| `ETCD3_LOG_LEVEL` | Set logging level (DEBUG, INFO, WARNING, ERROR) |
+### Configure via Environment
+
+```bash
+export ETCD_OBS_LOG_LEVEL=DEBUG
+export ETCD_OBS_LOG_FORMAT=json
+export ETCD_OBS_TRACING_ENABLED=true
+export ETCD_OBS_PROMETHEUS_ENABLED=true
+```
+
+### Configure Programmatically
+
+```python
+from etcd3 import ObservabilityConfig
+
+config = ObservabilityConfig(
+    tracing_enabled=True,
+    log_format="json",
+    log_level="INFO",
+    prometheus_enabled=True,
+)
+config.apply()
+```
+
+### Access Metrics
+
+```python
+from etcd3.exporters.prometheus import get_exporter
+
+exporter = get_exporter()
+if exporter:
+    print(exporter.metrics().decode())
+```
+
+## API Reference
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ETCD_OBS_LOG_LEVEL` | INFO | Logging level (DEBUG, INFO, WARNING, ERROR) |
+| `ETCD_OBS_LOG_FORMAT` | text | Log format (text, json, colored) |
+| `ETCD_OBS_TRACING_ENABLED` | true | Enable OpenTelemetry tracing |
+| `ETCD_OBS_TRACING_SERVICE_NAME` | etcd3-client | Service name for tracing |
+| `ETCD_OBS_PROMETHEUS_ENABLED` | false | Enable Prometheus metrics export |
 
 ## API Reference
 

{python_etcd3_async-0.1.0 → python_etcd3_async-0.1.5}/README_CN.md

@@ -15,6 +15,7 @@ Python etcd API v3 异步客户端，支持同步和异步操作。
 - **Keepalive 错误传播**: 租约保活错误正确传播，便于连接断开检测
 - **端点故障转移**: 支持多节点自动故障转移
 - **上下文管理**: 资源清理更加简洁
+- **可观测性**: 结构化日志、OpenTelemetry 追踪、Prometheus 指标
 
 ## 快速开始
 
@@ -284,14 +285,51 @@ client = await async_client(
 )
 ```
 
-## 环境变量
+## 可观测性
 
-| 变量 | 说明 |
-|------|------|
-| `ETCD3_LOG_LEVEL` | 设置日志级别 (DEBUG, INFO, WARNING, ERROR) |
+### 通过环境变量配置
+
+```bash
+export ETCD_OBS_LOG_LEVEL=DEBUG
+export ETCD_OBS_LOG_FORMAT=json
+export ETCD_OBS_TRACING_ENABLED=true
+export ETCD_OBS_PROMETHEUS_ENABLED=true
+```
+
+### 通过代码配置
+
+```python
+from etcd3 import ObservabilityConfig
+
+config = ObservabilityConfig(
+    tracing_enabled=True,
+    log_format="json",
+    log_level="INFO",
+    prometheus_enabled=True,
+)
+config.apply()
+```
+
+### 获取指标
+
+```python
+from etcd3.exporters.prometheus import get_exporter
+
+exporter = get_exporter()
+if exporter:
+    print(exporter.metrics().decode())
+```
 
 ## API 参考
 
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `ETCD_OBS_LOG_LEVEL` | INFO | 日志级别 (DEBUG, INFO, WARNING, ERROR) |
+| `ETCD_OBS_LOG_FORMAT` | text | 日志格式 (text, json, colored) |
+| `ETCD_OBS_TRACING_ENABLED` | true | 启用 OpenTelemetry 追踪 |
+| `ETCD_OBS_TRACING_SERVICE_NAME` | etcd3-client | 追踪服务名称 |
+| `ETCD_OBS_PROMETHEUS_ENABLED` | false | 启用 Prometheus 指标导出 |
+
 ### 客户端工厂函数
 
 | 函数 | 说明 |

python_etcd3_async-0.1.5/docs/en/guide/leader_election.md

@@ -0,0 +1,129 @@
+---
+title: Leader Election
+---
+
+# Leader Election
+
+The leader election pattern is used to designate one instance as the primary coordinator among multiple instances. python-etcd3-async provides a `LeaderElection` class that implements this pattern using etcd distributed locks.
+
+## Design Principles
+
+- **Lease-based**: Uses etcd Lease for automatic expiration
+- **Auto-renewal**: Automatically renews the lease while holding the lock
+- **Graceful shutdown**: Properly releases the lock on shutdown
+- **Lock loss callback**: Notifies the application when the lock is lost
+
+## Basic Usage
+
+```python
+import asyncio
+from etcd3 import async_client, AsyncLock
+
+class LeaderElection:
+    def __init__(self, client, name: str, ttl: int = 30):
+        self.client = client
+        self.name = name
+        self.key = f"election/{name}"
+        self.ttl = ttl
+        self._lock: Optional[AsyncLock] = None
+        self._is_leader = False
+        self._refresh_task: Optional[asyncio.Task] = None
+
+    async def try_become_leader(self, timeout: float = None) -> bool:
+        """Attempt to become leader"""
+        self._lock = await self.client.lock(self.key, ttl=self.ttl)
+        self._is_leader = await self._lock.acquire(timeout=timeout)
+        if self._is_leader:
+            self._start_refresh()
+        return self._is_leader
+
+    async def is_leader(self) -> bool:
+        """Check if current instance is leader"""
+        return self._is_leader
+
+    async def resign(self) -> bool:
+        """Voluntarily give up leader status"""
+        self._stop_refresh()
+        self._is_leader = False
+        if self._lock:
+            return await self._lock.release()
+        return False
+```
+
+## Complete Example
+
+```python
+import asyncio
+import logging
+import os
+from etcd3 import async_client
+
+logging.basicConfig(level=logging.INFO)
+
+
+async def main():
+    # Create client
+    client = await async_client(
+        host=os.environ.get("ETCD_HOST", "localhost"),
+        port=int(os.environ.get("ETCD_PORT", "2379"))
+    )
+
+    # Create election
+    election = LeaderElection(client, "my-service", ttl=30)
+
+    try:
+        # Try to become leader
+        if await election.try_become_leader():
+            print("Became leader")
+            # Do leader work...
+            while election.is_acquired:
+                await asyncio.sleep(10)
+                print("Leader task running...")
+        else:
+            print("Could not become leader")
+    finally:
+        await election.close()
+        await client.close()
+
+asyncio.run(main())
+```
+
+## TTL Considerations
+
+| TTL Value | Use Case |
+|-----------|----------|
+| 5-10s | Fast failover required |
+| 15-30s | General use (recommended) |
+| 60s+ | Low network frequency |
+
+- **Shorter TTL**: Faster failover when leader fails
+- **Longer TTL**: Lower network overhead, less sensitive to network jitter
+
+## Lock Loss Detection
+
+Set a callback to handle lock loss:
+
+```python
+def on_lock_lost(name, data):
+    print(f"Lock lost for {name}, will retry")
+    # Trigger re-election
+
+election.set_on_lost_callback(on_lock_lost)
+```
+
+## Watching for Leader Changes
+
+Monitor election results:
+
+```python
+async def on_new_leader(name, data):
+    print(f"New leader elected: {data}")
+
+await election.watch_election(on_new_leader)
+```
+
+## See Also
+
+- [Lock Operations](usage.md)
+- [Lease Operations](usage.md)
+- [examples/leader_election.py](https://github.com/owasd/python3-etcd-async/blob/main/examples/leader_election.py)