Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Browse files
Browse the repository at this point in the history
Updates to the documentation.
API docs included. Installatiion guide. First steps with the public API. (Incomplete)
- Loading branch information
1 parent
f32b535
commit 2132abf
Showing
12 changed files
with
259 additions
and
20 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,6 +1,28 @@ | ||
Zoop is a Python client library for the Apache Zookeeper project. | ||
Zoop - ZooKeeper for Python! | ||
============================ | ||
|
||
`Zookeeper`_ is a highly reliable distributed coordination service. | ||
|
||
*Zoop* gives you a Pythonic API for accessing ZooKeeper instances, as well as | ||
implementations of some common ZooKeeper patterns. This leaves you free to | ||
concentrate on whatever it was you were originally doing:: | ||
|
||
>>> zk = zoop.ZooKeeper('localhost:2181') | ||
>>> zk.connect() | ||
>>> q = zoop.Queue(zk, '/howdy') | ||
>>> def gotit(data): | ||
... print "Gotit got data:", data | ||
>>> q.watch(gotit) | ||
>>> q.put("frist!") | ||
Gotit got data: frist! | ||
|
||
|
||
.. _Zookeeper: http://zookeeper.apache.org/ | ||
|
||
.. image:: https://secure.travis-ci.org/davidmiller/zoop.png?branch=master | ||
:alt: Build Status | ||
:target: https://secure.travis-ci.org/davidmiller/zoop | ||
|
||
Usage | ||
===== | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,61 @@ | ||
.. _frist: | ||
|
||
=========== | ||
First Steps | ||
=========== | ||
|
||
So, you're all installed and ready to go... | ||
|
||
Making A Connection | ||
=================== | ||
|
||
The first thing you'll need is to create a client that's connected to your ZooKeeper instance:: | ||
|
||
>>> import zoop | ||
>>> zoop.divert_zoolog() | ||
>>> zk = zoop.ZooKeeper('localhost:2181') | ||
>>> zk.connect() | ||
>>> print zk | ||
<ZooKeeper Client for localhost:2181> | ||
|
||
1. Most things you'll need to do are accessible from the main zoop namespace. | ||
2. By default libzookeeper prints a *lot* of DEBUG trace to stderr. This is quite unpleasant, so let's stop that. | ||
3. The single argument here is the host:port of the ZooKeeper instance you're connecting to. | ||
4. We have to create the connection explicitly. | ||
|
||
CR(eate) U(pdate) D(estroy) | ||
=========================== | ||
|
||
Now that we have a connection, we can start to do something useful with it:: | ||
|
||
>>> zk.get_children('/') | ||
['zookeeper'] | ||
>>> zk.create('/frist') | ||
'/frist' | ||
>>> zk.create('/frist/hello', 'Hello Beautiful World') | ||
'/frist/hello' | ||
|
||
1. Keeping up the Filesystem metaphor, this is essentially *nix *ls*. | ||
2. Creating a Node requires an absolute path. | ||
3. The optional second argument is the Value of the Node. | ||
|
||
|
||
So - let's start accessing our creations:: | ||
|
||
>>> zk.get('/frist/hello') | ||
('Hello Beautiful World', {'pzxid': 737L, 'ctime': 1336029934025L, 'aversion': 0, 'mzxid': 737L, 'numChildren': 0, | ||
'ephemeralOwner': 0L, 'version': 0, 'dataLength': 21, 'mtime': 1336029934025L, 'cversion': 0, 'czxid': 737L}) | ||
>>> zk.set('/frist/hello', 'Hello Again') | ||
>>> zk.get('/frist/hello')[0] | ||
'Hello Again' | ||
|
||
1. The get() method returns a tuple of (Value dictionary-of-stats) | ||
2. We can update an existing Node | ||
|
||
And when we're done:: | ||
|
||
>>> zk.delete('/frist/hello') | ||
>>> zk.get_children('/') | ||
['zookeeper'] | ||
|
||
1. Deleting nodes uses the succinctly-named delete() method. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,22 +1,51 @@ | ||
.. Zoop documentation master file, created by | ||
sphinx-quickstart on Mon Apr 30 08:31:09 2012. | ||
You can adapt this file completely to your liking, but it should at least | ||
contain the root `toctree` directive. | ||
.. _zoop.lock: | ||
|
||
Welcome to Zoop's documentation! | ||
================================ | ||
Zoop - ZooKeeper for Python! | ||
============================ | ||
|
||
Contents: | ||
`Zookeeper`_ is a highly reliable distributed coordination service. | ||
|
||
.. toctree:: | ||
:maxdepth: 2 | ||
*Zoop* gives you a Pythonic API for accessing ZooKeeper instances, as well as | ||
implementations of some common ZooKeeper patterns. This leaves you free to | ||
concentrate on whatever it was you were originally doing:: | ||
|
||
>>> zk = zoop.ZooKeeper('localhost:2181') | ||
>>> zk.connect() | ||
>>> q = zk.Queue('/howdy') | ||
>>> q | ||
<ZooKeeper FIFO Queue at localhost:2181> | ||
>>> def gotit(data): | ||
... print "Gotit got data:", data | ||
>>> q.watch(gotit) | ||
>>> q.put("frist!") | ||
Gotit got data: frist! | ||
|
||
|
||
.. _Zookeeper: http://zookeeper.apache.org/ | ||
|
||
.. image:: https://secure.travis-ci.org/davidmiller/zoop.png?branch=master | ||
:alt: Build Status | ||
:target: https://secure.travis-ci.org/davidmiller/zoop | ||
|
||
Getting Started | ||
=============== | ||
|
||
Indices and tables | ||
================== | ||
:ref:`installation` | ||
|
||
* :ref:`genindex` | ||
* :ref:`modindex` | ||
* :ref:`search` | ||
:ref:`frist` | ||
|
||
API Docs | ||
======== | ||
|
||
|
||
.. toctree:: | ||
:maxdepth: 1 | ||
|
||
modules/client | ||
modules/enums | ||
modules/exceptions | ||
modules/lock | ||
modules/logutils | ||
modules/queue | ||
modules/watch | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,56 @@ | ||
.. _installation: | ||
|
||
============ | ||
Installation | ||
============ | ||
|
||
Let's get installed! | ||
|
||
Dependencies | ||
============ | ||
|
||
Zoop relies on the Python bindings to *libzookeeper* under the hood, so the | ||
first step is probably to get that installed. | ||
|
||
Via Your Package Manager | ||
------------------------ | ||
|
||
Many modern linux distributions will come with a package for the Python bindings | ||
to libzookeeper - for example, on Debian based distros one would simply:: | ||
|
||
$ apt-get install python-zookeeper | ||
|
||
Pip | ||
--- | ||
|
||
Alternatively, you can Pip install the package `zc-zookeeper-static`_ which is a self-contained | ||
statically built distribution with:: | ||
|
||
$ pip install zc-zookeeper-static | ||
|
||
.. _`zc-zookeeper-static`: http://pypi.python.org/pypi/zc-zookeeper-static | ||
|
||
|
||
Installing Zoop itself | ||
====================== | ||
|
||
The easiest wat to install zoop is via `pip`_:: | ||
|
||
$ pip install zoop | ||
|
||
.. _`pip`: http://www.pip-installer.org | ||
|
||
|
||
Use The Source | ||
-------------- | ||
|
||
You can also install zoop by getting yourself a copy of the `source`_ if you have git installed:: | ||
|
||
$ git clone git://github.com/davidmiller/zoop | ||
|
||
.. _`source`: https://github.com/davidmiller/zoop | ||
|
||
Installing ZooKeeper | ||
==================== | ||
|
||
How to install ZooKeeper is beyond the scope of this document, but please consult the excellent installation details at http://zookeeper.apache.org/ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,8 @@ | ||
.. _zoop.client: | ||
|
||
zoop.client | ||
=========== | ||
|
||
.. automodule:: zoop.client | ||
:members: | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
.. _zoop.enums: | ||
|
||
zoop.enums | ||
========== | ||
|
||
.. automodule:: zoop.enums | ||
:members: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
.. _zoop.exceptions: | ||
|
||
zoop.exceptions | ||
=============== | ||
|
||
.. automodule:: zoop.exceptions | ||
:members: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,8 @@ | ||
.. _zoop.lock: | ||
|
||
zoop.lock | ||
========= | ||
|
||
.. automodule:: zoop.lock | ||
:members: | ||
:inherited-members: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
.. _zoop.logutils: | ||
|
||
zoop.logutils | ||
============= | ||
|
||
.. automodule:: zoop.logutils | ||
:members: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
.. _zoop.queue: | ||
|
||
zoop.queue | ||
========= | ||
|
||
.. automodule:: zoop.queue | ||
:members: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
.. _zoop.watch: | ||
|
||
zoop.watch | ||
========= | ||
|
||
.. automodule:: zoop.watch | ||
:members: |