Misc.¶
Typing¶
Most of call are polymorphic and most of the types in documentation are just hints. Here is the full list of types:
-
class
aioconsul.typing.
ObjectIndex
¶ Used by polymorphic functions that accept any
str
ordict
that have an Index key.For example these two objects are equivalent:
a = { "Index": "1234-43-6789" } b = "1234-43-6789"
-
class
aioconsul.typing.
ObjectID
¶ Used by polymorphic functions that accept any
str
ordict
that have an ID key.These two objects are equivalent:
a = { "ID": "1234-43-6789" } b = "1234-43-6789"
-
class
aioconsul.typing.
Object
¶ Represents a
dict
where keys arestr
and values can be any type.For example:
{ "ID": "1234-43-6789", "Name": "foo", "Value": "bar" }
Depending of the endpoint, ID may be required or not.
-
class
aioconsul.typing.
Collection
¶ Represents a
list
where values areObject
.For example:
[{"ID": "1234"}, {"ID": "5678"}]
-
class
aioconsul.typing.
Mapping
¶ Represents a
dict
where keys areid
and values areObject
.For example:
{"service1": {"ID": "service1"}}
-
class
aioconsul.typing.
Meta
¶ Represents a
dict
that is associated to Response. These keys should be presents:- Index — a unique identifier representing the current state of the requested resource
- KnownLeader — indicates if there is a known leader
- LastContact — Contains the time in milliseconds that a server was last contacted by the leader node
Meta can be used for blocking / watch mode.
-
class
aioconsul.typing.
CollectionMeta
¶ A tuple where first value is a
Collection
and second value isMeta
.
-
class
aioconsul.typing.
ObjectMeta
¶ A tuple where first value is an
Object
and second value isMeta
.
-
class
aioconsul.typing.
Filter
¶ Regular expression to filter by.
It accepts a
re.Pattern
or astr
. These two objects are equivalent:a = re.compile("node-\d+") b = "node-\d+"
-
class
aioconsul.typing.
Consistency
¶ Most of the read query endpoints support multiple levels of consistency. Since no policy will suit all clients’ needs, these consistency modes allow the user to have the ultimate say in how to balance the trade-offs inherent in a distributed system. The three read modes are:
default — If not specified, the default is strongly consistent in almost all cases. However, there is a small window in which a new leader may be elected during which the old leader may service stale values. The trade-off is fast reads but potentially stale values. The condition resulting in stale reads is hard to trigger, and most clients should not need to worry about this case. Also, note that this race condition only applies to reads, not writes.
consistent — This mode is strongly consistent without caveats. It requires that a leader verify with a quorum of peers that it is still leader. This introduces an additional round-trip to all server nodes. The trade-off is increased latency due to an extra round trip. Most clients should not use this unless they cannot tolerate a stale read.
stale — This mode allows any server to service the read regardless of whether it is the leader. This means reads can be arbitrarily stale; however, results are generally consistent to within 50 milliseconds of the leader. The trade-off is very fast and scalable reads with a higher likelihood of stale values. Since this mode allows reads without a leader, a cluster that is unavailable will still be able to respond to queries.
-
class
aioconsul.typing.
Duration
¶ Defines a duration. Can be specified in the form of “10s” or “5m” or a
datetime.timedelta
.For example, these objects are equivalent:
timedelta(seconds=150) "2m30s"
-
class
aioconsul.typing.
Blocking
¶ Defines a blocking query.
It must be a
ObjectIndex
or better a tuple where second value is aDuration
.For example these values are equivalent:
a = {"Index": 1} b = 1 c = ({"Index": 1}, None)
For adding a wait, just set the second value of tuple.
-
class
aioconsul.typing.
Payload
¶ Currently only
bytes
andbytearray
are allowed. It may vary on Flags value in the futur.Internally, Payload will be base64 encoded/decoded when the endpoint requires it. End user does not have to do it.
The
KVEndpoint
is build on top of:PUT /v1/kv/(key)
- Body will be encodedGET /v1/kv/(key)
- Value will be decoded
For example:
PAYLOAD = b"bar" await client.kv.set("foo", PAYLOAD) response, _ = await client.kv.get("foo") assert response["Value"] == PAYLOAD
The
EventEndpoint
is build on top of:PUT /v1/event/fire/(name)
- Payload will be kept as isGET /v1/event/list
- Payload will be base64 encoded
For example:
PAYLOAD = b"qux" response = await client.event.fire("baz", PAYLOAD) assert response["Payload"] == PAYLOAD responses, _ = await client.kv.items("baz") assert responses[0]["Payload"] == PAYLOAD