Developers

Interfaces

class tooz.coordination.CoordinationDriver

Bases: object

CHARACTERISTICS = ()

Tuple of Characteristics introspectable enum member(s) that can be used to interogate how this driver works.

__weakref__

list of weak references to the object (if defined)

static create_group(group_id)

Request the creation of a group asynchronously.

Parameters:group_id (str) – the id of the group to create Returns:None Return type:CoordAsyncResult

static delete_group(group_id)

Delete a group asynchronously.

Parameters:group_id (str) – the id of the group to leave Returns:Result Return type:CoordAsyncResult

static get_groups()

Return the list composed by all groups ids asynchronously.

Returns:the list of all created group ids Return type:CoordAsyncResult

static get_leader(group_id)

Return the leader for a group.

Parameters:group_id – the id of the group: Returns:the leader Return type:CoordAsyncResult

static get_lock(name)

Return a distributed lock.

This is a exclusive lock, a second call to acquire() will block or return False.

Parameters:name – The lock name that is used to identify it across all nodes.

static get_member_capabilities(group_id, member_id)

Return the capabilities of a member asynchronously.

Parameters:

• group_id (str) – the id of the group of the member
• member_id (str) – the id of the member

Returns:

capabilities of a member

Return type:

CoordAsyncResult

static get_member_info(group_id, member_id)

Return the statistics and capabilities of a member asynchronously.

Parameters:

• group_id (str) – the id of the group of the member
• member_id (str) – the id of the member

Returns:

capabilities and statistics of a member

Return type:

CoordAsyncResult

static get_members(group_id)

Return the list of all members ids of the specified group.

Returns:list of all created group ids Return type:CoordAsyncResult

static heartbeat()

Update member status to indicate it is still alive.

Method to run once in a while to be sure that the member is not dead and is still an active member of a group.

Returns:The number of seconds to wait before sending a new heartbeat.

static join_group(group_id, capabilities='')

Join a group and establish group membership asynchronously.

Parameters:

• group_id (str) – the id of the group to join
• capabilities (object (typically str)) – the capabilities of the joined member

Returns:

None

Return type:

CoordAsyncResult

static leave_group(group_id)

Leave a group asynchronously.

Parameters:group_id (str) – the id of the group to leave Returns:None Return type:CoordAsyncResult

requires_beating = False

Usage requirement that if true requires that the heartbeat() be called periodically (at a given rate) to avoid locks, sessions and other from being automatically closed/discarded by the coordinators backing store.

static run_elect_coordinator()

Try to leader elect this coordinator & activate hooks on success.

static run_watchers(timeout=None)

Run the watchers callback.

This may also activate run_elect_coordinator() (depending on driver implementation).

static stand_down_group_leader(group_id)

Stand down as the group leader if we are.

Parameters:group_id – The group where we don’t want to be a leader anymore

start(start_heart=False)

Start the service engine.

If needed, the establishment of a connection to the servers is initiated.

stop()

Stop the service engine.

If needed, the connection to servers is closed and the client will disappear from all joined groups.

unwatch_elected_as_leader(group_id, callback)

Call a function when member gets elected as leader.

The callback functions will be executed when run_watchers is called.

Parameters:

• group_id – The group id to watch
• callback – The function to execute when a member leaves this group

unwatch_join_group(group_id, callback)

Stop executing a function when a group_id sees a new member joined.

Parameters:

• group_id – The group id to unwatch
• callback – The function that was executed when a member joined this group

unwatch_leave_group(group_id, callback)

Stop executing a function when a group_id sees a new member leaving.

Parameters:

• group_id – The group id to unwatch
• callback – The function that was executed when a member left this group

static update_capabilities(group_id, capabilities)

Update member capabilities in the specified group.

Parameters:

• group_id (str) – the id of the group of the current member
• capabilities (object (typically str)) – the capabilities of the updated member

Returns:

None

Return type:

CoordAsyncResult

watch_elected_as_leader(group_id, callback)

Call a function when member gets elected as leader.

The callback functions will be executed when run_watchers is called.

Parameters:

• group_id – The group id to watch
• callback – The function to execute when a member leaves this group

watch_join_group(group_id, callback)

Call a function when group_id sees a new member joined.

The callback functions will be executed when run_watchers is called.

Parameters:

• group_id – The group id to watch
• callback – The function to execute when a member joins this group

watch_leave_group(group_id, callback)

Call a function when group_id sees a new member leaving.

The callback functions will be executed when run_watchers is called.

Parameters:

• group_id – The group id to watch
• callback – The function to execute when a member leaves this group

Consul

Etcd

File

IPC

Memcached

Mysql

PostgreSQL

Redis

Zake

Zookeeper

Exceptions

class tooz.coordination.ToozError(message, cause=None)

Bases: exceptions.Exception

Exception raised when an internal error occurs.

Raised for instance in case of server internal error.

Variables:cause – the cause of the exception being raised, when not none this will itself be an exception instance, this is useful for creating a chain of exceptions for versions of python where this is not yet implemented/supported natively.

__weakref__

list of weak references to the object (if defined)

class tooz.coordination.ToozConnectionError(message, cause=None)

Bases: tooz.coordination.ToozError

Exception raised when the client cannot connect to the server.

class tooz.coordination.OperationTimedOut(message, cause=None)

Bases: tooz.coordination.ToozError

Exception raised when an operation times out.

class tooz.coordination.GroupNotCreated(group_id)

Bases: tooz.coordination.ToozError

Exception raised when the caller request an nonexistent group.

class tooz.coordination.GroupAlreadyExist(group_id)

Bases: tooz.coordination.ToozError

Exception raised trying to create an already existing group.

class tooz.coordination.MemberAlreadyExist(group_id, member_id)

Bases: tooz.coordination.ToozError

Exception raised trying to join a group already joined.

class tooz.coordination.MemberNotJoined(group_id, member_id)

Bases: tooz.coordination.ToozError

Exception raised trying to access a member not in a group.

class tooz.coordination.GroupNotEmpty(group_id)

Bases: tooz.coordination.ToozError

Exception raised when the caller try to delete a group with members.

tooz.coordination.raise_with_cause(exc_cls, message, *args, **kwargs)

Helper to raise + chain exceptions (when able) and associate a cause.

For internal usage only.

NOTE(harlowja): Since in py3.x exceptions can be chained (due to PEP 3134) we should try to raise the desired exception with the given cause.

Parameters:

• exc_cls – the ToozError class to raise.
• message – the text/str message that will be passed to the exceptions constructor as its first positional argument.
• args – any additional positional arguments to pass to the exceptions constructor.
• kwargs – any additional keyword arguments to pass to the exceptions constructor.