etcd3gw

2.6.0 verified Fri May 01 auth: no python

A Python client for the etcd v3 API via the etcd grpc-gateway. Version 2.6.0, requires Python >=3.10. Release cadence is irregular.

pip install etcd3gw

Common errors

error ModuleNotFoundError: No module named 'etcd3gw' ↓

cause Library not installed or installed in wrong environment.

fix

Run pip install etcd3gw in the correct Python environment.

error ImportError: cannot import name 'Etcd3Client' from 'etcd3gw' ↓

cause Using wrong import path for version 2.x.

fix

Use from etcd3gw.client import Etcd3Client.

error TypeError: cannot unpack non-iterable str object ↓

cause Calling `client.get(key)` and trying to unpack the result, but the library version returns a string (v1) instead of tuple (v2).

fix

Update to v2 and unpack: value, metadata = client.get(key). If stuck on v1, do not unpack.

error ConnectionError: HTTPConnectionPool ... Failed to establish a new connection ↓

cause etcd gateway not running or unreachable at given host:port.

fix

Verify etcd is running and the gateway endpoint (usually port 2379) is accessible. Check host/port arguments.

Warnings

breaking In version 2.0, the import path changed from `etcd3gw` to `etcd3gw.client`. Code using `from etcd3gw import Etcd3Client` will break. ↓

fix Change imports to `from etcd3gw.client import Etcd3Client`.

breaking The `get()` method now returns a tuple `(value, metadata)` instead of just `value`. In v1, `client.get(key)` returned the value as a string. In v2, it returns `(value, metadata)`. ↓

fix Unpack the result: `value, metadata = client.get(key)`.

deprecated Support for etcd v3.3 and earlier removed; requires etcd with v3 API and gateway endpoint. ↓

fix Ensure your etcd cluster exposes the grpc-gateway (port 2379 by default).

gotcha Client initialization does not validate connectivity; exceptions only occur on first actual operation. ↓

fix Call a simple operation like `client.get('/health')` to verify connection.

gotcha Timezone not handled in lease TTL; all times treated as UTC. ↓

fix Ensure your application works with UTC for lease TTL values.

Imports

Etcd3Client
wrong
```
from etcd3gw import Etcd3Client
```
correct
```
from etcd3gw.client import Etcd3Client
```
Etcd3Client is not exposed at package level in 2.x. Must import from submodule.
Etcd3Client
```
from etcd3gw import Etcd3Client
```
In version 1.x, direct import worked. Version 2.x changed location.

Quickstart

Create a client, write a key, read it back.

from etcd3gw.client import Etcd3Client

client = Etcd3Client(host='localhost', port=2379)
client.put('/key', 'value')
value, metadata = client.get('/key')
print(value)