### Install etcd3-gateway with virtualenvwrapper

Source: https://docs.openstack.org/etcd3gw/latest/installation.html

Installation command sequence when using virtualenvwrapper for environment management.

```bash
$ mkvirtualenv etcd3-gateway
$ pip install etcd3-gateway
```

--------------------------------

### Install etcd3-gateway via pip

Source: https://docs.openstack.org/etcd3gw/latest/installation.html

Standard installation command for the etcd3-gateway package.

```bash
$ pip install etcd3-gateway
```

--------------------------------

### Get Keys by Prefix with Metadata

Source: https://docs.openstack.org/etcd3gw/latest/_modules/etcd3gw/client.html

Fetches a range of keys that start with a given prefix, including their metadata. Ideal for retrieving related configuration or data.

```python
return self.get(
            key_prefix,
            metadata=True,
            range_end=_increment_last_byte(key_prefix),
            sort_order=sort_order,
            sort_target=sort_target,
        )
```

--------------------------------

### Basic etcd3gw Client Usage

Source: https://docs.openstack.org/etcd3gw/latest/usage.html

Demonstrates basic operations: initializing the client, putting and getting keys, and retrieving all keys. Ensure etcd is running on localhost:2379.

```python
from etcd3gw.client import Etcd3Client

client = Etcd3Client(host='localhost', port=2379)

# Put key
client.put(key='foo', value='bar')

# Get key
client.get(key='foo')

# Get all keys
client.get_all()
```

--------------------------------

### GET /get

Source: https://docs.openstack.org/etcd3gw/latest/api/etcd3gw.client.html

Retrieves keys from the etcd key-value store.

```APIDOC
## GET /get

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

### Parameters
- **key** (str) - Required - Key to retrieve
- **metadata** (bool) - Optional - Whether to return metadata
- **sort_order** (str) - Optional - 'ascend', 'descend', or None
- **sort_target** (str) - Optional - 'key', 'version', 'create', 'mod', or 'value'
- **range_end** (str) - Optional - End of range

### Response
#### Success Response (200)
- **result** (list) - List of bytes or tuples containing key-value pairs
```

--------------------------------

### etcd3gw Watcher Example

Source: https://docs.openstack.org/etcd3gw/latest/usage.html

Illustrates how to set up a watch on a specific key. The watcher blocks until an event occurs, and the watch can be cancelled using the provided cancel function. The event object contains details about the change.

```python
# Use watch
watcher, watch_cancel = client.watch(key='KEY')

for event in watcher: # blocks until event comes, cancel via watch_cancel()
    print(event)
    # modify event: {'kv': {'mod_revision': '8', 'version': '3', 'value': 'NEW_VAL', 'create_revision': '2', 'key': 'KEY', 'lease': '7587847878767953426'}}
```

--------------------------------

### Get All Keys with Metadata

Source: https://docs.openstack.org/etcd3gw/latest/_modules/etcd3gw/client.html

Retrieves all keys along with their metadata. Useful for full data dumps or initial synchronization.

```python
return self.get(
            key='\0',
            metadata=True,
            sort_order=sort_order,
            sort_target=sort_target,
            range_end='\0',
        )
```

--------------------------------

### Watch Key Prefix Once

Source: https://docs.openstack.org/etcd3gw/latest/_modules/etcd3gw/client.html

Watches a range of keys with a specified prefix and returns the first event. Supports optional timeout, start revision, and filters.

```python
def watch_prefix_once(
    self,
    key_prefix: str,
    timeout: float | int | None = None,
    *,
    start_revision: int | None = None,
    progress_notify: bool | None = None,
    filters: list[Literal['NOPUT', 'NODELETE']] | None = None,
    prev_kv: bool | None = None,
    watch_id: int | None = None,
    fragment: bool | None = None,
    **kwargs: Any,
) -> Event:
    """Watches a range of keys with a prefix, similar to watch_once.

    :param key_prefix: key prefix to watch
    :param timeout: (optional) timeout in seconds.
    :param start_revision: revision to watch from
    :param progress_notify: get periodic progress notifications
    :param filters: filter types (``"NOPUT"`` or ``"NODELETE"``)
    :param prev_kv: return the previous key-value on event
    :param watch_id: ID to assign to this watcher; 0 means auto-assign
        (etcd >= 3.4)
    :param fragment: split large watch responses into multiple smaller
        responses (etcd >= 3.4)
    """
    return self.watch_once(
        key_prefix,
        timeout=timeout,
        range_end=_encode(_increment_last_byte(key_prefix)),
        start_revision=start_revision,
        progress_notify=progress_notify,
        filters=filters,
        prev_kv=prev_kv,
        **kwargs,
    )
```

--------------------------------

### Construct Full URL for v3 API

Source: https://docs.openstack.org/etcd3gw/latest/_modules/etcd3gw/client.html

