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

{python_etcd3_async-0.2.0 → python_etcd3_async-0.2.1}/.cnb.yml

@@ -35,6 +35,13 @@ $:
         - name: ruff format
           script:
             - uv run --no-sync ruff format --check etcd3/ etcdrpc/ tests/
+        - name: generated protobuf code is up to date
+          # The generated code in etcdrpc/ is checked in and carries the
+          # grpcio/protobuf version floors this package supports. Regenerate
+          # it with the pinned codegen toolchain and fail if it drifted.
+          script:
+            - uv sync --group codegen
+            - uv run --no-sync ./scripts/gen-protos.sh --check
 
     - name: unit
       docker:

python_etcd3_async-0.2.1/.gitignore

@@ -0,0 +1,18 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+# The generated protobuf/gRPC code in etcdrpc/ is checked in on purpose:
+# it embeds GRPC_GENERATED_VERSION, which is the floor of the grpcio range
+# this package supports. Regenerate it with scripts/gen-protos.sh.
+.trae/documents/*
+.pytest_cache/
+.ruff_cache/
+htmlcov/
+# Virtual environments
+.venv
+/site
+.etcd-tls/

{python_etcd3_async-0.2.0 → python_etcd3_async-0.2.1}/AGENTS.md

@@ -67,10 +67,24 @@ uv run ruff format etcd3/ etcdrpc/       # Format
 
 ### Other
 ```bash
-uv run python gen_protos.py  # Regenerate protobuf
+./scripts/gen-protos.sh      # Regenerate the protobuf/gRPC code in etcdrpc/
 uv run mkdocs serve          # Serve docs
 ```
 
+### Protobuf / gRPC version floors
+- `etcdrpc/*_pb2*.py` is **generated code that is checked in**. The
+  `grpcio` and `protobuf` floors in `pyproject.toml` must equal the
+  versions embedded in it (`GRPC_GENERATED_VERSION` and the protobuf
+  gencode version).
+- The `codegen` dependency group pins the generator to that floor, so
+  regenerating never silently raises it. `scripts/gen-protos.sh` uses it.
+- The runtime dependencies are **ranges** (`grpcio>=...`, `protobuf>=...`):
+  the generated code only rejects a runtime *older* than the floor, so
+  newer versions are fine and the package can be installed next to other
+  packages that need a different grpcio.
+- `tests/test_grpc_compat.py` fails if the floors and the codegen pin
+  drift apart.
+
 ### Versioning
 - Single source of truth: `__version__` in `etcd3/__init__.py`
 - `pyproject.toml` uses `dynamic = ["version"]` via
@@ -179,7 +193,7 @@ etcd3/
   log.py / log_formatters.py / log_sampling.py  # Logging
   observability.py      # ObservabilityConfig / configure_from_env / auto_init
   exporters/            # Prometheus exporter
-etcdrpc/                # Generated protobuf/gRPC code
+etcdrpc/                # .proto sources + the generated protobuf/gRPC code
 tests/                  # Test files
 ```
 

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

@@ -82,9 +82,10 @@ uv run ruff format etcd3/ etcdrpc/
 
 ### Protobuf Generation
 ```bash
-# Protobuf files are auto-generated during build via hatchling hook
-# To manually regenerate:
-uv run python gen_protos.py
+# The generated code is checked in; regenerate it with:
+./scripts/gen-protos.sh
+# CI fails if the checked-in code drifts from the .proto files:
+./scripts/gen-protos.sh --check
 ```
 
 ### Environment Variables
@@ -212,7 +213,11 @@ Generated gRPC/Python bindings from etcd proto files:
 - `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).
+The generated code is checked in (it embeds `GRPC_GENERATED_VERSION`,
+the oldest grpcio this package supports) and regenerated with
+`scripts/gen-protos.sh` using the pinned `codegen` toolchain. The runtime
+dependencies are ranges, so newer grpcio/protobuf versions work and the
+package installs next to other packages with a different grpcio.
 
 ### Examples (`examples/`)
 

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

@@ -1,11 +1,28 @@
 Metadata-Version: 2.5
 Name: python-etcd3-async
-Version: 0.2.0
+Version: 0.2.1
 Summary: etcd3 async sdk
+Project-URL: Repository, https://cnb.cool/owasd/python3-etcd-async
+Project-URL: Source, https://cnb.cool/owasd/python3-etcd-async
+Project-URL: Homepage, https://cnb.cool/owasd/python3-etcd-async
+Project-URL: Issues, https://cnb.cool/owasd/python3-etcd-async/issues
+Project-URL: Changelog, https://cnb.cool/owasd/python3-etcd-async/blob/main/docs/en/resources/history.md
+Author: owasd
+License-Expression: Apache-2.0
+Keywords: async,etcd,etcd3,grpc,kubernetes
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: <4,>=3.12
-Requires-Dist: grpcio==1.76.0
+Requires-Dist: grpcio>=1.76.0
 Requires-Dist: prometheus-client>=0.24.1
-Requires-Dist: protobuf==6.31.1
+Requires-Dist: protobuf>=6.31.1
 Description-Content-Type: text/markdown
 
 # python-etcd3-async
@@ -23,7 +40,7 @@ Python async client for the etcd API v3, supporting both synchronous and asynchr
 - **Async/Sync dual support**: Same API for both async and sync usage with feature parity
 - **Automatic reconnection**: Auto-rebuild stale connections (e.g., after etcd server restart)
 - **Keepalive error propagation**: Lease keepalive errors are properly propagated for connection loss detection
-- **Endpoint failover**: Built-in support for multiple endpoints with automatic failover
+- **Endpoint failover**: Built-in support for multiple endpoints with opt-in automatic failover (`failover=True`)
 - **Context manager**: Clean resource management for both sync and async
 - **Observability**: Structured logging, OpenTelemetry tracing, and Prometheus metrics
 
@@ -272,8 +289,14 @@ client = await async_client(
 )
 
 # Multiple endpoints with failover
-client = await async_client(
-    endpoints=['localhost:2379', 'localhost:22379'],
+# (the single-endpoint factory does not take endpoints=)
+from etcd3 import AsyncMultiEndpointEtcd3Client, AsyncEndpoint
+
+client = AsyncMultiEndpointEtcd3Client(
+    endpoints=[
+        AsyncEndpoint('localhost', 2379, secure=False),
+        AsyncEndpoint('localhost', 22379, secure=False),
+    ],
     failover=True,  # Automatically switch to healthy endpoint
 )
 

{python_etcd3_async-0.2.0 → python_etcd3_async-0.2.1}/README.md

@@ -13,7 +13,7 @@ Python async client for the etcd API v3, supporting both synchronous and asynchr
 - **Async/Sync dual support**: Same API for both async and sync usage with feature parity
 - **Automatic reconnection**: Auto-rebuild stale connections (e.g., after etcd server restart)
 - **Keepalive error propagation**: Lease keepalive errors are properly propagated for connection loss detection
-- **Endpoint failover**: Built-in support for multiple endpoints with automatic failover
+- **Endpoint failover**: Built-in support for multiple endpoints with opt-in automatic failover (`failover=True`)
 - **Context manager**: Clean resource management for both sync and async
 - **Observability**: Structured logging, OpenTelemetry tracing, and Prometheus metrics
 
@@ -262,8 +262,14 @@ client = await async_client(
 )
 
 # Multiple endpoints with failover
-client = await async_client(
-    endpoints=['localhost:2379', 'localhost:22379'],
+# (the single-endpoint factory does not take endpoints=)
+from etcd3 import AsyncMultiEndpointEtcd3Client, AsyncEndpoint
+
+client = AsyncMultiEndpointEtcd3Client(
+    endpoints=[
+        AsyncEndpoint('localhost', 2379, secure=False),
+        AsyncEndpoint('localhost', 22379, secure=False),
+    ],
     failover=True,  # Automatically switch to healthy endpoint
 )
 

{python_etcd3_async-0.2.0 → python_etcd3_async-0.2.1}/README_CN.md

@@ -13,7 +13,7 @@ Python etcd API v3 异步客户端，支持同步和异步操作。
 - **同步/异步双模式**: 同一套 API 同时支持 sync 和 async，功能完全对等
 - **自动重连**: 自动重建失效连接（如 etcd 服务器重启后）
 - **Keepalive 错误传播**: 租约保活错误正确传播，便于连接断开检测
-- **端点故障转移**: 支持多节点自动故障转移
+- **端点故障转移**: 支持多节点，可选开启自动故障转移（`failover=True`）
 - **上下文管理**: 资源清理更加简洁
 - **可观测性**: 结构化日志、OpenTelemetry 追踪、Prometheus 指标
 
@@ -262,8 +262,14 @@ client = await async_client(
 )
 
 # 多节点故障转移
-client = await async_client(
-    endpoints=['localhost:2379', 'localhost:22379'],
+# （单端点工厂函数不接受 endpoints= 参数）
+from etcd3 import AsyncMultiEndpointEtcd3Client, AsyncEndpoint
+
+client = AsyncMultiEndpointEtcd3Client(
+    endpoints=[
+        AsyncEndpoint('localhost', 2379, secure=False),
+        AsyncEndpoint('localhost', 22379, secure=False),
+    ],
     failover=True,  # 自动切换到健康节点
 )
 

{python_etcd3_async-0.2.0 → python_etcd3_async-0.2.1}/docs/en/getting-started/installation.md

@@ -28,6 +28,12 @@ uv pip install -e .
 
 - Python 3.12+
 - etcd v3 API server (v3.1+ recommended)
+- `grpcio>=1.76.0` and `protobuf>=6.31.1`
+
+The grpcio and protobuf requirements are **ranges**, not exact pins, so the
+package installs next to other packages that need a different grpcio. The
+generated protobuf code only rejects a runtime that is *older* than the
+version it was generated with, so newer grpcio releases work as well.
 
 ## Virtual Environments with uv
 

{python_etcd3_async-0.2.0 → python_etcd3_async-0.2.1}/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}')
 ```
 
+## Write Results
+
+The sync and the async client return the same shapes for writes:
+
+| Call | Result |
+|------|--------|
+| `put(key, value)` | the response header (revision, etc.) |
+| `put(key, value, prev_kv=True)` | `KVMetadata` describing the **previous** value |
+| `delete(key)` | the number of deleted keys |
+| `delete_prefix(prefix)` | the number of deleted keys |
+| `delete(key, return_response=True)` | the full `DeleteRangeResponse` |
+
+```python
+# How many keys did that delete remove?
+removed = await client.delete('/mykey')
+
+# What was stored before this write?
+previous = await client.put('/mykey', 'new', prev_kv=True)
+print(previous.value)   # b'old'
+```
+
+`delete_prefix` accepts `return_response=True` on both clients as well.
+
 ## Batch Operations
 
 The three batch entry points share one concurrency and failure policy:

{python_etcd3_async-0.2.0 → python_etcd3_async-0.2.1}/docs/en/guide/configuration.md

@@ -75,12 +75,18 @@ client = AsyncMultiEndpointEtcd3Client(
 | `user` | str | None | Username for authentication |
 | `password` | str | None | Password for authentication |
 | `failover` | bool | False | Enable automatic failover between endpoints |
-| `max_retries` | int | 3 | Maximum retries for transient errors |
+| `max_retries` | int | 3 | Maximum retries for transient errors (read paths only) |
 | `retry_backoff` | float | 0.1 | Initial retry backoff in seconds |
 | `retry_max_backoff` | float | 10.0 | Maximum retry backoff in seconds |
 | `load_balancer` | LoadBalancerStrategy | PRIORITY | Load balancing strategy |
 | `health_check_interval` | float | 30.0 | Health check interval in seconds |
 
+`failover` and `load_balancer` decide which endpoint a request goes to:
+with `failover=True` a failed endpoint is bypassed, with `failover=False`
+the client stays on its endpoint and rebuilds the channel in place. The
+retry settings apply to the idempotent read paths only — writes are
+never retried automatically.
+
 ## Configuration Classes
 
 Every keyword above can also be passed as a typed dataclass via `config=`,

{python_etcd3_async-0.2.0 → python_etcd3_async-0.2.1}/docs/en/index.md

@@ -10,7 +10,7 @@ python-etcd3-async is an async Python client library for the etcd v3 API based o
 
 - **Async First**: Pure async operations using `grpc.aio`
 - **Sync Support**: Synchronous client API also available
-- **Failover**: Multi-endpoint support with automatic failover
+- **Failover**: Multi-endpoint support with opt-in automatic failover
 - **Auto Reconnection**: Automatic channel rebuild on connection failure
 - **Complete API**: Full support for all major etcd v3 features
 

{python_etcd3_async-0.2.0 → python_etcd3_async-0.2.1}/docs/en/operations/async_error_handling.md

@@ -22,7 +22,7 @@ This guide provides comprehensive information on the error handling mechanisms o
 The etcd3 async client provides robust error handling capabilities to ensure reliable operation in production environments. Key features include:
 
 - **Comprehensive error mapping**: All gRPC status codes are mapped to appropriate Python exceptions
-- **Exponential backoff retry**: Automatically retry transient errors with configurable backoff
+- **Exponential backoff retry**: Transient errors are retried on the idempotent read paths
 - **Resource management**: Proper cleanup of gRPC channels and other resources
 - **Monitoring**: Detailed metrics collection for error rates, latencies, and endpoint health
 - **Failover support**: Automatic switching between endpoints when failures occur
@@ -52,13 +52,23 @@ The etcd3 async client maps gRPC status codes to the following exception types:
 
 ## Retry Mechanism
 
-The etcd3 async client implements an exponential backoff retry strategy for transient errors. By default, it will retry the following error types:
+The client retries transient errors on the **idempotent read paths** (`get`,
+`get_prefix`, `get_range`, `get_all` and their `*_response` variants).
+By default, it will retry the following error types:
 
 - `UNAVAILABLE` (connection errors)
 - `DEADLINE_EXCEEDED` (timeouts)
 - `INTERNAL` (server errors)
 - `RESOURCE_EXHAUSTED` (resource constraints)
 
+**Writes are not retried automatically.** A failed request may already have
+been applied server-side, so repeating it could duplicate the effect.
+Retry writes in the application, and only where they are safe to repeat
+(idempotent puts). Treat `RevisionCompactedError` as a signal to resync
+state rather than to retry blindly.
+
+The same rules apply to the sync client.
+
 ### Retry Configuration
 
 You can configure the retry behavior when creating the client:

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

@@ -67,6 +67,15 @@ client = AsyncMultiEndpointEtcd3Client(
 )
 ```
 
+`max_retries` and the backoff settings apply to the idempotent read paths.
+Writes are never retried automatically — see
+[Error Handling](error_handling.md#retry-guidance).
+
+With `failover=True` a failed endpoint is bypassed and the client picks
+another healthy one. With `failover=False` the client stays on the
+endpoint it holds and rebuilds that endpoint's channel in place. The sync
+and the async client behave the same way.
+
 Each `Endpoint` also carries `time_retry` (default 300 s) — the window in
 which a failed endpoint stays marked failed before being considered again.
 

{python_etcd3_async-0.2.0 → python_etcd3_async-0.2.1}/docs/en/resources/history.md

@@ -4,8 +4,46 @@ title: History
 
 # History
 
+## v0.2.1 (2026-11)
+
+### grpcio / protobuf compatibility
+
+- The `grpcio` and `protobuf` requirements are now **ranges**
+  (`grpcio>=1.76.0`, `protobuf>=6.31.1`) instead of exact pins, so the
+  package installs next to other packages that need a different grpcio
+- The generated protobuf/gRPC code in `etcdrpc/` is checked in, and the
+  build no longer needs protoc or grpcio-tools - it works on every
+  supported Python
+- The generator is pinned to the supported floor in a new `codegen`
+  dependency group, so regenerating can never silently raise the floor
+  and break users on older grpcio
+- `scripts/gen-protos.sh` regenerates the code and
+  `scripts/gen-protos.sh --check` fails when it has drifted; the check
+  runs in CI
+- `tests/test_grpc_compat.py` pins the contract: the declared floors must
+  match the versions embedded in the generated code
+
+### Packaging
+
+- The package metadata now points at the repository
+  (https://cnb.cool/owasd/python3-etcd-async) and carries the license,
+  author, keywords and classifiers - the PyPI page of the previous
+  releases had no repository link at all
+- `scripts/publish.sh` publishes a release: it reads the token from
+  `~/.pypirc` (uv does not read that file itself), refuses placeholder
+  versions, only uploads the artifacts of the current version and asks
+  for a confirmation before uploading
+
+### Documentation
+
+- The guides now describe the 0.2.0 behaviour: the retry policy covers
+  the idempotent read paths only, the failover rules for both clients,
+  and the shared write results
+
 ## v0.2.0 (2026-11)
 
+### Sync and async parity
+
 Sync and async clients aligned on behaviour that had drifted apart:
 
 - **Endpoint selection**: the async client now applies the load balancer

{python_etcd3_async-0.2.0 → python_etcd3_async-0.2.1}/docs/en/resources/releasing.md

@@ -39,8 +39,8 @@ and hatch reads that attribute at build time — do not add a static
    uv run ruff check tests/ etcd3/ && uv run ruff format --check tests/ etcd3/
    ```
 
-5. **Build the distribution** (protobuf code is regenerated by the
-   hatch build hook).
+5. **Build the distribution** (the generated protobuf code is checked in,
+   so the build needs no protoc).
 
    ```bash
    uv build
@@ -56,10 +56,31 @@ and hatch reads that attribute at build time — do not add a static
 7. **Publish** to the index and tag the release:
 
    ```bash
-   uv publish          # or the project's index workflow
+   scripts/publish.sh publish    # builds if needed, uploads, confirms first
    git tag vX.Y.Z
    git push && git push --tags
    ```
 
+   `scripts/publish.sh` wraps `uv publish` because **`uv` does not read
+   `~/.pypirc`**: the script takes the token from the `[pypi]` section of
+   that file and passes it through `UV_PUBLISH_TOKEN`. In CI, where
+   trusted publishing (OIDC) is configured on PyPI, no token is needed and
+   the script publishes without one.
+
+   The script refuses to publish placeholder versions (`9.9.9`, `0.0.0`,
+   non-`MAJOR.MINOR.PATCH` strings) and warns when the version is already
+   on PyPI. A published version cannot be replaced, and it becomes the
+   version that installers resolve to, so a scratch version must never
+   reach the index - use `scripts/publish.sh dry-run` to test the upload
+   path instead.
+
+   Other commands: `check` (pre-flight checks only), `dry-run` (validates
+   the upload without sending anything), `build`, `verify` (waits until the
+   release shows up on PyPI).
+
+   Overrides: `PYPI_TOKEN`, `PYPI_CONFIG`, `PYPI_SECTION`,
+   `PYPI_PUBLISH_URL`, `PYPI_CHECK_URL`, `PUBLISH_CONFIRM=yes` (skips the
+   confirmation prompt).
+
 8. **Verify the published artifact** resolves from a clean environment
    (`uv add python-etcd3-async==X.Y.Z` in a scratch project).

{python_etcd3_async-0.2.0 → python_etcd3_async-0.2.1}/docs/zh/getting-started/installation.md

@@ -28,6 +28,11 @@ uv pip install -e .
 
 - Python 3.12+
 - etcd v3 API 服务器（推荐 v3.1+）
+- `grpcio>=1.76.0` 与 `protobuf>=6.31.1`
+
+grpcio 与 protobuf 的依赖是**区间**而非精确锁定，因此本包可以与需要其它
+grpcio 版本的包共存。生成的 protobuf 代码只会拒绝比生成时**更旧**的运行时
+版本，因此更新的 grpcio 同样可用。
 
 ## 使用 uv 管理虚拟环境
 

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

@@ -49,6 +49,29 @@ async for value, meta in client.get_range('/start', '/end'):
     print(f'{meta.key}: {value}')
 ```
 
+## 写操作返回值
+
+同步与异步客户端的写操作返回形态一致：
+
+| 调用 | 返回值 |
+|------|--------|
+| `put(key, value)` | 响应头（含 revision 等信息） |
+| `put(key, value, prev_kv=True)` | 描述**旧值**的 `KVMetadata` |
+| `delete(key)` | 删除的键数量 |
+| `delete_prefix(prefix)` | 删除的键数量 |
+| `delete(key, return_response=True)` | 完整的 `DeleteRangeResponse` |
+
+```python
+# 这次删除移除了多少个键？
+removed = await client.delete('/mykey')
+
+# 写入之前的值是什么？
+previous = await client.put('/mykey', 'new', prev_kv=True)
+print(previous.value)   # b'old'
+```
+
+两个客户端的 `delete_prefix` 都支持 `return_response=True`。
+
 ## 批量操作
 
 三个批量入口共享同一套并发与失败语义：条目并行执行，并发上限由

{python_etcd3_async-0.2.0 → python_etcd3_async-0.2.1}/docs/zh/guide/configuration.md

@@ -75,12 +75,16 @@ client = AsyncMultiEndpointEtcd3Client(
 | `user` | str | None | 认证用户名 |
 | `password` | str | None | 认证密码 |
 | `failover` | bool | False | 启用端点间自动故障转移 |
-| `max_retries` | int | 3 | 瞬态错误的最大重试次数 |
+| `max_retries` | int | 3 | 瞬态错误的最大重试次数（仅读路径） |
 | `retry_backoff` | float | 0.1 | 初始重试退避时间（秒） |
 | `retry_max_backoff` | float | 10.0 | 最大重试退避时间（秒） |
 | `load_balancer` | LoadBalancerStrategy | PRIORITY | 负载均衡策略 |
 | `health_check_interval` | float | 30.0 | 健康检查间隔（秒） |
 
+`failover` 与 `load_balancer` 共同决定请求发往哪个端点：`failover=True`
+时失败端点会被绕过，`failover=False` 时客户端留在当前端点并原地重建
+channel。重试参数只作用于幂等读路径——写操作永远不会自动重试。
+
 ## 配置类
 
 上述所有关键字都可以通过 `config=` 以带类型的 dataclass 传入，

{python_etcd3_async-0.2.0 → python_etcd3_async-0.2.1}/docs/zh/index.md

@@ -10,7 +10,7 @@ python-etcd3-async 是一个基于 `grpc.aio` 的 etcd v3 API 异步 Python 客
 
 - **异步优先**：使用 `grpc.aio` 实现纯异步操作
 - **同步支持**：同时提供同步客户端 API
-- **故障转移**：多端点支持，自动故障转移
+- **故障转移**：多端点支持，可选开启自动故障转移
 - **自动重连**：连接失效时自动重建
 - **完整 API**：支持 etcd v3 所有主要功能
 

{python_etcd3_async-0.2.0 → python_etcd3_async-0.2.1}/docs/zh/operations/async_error_handling.md

@@ -11,7 +11,7 @@ title: 异步错误处理
 etcd3 异步客户端提供强大的错误处理功能，确保在生产环境中的可靠运行。主要特性包括：
 
 - **全面错误映射**：所有 gRPC 状态码都映射到相应的 Python 异常
-- **指数退避重试**：自动重试瞬态错误，支持可配置退避
+- **指数退避重试**：在幂等读路径上自动重试瞬态错误，支持可配置退避
 - **资源管理**：正确清理 gRPC 通道和其他资源
 - **监控**：详细收集错误率、延迟和端点健康状况指标
 - **故障转移支持**：发生故障时自动切换端点
@@ -41,13 +41,20 @@ etcd3 异步客户端将 gRPC 状态码映射到以下异常类型：
 
 ## 重试机制
 
-etcd3 异步客户端对瞬态错误实现指数退避重试策略。默认情况下，它将重试以下错误类型：
+客户端在**幂等读路径**（`get`、`get_prefix`、`get_range`、`get_all` 及其
+`*_response` 变体）上对瞬态错误实现指数退避重试。默认情况下，它将重试以下错误类型：
 
 - `UNAVAILABLE`（连接错误）
 - `DEADLINE_EXCEEDED`（超时）
 - `INTERNAL`（服务器错误）
 - `RESOURCE_EXHAUSTED`（资源限制）
 
+**写操作不会自动重试。** 请求报错时可能已在服务端生效，重复执行可能产生
+重复副作用。写操作请在应用层重试，且仅在可安全重复时重试（幂等的 put）。
+遇到 `RevisionCompactedError` 应视为需要重新同步状态，而不是盲目重试。
+
+同步客户端遵循同样的规则。
+
 ### 重试配置
 
 创建客户端时可以配置重试行为：

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

@@ -60,6 +60,13 @@ client = AsyncMultiEndpointEtcd3Client(
 每个 `Endpoint` 还带有 `time_retry`（默认 300 秒）—
 失败端点在被重新纳入候选之前保持"失败"标记的时间窗口。
 
+`max_retries` 及退避参数只作用于幂等读路径。写操作永远不会自动重试，
+详见[错误处理](error_handling.md)。
+
+`failover=True` 时，失败端点会被绕过，客户端改用其它健康端点；
+`failover=False` 时，客户端留在当前端点并原地重建其 channel。
+同步与异步客户端行为一致。
+
 ## 观察恢复过程
 
 ```python

{python_etcd3_async-0.2.0 → python_etcd3_async-0.2.1}/docs/zh/operations/error_handling.md

@@ -59,7 +59,7 @@ except exceptions.NoServerAvailableError as e:
 ## 错误处理层
 
 - **一元调用**：由生成的错误处理器包装，把 `grpc.RpcError` 映射为
-  上述异常，并在多端点客户端上触发带退避的重试。
+  上述异常。
 - **生成器**（watch 迭代器、range 流）：错误在迭代过程中浮现时被映射；
   watch 被正常取消时，生成器处理器可能会静默结束流。
 - **保活流**（租约刷新）：映射后的错误会传播给消费方，
@@ -67,10 +67,14 @@ except exceptions.NoServerAvailableError as e:
 
 ## 重试建议
 
-启用 `failover=True` 时，客户端已对瞬时失败进行重试
-（`max_retries`、`retry_backoff`、`retry_max_backoff`）。
-应用层重试只用于可安全重复的操作（幂等的 put、读），
-并把 `RevisionCompactedError` 视为重新同步状态的信号，而非盲目重试。
+读操作（`get`、`get_prefix`、`get_range`、`get_all` 及其
+`*_response` 变体）在遇到瞬时失败时会自动重试，次数由
+`max_retries`、`retry_backoff`、`retry_max_backoff` 控制。
+
+**写操作不会自动重试。** 请求报错时可能已在服务端生效，重复执行可能
+产生重复副作用。写操作请在应用层重试，且仅在可安全重复时重试
+（幂等的 put）。把 `RevisionCompactedError` 视为需要重新同步状态的信号，
+而非盲目重试。
 
 ## 另见
 

{python_etcd3_async-0.2.0 → python_etcd3_async-0.2.1}/docs/zh/operations/failover.md

@@ -41,10 +41,14 @@ client = AsyncMultiEndpointEtcd3Client(
 2. 当请求因 UNAVAILABLE、DEADLINE_EXCEEDED 或 INTERNAL 失败时，
    端点被标记为失败
 3. 下一次操作时，客户端按负载均衡策略选择健康端点，
-   并在后台重建失败端点的通道
+   并在后台重建失败端点的通道。若 `failover=False`，
+   客户端则留在当前端点，并原地重建该端点的通道
 4. 定期健康检查（`health_check_interval`）在服务器恢复应答后
    将端点标记为健康
 
+两个客户端行为一致：同步与异步多端点客户端使用相同的策略和相同的
+故障转移规则。
+
 ## 负载均衡策略
 
 | 策略 | 描述 |

{python_etcd3_async-0.2.0 → python_etcd3_async-0.2.1}/docs/zh/resources/history.md

@@ -4,8 +4,39 @@ title: 更新历史
 
 # 更新历史
 
+## v0.2.1 (2026-11)
+
+### grpcio / protobuf 兼容性
+
+- `grpcio` 与 `protobuf` 的依赖改为**区间**
+  （`grpcio>=1.76.0`、`protobuf>=6.31.1`），不再精确锁定，因此本包可以与
+  需要其它 grpcio 版本的包共存
+- `etcdrpc/` 下生成的 protobuf/gRPC 代码改为入库，构建时不再需要 protoc
+  或 grpcio-tools，在所有受支持的 Python 上都能构建
+- 生成器在新增的 `codegen` 依赖组中锁定到所支持的下限，重新生成代码不会
+  悄悄抬高下限、导致使用旧版 grpcio 的用户在导入时失败
+- `scripts/gen-protos.sh` 用于重新生成代码，
+  `scripts/gen-protos.sh --check` 在代码发生漂移时报错，该检查已接入 CI
+- `tests/test_grpc_compat.py` 固化此约定：声明的下限必须与生成代码中嵌入的
+  版本一致
+
+### 打包
+
+- 包元数据现在指向代码仓库（https://cnb.cool/owasd/python3-etcd-async），
+  并补齐了许可证、作者、关键词与分类器——此前版本的 PyPI 页面完全没有
+  仓库链接
+- `scripts/publish.sh` 用于发布：从 `~/.pypirc` 读取 token（uv 本身不读该
+  文件），拒绝占位版本号，只上传当前版本的产物，并在上传前要求确认
+
+### 文档
+
+- 各指南已与 0.2.0 的行为对齐：重试策略只覆盖幂等读路径、两个客户端的
+  故障转移规则，以及统一的写操作返回值
+
 ## v0.2.0 (2026-11)
 
+### 同步 / 异步一致性
+
 同步与异步客户端在行为差异上完成对齐：
 
 - **端点选择**：异步客户端现在与同步客户端一样应用负载均衡策略，并在