kazoo.interfaces

Kazoo Interfaces

Changed in version 1.4: The classes in this module used to be interface declarations based on zope.interface.Interface. They were converted to normal classes and now serve as documentation only.

Public API

IHandler implementations should be created by the developer to be passed into KazooClient during instantiation for the preferred callback handling.

If the developer needs to use objects implementing the IAsyncResult interface, the IHandler.async_result() method must be used instead of instantiating one directly.

class kazoo.interfaces.IHandler(*args, **kwargs)

A Callback Handler for Zookeeper completion and watch callbacks.

This object must implement several methods responsible for determining how completion / watch callbacks are handled as well as the method for calling IAsyncResult callback functions.

These functions are used to abstract differences between a Python threading environment and asynchronous single-threaded environments like gevent. The minimum functionality needed for Kazoo to handle these differences is encompassed in this interface.

The Handler should document how callbacks are called for:

• Zookeeper completion events

• Zookeeper watch events

name

Human readable name of the Handler interface.

timeout_exception

Exception class that should be thrown and captured if a result is not available within the given time.

sleep_func

Appropriate sleep function that can be called with a single argument and sleep.

async_result()

Return an instance that conforms to the IAsyncResult interface appropriate for this handler

Return type:

IAsyncResult

create_connection(*args, **kwargs)

A socket method that implements Python’s socket.create_connection API

Return type:

Socket

create_socket_pair()

A socket method that implements Python’s socket.socketpair API

Return type:

tuple[Socket, Socket]

dispatch_callback(callback)

Dispatch to the callback object

Parameters:

callback (Callback) – A Callback object to be called.

Return type:

None

event_object()

Return an appropriate object that implements Python’s threading.Event API

Return type:

Event

lock_object()

Return an appropriate object that implements Python’s threading.Lock API

Return type:

Lockable

rlock_object()

Return an appropriate object that implements Python’s threading.RLock API

Return type:

ReentrantLock

select(rlist, wlist, xlist, timeout=None)

A select method that implements Python’s select.select API

Return type:

tuple[Iterable[int | HasFileNo], Iterable[int | HasFileNo], Iterable[int | HasFileNo]]

socket()

A socket method that implements Python’s socket.socket API

Return type:

Socket

spawn(func, *args, **kwargs)

Spawn a function to run asynchronously

Parameters:

• args (Any) – args to call the function with.

• kwargs (Any) – keyword args to call the function with.

Return type:

Threadlike

This method should return immediately and execute the function with the provided args and kwargs in an asynchronous manner.

start()

Start the handler, used for setting up the handler.

Return type:

None

stop()

Stop the handler. Should block until the handler is safely stopped.

Return type:

None

Private API

The IAsyncResult documents the proper implementation for providing a value that results from a Zookeeper completion callback. Since the KazooClient returns an IAsyncResult object instead of taking a completion callback for async functions, developers wishing to have their own callback called should use the IAsyncResult.rawlink() method.

class kazoo.interfaces.IAsyncResult(*args, **kwargs)

An Async Result object that can be queried for a value that has been set asynchronously.

This object is modeled on the gevent AsyncResult object.

The implementation must account for the fact that the set() and set_exception() methods will be called from within the Zookeeper thread which may require extra care under asynchronous environments.

value

Holds the value passed to set() if set() was called. Otherwise None.

exception

Holds the exception instance passed to set_exception() if set_exception() was called. Otherwise None.

property exception: Exception | None

The exception set by set_exception() or None if no exception has been set

get(block=True, timeout=None)

Return the stored value or raise the exception

Parameters:

• block (bool) – Whether this method should block or return immediately.

• timeout (float | None) – How long to wait for a value when block is True.

Return type:

Any

If this instance already holds a value / an exception, return / raise it immediately. Otherwise, block until set() or set_exception() has been called or until the optional timeout occurs.

get_nowait()

Return the value or raise the exception without blocking.

If nothing is available, raise the Timeout exception class on the associated IHandler interface.

Return type:

Any

rawlink(callback)

Register a callback to call when a value or an exception is set

Parameters:

callback (Callable[[IAsyncResult], Any]) – A callback function to call after set() or set_exception() has been called. This function will be passed a single argument, this instance.

Return type:

None

ready()

Return True if and only if it holds a value or an exception

Return type:

bool

set(value=None)

Store the value. Wake up the waiters.

Parameters:

value (Any) – Value to store as the result.

Return type:

None

Any waiters blocking on get() or wait() are woken up. Sequential calls to wait() and get() will not block at all.

set_exception(exception)

Store the exception. Wake up the waiters.

Parameters:

exception (Exception) – Exception to raise when fetching the value.

Return type:

None

Any waiters blocking on get() or wait() are woken up. Sequential calls to wait() and get() will not block at all.

successful()

Return True if and only if it is ready and holds a value

Return type:

bool

unlink(callback)

Remove the callback set by rawlink()

Parameters:

callback (Callable[[IAsyncResult], None]) – A callback function to remove.

Return type:

None

wait(timeout=None)

Block until the instance is ready.

Parameters:

timeout (float | None) – How long to wait for a value when block is True.

Return type:

Any

If this instance already holds a value / an exception, return / raise it immediately. Otherwise, block until set() or set_exception() has been called or until the optional timeout occurs.