Reads the value of a single key.

A missing key is not treated as an error; instead, a ReadResult with ReadResult.state set to 'missing' is returned.

>>> store = await ts.KvStore.open({'driver': 'memory'})
>>> await store.write(b'a', b'value')
KvStore.TimestampedStorageGeneration(...)
>>> await store.read(b'a')
KvStore.ReadResult(state='value', value=b'value', stamp=KvStore.TimestampedStorageGeneration(...))
>>> store[b'a']
b'value'
>>> await store.read(b'b')
KvStore.ReadResult(state='missing', value=b'', stamp=KvStore.TimestampedStorageGeneration(...))
>>> store[b'b']
Traceback (most recent call last):
    ...
KeyError...

>>> store[b'a'] = b'value'
>>> store[b'b'] = b'value'
>>> store.list().result()

If a transaction is bound, the read reflects any writes made within the transaction, and the commit of the transaction will fail if the value associated with key changes after the read due to external writes, i.e. consistent reads are guaranteed.

Parameters:¶

key: str¶

The key to read. This is appended (without any separator) to the existing path, if any.

if_not_equal: str | None = None¶

If specified, the read is aborted if the generation associated with key matches if_not_equal. An aborted read due to this condition is indicated by a ReadResult.state of 'unspecified'. This may be useful for validating a cached value cache validation at a higher level.

staleness_bound: float | None = None¶

Specifies a time in (fractional) seconds since the Unix epoch. If specified, data that is cached internally by the kvstore implementation may be used without validation if not older than the staleness_bound. Cached data older than staleness_bound must be validated before being returned. A value of float('inf') indicates that the result must be current as of the time the read request was made, i.e. it is equivalent to specifying a value of time.time(). A value of float('-inf') indicates that cached data may be returned without validation irrespective of its age.

batch: Batch | None = None¶

Batch to use for the read operation.

Warning

If specified, the returned Future will not, in general, become ready until the batch is submitted. Therefore, immediately awaiting the returned future will lead to deadlock.

Returns:¶

Future that resolves when the read operation completes.