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

{python_etcd3_async-0.1.6 → 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.1.6 → 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.1.6 → 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/`)
 
@@ -266,7 +271,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 +283,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.1}/PKG-INFO

@@ -1,11 +1,28 @@
 Metadata-Version: 2.5
 Name: python-etcd3-async
-Version: 0.1.6
+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.1.6 → 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.1.6 → 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.1.6 → 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.1/docs/en/guide/advanced_queries.md

@@ -0,0 +1,101 @@
+---
+title: Advanced Queries
+---
+
+# Advanced Queries
+
+## Range Options
+
+Range options are passed as keyword arguments to any range-based call
+(`get`, `get_prefix`, `get_range`, `get_all` and their `*_response` variants);
+they map to the fields of `RangeRequestConfig`.
+
+```python
+# Range options as keyword arguments
+resp = await client.get_prefix_response(
+    '/app/',
+    limit=100,           # Limit number of results
+    revision=5,          # Historical revision
+    count_only=True,     # Only return count
+    sort_order='ascend', # 'ascend' or 'descend'
+    sort_target='key',   # 'key' | 'version' | 'create' | 'mod'
+)
+print(f'{resp.count} keys under /app/')
+
+# Serializable read (hit the follower, lower latency)
+value, meta = await client.get('/mykey', serializable=True)
+
+# Keys only (no values transferred)
+async for value, meta in client.get_prefix('/app/', keys_only=True):
+    print(meta.key)
+```
+
+Other available options: `min_mod_revision`, `max_mod_revision`,
+`min_create_revision`, `max_create_revision`.
+
+## Prefix Query
+
+```python
+# Get all keys with prefix
+async for value, meta in client.get_prefix('/app/'):
+    print(f'{meta.key}: {value}')
+```
+
+## Range Query
+
+```python
+# Get keys in range [start, end)
+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:
+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)
+- [Configuration](configuration.md)

{python_etcd3_async-0.1.6 → 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.1.6 → python_etcd3_async-0.2.1}/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.1}/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.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.1.6 → 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.1.6 → python_etcd3_async-0.2.1}/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:
@@ -43,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.1.6 → python_etcd3_async-0.2.1}/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.1}/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 |