Constructs a complete URL for the v3 API by combining the base URL, API path, and a given path. Ensures the path does not start with a leading slash.

```python
def _get_url(self, path: str) -> str:
        """Construct a full url to the v3 API given a specific path

        :param path:
        :return: url
        """
        return self.base_url + self.api_path + path.lstrip("/")
```

--------------------------------

### Get Keys Associated with Lease

Source: https://docs.openstack.org/etcd3gw/latest/_modules/etcd3gw/lease.html

Retrieves a list of keys currently associated with a specific lease. This method makes a synchronous HTTP request.

```python
def keys(self) -> list[bytes]:
    """Get the keys associated with this lease.

    :return:
    """
    result = self.client.post(
        self.client.get_url("/kv/lease/timetolive"),
        json={"ID": self.id, "keys": True},
    )
    keys = result['keys'] if 'keys' in result else []
    return [_decode(key) for key in keys]
```

--------------------------------

### Get Lease Time To Live (TTL)

Source: https://docs.openstack.org/etcd3gw/latest/_modules/etcd3gw/lease.html

Retrieves lease information, specifically the Time To Live (TTL). This method makes a synchronous HTTP request by default.

```python
def ttl(self) -> int:
    """LeaseTimeToLive retrieves lease information.

    This method makes a synchronous HTTP request by default. To make an
    asynchronous HTTP request, please define a `callback` function
    to be invoked when receiving the response.

    :return:
    """
    result = self.client.post(
        self.client.get_url("/kv/lease/timetolive"), json={"ID": self.id}
    )
    return int(result['TTL'])
```

--------------------------------

### Etcd3Client Creation

Source: https://docs.openstack.org/etcd3gw/latest/_modules/etcd3gw/client.html

This snippet shows how to create an instance of the Etcd3Client, which is the main entry point for interacting with etcd.

```APIDOC
## Etcd3Client Creation

### Description
Instantiates an Etcd3Client to connect to the etcd server.

### Method
`client()`

### Parameters
#### Query Parameters
- **host** (string) - Optional - The hostname of the etcd server. Defaults to 'localhost'.
- **port** (integer) - Optional - The port of the etcd server. Defaults to 2379.
- **ca_cert** (string) - Optional - Path to the CA certificate file.
- **cert_key** (string) - Optional - Path to the client certificate key file.
- **cert_cert** (string) - Optional - Path to the client certificate file.
- **timeout** (float) - Optional - Connection timeout in seconds.
- **protocol** (string) - Optional - The protocol to use (e.g., 'http', 'https'). Defaults to 'http'.
- **api_path** (string) - Optional - The API path for etcd. Defaults to '/v3'.
- **session** (requests.Session) - Optional - A pre-configured requests Session object.

### Request Example
```python
from etcd3gw import client

etcd_client = client(host='my-etcd-host', port=2379)
```

### Response
#### Success Response (200)
- **Etcd3Client** (object) - An initialized Etcd3Client instance.
```

--------------------------------

### Get etcd Cluster Member Status

Source: https://docs.openstack.org/etcd3gw/latest/_modules/etcd3gw/client.html

Retrieves the status of an etcd cluster member. This is done by making a POST request to the '/maintenance/status' endpoint.

```python
def status(self) -> StatusResponse:
        """Status gets the status of the etcd cluster member.

        :return: json response
        """
        return cast(
            StatusResponse,
            self.post(self.get_url("/maintenance/status"), json={}),
        )
```

--------------------------------

### Create Etcd3Client Instance

Source: https://docs.openstack.org/etcd3gw/latest/_modules/etcd3gw/client.html

Instantiates an Etcd3Client with specified connection parameters. Supports custom host, port, and authentication certificates.

```python
def client(
    host: str = 'localhost',
    port: int = 2379,
    ca_cert: str | None = None,
    cert_key: str | None = None,
    cert_cert: str | None = None,
    timeout: float | None = None,
    protocol: str = "http",
    api_path: str | None = DEFAULT_API_PATH,
    session: requests.Session | None = None,
) -> Etcd3Client:
    """Return an instance of an Etcd3Client."""
    return Etcd3Client(
        host=host,
        port=port,
        ca_cert=ca_cert,
        cert_key=cert_key,
        cert_cert=cert_cert,
        timeout=timeout,
        api_path=api_path,
        protocol=protocol,
        session=session,
    )
```

--------------------------------

### etcd3gw Lease Management

Source: https://docs.openstack.org/etcd3gw/latest/usage.html

Shows how to create a lease with a specified TTL, associate a key with that lease, and then refresh or list keys associated with the lease. Leases are crucial for time-to-live based key expiration.

```python
# Create lease and use it
lease = client.lease(ttl=100)

client.put(key='foo', value='bar', lease=lease)

# Get lease keys
lease.keys()

# Refresh lease
lease.refresh()
```

--------------------------------

