Developers

Interfaces

class tooz.coordination.CoordinationDriver(member_id, parsed_url, options)

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 (ascii bytes) – the id of the group to create Returns:None Return type:CoordAsyncResult

static delete_group(group_id)

Delete a group asynchronously.

Parameters:group_id (ascii bytes) – 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 (ascii bytes) – the id of the group of the member
• member_id (ascii bytes) – 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 (ascii bytes) – the id of the group of the member
• member_id (ascii bytes) – the id of the member

Returns:

capabilities and statistics of a member

Return type:

CoordAsyncResult

static get_members(group_id)

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

Returns:set 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 (ascii bytes) – the id of the group to join
• capabilities (object) – the capabilities of the joined member

Returns:

None

Return type:

CoordAsyncResult

join_group_create(*args, **kw)

Join a group and create it if necessary.

If the group cannot be joined because it does not exist, it is created before being joined.

This function will keep retrying until it can create the group and join it. Since nothing is transactional, it may have to retry several times if another member is creating/deleting the group at the same time.

Parameters:

• group_id – Identifier of the group to join and create
• capabilities – the capabilities of the joined member

join_partitioned_group(group_id, weight=1, partitions=32)

Join a group and get a partitioner.

A partitioner allows to distribute a bunch of objects across several members using a consistent hash ring. Each object gets assigned (at least) one member responsible for it. It’s then possible to check which object is owned by any member of the group.

This method also creates if necessary, and joins the group with the selected weight.

Parameters:

• group_id – The group to create a partitioner for.
• weight – The weight to use in the hashring for this node.
• partitions – The number of partitions to create.

Returns:

A Partitioner object.

static leave_group(group_id)

Leave a group asynchronously.

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

leave_partitioned_group(partitioner)

Leave a partitioned group.

This leaves the partitioned group and stop the partitioner. :param group_id: The group to create a partitioner for.

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 (ascii bytes) – the id of the group of the current member
• capabilities (object) – 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

class tooz.drivers.etcd.EtcdDriver(member_id, parsed_url, options)

Bases: tooz.coordination.CoordinationDriver

An etcd based driver.

This driver uses etcd provide the coordination driver semantics and required API(s).

DEFAULT_HOST = 'localhost'

Default hostname used when none is provided.

DEFAULT_PORT = 2379

Default port used if none provided (4001 or 2379 are the common ones).

DEFAULT_TIMEOUT = 30

Default socket/lock/member/leader timeout used when none is provided.

lock_encoder_cls

Class that will be used to encode lock names into a valid etcd url.

alias of Base64LockEncoder

File

class tooz.drivers.file.FileDriver(member_id, parsed_url, options)

Bases: tooz.coordination.CoordinationDriverCachedRunWatchers, tooz.coordination.CoordinationDriverWithExecutor

A file based driver.

This driver uses files and directories (and associated file locks) to provide the coordination driver semantics and required API(s). It is missing some functionality but in the future these not implemented API(s) will be filled in.

General recommendations/usage considerations:

• It does not automatically delete members from groups of processes that have died, manual cleanup will be needed for those types of failures.
• It is not distributed (or recommended to be used in those situations, so the developer using this should really take that into account when applying this driver in there app).

CHARACTERISTICS = (<Characteristics.NON_TIMEOUT_BASED: 'NON_TIMEOUT_BASED'>, <Characteristics.DISTRIBUTED_ACROSS_THREADS: 'DISTRIBUTED_ACROSS_THREADS'>, <Characteristics.DISTRIBUTED_ACROSS_PROCESSES: 'DISTRIBUTED_ACROSS_PROCESSES'>)

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

HASH_ROUTINE = 'sha1'

This routine is used to hash a member (or group) id into a filesystem safe name that can be used for member lookup and group joining.

__init__(member_id, parsed_url, options)

Initialize the file driver.

IPC

Memcached

Mysql

PostgreSQL

Redis

Zake

Zookeeper

Exceptions

class tooz.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.ToozError

Exception raised when the client cannot connect to the server.

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

Bases: tooz.ToozError

Exception raised when an operation times out.

class tooz.coordination.GroupNotCreated(group_id)

Bases: tooz.ToozError

Exception raised when the caller request an nonexistent group.

class tooz.coordination.GroupAlreadyExist(group_id)

Bases: tooz.ToozError

Exception raised trying to create an already existing group.

class tooz.coordination.MemberAlreadyExist(group_id, member_id)

Bases: tooz.ToozError

Exception raised trying to join a group already joined.

class tooz.coordination.MemberNotJoined(group_id, member_id)

Bases: tooz.ToozError

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

class tooz.coordination.GroupNotEmpty(group_id)

Bases: tooz.ToozError

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

tooz.utils.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.