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

python_etcd3_async-0.1.6/.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.1.6}/.gitignore

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

python_etcd3_async-0.1.6/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.1.6}/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
 

python_etcd3_async-0.1.6/PHASE2_PLAN.md

@@ -0,0 +1,164 @@
+# python-etcd3-async 二期开发计划
+
+> 基线：一期完成后（commit `bac8307`），373 用例双模式全绿（无 etcd 285 passed/88 skipped；
+> localhost:12379 全部通过），覆盖率 TOTAL 55%，无任何 CI 资产。
+> 目标顺序执行，每个里程碑独立可验证、可提交。
+
+---
+
+## M1 — async 客户端自动认证闭环（P0，库核心）
+
+**问题**：`async_client(user=, password=)` 存了凭据但从不认证——`_init_auth()`
+(etcd3/async_multi_client.py:163) 是死代码；etcd 重启后 token 失效也不会重新认证。
+一期 `tests/conftest.py` 的 `etcd_auth` fixture 靠显式调用 workaround。
+
+**任务**：
+1. lazy 认证：`_get_channel()` 成功后（或统一在进入操作 handler 前）若
+   `_user and _password and not _auth_done` 则 `await _init_auth()`；保持现有双检锁幂等
+2. 重连重认证：endpoint channel 重建路径（`async_endpoint.py` 健康检查失败重建、
+   `async_multi_client` 的 NoServerAvailableError 重建处）将 `_auth_done` 置 False，
+   下次操作自动重新 Authenticate
+3. 移除 conftest `etcd_auth` 中的显式 `_init_auth()` workaround 与 TODO 注释
+4. 集成测试锁定行为：
+   - `tests/test_auth_integration.py` 新增：带凭据的 `async_client` 对 auth-enforced
+     实例直接读写成功（不再手工触发认证）
+   - 与 M3 的重启用例联动验证 token 失效后自动恢复
+
+**验收**：`up-auth` 环境下 `ETCD_AUTH_*` 三元组齐备 → 全套通过；conftest 无 TODO；
+无 etcd 与主实例模式回归不变。
+
+**风险**：触碰连接/重连主线。缓解：先完成 M3-6（重启自动化）铺底，再改 M1；
+若顺序被阻塞，M1 先只做 lazy 认证（第 1、3 步），重认证（第 2 步）拆后续提交。
+
+---
+
+## M2 — sync 客户端 auth 对等修复（P0，库核心）
+
+**问题**：`multi_client.py:155-176` 构造时同步 Authenticate，且设置
+`call_credentials`——一期已证明 grpc 拒绝在明文通道使用 call credentials
+（commit `42db025` 修了 async 侧），sync 侧同样路径目前**零测试**，明文 + auth
+实例下预期会失败。另外 `Exception("if using authentication credentials ...")`
+应换成 `etcd3.exceptions` 的专用异常而不是裸 Exception（顺带小改，单独提交）。
+
+**任务**：
+1. metadata-only 对齐：sync `_authenticate` 分支删除 `call_credentials` 赋值，
+   token 仅走 `self.metadata`（检查所有 stub 调用点均传 `metadata=self.metadata`，
+   缺漏处补齐）
+2. conftest 新增 `etcd_auth_sync` fixture（auth 三元组 → 同步 `client(...)` 带
+   user/password，否则回退主实例）
+3. `tests/test_auth_integration.py` 补 sync 版用例（与 async 同构：user/role/权限
+   生命周期 + auth-enforced 实例上的普通读写）
+4. 裸 `Exception` → `ValueError`/自定义异常（保持向后兼容看用法决定，先 grep tests/examples）
+
+**验收**：`up-auth` + sync fixture 用例双路（fallback/enforced）通过；
+`test_client.py`、`test_auth.py` 单元回归不变。
+
+---
+
+## M3 — 测试深化（P1）
+
+**任务**：
+1. **id(etcd) 迁移收尾**：Group A 剩余 33 处 `id(etcd)` 型 key 改 `key_prefix`
+   （`f"x_{id(etcd)}"` → `f"{key_prefix}x"` + 签名加参），机械替换后全量回归
+2. **cluster/maintenance 集成覆盖**（当前为 0）：
+   - `tests/test_cluster_integration.py`：member_list 基线断言（单节点）、
+     member_add/remove 往返（容器内可寻址的 peer URL，注意 podman 网络限制，
+     必要时标记 `@pytest.mark.unstable`）
+   - `tests/test_maintenance_integration.py`：status/endpoint Health 对主客户端、
+     alarm 列表只读；defrag 在单节点容器上跑通即可
+3. **watch 语义扩展**（并入现有 `test_async_client_integration.py` 或新文件）：
+   多 watcher 并行、prev_kv、start_revision 指向已压缩 revision →
+   `RevisionCompactedError`（配合 compact 操作制造压缩点）、progress notify
+4. **lease TTL 到期**：lease(2) + put，轮询 5s 内 key 消失
+5. **etcd 重启自动化**：`TestRefreshLeaseIntegration` 的"需手动重启"改为自动
+   `podman restart etcd-test`；新 marker `@pytest.mark.restart`，默认 skip，
+   `ETCD_TEST_RESTART=1` 时启用；重启用例必须自恢复（重认证后写读成功，依赖 M1-2）
+6. `scripts/etcd-test.sh` 增加 `restart` 子命令
+
+**验收**：全量跑后 etcd 残留 key 仍为 0；无 env 模式下全部新用例正确 skip；
+覆盖率 `etcd3/`（排除 etcdrpc）较基线提升 ≥8pp。
+
+---
+
+## M4 — TLS/secure 通道测试（P0-3）
+
+**任务**：
+1. `scripts/etcd-test.sh gen-certs`：openssl 自签 CA + server cert（SAN 含
+   localhost/127.0.0.1），输出到 `.etcd-tls/`（加入 .gitignore）
+2. `up-tls`：第三实例 `etcd-test-tls` 端口 24379，`--cert-file/--key-file/--trusted-ca-file`
+   + `--auth`（认证叠加 TLS，call credentials 合法路径）
+3. conftest 增加 `ETCD_TLS_*` 环境变量组与 `etcd_tls` fixture（secure + token
+   在 TLS 通道可继续用 call credentials，作为 M2 删除该路径的对照组）
+4. `tests/test_tls_integration.py`：证书连接读写、错误 CA 报
+   `ConnectionFailedError`、auth-over-TLS、（可选）client cert 认证
+5. 无 `ETCD_TLS_ENDPOINT` 时整套 auto-skip（纳入现有 gating：fixture 名集合加
+   `etcd_tls`）
+
+**验收**：`up-tls` 下 TLS 套件通过；未配置时 skip；`down` 清理全部三个容器与证书目录。
+
+---
+
+## M5 — CI 流水线（P2）
+
+**前置调查**：cnb.cool 的流水线配置格式与 podman/service 容器支持（文档 + 一次
+空跑验证）；若不支持容器，退化为纯 lint+unit 流水线，integration 留本地。
+
+**任务**（以 `.cnb.yml` 或平台等价物为例）：
+1. `lint`：`ruff check etcd3/ etcdrpc/ tests/` + `ruff format --check`（秒级，必跑）
+2. `unit`：`uv run pytest -m unit`（无 etcd）
+3. `integration`：起 etcd 服务（镜像同 `etcd-test.sh` 钉扎版本）→
+   `ETCD_ENDPOINT=... uv run pytest -m integration`
+4. `auth`（可选 allow-failure 起步）：双实例 + `ETCD_AUTH_*` 跑 auth 文件
+5. 覆盖率产物：`--cov=etcd3` 输出到报告，**拆分** etcd3 与 etcdrpc 两个数字，
+   etcd3 基线首次记录进 CI 注释（阶段目标 70%，只防回退不硬卡）
+
+**验收**：push 一个探针分支验证三条流水线端到端。
+
+---
+
+## M6 — 工程杂务（P2）
+
+1. 文档纠错：AGENTS.md / docs/en / docs/zh 的 `uv sync --extra dev`、
+   `uv sync --dev` 改为 `uv sync`（dev 是 `[dependency-groups]`，extras 不存在）
+2. pylint 二选一：补最小 `.pylintrc`（对齐 ruff 规则子集、禁噪音项）并从 CI lint
+   步骤调用；或直接删掉文档中的 pylint 命令——**建议后者**，ruff 已覆盖
+3. 版本单源化：`pyproject.toml` `dynamic = ["version"]` + hatch 读
+   `etcd3/__init__.py.__version__`（或反向），消灭 0.1.5 时手工三处同步；
+   附 `scripts/bump-version.sh` 或至少 AGENTS.md 记录唯一真相位置
+4. 发布检查表进入 docs/dev（build wheel → 装 → `import etcd3` 冒烟 → tag）
+
+---
+
+## 里程碑顺序与提交切分
+
+```
+M3-5/M3-6（重启自动化，铺底）
+  → M1（async 自动认证，含删 workaround）
+  → M2（sync 对等修复）
+  → M3-1..4（迁移与补盲）
+  → M4（TLS）
+  → M5（CI 固化）
+  → M6（杂务，随时可并行插队）
+```
+
+每个任务节点 1 个提交，沿用一期 style：`fix:` / `test:` / `chore(...)` / `docs:`。
+
+## 全局验证协议（每个提交都要过）
+
+```bash
+env -u ETCD_ENDPOINT -u ETCD_HOST -u ETCD_PORT uv run pytest      # 0 failed，集成 skip
+./scripts/etcd-test.sh up && ETCD_ENDPOINT=localhost:12379 uv run pytest   # 全绿
+./scripts/etcd-test.sh up-auth && ETCD_ENDPOINT=... ETCD_AUTH_*=... uv run pytest -m integration
+uv run ruff check etcd3/ etcdrpc/ tests/ && uv run ruff format --check etcd3/ etcdrpc/ tests/
+podman exec etcd-test etcdctl get "" --prefix --keys-only | grep -c 'pytest-'   # 恒为 0
+```
+
+## 风险登记
+
+| 风险 | 缓解 |
+|---|---|
+| M1 改重连主线引入回归 | 先落 M3-5 自动重启测试；M1 拆两个提交（lazy / re-auth） |
+| member_add 受 podman 单网络拓扑限制 | 断言降级为"add 成功 + list 可见"，remove 允许失败标记 unstable |
+| cnb CI 无容器服务 | M5 降级为 lint+unit，integration 保持本地脚本 |
+| sync 删除 call_credentials 影响 secure 用户 | M4 的 TLS 对照用例证明 token-in-metadata 在 TLS 通道同样有效，否则保留 secure 分支条件赋值 |
+| 覆盖率目标拉扯测试质量 | 只防回退不追数字，新断言必须真调 etcd API |

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

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