Skip to content
Browse files

Updates to the documentation.

API docs included.
Installatiion guide.
First steps with the public API. (Incomplete)
  • Loading branch information...
1 parent f32b535 commit 2132abf86786ba8778673a7098a43217477464d1 @davidmiller committed May 3, 2012
View
24 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
+=====
+
View
30 doc/source/conf.py
@@ -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 -----------------------------------------------------
@@ -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.
@@ -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".
@@ -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"
+ )
View
61 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.
View
57 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
View
56 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/
View
8 doc/source/modules/client.rst
@@ -0,0 +1,8 @@
+.. _zoop.client:
+
+zoop.client
+===========
+
+.. automodule:: zoop.client
+ :members:
+
View
7 doc/source/modules/enums.rst
@@ -0,0 +1,7 @@
+.. _zoop.enums:
+
+zoop.enums
+==========
+
+.. automodule:: zoop.enums
+ :members:
View
7 doc/source/modules/exceptions.rst
@@ -0,0 +1,7 @@
+.. _zoop.exceptions:
+
+zoop.exceptions
+===============
+
+.. automodule:: zoop.exceptions
+ :members:
View
8 doc/source/modules/lock.rst
@@ -0,0 +1,8 @@
+.. _zoop.lock:
+
+zoop.lock
+=========
+
+.. automodule:: zoop.lock
+ :members:
+ :inherited-members:
View
7 doc/source/modules/logutils.rst
@@ -0,0 +1,7 @@
+.. _zoop.logutils:
+
+zoop.logutils
+=============
+
+.. automodule:: zoop.logutils
+ :members:
View
7 doc/source/modules/queue.rst
@@ -0,0 +1,7 @@
+.. _zoop.queue:
+
+zoop.queue
+=========
+
+.. automodule:: zoop.queue
+ :members:
View
7 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.
Something went wrong with that request. Please try again.