kazoo.recipe.cache

TreeCache

Maintainer:

Jiangge Zhang <tonyseek@gmail.com>

Maintainer:

Haochuan Guo <guohaochuan@gmail.com>

Maintainer:

Tianwen Zhang <mail2tevin@gmail.com>

Status:

Alpha

A port of the Apache Curator’s TreeCache recipe. It builds an in-memory cache of a subtree in ZooKeeper and keeps it up-to-date.

See also: http://curator.apache.org/curator-recipes/tree-cache.html

Public API

class kazoo.recipe.cache.TreeCache(client, path)

The cache of a ZooKeeper subtree.

Parameters:

• client (KazooClient) – A KazooClient instance.

• path (str) – The root path of subtree.

start()

Starts the cache.

The cache is not started automatically. You must call this method.

After a cache started, all changes of subtree will be synchronized from the ZooKeeper server. Events will be fired for those activity.

Don’t forget to call close() if a tree was started and you don’t need it anymore, or you will leak the memory of cached nodes, even if you have released all references to the TreeCache instance. Because there are so many callbacks that have been registered to the Kazoo client.

See also listen().

Note

This method is not thread safe.

Return type:

None

close()

Closes the cache.

A closed cache was detached from ZooKeeper’s changes. And all nodes will be invalidated.

Once a tree cache was closed, it could not be started again. You should only close a tree cache while you want to recycle it.

Note

This method is not thread safe.

Return type:

None

listen(listener)

Registers a function to listen the cache events.

The cache events are changes of local data. They are delivered from watching notifications in ZooKeeper session.

This method can be use as a decorator.

Parameters:

listener (Callable[[TreeEvent], None]) – A callable object which accepting a TreeEvent instance as its argument.

Return type:

Callable[[TreeEvent], None]

listen_fault(listener)

Registers a function to listen the exceptions.

It is possible to meet some exceptions during the cache running. You could specific handlers for them.

This method can be use as a decorator.

Parameters:

listener (Callable[[Exception], None]) – A callable object which accepting an exception as its argument.

Return type:

Callable[[Exception], None]

get_data(path, default=None)

Gets data of a node from cache.

Parameters:

• path (str) – The absolute path string.

• default (NodeData | None) – The default value which will be returned if the node does not exist.

Raises:

ValueError – If the path is outside of this subtree.

Return type:

NodeData | None

Returns:

A NodeData instance.

get_children(path, default=None)

Gets node children list from in-memory snapshot.

Parameters:

• path (str) – The absolute path string.

• default (frozenset[str] | None) – The default value which will be returned if the node does not exist.

Raises:

ValueError – If the path is outside of this subtree.

Return type:

frozenset[str] | None

Returns:

The frozenset which including children names.

# FIXME the default return value should be an empty frozenset, # returning None is confusing.

class kazoo.recipe.cache.TreeEvent(iterable=(), /)

Bases: Tuple[int, NodeData | None]

The immutable event tuple of cache.

property event_data

A NodeData instance.

property event_type

An enumerate integer to indicate event type.

classmethod make(event_type, event_data=None)

Creates a new TreeEvent tuple.

Return type:

TreeEvent

Returns:

A TreeEvent instance.

class kazoo.recipe.cache.NodeData(iterable=(), /)

Bases: Tuple[str, bytes, ZnodeStat]

The immutable node data tuple of cache.

property data

The bytes data of current node.

classmethod make(path, data, stat)

Creates a new NodeData tuple.

Return type:

NodeData

Returns:

A NodeData instance.

property path

The absolute path string of current node.

property stat

The stat information of current node.