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

python_etcd3_async-0.2.0/.cnb.yml

@@ -0,0 +1,127 @@
+# CNB pipeline for python-etcd3-async (Phase-2 M5).
+#
+# Four pipelines run on every push (and reuse the same list for pull requests):
+#   lint        - ruff check + format gate (fast, always required)
+#   unit        - pytest -m unit, no etcd needed
+#   integration - spins an etcd container via dind, runs pytest -m integration
+#                 and reports etcd3 / etcdrpc coverage as separate numbers
+#   auth        - opt-in auth-forced etcd instance (allowFailure: best-effort)
+#
+# The etcd image is pinned to match scripts/etcd-test.sh. Integration-only
+# opt-in suites (member round-trip, restart, TLS) stay off here: they require
+# extra containers/env and remain local via scripts/etcd-test.sh.
+#
+# Coverage policy: report-only, no --cov-fail-under gate (we track regressions,
+# we do not chase the number). Baselines are recorded in the integration job.
+
+$:
+  push: &pipelines
+    - name: lint
+      docker:
+        image: python:3.12
+      env:
+        PIP_INDEX_URL: https://mirrors.cloud.tencent.com/pypi/simple
+        # Overrides the tsinghua default index from pyproject (mirrors.tuna
+        # rejects CNB build-node traffic); Tencent mirror is same-region.
+        UV_DEFAULT_INDEX: https://mirrors.cloud.tencent.com/pypi/simple
+      stages:
+        - name: setup
+          script:
+            - python -m pip install --quiet --no-cache-dir uv
+            - uv sync
+        - name: ruff check
+          script:
+            - uv run --no-sync ruff check etcd3/ etcdrpc/ tests/
+        - name: ruff format
+          script:
+            - uv run --no-sync ruff format --check etcd3/ etcdrpc/ tests/
+
+    - name: unit
+      docker:
+        image: python:3.12
+      env:
+        PIP_INDEX_URL: https://mirrors.cloud.tencent.com/pypi/simple
+        UV_DEFAULT_INDEX: https://mirrors.cloud.tencent.com/pypi/simple
+      stages:
+        - name: setup
+          script:
+            - python -m pip install --quiet --no-cache-dir uv
+            - uv sync
+        - name: pytest
+          script:
+            - uv run --no-sync pytest -m unit
+
+    - name: integration
+      services:
+        - docker
+      docker:
+        image: python:3.12
+      env:
+        ETCD_TEST_IMAGE: public.ecr.aws/eks-distro/etcd-io/etcd:v3.6.12-eks-1-37-latest
+        PIP_INDEX_URL: https://mirrors.cloud.tencent.com/pypi/simple
+        UV_DEFAULT_INDEX: https://mirrors.cloud.tencent.com/pypi/simple
+      stages:
+        - name: setup
+          script:
+            - python -m pip install --quiet --no-cache-dir uv
+            - uv sync
+        - name: start etcd
+          script:
+            - >-
+              docker run -d --rm --name etcd-ci -p 2379:2379 "$ETCD_TEST_IMAGE"
+              etcd --name ci
+              --listen-client-urls http://0.0.0.0:2379
+              --advertise-client-urls http://localhost:2379
+              --watch-progress-notify-interval=1s
+            - for i in $(seq 1 30); do docker exec etcd-ci etcdctl endpoint health >/dev/null 2>&1 && break; sleep 2; done
+            - docker exec etcd-ci etcdctl endpoint health
+        - name: pytest + coverage
+          script:
+            - ETCD_ENDPOINT=localhost:2379 uv run --no-sync pytest -m integration --cov=etcd3 --cov=etcdrpc
+        # Coverage floor is report-only; refresh these numbers when they move
+        # intentionally. The gate is a human reading this, not a hard fail.
+        # Baselines below are for THIS integration job only (unit tests run in
+        # the `unit` job and do not add to these figures).
+        #   etcd3:   56%  (floor; combined with unit job the local full-suite
+        #                  figure is higher — stage target is 70% full-suite)
+        #   etcdrpc: 36%  (generated protobuf code, tracked but not gated)
+        - name: coverage report
+          script:
+            - uv run --no-sync coverage report --include="etcd3/*" -m
+            - uv run --no-sync coverage report --include="etcdrpc/*" -m
+
+    - name: auth
+      allowFailure: true
+      services:
+        - docker
+      docker:
+        image: python:3.12
+      env:
+        ETCD_TEST_IMAGE: public.ecr.aws/eks-distro/etcd-io/etcd:v3.6.12-eks-1-37-latest
+        PIP_INDEX_URL: https://mirrors.cloud.tencent.com/pypi/simple
+        UV_DEFAULT_INDEX: https://mirrors.cloud.tencent.com/pypi/simple
+      stages:
+        - name: setup
+          script:
+            - python -m pip install --quiet --no-cache-dir uv
+            - uv sync
+        - name: start auth etcd
+          script:
+            - >-
+              docker run -d --rm --name etcd-auth -p 22379:2379 "$ETCD_TEST_IMAGE"
+              etcd --name auth
+              --listen-client-urls http://0.0.0.0:2379
+              --advertise-client-urls http://localhost:2379
+            - for i in $(seq 1 30); do docker exec etcd-auth etcdctl endpoint health >/dev/null 2>&1 && break; sleep 2; done
+            - docker exec etcd-auth etcdctl user add "root:etcd-test-root-pw"
+            - docker exec etcd-auth etcdctl user grant-role root root
+            - docker exec etcd-auth etcdctl auth enable
+        - name: pytest -m auth
+          script:
+            - >-
+              ETCD_ENDPOINT=localhost:22379
+              ETCD_AUTH_ENDPOINT=localhost:22379
+              ETCD_AUTH_USER=root
+              ETCD_AUTH_PASSWORD=etcd-test-root-pw
+              uv run --no-sync pytest -m auth
+  pull_request: *pipelines

