Skip to content

feat: Add election service methods #13

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
rapsealk wants to merge 12 commits into
base: main
Choose a base branch
from
+420 −45
Open

feat: Add election service methods #13

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
5cc24cf
feat: Add etcd election APIs
rapsealk Jul 28, 2022
859fb9a
fix: Delete unnecessary import (flake8)
rapsealk Jul 28, 2022
49013c2
fix: flake8 error
rapsealk Jul 28, 2022
73a9b26
docs: Add sphinx-generated document
rapsealk Jul 28, 2022
f4782c1
feat: Add testcase for election service methods
rapsealk Jul 29, 2022
0f3086d
docs: Add sphinx-generated document
rapsealk Jul 29, 2022
6eb9b00
fix: mypy error
rapsealk Jul 29, 2022
7d290a4
fix: Encapsulate encode/decode process with optional `encoding` argument
rapsealk Jul 29, 2022
204f67d
fix: mypy error
rapsealk Jul 29, 2022
0405183
docs: Update sphinx-generated document
rapsealk Jul 29, 2022
26d391b
fix: Cleanup granted leases after test is done
rapsealk Jul 29, 2022
df090e5
fix: Change variable name to prevent type conflict on reassignment
rapsealk Aug 1, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
183 changes: 143 additions & 40 deletions docs/references.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
Pure python asyncio Etcd client.


### _class_ etcetra.client.EtcdClient(addr: etcetra.types.HostPortPair, credentials: Optional[etcetra.types.EtcdCredential] = None, secure: bool = False, encoding: str = 'utf-8')
### _class_ etcetra.client.EtcdClient(addr: HostPortPair, credentials: Optional[EtcdCredential] = None, secure: bool = False, encoding: str = 'utf-8')
Wrapper class of underlying actual Etcd API implementations (KV, Watch, Txn, …).
In most cases, user can perform most of the jobs by creating EtcdClient object.

Expand Down Expand Up @@ -64,10 +64,36 @@ Acquired lock will automatically released when user exits with context.



### _class_ etcetra.client.EtcdCommunicator(channel: grpc.aio._base_channel.Channel, encoding: str = 'utf-8')
### _class_ etcetra.client.EtcdCommunicator(channel: Channel, encoding: str = 'utf-8')
Performs actual API calls to Etcd cluster and returns result.


#### create_lease_keepalive_task(id: int, interval: float)
Creates asyncio Task which sends Keepalive request to given lease ID.


* **Parameters**


* **id** – Lease ID to send Keepalive request.


* **interval** – Interval to send Keepalive request.



* **Returns**

**task**



* **Return type**

asyncio.Task



#### _async_ delete(key: str, prev_kv: bool = False, encoding: Optional[str] = None)
Deletes the given key the key-value store.
A delete request increments the revision of the key-value store
Expand Down Expand Up @@ -179,6 +205,109 @@ and generates a delete event in the event history for every deleted key.



#### _async_ election_campaign(name: str, lease_id: int, value: Optional[str] = None, encoding: Optional[str] = None)
Campaign waits to acquire leadership in an election,
returning a LeaderKey representing the leadership if successful.
The LeaderKey can then be used to issue new values on the election,
transactionally guard API requests on leadership still being held,
and resign from the election.


* **Parameters**


* **name** – Name is the election’s identifier for the campaign.


* **lease_id** – LeaseID is the ID of the lease attached to leadership of the election.
If the lease expires or is revoked before resigning leadership,
then the leadership is transferred to the next campaigner, if any.


* **value** – Value is the initial proclaimed value set when the campaigner wins the election.



* **Returns**

**leader** – Leader describes the resources used for holding leadereship of the election.



* **Return type**

etcetra.types.LeaderKey



#### _async_ election_leader(name: str, encoding: Optional[str] = None)
Returns the current election proclamation, if any.


* **Parameters**

**name** – Name is the election identifier for the leadership information.



* **Returns**

LeaderKey is the key-value pair representing the latest leader update



* **Return type**

leader_key