### POST /create

Source: https://docs.openstack.org/etcd3gw/latest/api/etcd3gw.client.html

Atomically create a key in etcd only if it does not already exist.

```APIDOC
## POST /create

### Description
Atomically create the given key only if the key doesn’t exist. This verifies that the create_revision of a key equals 0, then creates the key with the value.

### Parameters
- **key** (str) - Required - Key in etcd to create
- **value** (str) - Required - Value of the key
- **lease** (Lease) - Optional - Lease to connect with

### Response
#### Success Response (200)
- **status** (bool) - True if the create was successful, False otherwise
```

--------------------------------

### Etcd3Client Initialization and API Path Discovery

Source: https://docs.openstack.org/etcd3gw/latest/_modules/etcd3gw/client.html

Details the constructor for the Etcd3Client and the process of discovering the etcd API path.

```APIDOC
## Etcd3Client Initialization

### Description
Initializes a client to interact with etcd3's grpc-gateway /v3 HTTP API.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Constructor Signature
```python
Etcd3Client(
    host: str = 'localhost',
    port: int = 2379,
    protocol: str = "http",
    ca_cert: str | None = None,
    cert_key: str | None = None,
    cert_cert: str | None = None,
    timeout: float | int | None = None,
    api_path: str | None = DEFAULT_API_PATH,
    session: requests.Session | None = None,
)
```

### Parameters Details
- **host** (str) - Optional - The etcd host. Defaults to 'localhost'.
- **port** (int) - Optional - The etcd port. Defaults to 2379.
- **protocol** (str) - Optional - The protocol to use ('http' or 'https'). Defaults to 'http'.
- **ca_cert** (str | None) - Optional - Path to the CA certificate for SSL/TLS verification.
- **cert_key** (str | None) - Optional - Path to the client certificate key.
- **cert_cert** (str | None) - Optional - Path to the client certificate.
- **timeout** (float | int | None) - Optional - The request timeout in seconds.
- **api_path** (str | None) - Optional - The API path. Defaults to auto-discovery via `ETCD3GW_API_PATH` environment variable.
- **session** (requests.Session | None) - Optional - An existing `requests.Session` object. If not provided, a new session is created.

## API Path Discovery

### Description
This method automatically discovers the correct etcd API path (e.g., /v3/, /v3beta/, /v3alpha/) based on the etcd cluster version.

### Method
GET

### Endpoint
`/version`

### Parameters
None

### Response
#### Success Response (200)
- **etcdserver** (str) - The etcd server version string.

#### Response Example
```json
{
  "etcdserver": "3.5.0",
  "etcdcluster": "3.5.0"
}
```

### Error Handling
- **ConnectionTimeoutError**: Raised if the request times out.
- **ConnectionFailedError**: Raised if a connection error occurs.
- **Etcd3Exception**: Raised for non-200 status codes or malformed responses.
```

--------------------------------

### Initialize etcd3gw Client

Source: https://docs.openstack.org/etcd3gw/latest/api/etcd3gw.client.html

Initializes a new instance of the Etcd3Client to interact with an etcd server.

```APIDOC
## client(host, port, ca_cert, cert_key, cert_cert, timeout, protocol, api_path, session)

### Description
Returns an instance of an Etcd3Client to communicate with the etcd server.

### Parameters
#### Query Parameters
- **host** (str) - Optional - Hostname of the etcd server (default: 'localhost')
- **port** (int) - Optional - Port of the etcd server (default: 2379)
- **ca_cert** (str) - Optional - Path to CA certificate
- **cert_key** (str) - Optional - Path to certificate key
- **cert_cert** (str) - Optional - Path to certificate
- **timeout** (float) - Optional - Request timeout
- **protocol** (str) - Optional - Protocol to use (default: 'http')
- **api_path** (str) - Optional - Custom API path
- **session** (Session) - Optional - Requests session object
```

--------------------------------

### Initialize Lease Object

Source: https://docs.openstack.org/etcd3gw/latest/_modules/etcd3gw/lease.html

Initializes a Lease object with an ID and a client instance. This object is used to manage leases in etcd.

```python
class Lease:
    def __init__(self, id: int, client: '_client_module.Etcd3Client') -> None:
        """Lease object for expiring keys

        :param id:
        :param client:
        """
        self.id = id
        self.client: _client_module.Etcd3Client = client
```

--------------------------------

### Initialize Lock

Source: https://docs.openstack.org/etcd3gw/latest/_modules/etcd3gw/lock.html

Create a lock instance with a specified name and TTL. Requires an etcd3gw client instance.

```python
def __init__(
        self,
        name: str,
        ttl: int = DEFAULT_TIMEOUT,
        *,
        client: '_client_module.Etcd3Client',
    ) -> None:
        """Create a lock using the given name with specified timeout

        :param name:
        :param ttl:
        :param client:
        """
        self.name = name
        self.ttl = ttl
        self.client: _client_module.Etcd3Client = client
        self.key = LOCK_PREFIX + self.name
        self.lease: _lease_module.Lease | None = None
        self._uuid = str(uuid.uuid1())

```

