python-etcd3-async 0.1.6__tar.gz → 0.2.0__tar.gz

{python_etcd3_async-0.1.6 → python_etcd3_async-0.2.0}/CLAUDE.md

@@ -266,7 +266,11 @@ auto_init()  # Auto-initialize at import time
    - 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`
+3. **Endpoint failover:** Both `MultiEndpointEtcd3Client` and
+   `AsyncMultiEndpointEtcd3Client` track failed endpoints. With
+   `failover=True` a failed endpoint is bypassed and another healthy
+   endpoint is picked; with `failover=False` the client stays on the
+   endpoint it holds and rebuilds that endpoint's channel in place.
 
 4. **Load balancing:** Multiple strategies supported via `LoadBalancerStrategy`:
    - `PRIORITY` (default): Keep current endpoint if healthy, failover on failure
@@ -274,11 +278,14 @@ auto_init()  # Auto-initialize at import time
    - `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
+5. **Auto-reconnection:** Async has `_get_channel()` / `_acquire_channel()`,
+   sync has a matching `_get_channel()`, both with a background health probe
 
 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
+7. **Watch pattern:** Iterator + cancel function returns for both sync and
+   async. Cancelling sends a real cancel request to the server and unblocks
+   a pending iteration.
 
 8. **Request context tracking:** Use `client.context()` to track operations across async tasks:
    ```python

{python_etcd3_async-0.1.6 → python_etcd3_async-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: python-etcd3-async
-Version: 0.1.6
+Version: 0.2.0
 Summary: etcd3 async sdk
 Requires-Python: <4,>=3.12
 Requires-Dist: grpcio==1.76.0

{python_etcd3_async-0.1.6 → python_etcd3_async-0.2.0}/docs/en/guide/advanced_queries.md

@@ -49,6 +49,29 @@ async for value, meta in client.get_range('/start', '/end'):
     print(f'{meta.key}: {value}')
 ```
 
+## Batch Operations
+
+The three batch entry points share one concurrency and failure policy:
+items run in parallel, the concurrency ceiling is controlled by
+`concurrency`, and a failing item never aborts the whole batch.
+
+```python
+# Atomic transaction: all succeed or none do
+count = await client.kv.batch_put([('/a', '1'), ('/b', '2')])
+
+# Parallel execution: at most 10 at a time, failures only affect the count
+count = await client.kv.batch_put(items, atomic=False, concurrency=10)
+
+# Returns (success_count, [(failed_key, error), ...])
+success, failed = await client.kv.put_many(items, concurrency=10)
+```
+
+`batch_put` and `put_many` accept either an iterable of `(key, value)`
+tuples or a mapping; `batch_delete` accepts an iterable of keys.
+
+The effective ceiling for `concurrency` is the client's `max_concurrent`
+(default 100): callers may lower it, never raise it.
+
 ## See Also
 
 - [API Usage](usage.md)

{python_etcd3_async-0.1.6 → python_etcd3_async-0.2.0}/docs/en/guide/leases_locks.md

@@ -148,6 +148,8 @@ await lock.acquire()
 async with lock.auto_refresh(interval=10):  # default: ttl / 3
     await do_long_running_work()
 # background refresh stops on exit (the lock itself is NOT released here)
+# if the keep-alive loop fails, the error is raised on exit — otherwise the
+# lease may already be gone while the caller still believes it holds the lock
 ```
 
 For sync clients, iterate the generator yourself:

{python_etcd3_async-0.1.6 → python_etcd3_async-0.2.0}/docs/en/guide/sync_client.md

@@ -38,8 +38,8 @@ from etcd3 import MultiEndpointEtcd3Client, Endpoint, LoadBalancerStrategy
 
 etcd = MultiEndpointEtcd3Client(
     endpoints=[
-        Endpoint('10.0.0.1', 2379),
-        Endpoint('10.0.0.2', 2379),
+        Endpoint('10.0.0.1', 2379, secure=False),
+        Endpoint('10.0.0.2', 2379, secure=False),
     ],
     failover=True,
     max_retries=3,
@@ -49,6 +49,10 @@ etcd = MultiEndpointEtcd3Client(
 )
 ```
 
