etcd3.apis.auth

class etcd3.apis.auth.AuthAPI

Bases: etcd3.apis.base.BaseAPI

authenticate(name, password)

Authenticate processes an authenticate request.

Parameters:

• name (str) – name of the user
• password (str) – password of the user

auth_disable()

AuthDisable disables authentication.

auth_enable()

AuthEnable enables authentication.

role_add(name)

RoleAdd adds a new role.

Parameters:name (str) – name is the name of the role to add to the authentication system.

role_delete(role)

RoleDelete deletes a specified role.

Parameters:role (str) – None

role_get(role)

RoleGet gets detailed role information.

Parameters:role (str) – None

role_grant_permission(name, key=None, permType=<authpbPermissionType.READ: 'READ'>, range_end=None, prefix=False, all=False)

RoleGrantPermission grants a permission of a specified key or range to a specified role.

Parameters:

• name (str) – name is the name of the role which will be granted the permission.
• key (str or bytes) – the key been granted to the role
• perm (dict) – authpbPermissionType.READ or authpbPermissionType.WRITE or authpbPermissionType.READWRITE
• range_end (str or bytes) – range_end is the upper bound on the requested range [key, range_end). If range_end is ‘’, the range is all keys >= key. If range_end is key plus one (e.g., “aa”+1 == “ab”, “aÿ”+1 == “b”), then the range request gets all keys prefixed with key. If both key and range_end are ‘’, then the range request returns all keys.
• prefix (bool) – if the key is a prefix [default: False]
• all (bool) – all the keys [default: False]

role_list()

RoleList gets lists of all roles.

role_revoke_permission(role, key=None, range_end=None, prefix=False, all=False)

RoleRevokePermission revokes a key or range permission of a specified role.

Parameters:

• role (str) – the name of the role which will get permission revoked.
• key (str or bytes) – the key been revoked from the role
• range_end (str or bytes) – range_end is the upper bound on the requested range [key, range_end). If range_end is ‘’, the range is all keys >= key. If range_end is key plus one (e.g., “aa”+1 == “ab”, “aÿ”+1 == “b”), then the range request gets all keys prefixed with key. If both key and range_end are ‘’, then the range request returns all keys.
• prefix (bool) – if the key is a prefix [default: False]
• all (bool) – all the keys [default: False]

user_add(name, password)

UserAdd adds a new user.

Parameters:

• name (str) – name of the user
• password (str) – password of the user

user_change_password(name, password)

UserChangePassword changes the password of a specified user.

Parameters:

• name (str) – name is the name of the user whose password is being changed.
• password (str) – password is the new password for the user.

user_delete(name)

UserDelete deletes a specified user.

Parameters:name (str) – name is the name of the user to delete.

user_get(name)

UserGet gets detailed user information.

Parameters:name (str) – name is the name of the user to get.

user_grant_role(user, role)

UserGrant grants a role to a specified user.

Parameters:

• user (str) – user is the name of the user which should be granted a given role.
• role (str) – role is the name of the role to grant to the user.

user_list()

UserList gets a list of all users.

user_revoke_role(name, role)

UserRevokeRole revokes a role of specified user.

Parameters:

• name (str) – username to revoke
• role (str) – role name

etcd3.apis.base

class etcd3.apis.base.BaseAPI

Bases: object

__init__()

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

call_rpc(method, data=None, stream=False, encode=True, raw=False, **kwargs)

etcd3.apis.cluster

class etcd3.apis.cluster.ClusterAPI

Bases: etcd3.apis.base.BaseAPI

member_add(peerURLs)

MemberAdd adds a member into the cluster.

Parameters:peerURLs (list of str) – peerURLs is the list of URLs the added member will use to communicate with the cluster.

member_list()

MemberList lists all the members in the cluster.

member_remove(ID)

MemberRemove removes an existing member from the cluster.

Parameters:ID (int) – ID is the member ID of the member to remove.

member_update(ID, peerURLs)

MemberUpdate updates the member configuration.

Parameters:

• ID (int) – ID is the member ID of the member to update.
• peerURLs (list of str) – peerURLs is the new list of URLs the member will use to communicate with the cluster.

etcd3.apis.kv

class etcd3.apis.kv.KVAPI

Bases: etcd3.apis.base.BaseAPI