--------------------------------

### Watch a key once

Source: https://docs.openstack.org/etcd3gw/latest/_modules/etcd3gw/client.html

Watches a key and returns after the first event is received.

```python
    def watch_once(
        self,
        key: str,
        timeout: float | int | None = None,
        *,
        start_revision: int | None = None,
        progress_notify: bool | None = None,
        filters: list[Literal['NOPUT', 'NODELETE']] | None = None,
        prev_kv: bool | None = None,
        range_end: str | None = None,
        watch_id: int | None = None,
        fragment: bool | None = None,
        **kwargs: Any,
    ) -> Event:
        """Watch a key and stops after the first event.

        :param key: key to watch
        :param timeout: (optional) timeout in seconds.
        :param start_revision: revision to watch from
        :param progress_notify: get periodic progress notifications
        :param filters: filter types (``"NOPUT"`` or ``"NODELETE"``)
        :param prev_kv: return the previous key-value on event
        :param range_end: end of the range to watch (key is the start)
        :param watch_id: ID to assign to this watcher; 0 means auto-assign
            (etcd >= 3.4)
        :param fragment: split large watch responses into multiple smaller
            responses (etcd >= 3.4)
        :returns: event
        """
        event_queue: queue.Queue[Event] = queue.Queue()

        def callback(event: Event) -> None:
            event_queue.put(event)

        w = watch.Watcher(
            self,
            key,
            callback,
            start_revision=start_revision,
            progress_notify=progress_notify,
            filters=filters,
            prev_kv=prev_kv,
```

--------------------------------

### Watch Prefix Once

Source: https://docs.openstack.org/etcd3gw/latest/_modules/etcd3gw/client.html

This snippet demonstrates how to watch for changes under a specific key prefix and retrieve a single event.

```APIDOC
## Watch Prefix Once

### Description
Watches for key-value changes under a given prefix and returns the first event that occurs within the specified timeout.

### Method
`watch_prefix_once(key_prefix: str, timeout: float | int | None = None, *, start_revision: int | None = None, progress_notify: bool | None = None, filters: list[Literal['NOPUT', 'NODELETE']] | None = None, prev_kv: bool | None = None, watch_id: int | None = None, fragment: bool | None = None, **kwargs: Any) -> Event`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **key_prefix** (string) - Required - The prefix of the keys to watch.
- **timeout** (float or integer) - Optional - The maximum time in seconds to wait for an event. If None, it waits indefinitely.
- **start_revision** (integer) - Optional - The revision number to start watching from.
- **progress_notify** (boolean) - Optional - If True, enables periodic progress notifications.
- **filters** (list of strings) - Optional - A list of filters to apply. Can include 'NOPUT' or 'NODELETE'.
- **prev_kv** (boolean) - Optional - If True, the previous key-value pair will be returned with the event.
- **watch_id** (integer) - Optional - An ID to assign to this watcher. If 0, an ID is auto-assigned (etcd >= 3.4).
- **fragment** (boolean) - Optional - If True, large watch responses will be split into smaller responses (etcd >= 3.4).

### Request Example
```python
from etcd3gw.client import client

etcd_client = client()
try:
    event = etcd_client.watch_prefix_once('/my/prefix', timeout=5)
    print(f"Received event: {event}")
except Exception as e:
    print(f"An error occurred: {e}")
```

### Response
#### Success Response (200)
- **Event** (object) - An Event object representing the first change detected under the prefix.
```

--------------------------------

### Lease Object and Initialization

Source: https://docs.openstack.org/etcd3gw/latest/_modules/etcd3gw/lease.html

Represents an etcd lease object, used for managing expiring keys. It requires a lease ID and a client instance for interaction.

```APIDOC
## Lease Class

### Description
Represents an etcd lease object for managing expiring keys.

### Initialization
```python
Lease(id: int, client: '_client_module.Etcd3Client')
```

### Parameters
- **id** (int) - Required - The ID of the lease.
- **client** (_client_module.Etcd3Client) - Required - The etcd3gw client instance.
```

--------------------------------

### POST /lease/grant

Source: https://docs.openstack.org/etcd3gw/latest/_modules/etcd3gw/client.html

Creates a new lease with a specified time-to-live (TTL).

```APIDOC
## POST /lease/grant

### Description
Create a Lease object given a timeout.

### Method
POST

### Endpoint
/lease/grant

### Request Body
- **TTL** (int) - Required - Time to live for the lease.
- **ID** (int) - Required - ID for the lease (usually 0 for new).

### Response
#### Success Response (200)
- **ID** (int) - The ID of the created lease.
```

--------------------------------

