A python client for etcd
A python client for Etcd https://github.com/coreos/etcd
Official documentation: http://python-etcd.readthedocs.org/
This version of python-etcd will only work correctly with the etcd server version 2.0.x or later. If you are running an older version of etcd, please use python-etcd 0.3.3 or earlier.
This client is known to work with python 2.7 and with python 3.3 or above. It is not tested or expected to work in more outdated versions of python.
$ python setup.py install
The basic methods of the client have changed compared to previous versions, to reflect the new API structure; however a compatibility layer has been maintained so that you don’t necessarily need to rewrite all your existing code.
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', 4001), ('127.0.0.1', 4002), ('127.0.0.1', 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 # If you have defined a SRV record for _etcd._tcp.example.com pointing to the clients client = etcd.Client(srv_domain='example.com', protocol="https") # create a client against https://api.example.com:443/etcd client = etcd.Client(host='api.example.com', protocol='https', port=443, version_prefix='/etcd')
Write a key
client.write('/nodes/n1', 1) # with ttl client.write('/nodes/n2', 2, ttl=4) # sets the ttl to 4 seconds client.set('/nodes/n2', 1) # Equivalent, for compatibility reasons.
Read a key
client.read('/nodes/n2').value client.read('/nodes', recursive = True) #get all the values of a directory, recursively. client.get('/nodes/n2').value # raises etcd.EtcdKeyNotFound when key not found try: client.read('/invalid/path') except etcd.EtcdKeyNotFound: # do something print "error"
Delete a key
Atomic Compare and Swap
client.write('/nodes/n2', 2, prevValue = 4) # will set /nodes/n2 's value to 2 only if its previous value was 4 and client.write('/nodes/n2', 2, prevExist = False) # will set /nodes/n2 's value to 2 only if the key did not exist before client.write('/nodes/n2', 2, prevIndex = 30) # will set /nodes/n2 's value to 2 only if the key was last modified at index 30 client.test_and_set('/nodes/n2', 2, 4) #equivalent to client.write('/nodes/n2', 2, prevValue = 4)
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
Watch a key
client.read('/nodes/n1', wait = True) # will wait till the key is changed, and return once its changed client.read('/nodes/n1', wait = True, timeout=30) # will wait till the key is changed, and return once its changed, or exit with an exception after 30 seconds. client.read('/nodes/n1', wait = True, waitIndex = 10) # get all changes on this key starting from index 10 client.watch('/nodes/n1') #equivalent to client.read('/nodes/n1', wait = True) client.watch('/nodes/n1', index = 10)
Refreshing key TTL
(Since etcd 2.3.0) Keys in etcd can be refreshed without notifying current watchers.
This can be achieved by setting the refresh to true when updating a TTL.
You cannot update the value of a key when refreshing it.
client.write('/nodes/n1', 'value', ttl=30) # sets the ttl to 30 seconds client.refresh('/nodes/n1', ttl=600) # refresh ttl to 600 seconds, without notifying current watchers
# Initialize the lock object: # NOTE: this does not acquire a lock yet client = etcd.Client() # Or you can custom lock prefix, default is '/_locks/' if you are using HEAD client = etcd.Client(lock_prefix='/my_etcd_root/_locks') 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
Generate a sequential key in a directory
x = client.write("/dir/name", "value", append=True) print("generated key: " + x.key) print("stored value: " + x.value)
List contents of a directory
#stick a couple values in the directory client.write("/dir/name", "value1", append=True) client.write("/dir/name", "value2", append=True) directory = client.get("/dir/name") # loop through directory children for result in directory.children: print(result.key + ": " + result.value) # or just get the first child value print(directory.children.next().value)
To create a buildout,
$ python bootstrap.py $ bin/buildout
to test you should have etcd available in your system path:
to generate documentation,
$ cd docs $ make
To make a release
Update release date/version in NEWS.txt and setup.py
Run ‘python setup.py sdist’
Test the generated source distribution in dist/
Upload to PyPI: ‘python setup.py sdist register upload’
Release date: 3-Mar-2017
Remove dnspython2/3 requirement
Change property name setter in lock
Fixed acl tests
Added version/cluster_version properties to client
Fixes in lock when used as context manager
Fixed improper usage of urllib3 exceptions
Minor fixes for error classes
In lock return modifiedIndex to watch changes
In lock fix context manager exception handling
Improvments to the documentation
Remove _base_uri only after refresh from cluster
Avoid double update of _machines_cache
Release date: 10-Jan-2017
Fix some tests
Use sys,version_info tuple, instead of named tuple
Improve & fix documentation
Fix python3 specific problem when blocking on contented lock
Add refresh key method
Add custom lock prefix support
Release date: 14-Dec-2015
Fix check for parameters in case of connection error
Python 3.5 compatibility and general python3 cleanups
Added authentication and module for managing ACLs
Added srv record-based DNS discovery
Fixed (again) logging of cluster id changes
Fixed leader lookup
Properly retry request on exception
Client: clean up open connections when deleting
Release date: 8-Oct-2015
Fixed lock documentation
Fixed lock sequences due to etcd 2.2 change
Better exception management during response processing
Fixed logging of cluster ID changes
Fixed subtree results
Do not check cluster ID if etcd responses don’t contain the ID
Added a cause to EtcdConnectionFailed
Release date: 1-Aug-2015
Added client-side leader election
Added stats endpoints
Better exception handling
Check for cluster ID on each request
Added etcd.Client.members and fixed etcd.Client.leader
Removed locking and election etcd support
Allow the use of etcd proxies with reconnections
Implement pop: Remove key from etc and return the corresponding value.
Eternal watcher can be now recursive
Fix etcd.Client machines
Do not send parameters with None value to etcd
Support ttl=0 in write.
Moved pyOpenSSL into test requirements.
Always set certificate information so redirects from http to https work.
Release date: 12-Apr-2015
Forward leaves_only value in get_subtree() recursive calls
Fix README prevExists->prevExist
Added configurable version_prefix
Added support for recursive watch
Better error handling support (more detailed exceptions)
Fixed some unreliable tests
Release date: 4-Aug-2014
Fixed generated documentation version.
Release date: 4-Aug-2014
Added consisten read option
Fixed timeout parameter in read()
Added atomic delete parameter support
Fixed delete behaviour
Added update method that allows atomic updated on results
Fixed checks on write()
Added leaves generator to EtcdResult and get_subtree for recursive fetch
Added etcd_index to EtcdResult
Changed ethernal -> eternal
Updated urllib3 & pyOpenSSL libraries
Several performance fixes
Better parsing of etcd_index and raft_index
Removed duplicated tests
Added several integration and unit tests
Use etcd v0.3.0 in travis
Execute test using python setup.py test and nose
Release date: 18-Jan-2014
API v2 support
Python 3.3 compatibility
Release data: 30-Nov-2013
Added support for subdirectories in results.
Added support for reconnections, allowing death node tolerance.
Release date: 30-Sep-2013
Allow fetching of multiple keys (sub-nodes)
Release date: 18-Sep-2013
Release history Release notifications | RSS feed
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.