+`Endpoint` defaults to `secure=True`, which requires TLS credentials. Pass
+`secure=False` for a plaintext connection (or supply `ca_cert` /
+`cert_cert` / `cert_key` for TLS).
+
 ## KV Operations
 
 ```python
@@ -119,6 +123,9 @@ success, responses = etcd.transaction(
 | Lock keep-alive | iterate `lock.refresh()` | `async with lock.auto_refresh()` |
 | Batch ops | top-level `batch_put`/`batch_delete` | `client.kv.batch_put/concurrency=...` |
 | Maintenance | via `etcd.maintenance.*` | top-level `status/compact/...` |
+| Members | `etcd.members` (property) | `async for m in etcd.members()` |
+| Delete result | number of deleted keys | number of deleted keys |
+| Put result | response header (or `KVMetadata` with `prev_kv=True`) | response header (or `KVMetadata` with `prev_kv=True`) |
 | Close | `etcd.close()` | `await client.close()` |
 
 ## Blocking in Async Code

{python_etcd3_async-0.1.6 → python_etcd3_async-0.2.0}/docs/en/operations/auto_reconnection.md

@@ -25,6 +25,30 @@ required.
    - Phase 3: Update endpoint state (under lock)
 5. Once rebuilt successfully, the endpoint is marked as healthy again
 
+## Health Probe Task
+
+`health_check_interval` drives a background probe task:
+
+- It starts lazily on the client's first request — a client that is never
+  used owns no task at all;
+- Each cycle probes only the endpoints that are currently marked as failed,
+  so healthy endpoints cause no extra round trips;
+- An endpoint that answers again is marked as healthy immediately, without
+  waiting for the `time_retry` window to expire;
+- `close()` cancels the task, so its lifetime matches the client's exactly.
+
+The sync client behaves the same way, with a daemon thread
+(`etcd3-health-check`) as the carrier instead: it starts lazily when a
+channel is first acquired, and `close()` signals it to exit and waits for
+it to finish. The thread is a daemon, so it never keeps the process alive
+even if `close()` is never called.
+
+```python
+# Inspect endpoint state: marked-failed / ok
+for label, endpoint in client.endpoints.items():
+    print(label, 'marked-failed' if endpoint.is_failed() else 'ok')
+```
+
 ## Tuning Reconnection
 
 Recovery attempts are configured on the multi-endpoint clients:

{python_etcd3_async-0.1.6 → python_etcd3_async-0.2.0}/docs/en/operations/error_handling.md

@@ -60,8 +60,7 @@ current endpoint as failed, which drives [Failover](failover.md) and
 ## Handler Layers
 
 - **Unary calls**: wrapped by generated error handlers that map
-  `grpc.RpcError` to the exceptions above and (for the multi-endpoint
-  clients) trigger retry with backoff.
+  `grpc.RpcError` to the exceptions above.
 - **Generators** (watch iterators, range streams): errors are mapped as
   they surface during iteration; generator handlers may end the stream
   quietly when the watch is cancelled normally.
@@ -71,11 +70,15 @@ current endpoint as failed, which drives [Failover](failover.md) and
 
 ## Retry Guidance
 
-The client already retries transient failures when `failover=True`
-(`max_retries`, `retry_backoff`, `retry_max_backoff`). Retry at the
-application level only for operations that are safe to repeat (idempotent
-puts, reads) and treat `RevisionCompactedError` as a signal to resync
-state rather than to retry blindly.
+Read operations are retried automatically on transient failures
+(`UNAVAILABLE`, `DEADLINE_EXCEEDED`, `INTERNAL`), bounded by
+`max_retries`, `retry_backoff` and `retry_max_backoff`.
+
+Writes are **not** retried automatically: the request may already have been
+applied server-side when the error surfaced, so repeating it could duplicate
+the effect. Retry writes at the application level only where they are safe
+to repeat (idempotent puts), and treat `RevisionCompactedError` as a signal
+to resync state rather than to retry blindly.
 
 ## See Also
 

{python_etcd3_async-0.1.6 → python_etcd3_async-0.2.0}/docs/en/operations/failover.md

@@ -44,10 +44,14 @@ see [Configuration](../guide/configuration.md).
    the endpoint is marked failed
 3. On the next operation the client picks a healthy endpoint (per the load
    balancer strategy) and rebuilds the failed endpoint's channel in the
-   background
+   background. With `failover=False` the client instead stays on the
+   endpoint it holds and rebuilds that endpoint's channel in place.
 4. Periodic health checks (`health_check_interval`) recover endpoints once
    the server answers again
 
+Both clients behave identically here: the sync and the async multi-endpoint
+client apply the same strategy and the same failover rules.
+
 ## Load Balancer Strategies
 
 | Strategy | Description |

python_etcd3_async-0.2.0/docs/en/resources/history.md

@@ -0,0 +1,72 @@
+---
+title: History
+---
+
+# History
+
+## v0.2.0 (2026-11)
+
+Sync and async clients aligned on behaviour that had drifted apart:
+
+- **Endpoint selection**: the async client now applies the load balancer
+  strategy and fails over to a healthy endpoint, like the sync client.
+  The `failover` flag is honoured by both clients: with failover enabled a
+  failed endpoint is bypassed, with failover disabled the client stays on
+  its endpoint and rebuilds that endpoint's channel in place
+- **Watch cancellation**: the async client cancels the real watch instead
+  of watch id 0, so cancelling removes the server-side watch and unblocks
+  a pending iteration. The async watcher no longer races on a shared
+  event, and closing the client closes the watcher
+- **Return values**: `delete()` / `delete_prefix()` return the number of
+  deleted keys on both clients, `put()` returns the response header (or
+  the previous key-value metadata with `prev_kv=True`), and the async
+  client gained `kv.transaction()`
+- **Instrumentation**: every operation is recorded exactly once (the sync
+  client recorded it twice)
+- **Retries**: `max_retries` / `retry_backoff` now take effect on the
+  idempotent read paths. Writes are not retried automatically, because the
+  request may already have been applied when the error surfaced
+- **Compatibility shims**: `etcd3.client(...)` and
+  `await etcd3.async_client(...)` keep working after
+  `import etcd3.client` / `import etcd3.async_client`
+- Sync `put_many()` honours its `timeout` argument; a transaction may
+  omit `success` / `failure` on both clients
+
+## v0.1.6 (2026-10)
+
+- Sync client: health probe for `health_check_interval`; batch operation
+  semantics unified
+
+## v0.1.5 (2026-09)
+
+- Sync client: gRPC error handling imported consistently across operation
+  modules; reconnection and watch cancel now reach the server
+  (`cancel_watch` no longer leaks threads/streams)
+- Lock API: `Lock`/`AsyncLock.release()` return explicit status strings
+  (`released` / `not_owner` / `not_found` / `error`); sync `lock` restored
+  as a method with the operations namespace renamed to `lock_ops`
+- Watch: `Watch.iterator()` renamed to `get_iterator()`; iterator cancel
+  is server-side on timeout
+- Async: parallel endpoint health checks; error-mapping regression fixed
+- Documentation site restructured (en + zh)
+
+## v0.1.1 – v0.1.4 (2026-02 – 2026-04)
+
+- High-cohesion module split: `single_client` / `multi_client` /
+  `async_single_client` / `async_multi_client`, `sync_*_operations`
+  mixins, `config` / `async_config`, `errors`, `auth`, `leases`, `locks`,
+  `members`
+- `client.py` / `async_client.py` converted to compatibility shims
+- Auth (user/role/permission) API added
+- Async managers use the async channel for auto-reconnection
+- Service examples improved (dataclass + v2 variants)
+
+## v0.1.0
+
+- Initial release
+- Async client support (`grpc.aio`)
+- Sync client support
+- Lease, lock, watch and transaction operations
+- Multi-endpoint support with failover
+- Auto reconnection
+- Monitoring metrics

{python_etcd3_async-0.1.6 → python_etcd3_async-0.2.0}/docs/zh/guide/advanced_queries.md

@@ -49,6 +49,28 @@ async for value, meta in client.get_range('/start', '/end'):
     print(f'{meta.key}: {value}')
 ```
 