### etcd3gw.client.Etcd3Client Methods

Source: https://docs.openstack.org/etcd3gw/latest/genindex.html

This section details the methods available on the Etcd3Client class for interacting with etcd.

```APIDOC
## GET /api/etcd3gw/client/api_path

### Description
Retrieves the API path for the etcd3gw client.

### Method
GET

### Endpoint
/api/etcd3gw/client/api_path

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **api_path** (string) - The API path of the client.

#### Response Example
{
  "api_path": "/v3/kv"
}

## GET /api/etcd3gw/client/base_url

### Description
Retrieves the base URL of the etcd3gw client.

### Method
GET

### Endpoint
/api/etcd3gw/client/base_url

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **base_url** (string) - The base URL of the etcd client.

#### Response Example
{
  "base_url": "http://localhost:2379"
}

## POST /api/etcd3gw/client/create

### Description
Creates a new etcd3gw client instance.

### Method
POST

### Endpoint
/api/etcd3gw/client/create

### Parameters
#### Request Body
- **host** (string) - Required - The etcd host.
- **port** (integer) - Optional - The etcd port.
- **user** (string) - Optional - The etcd username.
- **password** (string) - Optional - The etcd password.
- **ca_cert** (string) - Optional - Path to the CA certificate.
- **cert_key** (string) - Optional - Path to the client certificate key.
- **cert_cert** (string) - Optional - Path to the client certificate.

### Request Example
{
  "host": "localhost",
  "port": 2379
}

### Response
#### Success Response (200)
- **client_id** (string) - An identifier for the created client.

#### Response Example
{
  "client_id": "client_123"
}

## DELETE /api/etcd3gw/client/delete

### Description
Deletes a key-value pair from etcd.

### Method
DELETE

### Endpoint
/api/etcd3gw/client/delete

### Parameters
#### Request Body
- **key** (string) - Required - The key to delete.

### Request Example
{
  "key": "mykey"
}

### Response
#### Success Response (200)
- **deleted** (integer) - The number of keys deleted.

#### Response Example
{
  "deleted": 1
}

## DELETE /api/etcd3gw/client/delete_prefix

### Description
Deletes all keys with a given prefix from etcd.

### Method
DELETE

### Endpoint
/api/etcd3gw/client/delete_prefix

### Parameters
#### Request Body
- **prefix** (string) - Required - The prefix of keys to delete.

### Request Example
{
  "prefix": "myprefix/"
}

### Response
#### Success Response (200)
- **deleted** (integer) - The number of keys deleted.

#### Response Example
{
  "deleted": 5
}

## GET /api/etcd3gw/client/get

### Description
Retrieves the value associated with a given key from etcd.

### Method
GET

### Endpoint
/api/etcd3gw/client/get

### Parameters
#### Query Parameters
- **key** (string) - Required - The key to retrieve.

### Request Example
None

### Response
#### Success Response (200)
- **value** (string) - The value associated with the key.
- **version** (integer) - The version of the key.
- **create_revision** (integer) - The revision at which the key was created.
- **mod_revision** (integer) - The revision at which the key was last modified.

#### Response Example
{
  "value": "myvalue",
  "version": 1,
  "create_revision": 1,
  "mod_revision": 1
}

## GET /api/etcd3gw/client/get_all

### Description
Retrieves all key-value pairs from etcd.

### Method
GET

### Endpoint
/api/etcd3gw/client/get_all

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **items** (array) - An array of key-value pairs.
  - **key** (string) - The key.
  - **value** (string) - The value.
  - **version** (integer) - The version of the key.
  - **create_revision** (integer) - The revision at which the key was created.
  - **mod_revision** (integer) - The revision at which the key was last modified.

#### Response Example
{
  "items": [
    {
      "key": "key1",
      "value": "value1",
      "version": 1,
      "create_revision": 1,
      "mod_revision": 1
    }
  ]
}

## GET /api/etcd3gw/client/get_prefix

### Description
Retrieves all key-value pairs with a given prefix from etcd.

### Method
GET

### Endpoint
/api/etcd3gw/client/get_prefix

### Parameters
#### Query Parameters
- **prefix** (string) - Required - The prefix to filter keys.

### Request Example
None

### Response
#### Success Response (200)
- **items** (array) - An array of key-value pairs.
  - **key** (string) - The key.
  - **value** (string) - The value.
  - **version** (integer) - The version of the key.
  - **create_revision** (integer) - The revision at which the key was created.
  - **mod_revision** (integer) - The revision at which the key was last modified.

#### Response Example
{
  "items": [
    {
      "key": "myprefix/key1",
      "value": "value1",
      "version": 1,
      "create_revision": 1,
      "mod_revision": 1
    }
  ]
}

## GET /api/etcd3gw/client/get_url

### Description
Retrieves the URL for a given etcd key.

### Method
GET

### Endpoint
/api/etcd3gw/client/get_url

### Parameters
#### Query Parameters
- **key** (string) - Required - The key to get the URL for.

### Request Example
None

### Response
#### Success Response (200)
- **url** (string) - The URL for the etcd key.

#### Response Example
{
  "url": "http://localhost:2379/v3/kv/range"
}

## POST /api/etcd3gw/client/lease

### Description
Creates a new lease with a specified TTL.

### Method
POST

### Endpoint
/api/etcd3gw/client/lease

### Parameters
#### Request Body
- **ttl** (integer) - Required - The time-to-live for the lease in seconds.

### Request Example
{
  "ttl": 60
}

### Response
#### Success Response (200)
- **lease_id** (string) - The ID of the created lease.

#### Response Example
{
  "lease_id": "lease_abc"
}

## POST /api/etcd3gw/client/lock

### Description
Acquires a distributed lock.

### Method
POST

### Endpoint
/api/etcd3gw/client/lock

### Parameters
#### Request Body
- **name** (string) - Required - The name of the lock.
- **ttl** (integer) - Optional - The time-to-live for the lock in seconds.

### Request Example
{
  "name": "my_lock",
  "ttl": 30
}

### Response
#### Success Response (200)
- **lock_id** (string) - An identifier for the acquired lock.

#### Response Example
{
  "lock_id": "lock_xyz"
}

## GET /api/etcd3gw/client/members

### Description
Retrieves the list of members in the etcd cluster.

### Method
GET

### Endpoint
/api/etcd3gw/client/members

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **members** (array) - A list of etcd cluster members.
  - **id** (string) - The ID of the member.
  - **name** (string) - The name of the member.
  - **peer_urls** (array) - The peer URLs of the member.
  - **client_urls** (array) - The client URLs of the member.

#### Response Example
{
  "members": [
    {
      "id": "member_1",
      "name": "etcd-0",
      "peer_urls": ["http://10.0.0.1:2380"],
      "client_urls": ["http://10.0.0.1:2379"]
    }
  ]
}

## POST /api/etcd3gw/client/post

### Description
Posts data to a specific key in etcd. This is typically used for creating or updating a key-value pair.

### Method
POST

### Endpoint
/api/etcd3gw/client/post

### Parameters
#### Request Body
- **key** (string) - Required - The key to post data to.
- **value** (string) - Required - The value to associate with the key.
- **lease** (string) - Optional - The lease ID to associate with the key.
- **prev_kv** (boolean) - Optional - Whether to return the previous key-value pair if it exists.

### Request Example
{
  "key": "newkey",
  "value": "newvalue",
  "lease": "lease_abc"
}

### Response
#### Success Response (200)
- **kv** (object) - The key-value pair that was posted.
  - **key** (string) - The key.
  - **value** (string) - The value.
  - **version** (integer) - The version of the key.
  - **create_revision** (integer) - The revision at which the key was created.
  - **mod_revision** (integer) - The revision at which the key was last modified.
- **prev_kv** (object) - The previous key-value pair, if `prev_kv` was true and the key existed.
  - **key** (string) - The key.
  - **value** (string) - The value.
  - **version** (integer) - The version of the key.
  - **create_revision** (integer) - The revision at which the key was created.
  - **mod_revision** (integer) - The revision at which the key was last modified.

#### Response Example
{
  "kv": {
    "key": "newkey",
    "value": "newvalue",
    "version": 1,
    "create_revision": 1,
    "mod_revision": 1
  }
}

## PUT /api/etcd3gw/client/put

### Description
Puts a key-value pair into etcd. This operation creates or updates a key.

### Method
PUT

### Endpoint
/api/etcd3gw/client/put

### Parameters
#### Request Body
- **key** (string) - Required - The key to put.
- **value** (string) - Required - The value to associate with the key.
- **lease** (string) - Optional - The lease ID to associate with the key.
- **prev_kv** (boolean) - Optional - Whether to return the previous key-value pair if it exists.

### Request Example
{
  "key": "mykey",
  "value": "myvalue",
  "lease": "lease_abc"
}

### Response
#### Success Response (200)
- **kv** (object) - The key-value pair that was put.
  - **key** (string) - The key.
  - **value** (string) - The value.
  - **version** (integer) - The version of the key.
  - **create_revision** (integer) - The revision at which the key was created.
  - **mod_revision** (integer) - The revision at which the key was last modified.
- **prev_kv** (object) - The previous key-value pair, if `prev_kv` was true and the key existed.
  - **key** (string) - The key.
  - **value** (string) - The value.
  - **version** (integer) - The version of the key.
  - **create_revision** (integer) - The revision at which the key was created.
  - **mod_revision** (integer) - The revision at which the key was last modified.

#### Response Example
{
  "kv": {
    "key": "mykey",
    "value": "myvalue",
    "version": 1,
    "create_revision": 1,
    "mod_revision": 1
  }
}

## POST /api/etcd3gw/client/replace

### Description
Replaces the value of an existing key only if its current version matches the expected version.

### Method
POST

### Endpoint
/api/etcd3gw/client/replace

### Parameters
#### Request Body
- **key** (string) - Required - The key to replace.
- **value** (string) - Required - The new value for the key.
- **version** (integer) - Required - The expected current version of the key.
- **lease** (string) - Optional - The lease ID to associate with the key.

### Request Example
{
  "key": "mykey",
  "value": "newvalue",
  "version": 1
}

### Response
#### Success Response (200)
- **kv** (object) - The updated key-value pair.
  - **key** (string) - The key.
  - **value** (string) - The value.
  - **version** (integer) - The new version of the key.
  - **create_revision** (integer) - The revision at which the key was created.
  - **mod_revision** (integer) - The revision at which the key was last modified.

#### Response Example
{
  "kv": {
    "key": "mykey",
    "value": "newvalue",
    "version": 2,
    "create_revision": 1,
    "mod_revision": 2
  }
}

## GET /api/etcd3gw/client/status

### Description
Retrieves the status of the etcd cluster.

### Method
GET

### Endpoint
/api/etcd3gw/client/status

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **leader** (string) - The ID of the leader node.
- **raft_index** (integer) - The current Raft index.
- **raft_term** (integer) - The current Raft term.

#### Response Example
{
  "leader": "leader_id",
  "raft_index": 1000,
  "raft_term": 5
}

## POST /api/etcd3gw/client/transaction

### Description
Executes a transaction in etcd. A transaction consists of a list of conditions and a list of operations.

### Method
POST

### Endpoint
/api/etcd3gw/client/transaction

### Parameters
#### Request Body
- **compare** (array) - Required - A list of comparison operations.
  - **attribute** (string) - Required - The attribute to compare (e.g., 'version', 'value').
  - **key** (string) - Required - The key to compare.
  - **operator** (string) - Required - The comparison operator (e.g., '==', '!=').
  - **value** (string) - Optional - The value to compare against.
  - **version** (integer) - Optional - The version to compare against.
- **success** (array) - Required - A list of operations to perform if the comparisons succeed.
  - **method** (string) - Required - The operation method (e.g., 'PUT', 'DELETE').
  - **key** (string) - Required - The key for the operation.
  - **value** (string) - Optional - The value for the operation.
  - **lease** (string) - Optional - The lease ID for the operation.
- **failure** (array) - Required - A list of operations to perform if the comparisons fail.
  - **method** (string) - Required - The operation method (e.g., 'PUT', 'DELETE').
  - **key** (string) - Required - The key for the operation.
  - **value** (string) - Optional - The value for the operation.
  - **lease** (string) - Optional - The lease ID for the operation.

### Request Example
{
  "compare": [
    {
      "attribute": "version",
      "key": "mykey",
      "operator": "==",
      "version": 1
    }
  ],
  "success": [
    {
      "method": "PUT",
      "key": "mykey",
      "value": "updatedvalue"
    }
  ],
  "failure": [
    {
      "method": "GET",
      "key": "mykey"
    }
  ]
}

### Response
#### Success Response (200)
- **succeeded** (boolean) - Whether the transaction succeeded.
- **responses** (array) - The responses from the operations performed.

#### Response Example
{
  "succeeded": true,
  "responses": [
    {
      "header": {
        "cluster_id": "cluster_1",
        "member_id": "member_1",
        "revision": 2
      },
      "count": 1
    }
  ]
}

## POST /api/etcd3gw/client/watch

### Description
Starts watching for changes on a given key or prefix.

### Method
POST

### Endpoint
/api/etcd3gw/client/watch

### Parameters
#### Request Body
- **key** (string) - Optional - The key to watch.
- **prefix** (string) - Optional - The prefix to watch.
- **with_prev_kv** (boolean) - Optional - Whether to include previous key-value pairs in events.

### Request Example
{
  "key": "mykey"
}

### Response
#### Success Response (200)
- **watch_id** (string) - The ID of the watch.

#### Response Example
{
  "watch_id": "watch_def"
}

## POST /api/etcd3gw/client/watch_once

### Description
Starts watching for changes on a given key or prefix and returns only the first event.

### Method
POST

### Endpoint
/api/etcd3gw/client/watch_once

### Parameters
#### Request Body
- **key** (string) - Optional - The key to watch.
- **prefix** (string) - Optional - The prefix to watch.
- **with_prev_kv** (boolean) - Optional - Whether to include previous key-value pairs in events.

### Request Example
{
  "prefix": "myprefix/"
}

### Response
#### Success Response (200)
- **event** (object) - The first watch event.
  - **type** (string) - The type of event (e.g., 'PUT', 'DELETE').
  - **kv** (object) - The key-value pair associated with the event.
    - **key** (string) - The key.
    - **value** (string) - The value.
    - **version** (integer) - The version of the key.
    - **create_revision** (integer) - The revision at which the key was created.
    - **mod_revision** (integer) - The revision at which the key was last modified.
  - **prev_kv** (object) - The previous key-value pair, if available.
    - **key** (string) - The key.
    - **value** (string) - The value.
    - **version** (integer) - The version of the key.
    - **create_revision** (integer) - The revision at which the key was created.
    - **mod_revision** (integer) - The revision at which the key was last modified.

#### Response Example
{
  "event": {
    "type": "PUT",
    "kv": {
      "key": "myprefix/key1",
      "value": "value1",
      "version": 1,
      "create_revision": 1,
      "mod_revision": 1
    }
  }
}

## POST /api/etcd3gw/client/watch_prefix

### Description
Starts watching for changes on a given prefix.

### Method
POST

### Endpoint
/api/etcd3gw/client/watch_prefix

### Parameters
#### Request Body
- **prefix** (string) - Required - The prefix to watch.
- **with_prev_kv** (boolean) - Optional - Whether to include previous key-value pairs in events.

### Request Example
{
  "prefix": "myprefix/"
}

### Response
#### Success Response (200)
- **watch_id** (string) - The ID of the watch.

#### Response Example
{
  "watch_id": "watch_ghi"
}

## POST /api/etcd3gw/client/watch_prefix_once

### Description
Starts watching for changes on a given prefix and returns only the first event.

### Method
POST

### Endpoint
/api/etcd3gw/client/watch_prefix_once

### Parameters
#### Request Body
- **prefix** (string) - Required - The prefix to watch.
- **with_prev_kv** (boolean) - Optional - Whether to include previous key-value pairs in events.

### Request Example
{
  "prefix": "myprefix/"
}

### Response
#### Success Response (200)
- **event** (object) - The first watch event.
  - **type** (string) - The type of event (e.g., 'PUT', 'DELETE').
  - **kv** (object) - The key-value pair associated with the event.
    - **key** (string) - The key.
    - **value** (string) - The value.
    - **version** (integer) - The version of the key.
    - **create_revision** (integer) - The revision at which the key was created.
    - **mod_revision** (integer) - The revision at which the key was last modified.
  - **prev_kv** (object) - The previous key-value pair, if available.
    - **key** (string) - The key.
    - **value** (string) - The value.
    - **version** (integer) - The version of the key.
    - **create_revision** (integer) - The revision at which the key was created.
    - **mod_revision** (integer) - The revision at which the key was last modified.

#### Response Example
{
  "event": {
    "type": "PUT",
    "kv": {
      "key": "myprefix/key1",
      "value": "value1",
      "version": 1,
      "create_revision": 1,
      "mod_revision": 1
    }
  }
}
```

