Python-etcd documentation — python-etcd 0.4.3 documentation (original) (raw)

A python client for Etcd https://github.com/coreos/etcd

Installation

Pre-requirements

Install etcd

From source

$ python setup.py install

Usage

Create a client object

import etcd

client = etcd.Client() # this will create a client against etcd server running on localhost on port 4001 client = etcd.Client(port=4002) client = etcd.Client(host='127.0.0.1', port=4003) client = etcd.Client(host='127.0.0.1', port=4003, allow_redirect=False) # wont let you run sensitive commands on non-leader machines, default is true client = etcd.Client( host='127.0.0.1', port=4003, allow_reconnect=True, protocol='https',)

Set a key

client.write('/nodes/n1', 1)

with ttl

client.write('/nodes/n2', 2, ttl=4) # sets the ttl to 4 seconds

create only

client.write('/nodes/n3', 'test', prevExist=False)

Compare and swap values atomically

client.write('/nodes/n3', 'test2', prevValue='test1') #this fails to write client.write('/nodes/n3', 'test2', prevIndex=10) #this fails to write

mkdir

client.write('/nodes/queue', None, dir=True)

Append a value to a queue dir

client.write('/nodes/queue', 'test', append=True) #will write i.e. /nodes/queue/11 client.write('/nodes/queue', 'test2', append=True) #will write i.e. /nodes/queue/12

You can also atomically update a result:

result = client.read('/foo') print(result.value) # bar result.value += u'bar' updated = client.update(result) # if any other client wrote '/foo' in the meantime this will fail print(updated.value) # barbar

Get a key

client.read('/nodes/n2').value #recursively read a directory r = client.read('/nodes', recursive=True, sorted=True) for child in r.children: print("%s: %s" % (child.key,child.value))

client.read('/nodes/n2', wait=True) #Waits for a change in value in the key before returning. client.read('/nodes/n2', wait=True, waitIndex=10)

raises etcd.EtcdKeyNotFound when key not found

try: client.read('/invalid/path') except etcd.EtcdKeyNotFound: # do something print "error"

Delete a key

client.delete('/nodes/n1') client.delete('/nodes', dir=True) #spits an error if dir is not empty client.delete('/nodes', recursive=True) #this works recursively

Locking module

Initialize the lock object:

NOTE: this does not acquire a lock yet

client = etcd.Client() lock = etcd.Lock(client, 'my_lock_name')

Use the lock object:

lock.acquire(blocking=True, # will block until the lock is acquired lock_ttl=None) # lock will live until we release it lock.is_acquired # True lock.acquire(lock_ttl=60) # renew a lock lock.release() # release an existing lock lock.is_acquired # False

The lock object may also be used as a context manager:

client = etcd.Client() with etcd.Lock(client, 'customer1') as my_lock: do_stuff() my_lock.is_acquired # True my_lock.acquire(lock_ttl=60) my_lock.is_acquired # False

Get machines in the cluster

Get leader of the cluster

Development setup

To create a buildout,

$ python bootstrap.py $ bin/buildout

to test you should have etcd available in your system path:

to generate documentation,

Release HOWTO

To make a release,

  1. Update release date/version in NEWS.txt and setup.py
  2. Run ‘python setup.py sdist’
  3. Test the generated source distribution in dist/
  4. Upload to PyPI: ‘python setup.py sdist register upload’
  5. Increase version in setup.py (for next release)

List of contributors at https://github.com/jplana/python-etcd/graphs/contributors