1=====
2kazoo
3=====
4
5Kazoo is a Python library designed to make working with :term:`Zookeeper` a
6more hassle-free experience that is less prone to errors.
7
8Kazoo features:
9
10* A wide range of recipe implementations, like Lock, Election or Queue
11* Data and Children Watchers
12* Simplified Zookeeper connection state tracking
13* Unified asynchronous API for use with greenlets or threads
14* Support for `gevent`_ >= 1.2
15* Support for `eventlet`_
16* Support for Zookeeper 3.3, 3.4, and 3.5 servers
17* Integrated testing helpers for Zookeeper clusters
18* Pure-Python based implementation of the wire protocol, avoiding all the
19  memory leaks, lacking features, and debugging madness of the C library
20
21Kazoo is heavily inspired by `Netflix Curator`_ simplifications and helpers.
22
23.. note::
24
25    You should be familiar with Zookeeper and have read the `Zookeeper
26    Programmers Guide`_ before using `kazoo`.
27
28Reference Docs
29==============
30
31.. toctree::
32   :maxdepth: 1
33
34   install
35   basic_usage
36   async_usage
37   implementation
38   testing
39   api
40   Changelog <changelog>
41   Contributing <contributing>
42
43Why
44===
45
46Using :term:`Zookeeper` in a safe manner can be difficult due to the variety of
47edge-cases in :term:`Zookeeper` and other bugs that have been present in the
48Python C binding. Due to how the C library utilizes a separate C thread for
49:term:`Zookeeper` communication some libraries like `gevent`_ (or `eventlet`_)
50also don't work properly by default.
51
52By utilizing a pure Python implementation, Kazoo handles all of these
53cases and provides a new asynchronous API which is consistent when
54using threads or `gevent`_ (or `eventlet`_) greenlets.
55
56Source Code
57===========
58
59All source code is available on `github under kazoo <https://github.com/python-
60zk/kazoo>`_.
61
62Bugs/Support
63============
64
65Bugs should be reported on the `kazoo github issue tracker
66<https://github.com/python-zk/kazoo/issues>`_.
67
68The developers of ``kazoo`` can frequently be found on the Freenode IRC
69network in the `\#zookeeper`_ channel.
70
71For general discussions and support questions, please use the
72`python-zk <https://groups.google.com/forum/#!forum/python-zk>`_ mailing list
73hosted on Google Groups.
74
75Indices and tables
76==================
77
78* :ref:`genindex`
79* :ref:`modindex`
80* :ref:`glossary`
81
82.. toctree::
83   :hidden:
84
85   glossary
86
87License
88=======
89
90``kazoo`` is offered under the Apache License 2.0.
91
92Authors
93=======
94
95``kazoo`` started under the `Nimbus Project`_ and through collaboration with
96the open-source community has been merged with code from `Mozilla`_ and the
97`Zope Corporation`_. It has since gathered an active community of over two
98dozen contributors from a variety of companies (twitter, mozilla, yahoo! and
99others).
100
101.. _Apache Zookeeper: http://zookeeper.apache.org/
102.. _Zookeeper Programmers Guide: http://zookeeper.apache.org/doc/trunk/zookeeperProgrammers.html
103.. _Zookeeper Recipes: http://zookeeper.apache.org/doc/current/recipes.html#sc_recoverableSharedLocks
104.. _Nimbus Project: http://www.nimbusproject.org/
105.. _Zope Corporation: http://zope.com/
106.. _Mozilla: http://www.mozilla.org/
107.. _Netflix Curator: https://github.com/Netflix/curator
108.. _gevent: http://gevent.org/
109.. _eventlet: http://eventlet.net/
110.. _\#zookeeper: irc://chat.freenode.net/zookeeper
111