{python_etcd3_async-0.1.5 → python_etcd3_async-0.2.0}/.gitignore

@@ -15,3 +15,4 @@ htmlcov/
 # Virtual environments
 .venv
 /site
+.etcd-tls/

python_etcd3_async-0.2.0/AGENTS.md

@@ -0,0 +1,240 @@
+# 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 (dev group included by default)
+uv pip install -e .        # Editable install
+```
+
+### Testing
+```bash
+# Unit tests only — no etcd needed; integration tests auto-skip when no endpoint is configured
+uv run pytest -m "not integration"
+
+# Full suite — requires a running etcd (integration tests FAIL if an endpoint
+# is configured but unreachable; that is intentional)
+./scripts/etcd-test.sh up                       # podman: etcd-test @ localhost:12379
+ETCD_ENDPOINT=localhost:12379 uv run pytest     # all 396 tests
+ETCD_ENDPOINT=localhost:12379 uv run pytest -m integration   # integration only
+ETCD_ENDPOINT=localhost:12379 uv run pytest --cov=etcd3 --cov=etcdrpc
+ETCD_ENDPOINT=localhost:12379 uv run pytest -v -k "test_name"  # Run tests matching pattern
+
+# Restart-automated tests (opt-in; restarts the etcd-test container mid-run)
+ETCD_ENDPOINT=localhost:12379 ETCD_TEST_RESTART=1 uv run pytest -m restart
+./scripts/etcd-test.sh restart [primary|auth]   # manual restart helper
+
+# Member add/remove round-trip (opt-in; mutates cluster membership via a learner)
+ETCD_ENDPOINT=localhost:12379 ETCD_TEST_MEMBER=1 uv run pytest tests/test_cluster_integration.py
+
+# Auth-enabled instance (optional; tests/test_auth_integration.py routes through it)
+./scripts/etcd-test.sh up-auth
+ETCD_ENDPOINT=localhost:12379 ETCD_AUTH_ENDPOINT=localhost:22379 \
+ETCD_AUTH_USER=root ETCD_AUTH_PASSWORD=etcd-test-root-pw uv run pytest tests/test_auth_integration.py
+
+# TLS+auth instance (optional; tests/test_tls_integration.py; certs auto-generated)
+./scripts/etcd-test.sh up-tls
+ETCD_TLS_ENDPOINT=localhost:24379 uv run pytest tests/test_tls_integration.py
+
+./scripts/etcd-test.sh down                     # remove all test containers + cert dir
+```
+- Integration tests write keys under a per-session random prefix cleaned up automatically
+- Shared fixtures/markers live in `tests/conftest.py` (`etcd`, `key_prefix`, `etcd_auth`, `etcd_tls`)
+
+### CI
+- Pipeline: `.cnb.yml` (CNB), runs on push / pull_request (any branch):
+  - `lint`: `ruff check` + `ruff format --check`
+  - `unit`: `pytest -m unit` (no etcd)
+  - `integration`: etcd container via dind (same pinned image as `etcd-test.sh`) → `pytest -m integration` + etcd3/etcdrpc coverage
+  - `auth`: auth-enforced etcd instance, `pytest -m auth` (allowFailure)
+- Member/restart/TLS suites stay local-only (opt-in env gates, see `scripts/etcd-test.sh`)
+- Coverage is report-only (no fail-under gate); baselines recorded in `.cnb.yml` comments
+
+### Linting
+```bash
+uv run ruff check etcd3/ etcdrpc/        # Check (etcdrpc/ is excluded as generated)
+uv run ruff format etcd3/ etcdrpc/       # Format
+```
+
+### Other
+```bash
+uv run python gen_protos.py  # Regenerate protobuf
+uv run mkdocs serve          # Serve docs
+```
+
+### Versioning
+- Single source of truth: `__version__` in `etcd3/__init__.py`
+- `pyproject.toml` uses `dynamic = ["version"]` via
+  `[tool.hatch.version] path = "etcd3/__init__.py"` — never add a static
+  `version` back; `uv.lock` refreshes automatically on the next `uv lock`
+- Release checklist: `docs/en/resources/releasing.md`
+
+## Code Style
+
+### Formatting
+- **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 (`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 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
+
+### Dual Client Design
+- **Sync**: `Etcd3Client` in `etcd3/single_client.py` (extends
+  `MultiEndpointEtcd3Client` in `etcd3/multi_client.py`, which also defines `Endpoint`)
+- **Async**: `AsyncEtcd3Client` in `etcd3/async_single_client.py` (extends
+  `AsyncMultiEndpointEtcd3Client` in `etcd3/async_multi_client.py`; `AsyncEndpoint`
+  lives in `etcd3/async_endpoint.py`)
+- `etcd3/client.py` / `etcd3/async_client.py` are compatibility shims re-exporting the above
+- Factories: `client()` (sync, single endpoint) and `async_client()` (async, single endpoint)
+
+### Extension Pattern (`etcd3/async_client_extensions.py`)
+- `AsyncKVOperations`, `AsyncLeaseOperations`, `AsyncLockOperations`
+- `AsyncClusterOperations`, `AsyncMaintenanceOperations`, `AsyncWatchOperations`
+
+### Load Balancing
+- `LoadBalancerStrategy` enum: `PRIORITY`, `ROUND_ROBIN`, `RANDOM`, `STICKY`
+
+### Package Structure
+```
+etcd3/
+  __init__.py           # Public exports (client, async_client, exceptions, etc.)
+  single_client.py      # Etcd3Client (sync single-endpoint)
+  multi_client.py       # MultiEndpointEtcd3Client + sync Endpoint
+  async_single_client.py  # AsyncEtcd3Client (async single-endpoint)
+  async_multi_client.py   # AsyncMultiEndpointEtcd3Client (main async client)
+  async_endpoint.py     # AsyncEndpoint (async gRPC channel handler)
+  client.py             # Compat shim (re-exports sync clients)
+  async_client.py       # Compat shim (re-exports async clients)
+  async_client_extensions.py  # Async operation mixins (KV/Lease/Lock/Cluster/Maintenance/Watch)
+  sync_kv_operations.py       # Sync KV operations mixin
+  sync_lock_operations.py     # Sync lock operations mixin
+  sync_cluster_operations.py  # Sync cluster operations mixin
+  sync_maintenance_operations.py  # Sync maintenance operations mixin
+  async_managers.py     # Async watch/cluster/maintenance managers
+  config.py             # ClientConfig, MultiEndpointConfig, RangeRequestConfig
+  async_config.py       # AsyncClientConfig, AsyncMultiEndpointConfig
+  endpoint.py           # BaseEndpoint (shared fail-state / health logic)
+  errors.py             # Error-handler decorator factories
+  exceptions.py         # Custom exceptions
+  auth.py               # AuthOperations / AsyncAuthOperations
+  leases.py             # Lease / AsyncLease objects
+  locks.py              # Lock / AsyncLock objects
+  watch.py              # Sync watch builder + iterator
+  async_watch.py        # Async watch builder + event iterator
+  events.py             # PutEvent / DeleteEvent classes
+  transactions.py       # Transaction compare/put/get builders
+  members.py            # Member class for cluster representation
+  shared.py             # Shared code between sync/async (Status, KVMetadata, ...)
+  utils.py              # Key encoding, prefixes, filter constants, LoadBalancerStrategy
+  trace.py / trace_attributes.py / monitor.py / async_monitor.py  # Tracing & monitoring
+  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
+tests/                  # Test files
+```
+
+## 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
+- Plain `uv run pytest` never fails for lack of etcd: integration tests
+  auto-skip unless an endpoint is configured (`ETCD_ENDPOINT` or `ETCD_HOST`/`ETCD_PORT`)
+- Configured endpoint unreachable => integration tests fail (intentional signal)
+- Markers: `-m unit` / `-m integration` / `-m auth`; shared fixtures in `tests/conftest.py`
+- Local test server: `./scripts/etcd-test.sh up` (podman, localhost:12379)
+- Integration keys live under a per-session random prefix, cleaned automatically
+- 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.5 → python_etcd3_async-0.2.0}/CLAUDE.md