compact(revision, physical=False)

Compact compacts the event history in the etcd key-value store. The key-value store should be periodically compacted or the event history will continue to grow indefinitely.

Parameters:

• revision (int) – revision is the key-value store revision for the compaction operation.
• physical (bool) – physical is set so the RPC will wait until the compaction is physically applied to the local database such that compacted entries are totally removed from the backend database. [default: False]

delete_range(key=None, range_end=None, prev_kv=False, prefix=False, all=False, txn_obj=False)

DeleteRange deletes the given range from the key-value store. A delete request increments the revision of the key-value store and generates a delete event in the event history for every deleted key.

Parameters:

• key (str or bytes) – key is the first key to delete in the range.
• range_end (str or bytes) – range_end is the key following the last key to delete for the range [key, range_end). If range_end is not given, the range is defined to contain only the key argument. If range_end is one bit larger than the given key, then the range is all the keys with the prefix (the given key). If range_end is ‘’, the range is all keys greater than or equal to the key argument.
• prev_kv (bool) – If prev_kv is set, etcd gets the previous key-value pairs before deleting it. The previous key-value pairs will be returned in the delete response.
• prefix (bool) – if the key is a prefix [default: False]
• all (bool) – all the keys [default: False]
• txn_obj (bool) – return dict for the txn instead of call the api

put(key, value, lease=0, prev_kv=False, ignore_value=False, ignore_lease=False, txn_obj=False)

Put puts the given key into the key-value store. A put request increments the revision of the key-value store and generates one event in the event history.

Parameters:

• key (str or bytes) – key is the key, in bytes, to put into the key-value store.
• value (str) – value is the value, in bytes, to associate with the key in the key-value store.
• lease (int) – lease is the lease ID to associate with the key in the key-value store. A lease value of 0 indicates no lease.
• prev_kv (bool) – If prev_kv is set, etcd gets the previous key-value pair before changing it. The previous key-value pair will be returned in the put response.
• ignore_value (bool) – If ignore_value is set, etcd updates the key using its current value. Returns an error if the key does not exist.
• ignore_lease (bool) – If ignore_lease is set, etcd updates the key using its current lease. Returns an error if the key does not exist.
• txn_obj (bool) – return dict for the txn instead of call the api

range(key=None, range_end=None, limit=0, revision=None, serializable=False, keys_only=False, count_only=False, min_mod_revision=None, max_mod_revision=None, min_create_revision=None, max_create_revision=None, sort_order=<RangeRequestSortOrder.NONE: 'NONE'>, sort_target=<RangeRequestSortTarget.KEY: 'KEY'>, prefix=False, all=False, txn_obj=False)

Range gets the keys in the range from the key-value store.

Parameters:

• key (str or bytes) – key is the first key for the range. If range_end is not given, the request only looks up key.
• range_end (str or bytes) – range_end is the upper bound on the requested range [key, range_end). If range_end is ‘’, the range is all keys >= key. If range_end is key plus one (e.g., “aa”+1 == “ab”, “aÿ”+1 == “b”), then the range request gets all keys prefixed with key. If both key and range_end are ‘’, then the range request returns all keys.
• limit (int) – limit is a limit on the number of keys returned for the request. When limit is set to 0, it is treated as no limit.
• revision (int) – revision is the point-in-time of the key-value store to use for the range. If revision is less or equal to zero, the range is over the newest key-value store. If the revision has been compacted, ErrCompacted is returned as a response.
• sort_order (RangeRequestSortOrder) – sort_order is the order for returned sorted results.
• sort_target (RangeRequestSortTarget) – sort_target is the key-value field to use for sorting.
• serializable (bool) – serializable sets the range request to use serializable member-local reads. Range requests are linearizable by default; linearizable requests have higher latency and lower throughput than serializable requests but reflect the current consensus of the cluster. For better performance, in exchange for possible stale reads, a serializable range request is served locally without needing to reach consensus with other nodes in the cluster.
• keys_only (bool) – keys_only when set returns only the keys and not the values.
• count_only (bool) – count_only when set returns only the count of the keys in the range.
• min_mod_revision (int) – min_mod_revision is the lower bound for returned key mod revisions; all keys with lesser mod revisions will be filtered away.
• max_mod_revision (int) – max_mod_revision is the upper bound for returned key mod revisions; all keys with greater mod revisions will be filtered away.
• min_create_revision (int) – min_create_revision is the lower bound for returned key create revisions; all keys with lesser create revisions will be filtered away.
• max_create_revision (int) – max_create_revision is the upper bound for returned key create revisions; all keys with greater create revisions will be filtered away.
• prefix (bool) – if the key is a prefix [default: False]
• all (bool) – all the keys [default: False]
• txn_obj (bool) – return dict for the txn instead of call the api

