kazoo.recipe.watchers

Higher level child and data watching API’s.

Maintainer:

Ben Bangert <ben@groovie.org>

Status:

Production

Note

DataWatch and ChildrenWatch may only handle a single function, attempts to associate a single instance with multiple functions will result in an exception being thrown.

Public API

class kazoo.recipe.watchers.DataWatch(client, path, func=None, *args, **kwargs)[source]

Watches a node for data updates and calls the specified function each time it changes

The function will also be called the very first time its registered to get the data.

Returning False from the registered function will disable future data change calls. If the client connection is closed (using the close command), the DataWatch will no longer get updates.

If the function supplied takes three arguments, then the third one will be a WatchedEvent. It will only be set if the change to the data occurs as a result of the server notifying the watch that there has been a change. Events like reconnection or the first call will not include an event.

If the node does not exist, then the function will be called with None for all values.

Tip

Because DataWatch can watch nodes that don’t exist, it can be used alternatively as a higher-level Exists watcher that survives reconnections and session loss.

Example with client:

@client.DataWatch('/path/to/watch')
def my_func(data, stat):
    print("Data is %s" % data)
    print("Version is %s" % stat.version)

# Above function is called immediately and prints

# Or if you want the event object
@client.DataWatch('/path/to/watch')
def my_func(data, stat, event):
    print("Data is %s" % data)
    print("Version is %s" % stat.version)
    print("Event is %s" % event)

Changed in version 1.2: DataWatch now ignores additional arguments that were previously passed to it and warns that they are no longer respected.

__init__(client, path, func=None, *args, **kwargs)[source]

Create a data watcher for a path

Parameters:
  • client (KazooClient) – A zookeeper client.

  • path (str) – The path to watch for data changes on.

  • func (callable) – Function to call initially and every time the node changes. func will be called with a tuple, the value of the node and a ZnodeStat instance.

__call__(func)[source]

Callable version for use as a decorator

Parameters:

func (callable) – Function to call initially and every time the data changes. func will be called with a tuple, the value of the node and a ZnodeStat instance.

class kazoo.recipe.watchers.ChildrenWatch(client, path, func=None, allow_session_lost=True, send_event=False)[source]

Watches a node for children updates and calls the specified function each time it changes

The function will also be called the very first time its registered to get children.

Returning False from the registered function will disable future children change calls. If the client connection is closed (using the close command), the ChildrenWatch will no longer get updates.

if send_event=True in __init__, then the function will always be called with second parameter, event. Upon initial call or when recovering a lost session the event is always None. Otherwise it’s a WatchedEvent instance.

Example with client:

@client.ChildrenWatch('/path/to/watch')
def my_func(children):
    print "Children are %s" % children

# Above function is called immediately and prints children
__init__(client, path, func=None, allow_session_lost=True, send_event=False)[source]

Create a children watcher for a path

Parameters:
  • client (KazooClient) – A zookeeper client.

  • path (str) – The path to watch for children on.

  • func (callable) – Function to call initially and every time the children change. func will be called with a single argument, the list of children.

  • allow_session_lost (bool) – Whether the watch should be re-registered if the zookeeper session is lost.

  • send_event (bool) – Whether the function should be passed the event sent by ZooKeeper or None upon initialization (see class documentation)

The path must already exist for the children watcher to run.

__call__(func)[source]

Callable version for use as a decorator

Parameters:

func (callable) – Function to call initially and every time the children change. func will be called with a single argument, the list of children.

class kazoo.recipe.watchers.PatientChildrenWatch(client, path, time_boundary=30)[source]

Patient Children Watch that returns values after the children of a node don’t change for a period of time

A separate watcher for the children of a node, that ignores changes within a boundary time and sets the result only when the boundary time has elapsed with no children changes.

Example:

watcher = PatientChildrenWatch(client, '/some/path',
                               time_boundary=5)
async_object = watcher.start()

# Blocks until the children have not changed for time boundary
# (5 in this case) seconds, returns children list and an
# async_result that will be set if the children change in the
# future
children, child_async = async_object.get()

Note

This Watch is different from DataWatch and ChildrenWatch as it only returns once, does not take a function that is called, and provides an IAsyncResult object that can be checked to see if the children have changed later.

__init__(client, path, time_boundary=30)[source]
start()[source]

Begin the watching process asynchronously

Returns:

An IAsyncResult instance that will be set when no change has occurred to the children for time boundary seconds.