Skip to content

Commit

Permalink
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
davidmiller committed May 3, 2012
1 parent f32b535 commit 2132abf
Show file tree
Hide file tree
Showing 12 changed files with 259 additions and 20 deletions.
24 changes: 23 additions & 1 deletion README.rst
@@ -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
=====

30 changes: 25 additions & 5 deletions doc/source/conf.py
Expand Up @@ -10,13 +10,24 @@
#
# All configuration values have a default; values that are commented out
# serve to show the default.
# Version
import re

VERSION_FILE = "../../zoop/_version.py"
verstrline = open(VERSION_FILE, "rt").read()
VSRE = r'^__version__ = [\'"]([^\'"]*)[\'"]'
mo = re.search(VSRE, verstrline, re.M)
if mo:
VERSION = mo.group(1)
else:
raise RuntimeError("Unable to find version string in {0}".format(VERSION_FILE))

import sys, os

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#sys.path.insert(0, os.path.abspath('.'))
sys.path.insert(0, os.path.abspath('../../'))

# -- General configuration -----------------------------------------------------

Expand Down Expand Up @@ -48,9 +59,9 @@
# built documents.
#
# The short X.Y version.
version = '0.0.1'
version = VERSION
# The full version, including alpha/beta/rc tags.
release = '0.0.1'
release = VERSION

# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
Expand Down Expand Up @@ -91,15 +102,15 @@

# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'default'
html_theme = 'sincere-sphinx'

# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#html_theme_options = {}

# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = []
html_theme_path = ['../../../']

# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
Expand Down Expand Up @@ -244,3 +255,12 @@

# Example configuration for intersphinx: refer to the Python standard library.
intersphinx_mapping = {'http://docs.python.org/': None}


# Sincere-Sphinx-specific settings
html_context = dict(
language = "Python",
source = "https://github.com/davidmiller/zoop",
bugs = "https://github.com/davidmiller/zoop/issues",
license = "LGPL"
)
61 changes: 61 additions & 0 deletions doc/source/frist.rst
@@ -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.
57 changes: 43 additions & 14 deletions doc/source/index.rst
@@ -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

56 changes: 56 additions & 0 deletions doc/source/installation.rst
@@ -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/
8 changes: 8 additions & 0 deletions doc/source/modules/client.rst
@@ -0,0 +1,8 @@
.. _zoop.client:

zoop.client
===========

.. automodule:: zoop.client
:members:

7 changes: 7 additions & 0 deletions doc/source/modules/enums.rst
@@ -0,0 +1,7 @@
.. _zoop.enums:

zoop.enums
==========

.. automodule:: zoop.enums
:members:
7 changes: 7 additions & 0 deletions doc/source/modules/exceptions.rst
@@ -0,0 +1,7 @@
.. _zoop.exceptions:

zoop.exceptions
===============

.. automodule:: zoop.exceptions
:members:
8 changes: 8 additions & 0 deletions doc/source/modules/lock.rst
@@ -0,0 +1,8 @@
.. _zoop.lock:

zoop.lock
=========

.. automodule:: zoop.lock
:members:
:inherited-members:
7 changes: 7 additions & 0 deletions doc/source/modules/logutils.rst
@@ -0,0 +1,7 @@
.. _zoop.logutils:

zoop.logutils
=============

.. automodule:: zoop.logutils
:members:
7 changes: 7 additions & 0 deletions doc/source/modules/queue.rst
@@ -0,0 +1,7 @@
.. _zoop.queue:

zoop.queue
=========

.. automodule:: zoop.queue
:members:
7 changes: 7 additions & 0 deletions doc/source/modules/watch.rst
@@ -0,0 +1,7 @@
.. _zoop.watch:

zoop.watch
=========

.. automodule:: zoop.watch
:members:

0 comments on commit 2132abf

Please sign in to comment.