etc

etc is an etcd Python client library. It provides all etcd options as snake_case. So there’s no camelCase confusion. It also provides several useful sugar functions such as etc.keep_node():

import etc

etcd = etc.etcd('http://127.0.0.1:4001')

try:
    etcd.set('/etc', u'what!', prev_value=u'what?', ttl=42)
except etc.TestFailed:
    pass
if isinstance(etcd.wait('/etc'), etc.Expired):
    print 'Expired'

Installation

etc is not available in PyPI yet. You should install via GitHub:

$ pip install https://github.com/sublee/etc/archive/master.zip

Usage

First of all, create a client object with your etcd URL:

import etc
etcd = etc.etcd('http://127.0.0.1:4001')

All etcd methods are in the client. etc.Client.get(), etc.Client.set(), and etc.Client.delete() are basic methods for most cases:

>>> etcd.set('/hello', u'Hello, world')
<etc.Set <etc.Value /hello='Hello, world' ...> ...>
>>> etcd.get('/hello')
<etc.Got <etc.Value /hello='Hello, world' ...> ...>
>>> etcd.delete('/hello')
<etc.Deleted ... prev_node=<etc.Value /hello='Hello, world' ...> ...>
>>> etcd.get('/hello')
Traceback (most recent call last):
  ...
etc.errors.KeyNotFound: [100] Key not found (/hello)

All etcd result types are mapped with subclasses of etc.EtcdResult; etc.Got, etc.Set, etc.Deleted, etc.Created, etc.Updated, etc.Expired, etc.ComparedThenSwapped, etc.ComparedThenDeleted. A result contains a node which is an instance of etc.Node. There’re 2 subclasses; etc.Value and etc.Directory. You will check whether a node is a directory or not by isinstance():

isinstance(etcd.get('/etc').node, etc.Value)

A directory node can be defined by dir parameter:

>>> etcd.set('/container', dir=True)
<etc.Set <etc.Directory /container[0] ...> ...>

API

etc.etcd(url='http://127.0.0.1:4001', mock=False, **kwargs)

Creates an etcd client.

class etc.Client(adapter)

An etcd client. It wraps an etc.adapter.Adapter and exposes humane public methods.

get(key, recursive=False, sorted=False, quorum=False, timeout=None)

Gets a value of a node.

>>> etcd.get('/hello')
<etc.Got <etc.Value /hello='Hello, world' ...> ...>
>>> etcd.get('/container', recursive=True)
<etc.Got <etc.Directory /container[2] ...> ...>
Parameters:
  • key – the key of the node to get.
  • recursive – include sub nodes recursively.
  • sorted – sort sub nodes by their keys.
  • quorum – ensure all quorums are ready to make result.
  • timeout – timeout in seconds.
wait(key, index=0, recursive=False, sorted=False, quorum=False, timeout=None)

Waits until a node changes.

Parameters:
  • key – the key of the node where it waits changes from.
  • index – wait a modification after this index.
  • recursive – wait until sub nodes change also.
  • sorted – sort sub nodes by their keys.
  • quorum – ensure all quorums are ready to make result.
  • timeout – timeout in seconds.
set(key, value=None, dir=False, ttl=None, prev_value=None, prev_index=None, timeout=None)

Sets a value to a node.

Parameters:
  • key – the key of the node to be created or updated.
  • value (unicode) – the node value. This parameter and dir parameter are exclusive of each other.
  • dir – make the node to be a directory. This parameter and value parameter are exclusive of each other.
  • ttl – tile to the node lives in seconds.
  • prev_value – check the current node value is equivalent with this value.
  • prev_index – check the current node’s modified index is equivalent with this index.
  • timeout – timeout in seconds.
create(key, value=None, dir=False, ttl=None, timeout=None)

Creates a new key.

Parameters:
  • key – the key of the node to be created.
  • value (unicode) – the node value. This parameter and dir parameter are exclusive of each other.
  • dir – make the node to be a directory. This parameter and value parameter are exclusive of each other.
  • ttl – tile to the node lives in seconds.
  • timeout – timeout in seconds.
update(key, value=None, dir=False, ttl=None, prev_value=None, prev_index=None, timeout=None)

Updates an existing key.

Parameters:
  • key – the key of the node to be updated.
  • value (unicode) – the node value. This parameter and dir parameter are exclusive of each other.
  • dir – make the node to be a directory. This parameter and value parameter are exclusive of each other.
  • ttl – tile to the node lives in seconds.
  • prev_value – check the current node value is equivalent with this value.
  • prev_index – check the current node’s modified index is equivalent with this index.
  • timeout – timeout in seconds.
append(key, value=None, dir=False, ttl=None, timeout=None)

Creates a new automatically increasing key in the given directory key.

Parameters:
  • key – the directory node key which will contain the new node.
  • value (unicode) – the node value. This parameter and dir parameter are exclusive of each other.
  • dir – make the node to be a directory. This parameter and value parameter are exclusive of each other.
  • ttl – tile to the node lives in seconds.
  • timeout – timeout in seconds.
delete(key, dir=False, recursive=False, prev_value=None, prev_index=None, timeout=None)

Deletes a node.

Parameters:
  • key – the node key to be deleted.
  • dir – whether the node is directory or not.
  • recursive – delete sub nodes recursively.
  • prev_value – check the current node value is equivalent with this value.
  • prev_index – check the current node’s modified index is equivalent with this index.
  • timeout – timeout in seconds.

etcd Results

class etc.Node(key, modified_index=None, created_index=None, ttl=None, expiration=None)
class etc.Value(key, value, *args, **kwargs)

An etcd value Node.

class etc.Directory(key, nodes=(), *args, **kwargs)

An etcd directory Node.

class etc.EtcdResult(node, prev_node=None, etcd_index=None, raft_index=None, raft_term=None)

A successful etcd result.

Don’t use this class directly. There’re specific subclasses to be used instead.

Subclasses:Got, Set, Deleted, Created, Updated, Expired, ComparedThenSwapped, ComparedThenDeleted.
class etc.EtcdError(message=None, cause=None, index=None)

A failed etcd result.

Subclasses:KeyNotFound, TestFailed, NotFile, NoMorePeer, NotDir, NodeExist, KeyIsPreserved, RootROnly, DirNotEmpty, ExistingPeerAddr, Unauthorized, ValueRequired, PrevValueRequired, TTLNaN, IndexNaN, ValueOrTTLRequired, TimeoutNaN, NameRequired, IndexOrValueRequired, IndexValueMutex, InvalidField, InvalidForm, RaftInternal, LeaderElect, WatcherCleared, EventIndexCleared, StandbyInternal, InvalidActiveSize, InvalidRemoveDelay.

Licensing and Author

This project is licensed under the BSD license. See LICENSE for the details.

I’m Heungsub Lee, a game server architect. Any regarding questions or patches are welcomed.