#### _async_ election_observe(name: str, encoding: Optional[str] = None)
Observe streams election proclamations in-order as made by the election’s elected leaders.


* **Parameters**

**name** – Name is the election identifier for the leadership information.



* **Returns**

**event** – A KeyValue object containing event information.



* **Return type**

AsyncIterator[KeyValue]



#### _async_ election_proclaim(leader: LeaderKey, value: str, encoding: Optional[str] = None)
Proclaim updates the leader’s posted value with a new value.


* **Parameters**


* **leader** – Leader is the leadership hold on the election.


* **value** – Value is an update meant to overwrite the leader’s current value.



#### _async_ election_resign(leader: LeaderKey, encoding: Optional[str] = None)
Resign releases election leadership so other campaigners may acquire leadership on the election.


* **Parameters**

**leader** – Leader is the leadership to relinquish by resignation.



#### _async_ get(key: str, max_create_revision: Optional[str] = None, max_mod_revision: Optional[str] = None, min_create_revision: Optional[str] = None, min_mod_revision: Optional[str] = None, revision: Optional[str] = None, encoding: Optional[str] = None)
Gets value associated with given key from the key-value store.

Expand Down Expand Up @@ -229,7 +358,7 @@ Gets value associated with given key from the key-value store.



#### _async_ get_prefix(key: str, max_create_revision: Optional[str] = None, max_mod_revision: Optional[str] = None, min_create_revision: Optional[str] = None, min_mod_revision: Optional[str] = None, revision: Optional[str] = None, sort_order: etcetra.types.RangeRequestSortOrder = RangeRequestSortOrder.NONE, sort_target: etcetra.types.RangeRequestSortTarget = RangeRequestSortTarget.KEY, encoding: Optional[str] = None)
#### _async_ get_prefix(key: str, max_create_revision: Optional[str] = None, max_mod_revision: Optional[str] = None, min_create_revision: Optional[str] = None, min_mod_revision: Optional[str] = None, revision: Optional[str] = None, sort_order: RangeRequestSortOrder = RangeRequestSortOrder.NONE, sort_target: RangeRequestSortTarget = RangeRequestSortTarget.KEY, encoding: Optional[str] = None)
Gets the key-value in dictionary from the key-value store with given key prefix.
i.e. get_prefix(‘/sorna/local’) call looks up all keys which has /sorna/local prefix.

Expand Down Expand Up @@ -286,7 +415,7 @@ i.e. get_prefix(‘/sorna/local’) call looks up all keys which has /sorna/loca



#### _async_ get_range(key: str, range_end: str, limit: Optional[str] = None, max_create_revision: Optional[str] = None, max_mod_revision: Optional[str] = None, min_create_revision: Optional[str] = None, min_mod_revision: Optional[str] = None, revision: Optional[str] = None, sort_order: etcetra.types.RangeRequestSortOrder = RangeRequestSortOrder.NONE, sort_target: etcetra.types.RangeRequestSortTarget = RangeRequestSortTarget.KEY, encoding: Optional[str] = None)
#### _async_ get_range(key: str, range_end: str, limit: Optional[str] = None, max_create_revision: Optional[str] = None, max_mod_revision: Optional[str] = None, min_create_revision: Optional[str] = None, min_mod_revision: Optional[str] = None, revision: Optional[str] = None, sort_order: RangeRequestSortOrder = RangeRequestSortOrder.NONE, sort_target: RangeRequestSortTarget = RangeRequestSortTarget.KEY, encoding: Optional[str] = None)
Gets the key-value in dictionary from the key-value store with keys in [key, range_end) range.


Expand Down Expand Up @@ -374,7 +503,7 @@ Each expired key generates a delete event in the event history.