@@ -10,12 +10,9 @@ python-etcd3-async is an async Python client library for the etcd v3 API using `
 
 ### Development Setup
 ```bash
-# Install dependencies
+# Install dependencies (includes the dev group)
 uv sync
 
-# Install dev dependencies
-uv sync --extra dev
-
 # Run Python commands
 uv run python <script.py>
 
@@ -25,22 +22,55 @@ uv pip install -e .
 
 ### Testing
 ```bash
-# Run all tests (requires ETCD_ENDPOINT environment variable)
-ETCD_ENDPOINT=127.0.0.1:2379 uv run pytest
+# Unit tests only — no etcd needed; integration tests auto-skip without an endpoint
+uv run pytest -m "not integration"
+
+# Start the local test etcd (podman, localhost:12379)
+./scripts/etcd-test.sh up
+
+# Run all tests against it
+ETCD_ENDPOINT=localhost:12379 uv run pytest
 
 # Run a single test file
-ETCD_ENDPOINT=192.168.31.15:12379 uv run pytest tests/test_async_client.py
+ETCD_ENDPOINT=localhost: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
+ETCD_ENDPOINT=localhost:12379 uv run pytest tests/test_locks.py::TestAsyncLock::test_async_lock_acquire_succeeds_after_wait -v
+
+# Integration tests only / unit tests only
+ETCD_ENDPOINT=localhost:12379 uv run pytest -m integration
+uv run pytest -m unit
+
+# Restart-automated tests (opt-in; restarts the etcd-test container mid-run)
+ETCD_ENDPOINT=localhost:12379 ETCD_TEST_RESTART=1 uv run pytest -m restart
+./scripts/etcd-test.sh restart [primary|auth]
+
+# Member add/remove round-trip (opt-in; mutates cluster membership via a learner)
+ETCD_ENDPOINT=localhost:12379 ETCD_TEST_MEMBER=1 uv run pytest tests/test_cluster_integration.py
 
 # Run with coverage
-ETCD_ENDPOINT=192.168.31.15:12379 uv run pytest --cov=etcd3 --cov=etcdrpc
+ETCD_ENDPOINT=localhost:12379 uv run pytest --cov=etcd3 --cov=etcdrpc
+
+# Auth-enabled instance (optional)
+./scripts/etcd-test.sh up-auth
+ETCD_ENDPOINT=localhost:12379 ETCD_AUTH_ENDPOINT=localhost:22379 \
+ETCD_AUTH_USER=root ETCD_AUTH_PASSWORD=etcd-test-root-pw uv run pytest tests/test_auth_integration.py
 
-# Run with verbose output
-ETCD_ENDPOINT=192.168.31.15:12379 uv run pytest -v
+# TLS+auth instance (optional; certs generated into .etcd-tls/)
+./scripts/etcd-test.sh up-tls
+ETCD_TLS_ENDPOINT=localhost:24379 uv run pytest tests/test_tls_integration.py
 ```
 