+## 批量操作
+
+三个批量入口共享同一套并发与失败语义：条目并行执行，并发上限由
+`concurrency` 控制，单个条目失败不会中断整批。
+
+```python
+# 原子事务：全部成功或全部失败
+count = await client.kv.batch_put([('/a', '1'), ('/b', '2')])
+
+# 并行执行：最多 10 个并发，单条失败只计入失败数
+count = await client.kv.batch_put(items, atomic=False, concurrency=10)
+
+# 返回 (成功数, [(失败的键, 异常), ...])
+success, failed = await client.kv.put_many(items, concurrency=10)
+```
+
+`batch_put` 与 `put_many` 都接受 `(key, value)` 元组序列或字典；
+`batch_delete` 接受键序列。
+
+`concurrency` 的实际上限为客户端创建时的 `max_concurrent`（默认 100），
+调用方只能调低、不能调高。
+
 ## 另见
 
 - [API 使用](usage.md)

{python_etcd3_async-0.1.6 → python_etcd3_async-0.2.0}/docs/zh/guide/leases_locks.md

@@ -142,6 +142,8 @@ await lock.acquire()
 async with lock.auto_refresh(interval=10):  # 默认 ttl / 3
     await do_long_running_work()
 # 退出上下文时停止后台刷新（注意：并不会释放锁）
