Python-etcd3 Documentation

Transcript

python-etcd3 Documentation Release 0.7.0 Louis Taylor Oct 04, 2017 Contents 1 python-etcd3 3 2 Installation 2.1 Stable release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.2 From sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 5 5 3 API Usage 3.1 Putting values into etcd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 7 4 Contributing 4.1 Types of Contributions . . 4.2 Get Started! . . . . . . . . 4.3 Pull Request Guidelines . 4.4 Generating protobuf stubs 4.5 Cutting new releases . . . 5 Indices and tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 15 16 17 17 17 19 i ii python-etcd3 Documentation, Release 0.7.0 Contents: Contents 1 python-etcd3 Documentation, Release 0.7.0 2 Contents CHAPTER 1 python-etcd3 Python client for the etcd API v3, supported under python 2.7, 3.4 and 3.5. Warning: the API is mostly stable, but may change in the future If you’re interested in using this library, please get involved. • Free software: Apache Software License 2.0 • Documentation: https://python-etcd3.readthedocs.io. Basic usage: import etcd3 etcd = etcd3.client() etcd.get('foo') etcd.put('bar', 'doot') etcd.delete('bar') # locks lock = etcd.lock('thing') # do something lock.release() with etcd.lock('doot-machine') as lock: # do something # transactions etcd.transaction( compare=[ etcd.transactions.value('/doot/testing') == 'doot', etcd.transactions.version('/doot/testing') > 0, ], success=[ etcd.transactions.put('/doot/testing', 'success'), ], 3 python-etcd3 Documentation, Release 0.7.0 failure=[ etcd.transactions.put('/doot/testing', 'failure'), ] ) # watch key watch_count = 0 events_iterator, cancel = etcd.watch("/doot/watch") for event in events_iterator: print(event) watch_count += 1 if watch_count > 10: cancel() # watch prefix watch_count = 0 events_iterator, cancel = etcd.watch_prefix("/doot/watch/prefix/") for event in events_iterator: print(event) watch_count += 1 if watch_count > 10: cancel() # recieve watch events via callback function def watch_callback(event): print(event) watch_id = etcd.add_watch_callback("/anotherkey", watch_callback) # cancel watch etcd.cancel_watch(watch_id) 4 Chapter 1. python-etcd3 CHAPTER 2 Installation Stable release To install python-etcd3, run this command in your terminal: $ pip install etcd3 This is the preferred method to install python-etcd3, as it will always install the most recent stable release. If you don’t have pip installed, this Python installation guide can guide you through the process. From sources The sources for python-etcd3 can be downloaded from the Github repo. You can either clone the public repository: $ git clone git://github.com/kragniz/python-etcd3 Or download the tarball: $ curl -OL https://github.com/kragniz/python-etcd3/tarball/master Once you have a copy of the source, you can install it with: $ python setup.py install 5 python-etcd3 Documentation, Release 0.7.0 6 Chapter 2. Installation CHAPTER 3 API Usage To use python-etcd3 in a project: import etcd3 and create a client: etcd = etcd3.client() This defaults to localhost, but you can specify the host and port: etcd = etcd3.client(host='etcd-host-01', port=2379) Putting values into etcd Values can be stored with the put method: etcd.put('/key', 'dooot') You can check this has been stored correctly by testing with etcdctl: $ ETCDCTL_API=3 etcdctl get /key /key dooot API class etcd3.Etcd3Client(host=’localhost’, port=2379, ca_cert=None, cert_key=None, cert_cert=None, timeout=None, user=None, password=None) 7 python-etcd3 Documentation, Release 0.7.0 get(key) Get the value of a key from etcd. example usage: >>> import etcd3 >>> etcd = etcd3.client() >>> etcd.get('/thing/key') 'hello world' Parameters key – key in etcd to get Returns value of key and metadata Return type bytes, KVMetadata get_prefix(key_prefix, sort_order=None, sort_target=’key’) Get a range of keys with a prefix. Parameters key_prefix – first key in range Returns sequence of (value, metadata) tuples get_all(sort_order=None, sort_target=’key’) Get all keys currently stored in etcd. Returns sequence of (value, metadata) tuples put(key, value, lease=None) Save a value to etcd. Example usage: >>> import etcd3 >>> etcd = etcd3.client() >>> etcd.put('/thing/key', 'hello world') Parameters • key – key in etcd to set • value (bytes) – value to set key to • lease (either Lease, or int (ID of lease)) – Lease to associate with this key. replace(key, initial_value, new_value) Atomically replace the value of a key with a new value. This compares the current value of a key, then replaces it with a new value if it is equal to a specified value. This operation takes place in a transaction. Parameters • key – key in etcd to replace • initial_value (bytes) – old value to replace • new_value (bytes) – new value of the key Returns status of transaction, True if the replace was successful, False otherwise Return type bool 8 Chapter 3. API Usage python-etcd3 Documentation, Release 0.7.0 delete(key) Delete a single key in etcd. Parameters key – key in etcd to delete Returns True if the key has been deleted delete_prefix(prefix) Delete a range of keys with a prefix in etcd. status() Get the status of the responding member. add_watch_callback(*args, **kwargs) Watch a key or range of keys and call a callback on every event. If timeout was declared during the client initialization and the watch cannot be created during that time the method raises a WatchTimedOut exception. Parameters • key – key to watch • callback – callback function Returns watch_id. Later it could be used for cancelling watch. watch(key, **kwargs) Watch a key. Example usage: Parameters key – key to watch Returns tuple of events_iterator and cancel. Use events_iterator to get the events of key changes and cancel to cancel the watch request watch_prefix(key_prefix, **kwargs) Watches a range of keys with a prefix. watch_once(key, timeout=None, **kwargs) Watch a key and stops after the first event. If the timeout was specified and event didn’t arrived method will raise WatchTimedOut exception. Parameters • key – key to watch • timeout – (optional) timeout in seconds. Returns Event watch_prefix_once(key_prefix, timeout=None, **kwargs) Watches a range of keys with a prefix and stops after the first event. If the timeout was specified and event didn’t arrived method will raise WatchTimedOut exception. cancel_watch(watch_id) Stop watching a key or range of keys. Parameters watch_id – watch_id returned by add_watch_callback method transaction(compare, success=None, failure=None) Perform a transaction. Example usage: 3.1. Putting values into etcd 9 python-etcd3 Documentation, Release 0.7.0 etcd.transaction( compare=[ etcd.transactions.value('/doot/testing') == 'doot', etcd.transactions.version('/doot/testing') > 0, ], success=[ etcd.transactions.put('/doot/testing', 'success'), ], failure=[ etcd.transactions.put('/doot/testing', 'failure'), ] ) Parameters • compare – A list of comparisons to make • success – A list of operations to perform if all the comparisons are true • failure – A list of operations to perform if any of the comparisons are false Returns A tuple of (operation status, responses) lease(ttl, lease_id=None) Create a new lease. All keys attached to this lease will be expired and deleted if the lease expires. A lease can be sent keep alive messages to refresh the ttl. Parameters • ttl – Requested time to live • lease_id – Requested ID for the lease Returns new lease Return type Lease revoke_lease(lease_id) Revoke a lease. Parameters lease_id – ID of the lease to revoke. lock(name, ttl=60) Create a new lock. Parameters • name (string or bytes) – name of the lock • ttl (int) – length of time for the lock to live for in seconds. The lock will be released after this time elapses, unless refreshed Returns new lock Return type Lock add_member(urls) Add a member into the cluster. Returns new member Return type Member 10 Chapter 3. API Usage python-etcd3 Documentation, Release 0.7.0 remove_member(member_id) Remove an existing member from the cluster. Parameters member_id – ID of the member to remove update_member(member_id, peer_urls) Update the configuration of an existing member in the cluster. Parameters • member_id – ID of the member to update • peer_urls – new list of peer urls the member will use to communicate with the cluster members List of all members associated with the cluster. Type sequence of Member compact(revision, physical=False) Compact the event history in etcd up to a given revision. All superseded keys with a revision less than the compaction revision will be removed. Parameters • revision – revision for the compaction operation • physical – if set to True, the request will wait until the compaction is physically applied to the local database such that compacted entries are totally removed from the backend database defragment() Defragment a member’s backend database to recover storage space. hash() Return the hash of the local KV state. Returns kv state hash Return type int create_alarm(member_id=0) Create an alarm. If no member id is given, the alarm is activated for all the members of the cluster. Only the no space alarm can be raised. Parameters member_id – The cluster member id to create an alarm to. If 0, the alarm is created for all the members of the cluster. Returns list of Alarm list_alarms(member_id=0, alarm_type=’none’) List the activated alarms. Parameters • member_id – • alarm_type – The cluster member id to create an alarm to. If 0, the alarm is created for all the members of the cluster. Returns sequence of Alarm disarm_alarm(member_id=0) Cancel an alarm. 3.1. Putting values into etcd 11 python-etcd3 Documentation, Release 0.7.0 Parameters member_id – The cluster member id to cancel an alarm. If 0, the alarm is canceled for all the members of the cluster. Returns List of Alarm snapshot(file_obj) Take a snapshot of the database. Parameters file_obj – A file-like object to write the database contents in. class etcd3.Member(id, name, peer_urls, client_urls, etcd_client=None) A member of the etcd cluster. Variables • id – ID of the member • name – human-readable name of the member • peer_urls – list of URLs the member exposes to the cluster for communication • client_urls – list of URLs the member exposes to clients for communication remove() Remove this member from the cluster. update(peer_urls) Update the configuration of this member. Parameters peer_urls – new list of peer urls the member will use to communicate with the cluster active_alarms Get active alarms of the member. Returns Alarms class etcd3.Lease(lease_id, ttl, etcd_client=None) A lease. Variables • id – ID of the lease • ttl – time to live for this lease revoke() Revoke this lease. refresh() Refresh the time to live for this lease. class etcd3.Lock(name, ttl=60, etcd_client=None) A distributed lock. This can be used as a context manager, with the lock being acquired and released as you would expect: etcd = etcd3.client() # create a lock that expires after 20 seconds with etcd.lock('toot', ttl=20) as lock: # do something that requires the lock print(lock.is_acquired()) # refresh the timeout on the lease lock.refresh() 12 Chapter 3. API Usage python-etcd3 Documentation, Release 0.7.0 Parameters • name (string or bytes) – name of the lock • ttl (int) – length of time for the lock to live for in seconds. The lock will be released after this time elapses, unless refreshed acquire(timeout=10) Acquire the lock. Params timeout Maximum time to wait before returning. None means forever, any other value equal or greater than 0 is the number of seconds. Returns True if the lock has been acquired, False otherwise. release() Release the lock. refresh() Refresh the time to live on this lock. is_acquired() Check if this lock is currently acquired. 3.1. Putting values into etcd 13 python-etcd3 Documentation, Release 0.7.0 14 Chapter 3. API Usage CHAPTER 4 Contributing Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given. You can contribute in many ways: Types of Contributions Report Bugs Report bugs at https://github.com/kragniz/python-etcd3/issues. If you are reporting a bug, please include: • Your operating system name and version. • Any details about your local setup that might be helpful in troubleshooting. • Detailed steps to reproduce the bug. Fix Bugs Look through the GitHub issues for bugs. Anything tagged with “bug” and “help wanted” is open to whoever wants to implement it. Implement Features Look through the GitHub issues for features. Anything tagged with “enhancement” and “help wanted” is open to whoever wants to implement it. 15 python-etcd3 Documentation, Release 0.7.0 Write Documentation python-etcd3 could always use more documentation, whether as part of the official python-etcd3 docs, in docstrings, or even on the web in blog posts, articles, and such. Submit Feedback The best way to send feedback is to file an issue at https://github.com/kragniz/etcd3/issues. If you are proposing a feature: • Explain in detail how it would work. • Keep the scope as narrow as possible, to make it easier to implement. • Remember that this is a volunteer-driven project, and that contributions are welcome :) Get Started! Ready to contribute? Here’s how to set up etcd3 for local development. 1. Fork the etcd3 repo on GitHub. 2. Clone your fork locally: $ git clone [email protected]:your_name_here/etcd3.git 3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development: $ mkvirtualenv etcd3 $ cd etcd3/ $ python setup.py develop 4. Create a branch for local development: $ git checkout -b name-of-your-bugfix-or-feature Now you can make your changes locally. 5. When you’re done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox: $ flake8 etcd3 tests $ python setup.py test or py.test $ tox To get flake8 and tox, just pip install them into your virtualenv. 6. Commit your changes and push your branch to GitHub: $ git add . $ git commit -m "Your detailed description of your changes." $ git push origin name-of-your-bugfix-or-feature 7. Submit a pull request through the GitHub website. 16 Chapter 4. Contributing python-etcd3 Documentation, Release 0.7.0 Pull Request Guidelines Before you submit a pull request, check that it meets these guidelines: 1. The pull request should include tests. 2. If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst. 3. The pull request should work for Python 2.6, 2.7, 3.3, 3.4 and 3.5, and for PyPy. Check https://travis-ci.org/ kragniz/etcd3/pull_requests and make sure that the tests pass for all supported Python versions. Generating protobuf stubs If the upstream protobuf files changes, copy the stubs: $ cp etcd/etcdserver/etcdserverpb/*.proto python-etcd3/etcd3/proto/ Then: $ cd python-etcd3 $ tox -e genproto Cutting new releases The release process to PyPi is automated using travis deploys and bumpversion. 1. Check changes since the last release: $ git log $(git describe --tags --abbrev=0)..HEAD --oneline 2. Bump the version (respecting semver, one of major, minor or patch): $ bumpversion patch 3. Push to github: $ git push $ git push --tags 4. Wait for travis tests to run and deploy to PyPI 4.3. Pull Request Guidelines 17 python-etcd3 Documentation, Release 0.7.0 18 Chapter 4. Contributing CHAPTER 5 Indices and tables • genindex • modindex • search 19 python-etcd3 Documentation, Release 0.7.0 20 Chapter 5. Indices and tables Index A M acquire() (etcd3.Lock method), 13 active_alarms (etcd3.Member attribute), 12 add_member() (etcd3.Etcd3Client method), 10 add_watch_callback() (etcd3.Etcd3Client method), 9 Member (class in etcd3), 12 members (etcd3.Etcd3Client attribute), 11 C cancel_watch() (etcd3.Etcd3Client method), 9 compact() (etcd3.Etcd3Client method), 11 create_alarm() (etcd3.Etcd3Client method), 11 P put() (etcd3.Etcd3Client method), 8 R defragment() (etcd3.Etcd3Client method), 11 delete() (etcd3.Etcd3Client method), 8 delete_prefix() (etcd3.Etcd3Client method), 9 disarm_alarm() (etcd3.Etcd3Client method), 11 refresh() (etcd3.Lease method), 12 refresh() (etcd3.Lock method), 13 release() (etcd3.Lock method), 13 remove() (etcd3.Member method), 12 remove_member() (etcd3.Etcd3Client method), 10 replace() (etcd3.Etcd3Client method), 8 revoke() (etcd3.Lease method), 12 revoke_lease() (etcd3.Etcd3Client method), 10 E S Etcd3Client (class in etcd3), 7 snapshot() (etcd3.Etcd3Client method), 12 status() (etcd3.Etcd3Client method), 9 D G get() (etcd3.Etcd3Client method), 7 get_all() (etcd3.Etcd3Client method), 8 get_prefix() (etcd3.Etcd3Client method), 8 H T transaction() (etcd3.Etcd3Client method), 9 U hash() (etcd3.Etcd3Client method), 11 update() (etcd3.Member method), 12 update_member() (etcd3.Etcd3Client method), 11 I W is_acquired() (etcd3.Lock method), 13 watch() (etcd3.Etcd3Client method), 9 watch_once() (etcd3.Etcd3Client method), 9 watch_prefix() (etcd3.Etcd3Client method), 9 watch_prefix_once() (etcd3.Etcd3Client method), 9 L Lease (class in etcd3), 12 lease() (etcd3.Etcd3Client method), 10 list_alarms() (etcd3.Etcd3Client method), 11 Lock (class in etcd3), 12 lock() (etcd3.Etcd3Client method), 10 21