txn(compare, success, failure)

Txn processes multiple requests in a single transaction. A txn request increments the revision of the key-value store and generates events with the same revision for every completed request. It is not allowed to modify the same key several times within one txn.

Parameters:

• compare (list of dict) – compare is a list of predicates representing a conjunction of terms. If the comparisons succeed, then the success requests will be processed in order, and the response will contain their respective responses in order. If the comparisons fail, then the failure requests will be processed in order, and the response will contain their respective responses in order.
• success (list of dict) – success is a list of requests which will be applied when compare evaluates to true.
• failure (list of dict) – failure is a list of requests which will be applied when compare evaluates to false.

etcd3.apis.lease

class etcd3.apis.lease.LeaseAPI

Bases: etcd3.apis.base.BaseAPI

lease_revoke(ID)

LeaseRevoke revokes a lease. All keys attached to the lease will expire and be deleted.

Parameters:ID (int) – ID is the lease ID to revoke. When the ID is revoked, all associated keys will be deleted.

lease_time_to_live(ID, keys=False)

LeaseTimeToLive retrieves lease information.

Parameters:

• ID (int) – ID is the lease ID for the lease.
• keys (bool) – keys is true to query all the keys attached to this lease.

lease_grant(TTL, ID=0)

LeaseGrant creates a lease which expires if the server does not receive a keepAlive within a given time to live period. All keys attached to the lease will be expired and deleted if the lease expires. Each expired key generates a delete event in the event history.

Parameters:

• TTL (int) – TTL is the advisory time-to-live in seconds. the minimum value is 2s
• ID (int) – ID is the requested ID for the lease. If ID is set to 0, the lessor chooses an ID.

lease_keep_alive(data)

PLEASE USE THE TRANSACTION UTIL

LeaseKeepAlive keeps the lease alive by streaming keep alive requests from the client to the server and streaming keep alive responses from the server to the client.

Parameters:data – ID stream inputs of the lease to keep alive. which not works for now

lease_keep_alive_once(ID)

this api only send keep alive once instead of streaming send multiple IDs

LeaseKeepAlive keeps the lease alive by streaming keep alive requests from the client to the server and streaming keep alive responses from the server to the client.

Parameters:ID (int) – ID is the lease ID for the lease to keep alive.

etcd3.apis.lock

class etcd3.apis.lock.LockAPI

Bases: etcd3.apis.base.BaseAPI

lock(name, lease=0)

Lock acquires a distributed shared lock on a given named lock. On success, it will return a unique key that exists so long as the lock is held by the caller. This key can be used in conjunction with transactions to safely ensure updates to etcd only occur while holding lock ownership. The lock is held until Unlock is called on the key or the lease associate with the owner expires.

Parameters:

• name (str) – name is the identifier for the distributed shared lock to be acquired.
• lease (int) – lease is the lease ID to associate with the key in the key-value store. A lease value of 0 indicates no lease.

unlock(key)

Unlock takes a key returned by Lock and releases the hold on lock. The next Lock caller waiting for the lock will then be woken up and given ownership of the lock.

Parameters:

• key (str or bytes) – key is the lock ownership key granted by Lock.
• lease (int) – lease is the lease ID to associate with the key in the key-value store. A lease value of 0 indicates no lease.

etcd3.apis.maintenance

class etcd3.apis.maintenance.MaintenanceAPI

Bases: etcd3.apis.base.BaseAPI

alarm(memberID, action=<AlarmRequestAlarmAction.GET: 'GET'>, alarm=<etcdserverpbAlarmType.NONE: 'NONE'>)

Alarm activates, deactivates, and queries alarms regarding cluster health.

Parameters:

