python-etcd-azion 0.3.4

python-etcd 文档
=========================

Etcd的Python客户端 https://github.com/coreos/etcd

官方文档: http://python-etcd.readthedocs.org/

.. image:: https://travis-ci.org/jplana/python-etcd.png?branch=master
:target: https://travis-ci.org/jplana/python-etcd

安装
------------

先决条件
~~~~~~~~~~~~~~~~

安装etcd（0.2.rc1或更高版本）。此版本的python-etcd只能与etcd API版本2正确工作。

此客户端已知与python 2.7和python 3.3或更高版本兼容。它未在更旧的python版本中测试，也不期望在更旧的版本中工作。

从源代码
~~~~~~~~~~~

.. code:: bash

$ python setup.py install

使用
-----

客户端的基本方法与先前版本相比已更改，以反映新的API结构；然而，已经维护了一个兼容层，因此您不一定需要重写所有现有的代码。

创建客户端对象
~~~~~~~~~~~~~~~~~~~~~~

.. code:: python

import etcd

client = etcd.Client() # 这将在本地主机端口4001上运行etcd服务器的客户端
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) # 不会在非领导者机器上运行敏感命令，默认为true
# 创建一个针对https://api.example.com:443/etcd的客户端
client = etcd.Client(host='api.example.com', protocol='https', port=443, version_prefix='/etcd')
写入一个键
~~~~~~~~~

.. code:: python

client.write('/nodes/n1', 1)
# 带有ttl
client.write('/nodes/n2', 2, ttl=4) # 将ttl设置为4秒
client.set('/nodes/n2', 1) # 相同，出于兼容性原因。

读取一个键
~~~~~~~~~

.. code:: python

client.read('/nodes/n2').value
client.read('/nodes', recursive = True) # 获取目录的所有值，递归。
client.get('/nodes/n2').value

删除一个键
~~~~~~~~~~~~

.. code:: python

client.delete('/nodes/n1')

原子比较和交换
~~~~~~~~~~~~

.. code:: python

client.write('/nodes/n2', 2, prevValue = 4) # 只有当/nodes/n2的前一个值是4时，才会将其值设置为2
client.write('/nodes/n2', 2, prevExist = False) # 只有当键之前不存在时，才会将其值设置为2
client.write('/nodes/n2', 2, prevIndex = 30) # 只有当键最后修改的索引是30时，才会将其值设置为2
client.test_and_set('/nodes/n2', 2, 4) # 等同于client.write('/nodes/n2', 2, prevValue = 4)

您还可以原子地更新一个结果

.. code:: python

result = client.read('/foo')
print(result.value) # bar
result.value += u'bar'
updated = client.update(result) # 如果在此期间其他客户端在'/foo'上进行了写入，这将失败
print(updated.value) # barbar

监视一个键
~~~~~~~~~~~

.. code:: python

client.read('/nodes/n1', wait = True) # 将等待键被更改，并在更改后返回
client.read('/nodes/n1', wait = True, timeout=30) # 将等待键被更改，并在更改后返回，或者在30秒后异常退出。
client.read('/nodes/n1', wait = True, waitIndex = 10) # 从索引10开始获取此键的所有更改
client.watch('/nodes/n1') # 等同于client.read('/nodes/n1', wait = True)
client.watch('/nodes/n1', index = 10)

锁定模块
~~~~~~~~~~~~~~

.. code:: python

# 初始化锁对象
# 注意：这不会立即获取锁
client = etcd.Client()
lock = client.get_lock('/customer1', ttl=60)

# 使用锁对象
lock.acquire(timeout=30) # 如果30秒内无法获取锁，则返回
lock.is_locked() # True
lock.renew(60)
lock.release()
lock.is_locked() # False

# 锁对象也可以用作上下文管理器
client = etcd.Client()
lock = client.get_lock('/customer1', ttl=60)
with lock as my_lock
do_stuff()
lock.is_locked() # True
lock.renew(60)
lock.is_locked() # False


领导选举模块
~~~~~~~~~~~~~~~~~~~~~~

.. code:: python

# 设置一个带有名称的领导者对象；如果没有提供名称，则使用本地主机名。
# 0或没有ttl意味着领导者对象是持久的。
client.election.set('/mysql', name='foo.example.com', ttl=120, timeout=30) # 返回etcd索引
client = etcd.Client()
# 获取名称

print(client.election.get('/mysql')) # 'foo.example.com'
# 删除它！
print(client.election.delete('/mysql', name='foo.example.com'))
获取集群中的机器

client.machines
~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code:: python

获取集群的领导者

client.leader
~~~~~~~~~~~~~~~~~~~~~~~~~

.. code:: python

开发设置

创建一个buildout
-----------------

在创建buildout时，

.. code:: bash

$ python bootstrap.py
$ bin/buildout

要测试，您应该将etcd配置在系统路径中

.. code:: bash

$ bin/test

要生成文档，

.. code:: bash

$ cd docs
$ make

发布指南
-------------

要发布一个版本，

1) 更新NEWS.txt和setup.py中的发布日期/版本
2) 运行'python setup.py sdist'
3) 测试在dist/中生成的源分布
4) 上传到PyPI: 'python setup.py sdist register upload'


新闻
====

0.3.4
-----

在更多异常中重试

0.3.3
-----
发布日期：2015-04-12*

在get_subtree()递归调用中传递leaves_only值
修复README中的prevExists->prevExist
添加可配置的version_prefix
添加递归监视支持
更好的错误处理支持（更详细的异常）
修复了一些不可靠的测试
修复Python 2.6中不正确的.format用法
将包名更改为python-etcd-azion


0.3.2
-----

发布日期：2014-08-04*

修复了生成的文档版本。


0.3.1
-----

发布日期：2014-08-04*

添加了一致读取选项
修复了read()中的超时参数
添加了对原子删除参数的支持
修复了删除行为
添加了允许在结果上原子更新的更新方法
修复了write()上的检查
向EtcdResult和get_subtree添加了leaves生成器，用于递归获取
向EtcdResult添加了etcd_index
将ethernal改为eternal
更新了urllib3和pyOpenSSL库
几个性能修复
更好地解析etcd_index和raft_index
删除了重复的测试
添加了几个集成和单元测试
在travis中使用etcd v0.3.0
使用`python setup.py test`和nose执行测试


0.3.0
-----

发布日期：2014-01-18*

API v2支持
Python 3.3兼容性


0.2.1
-----

发布日期：2013-11-30*

SSL支持
在结果中添加了对子目录的支持。
改进测试
添加了对重连的支持，允许容忍死亡节点。


0.2.0
-----

发布日期：2013-09-30*

允许获取多个密钥（子节点）


0.1
---

发布日期：2013-09-18*

初始发布