--------------------------------

### Create etcd Lease

Source: https://docs.openstack.org/etcd3gw/latest/_modules/etcd3gw/client.html

Creates a lease object with a specified Time-To-Live (TTL). A lease is used to manage the lifecycle of keys in etcd. The lease ID is extracted from the response.

```python
def lease(self, ttl: int = DEFAULT_TIMEOUT) -> Lease:
        """Create a Lease object given a timeout

        :param ttl: timeout
        :return: Lease object
        """
        result = self.post(
            self.get_url("/lease/grant"), json={"TTL": ttl, "ID": 0}
        )
        return Lease(int(result['ID']), client=self)
```

--------------------------------

### Watch a key prefix in etcd

Source: https://docs.openstack.org/etcd3gw/latest/_modules/etcd3gw/client.html

Watches a range of keys sharing a common prefix.

```python
    def watch_prefix(
        self,
        key_prefix: str,
        *,
        start_revision: int | None = None,
        progress_notify: bool | None = None,
        filters: list[Literal['NOPUT', 'NODELETE']] | None = None,
        prev_kv: bool | None = None,
        watch_id: int | None = None,
        fragment: bool | None = None,
        **kwargs: Any,
    ) -> tuple[Iterator[Event], Callable[[], None]]:
        """The same as ``watch``, but watches a range of keys with a prefix.

        :param key_prefix: key prefix to watch
        :param start_revision: revision to watch from
        :param progress_notify: get periodic progress notifications
        :param filters: filter types (``"NOPUT"`` or ``"NODELETE"``)
        :param prev_kv: return the previous key-value on event
        :param watch_id: ID to assign to this watcher; 0 means auto-assign
            (etcd >= 3.4)
        :param fragment: split large watch responses into multiple smaller
            responses (etcd >= 3.4)
        """
        return self.watch(
            key_prefix,
            range_end=_encode(_increment_last_byte(key_prefix)),
            start_revision=start_revision,
            progress_notify=progress_notify,
            filters=filters,
            prev_kv=prev_kv,
            **kwargs,
        )
```