python-etcd3-async 0.1.0__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.0 → 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.0 → 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=192.168.31.15:12379 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
 
-# Run with verbose output
-ETCD_ENDPOINT=192.168.31.15:12379 uv run pytest -v
+# 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
+
+# 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,14 +90,22 @@ uv run python gen_protos.py
 ### Environment Variables
 | Variable | Description |
 |----------|-------------|
-| `ETCD3_LOG_LEVEL` | Set logging level (DEBUG, INFO, WARNING, ERROR) |
-| `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 |
+| `ETCD_OBS_PROMETHEUS_ENABLED` | Enable Prometheus metrics |
 
 ## Project Rules
 
 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
 
@@ -78,23 +113,26 @@ uv run python gen_protos.py
 
 ### Core Client Classes
 
-**Sync client (`etcd3/client.py`):**
-- `MultiEndpointEtcd3Client` - Base class with multiple endpoints and failover support
-- `Etcd3Client` - Single endpoint client, inherits from `MultiEndpointEtcd3Client`
-- `Endpoint` - Single etcd cluster endpoint with gRPC channel
+**Sync client modules:**
+- `etcd3/single_client.py` - `Etcd3Client` - Single endpoint client, inherits from `MultiEndpointEtcd3Client`
+- `etcd3/multi_client.py` - `MultiEndpointEtcd3Client` - Base class with multiple endpoints and failover support, `Endpoint` - Single etcd cluster endpoint with gRPC channel
+- `etcd3/client.py` - Compatibility shim (re-exports from the above modules)
 
-**Async client (`etcd3/async_client.py`):**
-- `AsyncMultiEndpointEtcd3Client` - Main async client with failover support
-- `AsyncEtcd3Client` - Alias for backward compatibility
-- `async_client()` - Factory function
+**Async client modules:**
+- `etcd3/async_single_client.py` - `AsyncEtcd3Client` - Single endpoint async client
+- `etcd3/async_multi_client.py` - `AsyncMultiEndpointEtcd3Client` - Main async client with failover support, `AsyncEndpoint` - Single etcd cluster endpoint with async gRPC channel
+- `etcd3/async_client.py` - Compatibility shim (re-exports from the above modules)
 
 ### Configuration Classes
 
-**`RangeRequestConfig`** - Dataclass for range query options (limit, revision, sort_order, etc.)
-
-**`ClientConfig`** / **`AsyncClientConfig`** - Client connection configuration (host, port, timeout, TLS, auth)
+**`etcd3/config.py`:**
+- `RangeRequestConfig` - Dataclass for range query options (limit, revision, sort_order, etc.)
+- `ClientConfig` - Client connection configuration (host, port, timeout, TLS, auth)
+- `MultiEndpointConfig` - Multi-endpoint failover configuration
 
-**`AsyncMultiEndpointConfig`** - Multi-endpoint failover configuration
+**`etcd3/async_config.py`:**
+- `AsyncClientConfig` - Async client connection configuration
+- `AsyncMultiEndpointConfig` - Async multi-endpoint failover configuration
 
 ### Async Operation Extensions (`etcd3/async_client_extensions.py`)
 
@@ -117,12 +155,14 @@ Operation classes that wrap async functionality with error handling decorators:
 **`etcd3/endpoint.py`** - Base endpoint with shared logic:
 - `BaseEndpoint` - Common endpoint functionality (fail state, health check)
 
-**`etcd3/async_endpoint.py`** (async `AsyncEndpoint` class):
+**`etcd3/async_endpoint.py`** - Async `AsyncEndpoint` class:
 - Async gRPC channel with `is_healthy()` and `rebuild_channel()`
 
-**`etcd3/client.py`** (sync `Endpoint` class):
+**`etcd3/multi_client.py`** - Sync `Endpoint` class:
 - Sync gRPC channel with `is_healthy()` and `rebuild_channel()`
 
+**`etcd3/async_multi_client.py`** - Async `AsyncEndpoint` class (re-exported from async_endpoint)
+
 ### Shared Components
 
 **`etcd3/shared.py`:**
@@ -131,8 +171,12 @@ Operation classes that wrap async functionality with error handling decorators:
 - `Status`, `Alarm` - Status information classes
 - `EtcdTokenCallCredentials` - Authentication credentials
 - `RequestBuilder` - gRPC request builder utility
-- `_handle_errors` / `_async_handle_errors` - Error handling decorators
-- `_make_sync_handle_generator_errors_with_tracing` - Generator error decorator with `propagate_errors` support
+
+**`etcd3/errors.py`:**
+- `create_sync_error_handlers()` - Factory for sync error handling decorators
+- `create_async_error_handlers()` - Factory for async error handling decorators
+- `_make_sync_handle_errors_with_tracing` - Sync error handler with tracing
+- `_make_async_handle_errors_with_tracing` - Async error handler with tracing
 
 **`etcd3/trace.py`:** Request tracing and monitoring utilities
 
@@ -181,12 +225,45 @@ Compiled during build via `gen_protos.py` (hatchling build hook).
 | `service_discovery.py` | Async service discovery with watch callbacks |
 | `service_discovery_sync.py` | Sync version using polling |
 
+### Observability Utilities
+
+**Logging:**
+- `get_logger(name)` - Get a logger instance
+- `set_log_level(level)` - Set global log level
+
+**Tracing:**
+- `get_tracer()` - Get OpenTelemetry tracer
+- `create_span(name, attributes)` - Create a tracing span
+- `is_tracing_available()` - Check if tracing is enabled
+
+**Prometheus Metrics:**
+- `get_exporter()` - Get Prometheus exporter instance
+- `is_prometheus_available()` - Check if Prometheus is available
+
+**Configuration:**
+```python
+from etcd3 import ObservabilityConfig, configure_from_env, auto_init
+
+# Configure programmatically
+config = ObservabilityConfig(
+    tracing_enabled=True,
+    log_format="json",
+    log_level="INFO",
+    prometheus_enabled=True,
+)
+config.apply()
+
+# Or from environment variables
+configure_from_env()
+auto_init()  # Auto-initialize at import time
+```
+
 ## Key Design Patterns
 
-1. **Dual sync/async implementations:** Same API for sync (`client.py`) and async (`async_client.py`)
+1. **Dual sync/async implementations:** Same API for sync and async clients (client modules in `single_client.py` / `async_single_client.py`, with shims for backward compatibility)
 
 2. **Error handling decorators:**
-   - `_handle_errors` / `_async_handle_errors` - Standard error handling
+   - 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`