• action (AlarmRequestAlarmAction) – action is the kind of alarm request to issue. The action may GET alarm statuses, ACTIVATE an alarm, or DEACTIVATE a raised alarm.
• memberID (int) – memberID is the ID of the member associated with the alarm. If memberID is 0, the alarm request covers all members.
• alarm (etcdserverpbAlarmType) – alarm is the type of alarm to consider for this request.

alarm_get(memberID, alarm)

Queries alarms regarding cluster health.

Parameters:

• memberID (int) – memberID is the ID of the member associated with the alarm. If memberID is 0, the alarm request covers all members.
• alarm (etcdserverpbAlarmType) – alarm is the type of alarm to consider for this request.

alarm_activate(memberID, alarm)

Activates alarms regarding cluster health.

Parameters:

• memberID (int) – memberID is the ID of the member associated with the alarm. If memberID is 0, the alarm request covers all members.
• alarm (etcdserverpbAlarmType) – alarm is the type of alarm to consider for this request.

alarm_deactivate(memberID, alarm)

Deactivates alarms regarding cluster health.

Parameters:

• memberID (int) – memberID is the ID of the member associated with the alarm. If memberID is 0, the alarm request covers all members.
• alarm (etcdserverpbAlarmType) – alarm is the type of alarm to consider for this request.

defragment()

Defragment defragments a member’s backend database to recover storage space.

hash()

Hash returns the hash of the local KV state for consistency checking purpose. This is designed for testing; do not use this in production when there are ongoing transactions.

snapshot()

Snapshot sends a snapshot of the entire backend from a member over a stream to a client.

status()

Status gets the status of the member.

etcd3.apis.watch

class etcd3.apis.watch.WatchAPI

Bases: etcd3.apis.base.BaseAPI

watch(create_request=None, cancel_request=None, **kwargs)

PLEASE USE THE WATCH UTIL

Watch watches for events happening or that have happened. Both input and output are streams; the input stream is for creating and canceling watchers and the output stream sends events. One watch RPC can watch on multiple key ranges, streaming events for several watches at once. The entire event history can be watched starting from the last compaction revision.

Parameters:

• create_request (dict) – None
• cancel_request (dict) – None

watch_create(key=None, range_end=None, start_revision=None, progress_notify=None, prev_kv=None, prefix=False, all=False, no_put=False, no_delete=False, **kwargs)

WatchCreate creates a watch stream on given key or key_range

Parameters:

• key (str or bytes) – key is the key to register for watching.
• range_end (str or bytes) – range_end is the end of the range [key, range_end) to watch. If range_end is not given, only the key argument is watched. If range_end is equal to ‘’, all keys greater than or equal to the key argument are watched. If the range_end is one bit larger than the given key, then all keys with the prefix (the given key) will be watched.
• start_revision (int) – start_revision is an optional revision to watch from (inclusive). No start_revision is “now”.
• progress_notify (bool) – progress_notify is set so that the etcd server will periodically send a WatchResponse with no events to the new watcher if there are no recent events. It is useful when clients wish to recover a disconnected watcher starting from a recent known revision. The etcd server may decide how often it will send notifications based on current load.
• prev_kv (bool) – If prev_kv is set, created watcher gets the previous KV before the event happens. If the previous KV is already compacted, nothing will be returned.
• prefix (bool) – if the key is a prefix [default: False]
• all (bool) – all the keys [default: False]
• no_put (bool) – filter out the put events at server side before it sends back to the watcher. [default: False]
• no_delete (bool) – filter out the delete events at server side before it sends back to the watcher. [default: False]

watch_cancel(watch_id, **kwargs)

NOT SUPPORTED UNDER ETCD 3.3-

https://github.com/coreos/etcd/pull/9065

WatchCancel cancels a watch stream

Parameters:watch_id (int) – watch_id is the watcher id to cancel so that no more events are transmitted.

etcd3.apis.extra

class etcd3.apis.extra.EtcdVersion(etcdserver, etcdcluster)

Bases: tuple

etcdcluster

Alias for field number 1

etcdserver

Alias for field number 0

class etcd3.apis.extra.ExtraAPI

Bases: etcd3.apis.base.BaseAPI

version()

get the version of etcdserver and etcdcluster

Returns:EtcdVersion

health()

get the health of etcd-server

Returns:EtcdVersion

metrics_raw()

get the raw /metrics text

Returns:str

metrics()

get the modelized metrics parsed by prometheus_client