+### CI (`.cnb.yml`)
+Runs on push / pull_request (any branch):
+- `lint` — ruff check + format --check
+- `unit` — `pytest -m unit` (no etcd)
+- `integration` — etcd via dind (pinned image matches etcd-test.sh) → `pytest -m integration` + etcd3/etcdrpc coverage
+- `auth` — auth-enforced etcd, `pytest -m auth` (allowFailure)
+
+Member/restart/TLS suites stay local-only (opt-in env gates). Coverage is
+report-only (no fail-under gate); baselines are recorded in `.cnb.yml`.
+
 ### Linting & Formatting
 ```bash
 # Check with ruff
@@ -48,9 +78,6 @@ uv run ruff check etcd3/ etcdrpc/
 
 # Format with ruff
 uv run ruff format etcd3/ etcdrpc/
-
-# Run pylint
-pylint etcd3/ etcdrpc/
 ```
 
 ### Protobuf Generation
@@ -63,7 +90,12 @@ uv run python gen_protos.py
 ### Environment Variables
 | Variable | Description |
 |----------|-------------|
-| `ETCD_ENDPOINT` | etcd server address for testing (e.g., 192.168.31.15:12379) |
+| `ETCD_ENDPOINT` | etcd server address for testing (e.g., localhost:12379 via scripts/etcd-test.sh) |
+| `ETCD_AUTH_ENDPOINT` | optional auth-enabled etcd address (e.g., localhost:22379) |
+| `ETCD_AUTH_USER` / `ETCD_AUTH_PASSWORD` | credentials for the auth-enabled test instance |
+| `ETCD_TLS_ENDPOINT` | TLS+auth etcd address for testing (e.g., localhost:24379 via scripts/etcd-test.sh up-tls) |
+| `ETCD_TLS_CA` | CA cert path used to verify the TLS server (default: `.etcd-tls/ca.crt`) |
+| `ETCD_TLS_USER` / `ETCD_TLS_PASSWORD` | credentials for the TLS+auth test instance |
 | `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 |
@@ -73,7 +105,7 @@ uv run python gen_protos.py
 
 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
+3. Follow PEP8; use `ruff` for linting and formatting (etcdrpc/ is excluded as generated)
 4. Use `pytest` and `pytest-asyncio` for sync and async tests
 5. Use context7 MCP to query official documentation
 
@@ -234,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
@@ -242,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.5 → python_etcd3_async-0.2.0}/PKG-INFO

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

python_etcd3_async-0.2.0/docs/en/getting-started/installation.md

@@ -0,0 +1,73 @@
+---
+title: Installation
+---
+
+# Installation
+
+## Stable Release
+
+To install python-etcd3-async, run this command in your terminal:
+
+```bash
+uv pip install python-etcd3-async
+```
+
+This is the preferred method to install, as it will always install the most recent stable release.
+
+## From Sources
+
+The sources for python-etcd3-async can be downloaded from the [CNB repo](https://cnb.cool/owasd/python3-etcd-async).
+
+```bash
+git clone https://cnb.cool/owasd/python3-etcd-async.git
+cd python3-etcd-async
+uv pip install -e .
+```
+
+## Requirements
+
+- Python 3.12+
+- etcd v3 API server (v3.1+ recommended)
+
+## Virtual Environments with uv
+
+For an application project managed by [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv init myapp && cd myapp
+uv add python-etcd3-async
+```
+
+uv creates and syncs `.venv` automatically; run code with `uv run python ...`.
+With pip/venv instead:
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install python-etcd3-async
+```
+
+## Verify the Installation
+
+```bash
+python -c "import etcd3; print(etcd3.__version__)"
+```
+
+Then connect to a running etcd:
+
+```python
+import asyncio
+from etcd3 import async_client
+
+async def main():
+    client = await async_client(host='localhost', port=2379)
+    print(await client.status())
+    await client.close()
+
+asyncio.run(main())
+```
+
+## See Also
+
+- [API Usage](../guide/usage.md)
+- [Configuration](../guide/configuration.md)
+- [Sync Client](../guide/sync_client.md)

python_etcd3_async-0.2.0/docs/en/guide/advanced_queries.md

@@ -0,0 +1,78 @@
+---
+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}')
+```
+
+## 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)