## Module Reference

this page last updated: 2020-03-11 20:36:36

# Module Reference

## Interfaces

class `tooz.coordination.``CoordinationDriver`(member_id, parsed_url, options)
  `CHARACTERISTICS` = ()

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

  `__init__`(member_id, parsed_url, options)

    Initialize self. See help(type(self)) for accurate signature.

  `__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=b'')

    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`(group_id, capabilities=b'')

    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

class `tooz.drivers.consul.``ConsulDriver`(member_id, parsed_url, options)

  This driver uses python-consul client against consul servers.

  The ConsulDriver implements a minimal set of coordination driver API(s) needed to make Consul being used as an option for Distributed Locking. The data is stored in Consul’s key-value store.

  The Consul driver connection URI should look like:

      consul://HOST[:PORT][?OPTION1=VALUE1[&OPTION2=VALUE2[&...]]]

  If not specified, PORT defaults to 8500. Available options are:

  Name | Default
  --- | ---
  ttl | 15
  namespace | tooz

  For details on the available options, refer to http://python-consul.readthedocs.org/en/latest/.

  `DEFAULT_PORT` = 8500

    Default consul port if not provided.

  `DEFAULT_TTL` = 15

    Default TTL

  `TOOZ_NAMESPACE` = 'tooz'

    Default namespace when none is provided

  `__init__`(member_id, parsed_url, options)

    Initialize self. See help(type(self)) for accurate signature.

  `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.

  `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

  `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

### Etcd

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

  An etcd based driver.

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

  The Etcd driver connection URI should look like:

      etcd://[HOST[:PORT]][?OPTION1=VALUE1[&OPTION2=VALUE2[&...]]]

  If not specified, HOST defaults to localhost and PORT defaults to 2379. Available options are:

  Name | Default
  --- | ---
  protocol | http
  timeout | 30
  lock_timeout | 30

  `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.

  `__init__`(member_id, parsed_url, options)

    Initialize self. See help(type(self)) for accurate signature.

  `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.

  `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.

  `lock_encoder_cls`

    alias of `tooz.utils.Base64LockEncoder`

  `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

  `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

### Etcd3

### Etcd3gw

### File

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

  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.

  The File driver connection URI should look like:

      file://DIRECTORY[?timeout=TIMEOUT]

  DIRECTORY is the location that should be used to store lock files. TIMEOUT defaults to 10.

  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.

  `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

  `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

  `get_groups`()

    Return the list composed by all groups ids asynchronously.

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

  `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.

  `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

  `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

  `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.

  `join_group`(group_id, capabilities=b'')

    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

  `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

  static `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

  static `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

### IPC

class `tooz.drivers.ipc.``IPCDriver`(member_id, parsed_url, options)

  A IPC based driver.

  This driver uses IPC concepts 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.

  The IPC driver connection URI should look like:

      ipc://

  General recommendations/usage considerations:

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

  `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

  `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

  `get_groups`()

    Return the list composed by all groups ids asynchronously.

    Returns: | the list of all created group ids
    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.

  `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

### Memcached

class `tooz.drivers.memcached.``MemcachedDriver`(member_id, parsed_url, options)

  A memcached based driver.

  This driver users memcached concepts to provide the coordination driver semantics and required API(s). It is fully functional and implements all of the coordination driver API(s). It stores data into memcache using expiries and msgpack encoded values.

  The Memcached driver connection URI should look like:

      memcached://[HOST[:PORT]][?OPTION1=VALUE1[&OPTION2=VALUE2[&...]]]

  If not specified, HOST defaults to localhost and PORT defaults to 11211. Available options are:

  Name | Default
  --- | ---
  timeout | 30
  membership_timeout | 30
  lock_timeout | 30
  leader_timeout | 30
  max_pool_size | None

  General recommendations/usage considerations:

  - Memcache (without different backend technology) is a cache enough said.
  `CHARACTERISTICS` = (<Characteristics.DISTRIBUTED_ACROSS_THREADS: 'DISTRIBUTED_ACROSS_THREADS'>, <Characteristics.DISTRIBUTED_ACROSS_PROCESSES: 'DISTRIBUTED_ACROSS_PROCESSES'>, <Characteristics.DISTRIBUTED_ACROSS_HOSTS: 'DISTRIBUTED_ACROSS_HOSTS'>, <Characteristics.CAUSAL: 'CAUSAL'>)

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

  `DEFAULT_TIMEOUT` = 30

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

  `GROUP_LEADER_PREFIX` = b'_TOOZ_GROUP_LEADER_'

    Key prefix attached to leaders of groups (used in name-spacing keys)

  `GROUP_LIST_KEY` = b'_TOOZ_GROUP_LIST'

    Key where all groups ‘known’ are stored.

  `GROUP_PREFIX` = b'_TOOZ_GROUP_'

    Key prefix attached to groups (used in name-spacing keys)

  `MEMBER_PREFIX` = b'_TOOZ_MEMBER_'

    Key prefix attached to members of groups (used in name-spacing keys)

  `STILL_ALIVE` = b"It's alive!"

    String used to keep a key/member alive (until it next expires).

  `__init__`(member_id, parsed_url, options)

    Initialize self. See help(type(self)) for accurate signature.

  `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

  `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

  `get_groups`()

    Return the list composed by all groups ids asynchronously.

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

  `get_leader`(group_id)

    Return the leader for a group.

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

  `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.

  `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

  `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

  `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.

  `join_group`(group_id, capabilities=b'')

    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

  `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

  `run_elect_coordinator`()

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

  `run_watchers`(timeout=None)

    Run the watchers callback.

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

  `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