#### _async_ keys_prefix(key: str, max_create_revision: Optional[str] = None, max_mod_revision: Optional[str] = None, min_create_revision: Optional[str] = None, min_mod_revision: Optional[str] = None, revision: Optional[str] = None, sort_order: etcetra.types.RangeRequestSortOrder = RangeRequestSortOrder.NONE, sort_target: etcetra.types.RangeRequestSortTarget = RangeRequestSortTarget.KEY, encoding: Optional[str] = None)
#### _async_ keys_prefix(key: str, max_create_revision: Optional[str] = None, max_mod_revision: Optional[str] = None, min_create_revision: Optional[str] = None, min_mod_revision: Optional[str] = None, revision: Optional[str] = None, sort_order: RangeRequestSortOrder = RangeRequestSortOrder.NONE, sort_target: RangeRequestSortTarget = RangeRequestSortTarget.KEY, encoding: Optional[str] = None)
Gets the keys which has given prefix from the key-value store.


Expand Down Expand Up @@ -430,7 +559,7 @@ Gets the keys which has given prefix from the key-value store.



#### _async_ keys_range(key: str, range_end: str, limit: Optional[str] = None, max_create_revision: Optional[str] = None, max_mod_revision: Optional[str] = None, min_create_revision: Optional[str] = None, min_mod_revision: Optional[str] = None, revision: Optional[str] = None, serializable: bool = True, sort_order: etcetra.types.RangeRequestSortOrder = RangeRequestSortOrder.NONE, sort_target: etcetra.types.RangeRequestSortTarget = RangeRequestSortTarget.KEY, encoding: Optional[str] = None)
#### _async_ keys_range(key: str, range_end: str, limit: Optional[str] = None, max_create_revision: Optional[str] = None, max_mod_revision: Optional[str] = None, min_create_revision: Optional[str] = None, min_mod_revision: Optional[str] = None, revision: Optional[str] = None, serializable: bool = True, sort_order: RangeRequestSortOrder = RangeRequestSortOrder.NONE, sort_target: RangeRequestSortTarget = RangeRequestSortTarget.KEY, encoding: Optional[str] = None)
Gets the keys in the range from the key-value store.


Expand Down Expand Up @@ -489,32 +618,6 @@ Gets the keys in the range from the key-value store.



#### _async_ lease_keepalive(id: int, interval: float)
Creates asyncio Task which sends Keepalive request to given lease ID.


* **Parameters**


* **id** – Lease ID to send Keepalive request.


* **interval** – Interval to send Keepalive request.



* **Returns**

**task**



* **Return type**

asyncio.Task



#### _async_ put(key: str, value: Optional[str], lease: Optional[int] = None, prev_kv: bool = False, encoding: Optional[str] = None)
Puts given key into the key-value store.

Expand Down Expand Up @@ -566,7 +669,7 @@ Revokes a lease. All keys attached to the lease will expire and be deleted.



#### _async_ txn(txn_builder: Callable[[etcetra.client.EtcdTransactionAction], None], encoding: Optional[str] = None)
#### _async_ txn(txn_builder: Callable[[EtcdTransactionAction], None], encoding: Optional[str] = None)
A shorthand helper for Txn, with no compare arguments.
This can be helpful when user just wants to execute transaction without
any conditions.
Expand Down Expand Up @@ -608,7 +711,7 @@ any conditions.



#### _async_ txn_compare(compares: List[rpc_pb2.Compare], txn_builder: Callable[[etcetra.client.EtcdTransactionAction, etcetra.client.EtcdTransactionAction], None], encoding: Optional[str] = None)
#### _async_ txn_compare(compares: List[Compare], txn_builder: Callable[[EtcdTransactionAction, EtcdTransactionAction], None], encoding: Optional[str] = None)
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.
Expand Down Expand Up @@ -667,7 +770,7 @@ It is not allowed to modify the same key several times within one txn.



#### watch(key: str, ready_event: Optional[asyncio.locks.Event] = None, filters: Optional[List[etcetra.types.WatchCreateRequestFilterType]] = None, prev_kv: bool = False, progress_notify: bool = False, start_revision: Optional[int] = None, watch_id: Optional[int] = None, encoding: Optional[str] = None)
#### watch(key: str, ready_event: Optional[Event] = None, filters: Optional[List[WatchCreateRequestFilterType]] = None, prev_kv: bool = False, progress_notify: bool = False, start_revision: Optional[int] = None, watch_id: Optional[int] = None, encoding: Optional[str] = None)
Async iterator which 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.
Expand Down Expand Up @@ -729,7 +832,7 @@ The entire event history can be watched starting from the last compaction revisi