+# 若保活循环中途失败，退出上下文时会抛出该异常 ——
+# 否则租约可能已失效，而调用方仍以为持锁
 ```
 
 同步客户端需自行迭代生成器：

{python_etcd3_async-0.1.6 → python_etcd3_async-0.2.0}/docs/zh/guide/sync_client.md

@@ -36,8 +36,8 @@ from etcd3 import MultiEndpointEtcd3Client, Endpoint, LoadBalancerStrategy
 
 etcd = MultiEndpointEtcd3Client(
     endpoints=[
-        Endpoint('10.0.0.1', 2379),
-        Endpoint('10.0.0.2', 2379),
+        Endpoint('10.0.0.1', 2379, secure=False),
+        Endpoint('10.0.0.2', 2379, secure=False),
     ],
     failover=True,
     max_retries=3,
@@ -47,6 +47,9 @@ etcd = MultiEndpointEtcd3Client(
 )
 ```
 
+`Endpoint` 默认为 `secure=True`，此时必须提供 TLS 凭据。纯文本连接请传
+`secure=False`（或提供 `ca_cert` / `cert_cert` / `cert_key` 启用 TLS）。
+
 ## 键值操作
 
 ```python
@@ -117,6 +120,9 @@ success, responses = etcd.transaction(
 | 锁保活 | 迭代 `lock.refresh()` | `async with lock.auto_refresh()` |
 | 批量操作 | 顶层 `batch_put`/`batch_delete` | `client.kv.batch_put(concurrency=...)` |
 | 运维 | 经 `etcd.maintenance.*` | 顶层 `status/compact/...` |
+| 成员列表 | `etcd.members`（属性） | `async for m in etcd.members()` |
+| 删除结果 | 删除的键数量 | 删除的键数量 |
+| 写入结果 | 响应头（`prev_kv=True` 时为 `KVMetadata`） | 响应头（`prev_kv=True` 时为 `KVMetadata`） |
 | 关闭 | `etcd.close()` | `await client.close()` |
 
 ## 在异步代码中调用同步客户端

{python_etcd3_async-0.1.6 → python_etcd3_async-0.2.0}/docs/zh/operations/auto_reconnection.md

@@ -20,6 +20,25 @@ title: 自动重连
    - 阶段3：更新端点状态（在锁内）
 5. 重建成功后，端点被重新标记为健康
 
+## 健康探测任务
+
+`health_check_interval` 对应一个后台探测任务：
+
+- 客户端首次发起请求时惰性启动 —— 从未使用的客户端不占用任何任务；
+- 每个周期只探测被标记为失败的端点，健康端点不做无谓往返；
+- 端点恢复应答后立即被标记为健康，不必等到 `time_retry` 窗口结束；
+- `close()` 会取消该任务，任务生命周期与客户端严格一致。
+
+同步客户端行为一致，只是载体换成守护线程（`etcd3-health-check`）：
+首次取通道时惰性启动，`close()` 通知其退出并等待收尾；
+线程为守护线程，即使未调用 `close()` 也不会阻止进程退出。
+
+```python
+# 观察端点状态：marked-failed / ok
+for label, endpoint in client.endpoints.items():
+    print(label, 'marked-failed' if endpoint.is_failed() else 'ok')
+```
+
 ## 重连调优
 
 恢复相关参数在多端点客户端上配置：

python_etcd3_async-0.2.0/docs/zh/resources/history.md

@@ -0,0 +1,63 @@
+---
+title: 更新历史
+---
+
+# 更新历史
+
+## v0.2.0 (2026-11)
+
+同步与异步客户端在行为差异上完成对齐：
+
+- **端点选择**：异步客户端现在与同步客户端一样应用负载均衡策略，并在
+  端点失败时切换到健康端点。两个客户端都真正尊重 `failover` 参数：
+  开启时绕过失败端点，关闭时留在当前端点并原地重建其 channel
+- **Watch 取消**：异步客户端取消的是真实的 watch（此前取消的是并不存在
+  的 watch id 0），因此取消会真正移除服务端 watch 并唤醒阻塞中的迭代
+  器。异步 watcher 不再共享事件产生竞态，关闭客户端也会关闭 watcher
+- **返回值**：两个客户端的 `delete()` / `delete_prefix()` 均返回删除的键
+  数量，`put()` 均返回响应头（`prev_kv=True` 时返回旧值元数据），异步
+  客户端新增 `kv.transaction()`
+- **埋点**：每个操作只会被记录一次（同步客户端此前重复记录）
+- **重试**：`max_retries` / `retry_backoff` 现在对幂等读路径生效。写操作
+  不自动重试，因为报错时请求可能已在服务端生效
+- **兼容层**：`import etcd3.client` / `import etcd3.async_client` 之后，
+  `etcd3.client(...)` 与 `await etcd3.async_client(...)` 仍可正常调用
+- 同步端 `put_many()` 现在真正使用其 `timeout` 参数；两个客户端的事务都
+  可以省略 `success` / `failure`
+
+## v0.1.6 (2026-10)
+
+- 同步客户端：实现 `health_check_interval` 健康探测；统一批量操作语义
+
+## v0.1.5 (2026-09)
+
+- 同步客户端：各操作模块统一复用 gRPC 错误处理；重连与 watch 取消
+  现在真正送达服务端（`cancel_watch` 不再泄漏线程/流）
+- 锁 API：`Lock`/`AsyncLock.release()` 返回明确的语义状态
+  （`released` / `not_owner` / `not_found` / `error`）；同步 `lock`
+  恢复为方法，操作命名空间更名为 `lock_ops`
+- Watch：`Watch.iterator()` 更名为 `get_iterator()`；迭代器超时即
+  取消服务端 watch
+- 异步：端点健康检查并行化；修复错误映射回归
+- 文档站重构（中英双语）
+
+## v0.1.1 – v0.1.4 (2026-02 – 2026-04)
+
+- 高内聚模块拆分：`single_client` / `multi_client` /
+  `async_single_client` / `async_multi_client`、`sync_*_operations`
+  混入、`config` / `async_config`、`errors`、`auth`、`leases`、`locks`、
+  `members`
+- `client.py` / `async_client.py` 转为兼容性 shim
+- 新增 Auth（用户/角色/权限）API
+- 异步 managers 使用异步 channel 实现自动重连
+- 服务示例改进（dataclass + v2 版本）
+
+## v0.1.0
+
+- 初始发布
+- 支持异步客户端（`grpc.aio`）
+- 支持同步客户端
+- 租约、锁、观察与事务操作
+- 多端点支持与故障转移
+- 自动重连
+- 监控指标

{python_etcd3_async-0.1.6 → python_etcd3_async-0.2.0}/etcd3/__init__.py

@@ -8,6 +8,7 @@ from etcd3.shared import Transactions
 from etcd3.async_single_client import AsyncEtcd3Client
 from etcd3.async_multi_client import AsyncMultiEndpointEtcd3Client
 from etcd3.async_endpoint import AsyncEndpoint
+from etcd3.async_endpoint import AsyncEndpointConfig
 from etcd3.async_client_extensions import get_request_context, set_request_context
 from etcd3.exceptions import Etcd3Exception
 from etcd3.observability import ObservabilityConfig
@@ -50,7 +51,7 @@ from etcd3.async_single_client import async_client
 
 __author__ = "owasd"
 __email__ = ""
-__version__ = "0.1.6"
+__version__ = "0.2.0"
 
 __all__ = (
     "etcdrpc",
@@ -71,6 +72,7 @@ __all__ = (
     "Permission",
     "MultiEndpointEtcd3Client",
     "AsyncEndpoint",
+    "AsyncEndpointConfig",
     "AsyncEtcd3Client",
     "AsyncMultiEndpointEtcd3Client",
     "async_client",

{python_etcd3_async-0.1.6 → python_etcd3_async-0.2.0}/etcd3/async_client.py

@@ -8,6 +8,9 @@ For new code, prefer importing from:
     - etcd3.async_endpoint: AsyncEndpoint
 """
 
+import sys
+import types
+
 # Re-export config classes
 from etcd3.async_config import AsyncClientConfig, AsyncMultiEndpointConfig
 from etcd3.config import RangeRequestConfig
@@ -48,3 +51,21 @@ __all__ = [
     "_async_handle_keepalive_errors",
     "async_client",
 ]
+
+
+class _CallableModule(types.ModuleType):
+    """Module that can also be awaited like the factory function it re-exports.
+
+    ``import etcd3.async_client`` makes Python rebind the
+    ``etcd3.async_client`` attribute from the factory function to this
+    module. Without this, the documented ``await etcd3.async_client(...)``
+    call would break for anyone who imported the compatibility shim.
+    Calling the module delegates to the factory function, so both
+    spellings keep working.
+    """
+
+    def __call__(self, *args, **kwargs):
+        return async_client(*args, **kwargs)
+
+
+sys.modules[__name__].__class__ = _CallableModule