### Mysql

class `tooz.drivers.mysql.``MySQLDriver`(member_id, parsed_url, options)

  A MySQL based driver.

  This driver users MySQL database tables 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.

  The MySQL driver connection URI should look like:

      mysql://USERNAME:PASSWORD@HOST[:PORT]/DBNAME[?unix_socket=SOCKET_PATH]

  If not specified, PORT defaults to 3306.

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

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

  `__init__`(member_id, parsed_url, options)

    Initialize the MySQL driver.

  `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 `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

  static `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

  static `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 `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

  static `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

  static `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

### PostgreSQL

class `tooz.drivers.pgsql.``PostgresDriver`(member_id, parsed_url, options)

  A PostgreSQL based driver.

  This driver users PostgreSQL database tables 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.

  The PostgreSQL driver connection URI should look like:

      postgresql://[USERNAME[:PASSWORD]@]HOST:PORT?dbname=DBNAME

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

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

  `__init__`(member_id, parsed_url, options)

    Initialize the PostgreSQL driver.

  `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 `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

  static `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

  static `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 `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

  static `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

  static `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

### Redis

class `tooz.drivers.redis.``RedisDriver`(member_id, parsed_url, options)

  Redis provides a few nice benefits that act as a poormans zookeeper.

  It is fully functional and implements all of the coordination driver API(s). It stores data into redis using the provided redis API(s) using msgpack encoded values as needed.

  - Durability (when setup with AOF mode).
  - Consistent, note that this is still restricted to only one redis server, without the recently released redis (alpha) clustering > 1 server will not be consistent when partitions or failures occur (even redis clustering docs state it is not a fully AP or CP solution, which means even with it there will still be potential inconsistencies).
  - Master/slave failover (when setup with redis sentinel), giving some notion of HA (values can be lost when a failover transition occurs).

  The Redis driver connection URI should look like:

      redis://[:PASSWORD@]HOST:PORT[?OPTION=VALUE[&OPTION2=VALUE2[&...]]]

  For a list of options recognized by this driver, see the documentation for the member CLIENT_ARGS, and to determine the expected types of those options see CLIENT_BOOL_ARGS, CLIENT_INT_ARGS, and CLIENT_LIST_ARGS.

  To use a sentinel the connection URI must point to the sentinel server. At connection time the sentinel will be asked for the current IP and port of the master and then connect there. The connection URI for sentinel should be written as follows:

      redis://<sentinel host>:<sentinel port>?sentinel=<master name>

  Additional sentinel hosts are listed with multiple `sentinel_fallback` parameters as follows:

      redis://<sentinel host>:<sentinel port>?sentinel=<master name>&
        sentinel_fallback=<other sentinel host>:<sentinel port>&
        sentinel_fallback=<other sentinel host>:<sentinel port>&
        sentinel_fallback=<other sentinel host>:<sentinel port>

  Further resources/links:

  - http://redis.io/
  - http://redis.io/topics/sentinel
  - http://redis.io/topics/cluster-spec

  Note that this client will itself retry on transaction failure (when they keys being watched have changed underneath the current transaction). Currently the number of attempts that are tried is infinite (this might be addressed in https://github.com/andymccurdy/redis-py/issues/566 when that gets worked on). See http://redis.io/topics/transactions for more information on this topic.

  General recommendations/usage considerations:

  - When used for locks, run in AOF mode and think carefully about how your redis deployment handles losing a server (the clustering support is supposed to aid in losing servers, but it is also of unknown reliablity and is relatively new, so use at your own risk).
  `CHARACTERISTICS` = (<Characteristics.DISTRIBUTED_ACROSS_THREADS: 'DISTRIBUTED_ACROSS_THREADS'>, <Characteristics.DISTRIBUTED_ACROSS_PROCESSES: 'DISTRIBUTED_ACROSS_PROCESSES'>, <Characteristics.DISTRIBUTED_ACROSS_HOSTS: 'DISTRIBUTED_ACROSS_HOSTS'>, <Characteristics.CAUSAL: 'CAUSAL'>)

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

  `CLIENT_ARGS` = frozenset({'socket_timeout', 'sentinel_fallback', 'db', 'encoding', 'ssl_certfile', 'socket_keepalive', 'retry_on_timeout', 'ssl_keyfile', 'ssl', 'sentinel'})

    Keys that we allow to proxy from the coordinator configuration into the redis client (used to configure the redis client internals so that it works as you expect/want it to).

    See: http://redis-py.readthedocs.org/en/latest/#redis.Redis

    See: https://github.com/andymccurdy/redis-py/blob/2.10.3/redis/client.py

  `CLIENT_BOOL_ARGS` = frozenset({'retry_on_timeout', 'ssl'})

    Client arguments that are expected to be boolean convertible.

  `CLIENT_DEFAULT_SOCKET_TO` = 30

    Default socket timeout to use when none is provided.

  `CLIENT_INT_ARGS` = frozenset({'db', 'socket_timeout', 'socket_keepalive'})

    Client arguments that are expected to be int convertible.

  `CLIENT_LIST_ARGS` = frozenset({'sentinel_fallback'})

    Client arguments that are expected/allowed to be lists.

  `DEFAULT_ENCODING` = 'utf8'

    This is for python3.x; which will behave differently when returned binary types or unicode types (redis uses binary internally it appears), so to just stick with a common way of doing this, make all the things binary (with this default encoding if one is not given and a unicode string is provided).

  `DEFAULT_NAMESPACE` = b'_tooz'

    Default namespace for keys when none is provided.

  `GROUP_EXISTS` = b'__created__'

    Redis deletes dictionaries that have no keys in them, which means the key will disappear which means we can’t tell the difference between a group not existing and a group being empty without this key being saved…

  `GROUP_EXISTS_VALUE` = b'1'

    Value used (with group exists key) to keep a group from disappearing.

  `MIN_VERSION` = LooseVersion ('2.6.0')

    The min redis version that this driver requires to operate with…

  `NAMESPACE_SEP` = b':'

    Separator that is used to combine a key with the namespace (to get the actual key that will be used).

  `SCRIPTS` = {'create_group': '\n-- Extract *all* the variables (so we can easily know what they are)...\nlocal namespaced_group_key = KEYS[1]\nlocal all_groups_key = KEYS[2]\nlocal no_namespaced_group_key = ARGV[1]\nif redis.call("exists", namespaced_group_key) == 1 then\n return 0\nend\nredis.call("sadd", all_groups_key, no_namespaced_group_key)\nredis.call("hset", namespaced_group_key,\n "${group_existence_key}", "${group_existence_value}")\nreturn 1\n', 'delete_group': '\n-- Extract *all* the variables (so we can easily know what they are)...\nlocal namespaced_group_key = KEYS[1]\nlocal all_groups_key = KEYS[2]\nlocal no_namespaced_group_key = ARGV[1]\nif redis.call("exists", namespaced_group_key) == 0 then\n return -1\nend\nif redis.call("sismember", all_groups_key, no_namespaced_group_key) == 0 then\n return -2\nend\nif redis.call("hlen", namespaced_group_key) > 1 then\n return -3\nend\n-- First remove from the set (then delete the group); if the set removal\n-- fails, at least the group will still exist (and can be fixed manually)...\nif redis.call("srem", all_groups_key, no_namespaced_group_key) == 0 then\n return -4\nend\nredis.call("del", namespaced_group_key)\nreturn 1\n', 'update_capabilities': '\n-- Extract *all* the variables (so we can easily know what they are)...\nlocal group_key = KEYS[1]\nlocal member_id = ARGV[1]\nlocal caps = ARGV[2]\nif redis.call("exists", group_key) == 0 then\n return -1\nend\nif redis.call("hexists", group_key, member_id) == 0 then\n return -2\nend\nredis.call("hset", group_key, member_id, caps)\nreturn 1\n'}

    Lua template scripts that will be used by various methods (they are turned into real scripts and loaded on call into the `start()` method).

  `STILL_ALIVE` = b'Not dead!'

    String used to keep a key/member alive (until it next expires).

  `__init__`(member_id, parsed_url, options)

    Initialize self. See help(type(self)) for accurate signature.

  `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

  `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

  `get_groups`()

    Return the list composed by all groups ids asynchronously.

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

  `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.

  `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

  `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

  `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.

  `join_group`(group_id, capabilities=b'')

    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

  `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

  `run_elect_coordinator`()

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

  `run_watchers`(timeout=None)

    Run the watchers callback.

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

  `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

### Zake

class `tooz.drivers.zake.``ZakeDriver`(member_id, parsed_url, options)

  This driver uses the zake client to mimic real zookeeper servers.

  It should be mainly used (and is really only intended to be used in this manner) for testing and integration (where real zookeeper servers are typically not available).

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

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

### Zookeeper

class `tooz.drivers.zookeeper.``KazooDriver`(member_id, parsed_url, options)

  This driver uses the kazoo client against real zookeeper servers.

  It is fully functional and implements all of the coordination driver API(s). It stores data into zookeeper using znodes and msgpack encoded values.

  To configure the client to your liking a subset of the options defined at http://kazoo.readthedocs.org/en/latest/api/client.html will be extracted from the coordinator url (or any provided options), so that a specific coordinator can be created that will work for you.

  The Zookeeper coordinator url should look like:

      zookeeper://[USERNAME:PASSWORD@][HOST[:PORT]][?OPTION1=VALUE1[&OPTION2=VALUE2[&...]]]

  Currently the following options will be proxied to the contained client:

  Name | Source | Default
  --- | --- | ---
  hosts | url netloc + ‘hosts’ option key | localhost:2181
  timeout | ‘timeout’ options key | 10.0 (kazoo default)
  connection_retry | ‘connection_retry’ options key | None
  command_retry | ‘command_retry’ options key | None
  randomize_hosts | ‘randomize_hosts’ options key | True

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

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

  `TOOZ_NAMESPACE` = b'tooz'

    Default namespace when none is provided.

  `__init__`(member_id, parsed_url, options)

    Initialize self. See help(type(self)) for accurate signature.

  `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

  `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

  `get_groups`()

    Return the list composed by all groups ids asynchronously.

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

  `get_leader`(group_id)

    Return the leader for a group.

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

  `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.

  `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

  `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

  `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

  `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.

  `join_group`(group_id, capabilities=b'')

    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

  `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

  `run_elect_coordinator`()

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

  `run_watchers`(timeout=None)

    Run the watchers callback.

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

  `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

  `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

## Exceptions

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

  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.

  `__init__`(message, cause=None)

    Initialize self. See help(type(self)) for accurate signature.

  `__weakref__`

    list of weak references to the object (if defined)

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

  Exception raised when the client cannot connect to the server.

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

  Exception raised when an operation times out.

class `tooz.coordination.``GroupNotCreated`(group_id)

  Exception raised when the caller request an nonexistent group.

  `__init__`(group_id)

    Initialize self. See help(type(self)) for accurate signature.

class `tooz.coordination.``GroupAlreadyExist`(group_id)

  Exception raised trying to create an already existing group.

  `__init__`(group_id)

    Initialize self. See help(type(self)) for accurate signature.

class `tooz.coordination.``MemberAlreadyExist`(group_id, member_id)

  Exception raised trying to join a group already joined.

  `__init__`(group_id, member_id)

    Initialize self. See help(type(self)) for accurate signature.

class `tooz.coordination.``MemberNotJoined`(group_id, member_id)

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

  `__init__`(group_id, member_id)

    Initialize self. See help(type(self)) for accurate signature.

class `tooz.coordination.``GroupNotEmpty`(group_id)

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

  `__init__`(group_id)

    Initialize self. See help(type(self)) for accurate signature.

`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.

this page last updated: 2020-03-11 20:36:36

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.

found an error? report a bug questions?