#### watch_prefix(key: str, ready_event: Optional[asyncio.locks.Event] = None, filters: Optional[List[etcetra.types.WatchCreateRequestFilterType]] = None, prev_kv: bool = False, progress_notify: bool = True, start_revision: Optional[int] = None, watch_id: Optional[int] = None, encoding: Optional[str] = None)
#### watch_prefix(key: str, ready_event: Optional[Event] = None, filters: Optional[List[WatchCreateRequestFilterType]] = None, prev_kv: bool = False, progress_notify: bool = True, start_revision: Optional[int] = None, watch_id: Optional[int] = None, encoding: Optional[str] = None)
Watches for events happening or that have happened along keys with given prefix.
Both input and output are streams; the input stream is for creating and canceling watchers
and the output stream sends events.
Expand Down Expand Up @@ -801,7 +904,7 @@ A delete request increments the revision of the key-value store
and generates a delete event in the event history for every deleted key.


#### get(key: str, limit: Optional[str] = None, max_create_revision: Optional[str] = None, max_mod_revision: Optional[str] = None, min_create_revision: Optional[str] = None, min_mod_revision: Optional[str] = None, revision: Optional[str] = None, serializable: bool = True, sort_order: etcetra.types.RangeRequestSortOrder = RangeRequestSortOrder.NONE, sort_target: etcetra.types.RangeRequestSortTarget = RangeRequestSortTarget.KEY, encoding: Optional[str] = None)
#### get(key: str, limit: Optional[str] = None, max_create_revision: Optional[str] = None, max_mod_revision: Optional[str] = None, min_create_revision: Optional[str] = None, min_mod_revision: Optional[str] = None, revision: Optional[str] = None, serializable: bool = True, sort_order: RangeRequestSortOrder = RangeRequestSortOrder.NONE, sort_target: RangeRequestSortTarget = RangeRequestSortTarget.KEY, encoding: Optional[str] = None)
Gets the keys in the range from the key-value store.


Expand All @@ -822,7 +925,7 @@ An enumeration.
### _class_ etcetra.types.CompareKey(key: 'str', target_lease: 'Optional[int]' = None, mod_revision: 'Optional[int]' = None, range_end: 'Optional[str]' = None, target_version: 'Optional[int]' = None, encoding: 'str' = 'utf-8')

### etcetra.types.DeleteRangeRequestType()
alias of `rpc_pb2.DeleteRangeRequest`
alias of `DeleteRangeRequest`


### _class_ etcetra.types.EtcdCredential(username: 'str', password: 'str')
Expand All @@ -832,7 +935,7 @@ alias of `rpc_pb2.DeleteRangeRequest`
### _class_ etcetra.types.HostPortPair(host: 'str', port: 'int')

### etcetra.types.PutRequestType()
alias of `rpc_pb2.PutRequest`
alias of `PutRequest`


### _class_ etcetra.types.RangeRequestSortOrder(value)
Expand All @@ -844,7 +947,7 @@ An enumeration.


### etcetra.types.RangeRequestType()
alias of `rpc_pb2.RangeRequest`
alias of `RangeRequest`


### _class_ etcetra.types.TxnReturnType(values, success)
Expand Down
2 changes: 1 addition & 1 deletion scripts/compile_protobuf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -164,7 +164,7 @@ def main(version: str, repo_path: Optional[Path] = None):
parser.add_argument('version', type=str, help='target etcd version')
parser.add_argument(
'--repository-path', type=str,
help='git repository folder path of etcd source code to use. Ff not supplied, '
help='git repository folder path of etcd source code to use. If not supplied, '
Copy link
Member

@kyujin-cho kyujin-cho Jul 28, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oops

'this script will clone fresh repo on temporary directory and remove it upon exit.')
args = parser.parse_args()

Expand Down
Loading