flo-python 0.1.2__py3-none-any.whl → 0.1.4__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
flo/__init__.py CHANGED
@@ -46,15 +46,18 @@ from .exceptions import (
46
46
  InvalidMagicError,
47
47
  KeyTooLargeError,
48
48
  NamespaceTooLargeError,
49
+ NoNamespaceError,
49
50
  NonRetryableError,
50
51
  NotConnectedError,
51
52
  NotFoundError,
53
+ OutcomePendingError,
52
54
  OverloadedError,
53
55
  PayloadTooLargeError,
54
56
  ProtocolError,
55
57
  RateLimitedError,
56
58
  RequestTimeoutError,
57
59
  ServerError,
60
+ StaleNotFoundError,
58
61
  TableMismatchError,
59
62
  UnauthorizedError,
60
63
  UnavailableError,
@@ -69,7 +72,6 @@ from .retry import DEFAULT_RETRY_POLICY, RetryPolicy
69
72
  from .types import (
70
73
  AckOptions,
71
74
  ActionDeleteOptions,
72
- ActionInfo,
73
75
  ActionInvokeOptions,
74
76
  ActionInvokeResult,
75
77
  ActionListOptions,
@@ -85,10 +87,12 @@ from .types import (
85
87
  DlqListOptions,
86
88
  DlqRequeueOptions,
87
89
  EnqueueOptions,
90
+ ExistsResult,
88
91
  GetJsonResult,
89
92
  GetOptions,
90
93
  GetResult,
91
94
  HistoryOptions,
95
+ HistoryResult,
92
96
  IncrResult,
93
97
  KVBeginResult,
94
98
  KVCommitResult,
@@ -107,12 +111,14 @@ from .types import (
107
111
  ProcessingCancelOptions,
108
112
  ProcessingListEntry,
109
113
  ProcessingListOptions,
114
+ ProcessingListResult,
110
115
  ProcessingStatusOptions,
111
116
  ProcessingStatusResult,
112
117
  ProcessingStopOptions,
113
118
  ProcessingSubmitOptions,
114
119
  ProcessingSyncOptions,
115
120
  ProcessingSyncResult,
121
+ ProcessKind,
116
122
  PutOptions,
117
123
  PutResult,
118
124
  Ran,
@@ -125,6 +131,7 @@ from .types import (
125
131
  StreamAppendOptions,
126
132
  StreamAppendResult,
127
133
  StreamClaimResult,
134
+ StreamDeleteOptions,
128
135
  StreamGroupAckOptions,
129
136
  StreamGroupJoinOptions,
130
137
  StreamGroupNackOptions,
@@ -143,22 +150,28 @@ from .types import (
143
150
  WorkerAwaitOptions,
144
151
  WorkerAwaitResult,
145
152
  WorkerCompleteOptions,
153
+ WorkerDetails,
146
154
  WorkerFailOptions,
147
155
  WorkerInfo,
148
156
  WorkerListOptions,
149
157
  WorkerListResult,
158
+ WorkerProcess,
150
159
  WorkerRegisterOptions,
151
160
  WorkerStatus,
152
161
  WorkerTouchOptions,
153
162
  WorkerType,
154
163
  WorkflowCancelOptions,
155
164
  WorkflowCreateOptions,
165
+ WorkflowDefinitionEntry,
156
166
  WorkflowDisableOptions,
157
167
  WorkflowEnableOptions,
158
168
  WorkflowGetDefinitionOptions,
159
169
  WorkflowHistoryOptions,
160
170
  WorkflowListDefinitionsOptions,
171
+ WorkflowListDefinitionsResult,
161
172
  WorkflowListRunsOptions,
173
+ WorkflowListRunsResult,
174
+ WorkflowRunEntry,
162
175
  WorkflowSignalOptions,
163
176
  WorkflowStartOptions,
164
177
  WorkflowStatusOptions,
@@ -177,7 +190,7 @@ from .worker import (
177
190
  )
178
191
  from .workflows import WorkflowOperations
179
192
 
180
- __version__ = "0.1.2"
193
+ __version__ = "0.1.4"
181
194
 
182
195
  __all__ = [
183
196
  "Transaction",
@@ -191,6 +204,8 @@ __all__ = [
191
204
  "KVMGetOptions",
192
205
  "KVExpireOptions",
193
206
  "GetResult",
207
+ "HistoryResult",
208
+ "ExistsResult",
194
209
  "GetJsonResult",
195
210
  "MGetEntry",
196
211
  "PutResult",
@@ -231,10 +246,13 @@ __all__ = [
231
246
  "BlockTooLongError",
232
247
  "ServerError",
233
248
  "NotFoundError",
249
+ "NoNamespaceError",
234
250
  "BadRequestError",
235
251
  "ConflictError",
236
252
  "UnauthorizedError",
237
253
  "OverloadedError",
254
+ "OutcomePendingError",
255
+ "StaleNotFoundError",
238
256
  "UnavailableError",
239
257
  "RateLimitedError",
240
258
  "InternalServerError",
@@ -281,6 +299,7 @@ __all__ = [
281
299
  "StreamTrimOptions",
282
300
  "StreamTrimResult",
283
301
  "StreamInfoOptions",
302
+ "StreamDeleteOptions",
284
303
  "StreamGroupJoinOptions",
285
304
  "StreamGroupReadOptions",
286
305
  "StreamGroupAckOptions",
@@ -288,7 +307,6 @@ __all__ = [
288
307
  # Action types
289
308
  "ActionType",
290
309
  "RunStatus",
291
- "ActionInfo",
292
310
  "ActionRunStatus",
293
311
  "ActionInvokeResult",
294
312
  "ActionListResult",
@@ -301,7 +319,10 @@ __all__ = [
301
319
  # Worker types
302
320
  "TaskAssignment",
303
321
  "WorkerAwaitResult",
322
+ "ProcessKind",
323
+ "WorkerDetails",
304
324
  "WorkerInfo",
325
+ "WorkerProcess",
305
326
  "WorkerListResult",
306
327
  "WorkerStatus",
307
328
  "WorkerType",
@@ -322,7 +343,11 @@ __all__ = [
322
343
  "WorkflowCancelOptions",
323
344
  "WorkflowHistoryOptions",
324
345
  "WorkflowListRunsOptions",
346
+ "WorkflowListRunsResult",
347
+ "WorkflowRunEntry",
325
348
  "WorkflowListDefinitionsOptions",
349
+ "WorkflowListDefinitionsResult",
350
+ "WorkflowDefinitionEntry",
326
351
  "WorkflowDisableOptions",
327
352
  "WorkflowEnableOptions",
328
353
  "WorkflowSyncOptions",
@@ -337,5 +362,6 @@ __all__ = [
337
362
  "ProcessingSyncOptions",
338
363
  "ProcessingStatusResult",
339
364
  "ProcessingListEntry",
365
+ "ProcessingListResult",
340
366
  "ProcessingSyncResult",
341
367
  ]
flo/actions.py CHANGED
@@ -11,7 +11,9 @@ from typing import TYPE_CHECKING
11
11
 
12
12
  from .kv_body import (
13
13
  decode_action_invoke_answer,
14
+ decode_action_list_answer,
14
15
  decode_action_status_answer,
16
+ decode_worker_info_answer,
15
17
  decode_worker_list_answer,
16
18
  encode_worker_list_body,
17
19
  )
@@ -30,10 +32,12 @@ from .types import (
30
32
  WorkerAwaitOptions,
31
33
  WorkerAwaitResult,
32
34
  WorkerCompleteOptions,
35
+ WorkerDetails,
33
36
  WorkerFailOptions,
34
37
  WorkerListOptions,
35
38
  WorkerListResult,
36
39
  WorkerRegisterOptions,
40
+ WorkerStatus,
37
41
  WorkerTouchOptions,
38
42
  )
39
43
  from .wire import (
@@ -156,28 +160,28 @@ class ActionOperations:
156
160
  self,
157
161
  options: ActionListOptions | None = None,
158
162
  ) -> ActionListResult:
159
- """List registered actions.
163
+ """List a page of the namespace's registered actions.
160
164
 
161
165
  Args:
162
- options: Optional list options.
166
+ options: The page's limit and cursor (the last page's ``cursor``;
167
+ None starts).
163
168
 
164
169
  Returns:
165
- ActionListResult with list of actions.
170
+ ActionListResult with the page's action names and the next
171
+ page's cursor, None on the last page.
166
172
  """
167
173
  opts = options or ActionListOptions()
168
174
  namespace = self._client.get_namespace(opts.namespace)
169
175
 
170
- value = serialize_action_list_value(limit=opts.limit)
171
-
172
- await self._client._send_and_check(
176
+ response = await self._client._send_and_check(
173
177
  OpCode.ACTION_LIST,
174
178
  namespace,
175
179
  (opts.prefix or "").encode("utf-8"),
176
- value,
180
+ serialize_action_list_value(limit=opts.limit, cursor=opts.cursor),
177
181
  )
178
182
 
179
- # Parse list response - format TBD based on server implementation
180
- return ActionListResult(actions=[])
183
+ names, cursor = decode_action_list_answer(response.data)
184
+ return ActionListResult(names=names, cursor=cursor)
181
185
 
182
186
  async def delete(
183
187
  self,
@@ -229,6 +233,7 @@ class WorkerOperations:
229
233
 
230
234
  value = serialize_worker_register_value(
231
235
  task_types,
236
+ worker_type=int(opts.worker_type),
232
237
  max_concurrency=opts.concurrency,
233
238
  metadata=opts.metadata,
234
239
  machine_id=opts.machine_id,
@@ -246,24 +251,57 @@ class WorkerOperations:
246
251
  worker_id: str,
247
252
  current_load: int = 0,
248
253
  namespace: str | None = None,
249
- ) -> None:
254
+ ) -> WorkerStatus:
250
255
  """Send a worker heartbeat to keep the registration alive.
251
256
 
252
257
  Args:
253
258
  worker_id: Worker identifier.
254
259
  current_load: Current number of active tasks.
255
260
  namespace: Optional namespace override.
261
+
262
+ Returns:
263
+ The worker's status on the server: DRAINING once it is drained.
264
+
265
+ Raises:
266
+ NotFoundError: The server doesn't know the worker (it never
267
+ registered, or was removed after going silent).
256
268
  """
257
269
  import struct
258
270
 
259
271
  ns = self._client.get_namespace(namespace)
260
272
  value = struct.pack("<I", current_load)
261
- await self._client._send_and_check(
273
+ response = await self._client._send_and_check(
262
274
  OpCode.WORKER_HEARTBEAT,
263
275
  ns,
264
276
  worker_id.encode("utf-8"),
265
277
  value,
266
278
  )
279
+ if len(response.data) != 1:
280
+ raise ValueError(f"heartbeat answer is {len(response.data)} bytes, want 1")
281
+ return WorkerStatus(response.data[0])
282
+
283
+ async def drain(self, worker_id: str, namespace: str | None = None) -> None:
284
+ """Mark a worker draining: the server gives it no more work, and
285
+ its heartbeats answer DRAINING until it deregisters.
286
+
287
+ Raises:
288
+ NotFoundError: The server doesn't know the worker.
289
+ """
290
+ await self._client._send_and_check(
291
+ OpCode.WORKER_DRAIN,
292
+ self._client.get_namespace(namespace),
293
+ worker_id.encode("utf-8"),
294
+ b"",
295
+ )
296
+
297
+ async def deregister(self, worker_id: str, namespace: str | None = None) -> None:
298
+ """Remove a worker from the registry."""
299
+ await self._client._send_and_check(
300
+ OpCode.WORKER_DEREGISTER,
301
+ self._client.get_namespace(namespace),
302
+ worker_id.encode("utf-8"),
303
+ b"",
304
+ )
267
305
 
268
306
  async def await_task(
269
307
  self,
@@ -412,8 +450,23 @@ class WorkerOperations:
412
450
  OpCode.WORKER_LIST,
413
451
  namespace,
414
452
  b"",
415
- encode_worker_list_body(opts.limit, opts.cursor),
453
+ encode_worker_list_body(opts.limit, opts.cursor, opts.action),
416
454
  )
417
455
 
418
456
  workers, cursor = decode_worker_list_answer(response.data)
419
457
  return WorkerListResult(workers=workers, cursor=cursor)
458
+
459
+ async def info(self, worker_id: str, namespace: str | None = None) -> WorkerDetails:
460
+ """A worker's record: its row, as :meth:`list` shows it, the metadata
461
+ it registered with, and its processes with their run and fail counts.
462
+
463
+ Raises:
464
+ NotFoundError: The server doesn't know the worker.
465
+ """
466
+ response = await self._client._send_and_check(
467
+ OpCode.WORKER_INFO,
468
+ self._client.get_namespace(namespace),
469
+ worker_id.encode("utf-8"),
470
+ b"",
471
+ )
472
+ return decode_worker_info_answer(response.data)
flo/client.py CHANGED
@@ -15,6 +15,7 @@ from .exceptions import (
15
15
  NotConnectedError,
16
16
  ProtocolError,
17
17
  RequestTimeoutError,
18
+ ServerError,
18
19
  UnexpectedEofError,
19
20
  raise_for_status,
20
21
  )
@@ -23,7 +24,7 @@ from .types import _DEFAULT_WORKER_BLOCK_MS, HEADER_SIZE, OpCode, OptionTag, Sta
23
24
  from .wire import (
24
25
  OptionsIterator,
25
26
  RawResponse,
26
- compute_crc32,
27
+ compute_crc32c,
27
28
  parse_response_header,
28
29
  serialize_request,
29
30
  )
@@ -387,7 +388,7 @@ class FloClient:
387
388
  except asyncio.TimeoutError as e:
388
389
  raise RequestTimeoutError(f"No response to {op_code.name}") from e
389
390
 
390
- status, data_len, resp_request_id, crc = parse_response_header(header_data)
391
+ status, data_len, resp_request_id, crc, stale = parse_response_header(header_data)
391
392
 
392
393
  if data_len > 0:
393
394
  try:
@@ -406,10 +407,10 @@ class FloClient:
406
407
  else:
407
408
  response_data = b""
408
409
 
409
- computed_crc = compute_crc32(header_data, response_data)
410
+ computed_crc = compute_crc32c(header_data, response_data)
410
411
  if computed_crc != crc:
411
412
  raise InvalidChecksumError(
412
- f"CRC32 mismatch: 0x{computed_crc:08X} != 0x{crc:08X}"
413
+ f"CRC32C mismatch: 0x{computed_crc:08X} != 0x{crc:08X}"
413
414
  )
414
415
  if resp_request_id == 0:
415
416
  # The server answers a request it could not parse with
@@ -435,7 +436,9 @@ class FloClient:
435
436
  if self._debug:
436
437
  logger.debug(f"[flo] <- {status.name} {len(response_data)} bytes")
437
438
 
438
- return RawResponse(status=status, data=response_data, request_id=resp_request_id)
439
+ return RawResponse(
440
+ status=status, data=response_data, request_id=resp_request_id, stale=stale
441
+ )
439
442
 
440
443
  async def _send_and_check(
441
444
  self,
@@ -471,7 +474,11 @@ class FloClient:
471
474
  if allow_not_found and response.status == StatusCode.NOT_FOUND:
472
475
  return response
473
476
 
474
- raise_for_status(response.status, response.data)
477
+ try:
478
+ raise_for_status(response.status, response.data)
479
+ except ServerError as e:
480
+ e.stale = response.stale
481
+ raise
475
482
  return response # Unreachable, but makes type checker happy
476
483
 
477
484
  def get_namespace(self, override: str | None) -> str:
flo/exceptions.py CHANGED
@@ -101,7 +101,7 @@ class TableMismatchError(ProtocolError):
101
101
 
102
102
 
103
103
  class InvalidChecksumError(ProtocolError):
104
- """CRC32 checksum validation failed."""
104
+ """A frame's CRC32C checksum didn't match."""
105
105
 
106
106
  pass
107
107
 
@@ -166,6 +166,9 @@ class ServerError(FloError):
166
166
  reason: Reason = Reason.UNCLASSIFIED
167
167
  # Whether the request took effect; unknown unless the server said.
168
168
  ran: Ran = Ran.UNKNOWN
169
+ # A halted shard answered, from its state just before the entry it
170
+ # halted at.
171
+ stale: bool = False
169
172
 
170
173
  def __init__(self, message: str, status_code: StatusCode):
171
174
  super().__init__(message)
@@ -179,6 +182,24 @@ class NotFoundError(ServerError):
179
182
  super().__init__(message, StatusCode.NOT_FOUND)
180
183
 
181
184
 
185
+ class StaleNotFoundError(NotFoundError):
186
+ """A halted shard didn't have the key, as of the entry it halted at
187
+ (``stale`` is True). It may exist since: a write after the halt hasn't
188
+ applied. kv.get and kv.json_get raise it rather than report the key
189
+ absent."""
190
+
191
+ stale = True
192
+
193
+
194
+ class NoNamespaceError(ServerError):
195
+ """The namespace the request names doesn't exist. Not a NotFoundError,
196
+ which means a missing key, so a missing namespace never reads as an
197
+ absent key."""
198
+
199
+ def __init__(self, message: str = StatusCode.NO_NAMESPACE.message()):
200
+ super().__init__(message, StatusCode.NO_NAMESPACE)
201
+
202
+
182
203
  class BadRequestError(ServerError):
183
204
  """Invalid request parameters."""
184
205
 
@@ -218,13 +239,25 @@ class UnavailableError(ServerError):
218
239
  """No leader, or the shard isn't taking writes or is offline. Retryable.
219
240
 
220
241
  The message says why; an offline shard stays unavailable until an
221
- operator acts, so whether and when to retry is the caller's call.
242
+ operator acts, so whether and when to retry is the caller's call. With
243
+ reason SHARD_HALTED the shard halted and takes no writes until an
244
+ operator repairs it; the client doesn't retry that one.
222
245
  """
223
246
 
224
247
  def __init__(self, message: str = StatusCode.UNAVAILABLE.message()):
225
248
  super().__init__(message, StatusCode.UNAVAILABLE)
226
249
 
227
250
 
251
+ class OutcomePendingError(ServerError):
252
+ """The write committed but hasn't applied: its shard halted at or before
253
+ it (reason SHARD_HALTED, ran UNKNOWN). The message says whether it
254
+ applies when the shard resumes. Never retried: resending it would write
255
+ it twice, or halt again."""
256
+
257
+ def __init__(self, message: str = StatusCode.OUTCOME_PENDING.message()):
258
+ super().__init__(message, StatusCode.OUTCOME_PENDING)
259
+
260
+
228
261
  class InternalServerError(ServerError):
229
262
  """Internal server error. Not retryable: the server uses it for a write
230
263
  that committed but wasn't applied, which must not be resent."""
@@ -287,11 +320,13 @@ def _error_for(status: StatusCode, message: str) -> ServerError:
287
320
 
288
321
  error_map: dict[StatusCode, Callable[[str], ServerError]] = {
289
322
  StatusCode.NOT_FOUND: NotFoundError,
323
+ StatusCode.NO_NAMESPACE: NoNamespaceError,
290
324
  StatusCode.BAD_REQUEST: BadRequestError,
291
325
  StatusCode.CONFLICT: ConflictError,
292
326
  StatusCode.UNAUTHORIZED: UnauthorizedError,
293
327
  StatusCode.OVERLOADED: OverloadedError,
294
328
  StatusCode.UNAVAILABLE: UnavailableError,
329
+ StatusCode.OUTCOME_PENDING: OutcomePendingError,
295
330
  StatusCode.RATE_LIMITED: RateLimitedError,
296
331
  StatusCode.INTERNAL_ERROR: InternalServerError,
297
332
  StatusCode.ERROR_GENERIC: GenericServerError,
flo/kv.py CHANGED
@@ -6,7 +6,12 @@ Key-value store operations for Flo client.
6
6
  import json
7
7
  from typing import TYPE_CHECKING, Any
8
8
 
9
- from .exceptions import IncompleteResponseError, ServerError, raise_for_status
9
+ from .exceptions import (
10
+ IncompleteResponseError,
11
+ ServerError,
12
+ StaleNotFoundError,
13
+ raise_for_status,
14
+ )
10
15
  from .kv_body import (
11
16
  decode_delete_answer,
12
17
  decode_empty_answer,
@@ -36,10 +41,12 @@ from .kv_body import (
36
41
  )
37
42
  from .types import (
38
43
  DeleteOptions,
44
+ ExistsResult,
39
45
  GetJsonResult,
40
46
  GetOptions,
41
47
  GetResult,
42
48
  HistoryOptions,
49
+ HistoryResult,
43
50
  IncrResult,
44
51
  KVExistsOptions,
45
52
  KVExpireOptions,
@@ -53,7 +60,6 @@ from .types import (
53
60
  Reason,
54
61
  ScanOptions,
55
62
  ScanResult,
56
- VersionEntry,
57
63
  )
58
64
  from .wire import RawResponse
59
65
 
@@ -66,17 +72,24 @@ def _key(key: str | bytes) -> bytes:
66
72
  return key.encode("utf-8") if isinstance(key, str) else key
67
73
 
68
74
 
69
- def _absent(response: RawResponse) -> bool:
75
+ def _absent(response: RawResponse, *, stale_raises: bool = False) -> bool:
70
76
  """Whether a not-found answer says the thing is absent; any other not-found
71
- (no such transaction) is raised."""
77
+ (no such transaction) is raised. With stale_raises, an absent key on a
78
+ stale answer raises StaleNotFoundError: absent as of the halt is not
79
+ absent."""
72
80
  if not response.is_not_found():
73
81
  return False
74
82
  try:
75
83
  raise_for_status(response.status, response.data)
76
84
  except ServerError as e:
77
- if e.reason == Reason.NOT_FOUND:
78
- return True
79
- raise
85
+ e.stale = response.stale
86
+ if e.reason != Reason.NOT_FOUND:
87
+ raise
88
+ if stale_raises and response.stale:
89
+ stale = StaleNotFoundError(str(e))
90
+ stale.reason, stale.ran = e.reason, e.ran
91
+ raise stale from None
92
+ return True
80
93
  return False # pragma: no cover - raise_for_status always raises here
81
94
 
82
95
 
@@ -87,9 +100,11 @@ async def kv_get(
87
100
  response = await client._send_and_check(
88
101
  OpCode.KV_GET, namespace, _key(key), encode_get_body(opts, txn), allow_not_found=True
89
102
  )
90
- if _absent(response):
103
+ if _absent(response, stale_raises=True):
91
104
  return None
92
- return decode_get_answer(response.data)
105
+ result = decode_get_answer(response.data)
106
+ result.stale = response.stale
107
+ return result
93
108
 
94
109
 
95
110
  async def kv_set(
@@ -163,12 +178,14 @@ async def kv_exists(
163
178
  key: str | bytes,
164
179
  opts: KVExistsOptions,
165
180
  txn: int | None = None,
166
- ) -> bool:
181
+ ) -> ExistsResult:
167
182
  """kv.exists, inside transaction ``txn`` when given."""
168
183
  response = await client._send_and_check(
169
184
  OpCode.KV_EXISTS, namespace, _key(key), encode_exists_body(opts.routing_key, txn)
170
185
  )
171
- return decode_exists_answer(response.data)[0]
186
+ result = decode_exists_answer(response.data)
187
+ result.stale = response.stale
188
+ return result
172
189
 
173
190
 
174
191
  class KVOperations:
@@ -184,8 +201,15 @@ class KVOperations:
184
201
  ) -> GetResult | None:
185
202
  """Get value and version for a key.
186
203
 
187
- Returns ``GetResult(value, version)``, or ``None`` if the key is not
188
- found, also when a wait (``wait_ms``) ends without it.
204
+ Returns ``GetResult(value, version, expires_at_ms)``, or ``None`` if
205
+ the key is not found, also when a wait (``wait_ms``) ends without it.
206
+ ``expires_at_ms`` is when the key's TTL runs out (unix ms), ``None``
207
+ when it has none. ``stale`` says a halted shard answered.
208
+
209
+ Raises:
210
+ NoNamespaceError: The namespace was never created.
211
+ StaleNotFoundError: A halted shard had no such key as of the entry
212
+ it halted at; it may exist since.
189
213
 
190
214
  Example:
191
215
  result = await client.kv.get("user:123")
@@ -281,6 +305,8 @@ class KVOperations:
281
305
  )
282
306
  if next_index == 0:
283
307
  raise IncompleteResponseError("kv.mget answered none of the keys asked")
308
+ for e in entries:
309
+ e.stale = response.stale
284
310
  out.extend(entries)
285
311
  done += len(entries)
286
312
  return out
@@ -293,13 +319,14 @@ class KVOperations:
293
319
  """List the names of keys with a prefix ("" for all), a page at a time.
294
320
 
295
321
  Example:
296
- result = await client.kv.scan("user:")
297
- for name in result.names:
298
- print(name)
299
-
300
- # Next pages
301
- while result.cursor is not None:
302
- result = await client.kv.scan("user:", ScanOptions(cursor=result.cursor))
322
+ opts = ScanOptions()
323
+ while True:
324
+ result = await client.kv.scan("user:", opts)
325
+ for name in result.names:
326
+ print(name)
327
+ if result.cursor is None:
328
+ break
329
+ opts = ScanOptions(cursor=result.cursor)
303
330
  """
304
331
  opts = options or ScanOptions()
305
332
  response = await self._client._send_and_check(
@@ -309,31 +336,41 @@ class KVOperations:
309
336
  encode_scan_body(opts.limit, opts.cursor),
310
337
  )
311
338
  names, cursor = decode_scan_answer(response.data)
312
- return ScanResult(names=names, cursor=cursor)
339
+ return ScanResult(names=names, cursor=cursor, stale=response.stale)
313
340
 
314
341
  async def history(
315
342
  self,
316
343
  key: str | bytes,
317
344
  options: HistoryOptions | None = None,
318
- ) -> list[VersionEntry]:
319
- """A key's versions, newest first, each with when it was written; empty
320
- for a missing key.
345
+ ) -> HistoryResult:
346
+ """A page of a key's versions, newest first, each with when it was
347
+ written and whether it was a delete (``deleted``, with an empty
348
+ value); empty for a missing key. ``more`` says older kept versions
349
+ follow: ask again with ``before_version`` set to the last version of
350
+ this page.
321
351
 
322
352
  Example:
323
- for entry in await client.kv.history("user:123", HistoryOptions(limit=10)):
324
- print(f"v{entry.version} at {entry.at_ms}: {entry.value}")
353
+ opts = HistoryOptions(limit=10)
354
+ while True:
355
+ page = await client.kv.history("user:123", opts)
356
+ for entry in page.versions:
357
+ print(f"v{entry.version} at {entry.at_ms}: {entry.value}")
358
+ if not page.more or not page.versions:
359
+ break
360
+ opts = HistoryOptions(limit=10, before_version=page.versions[-1].version)
325
361
  """
326
362
  opts = options or HistoryOptions()
327
363
  response = await self._client._send_and_check(
328
364
  OpCode.KV_HISTORY,
329
365
  self._client.get_namespace(opts.namespace),
330
366
  _key(key),
331
- encode_history_body(opts.limit, opts.routing_key),
367
+ encode_history_body(opts.limit, opts.before_version, opts.routing_key),
332
368
  allow_not_found=True,
333
369
  )
334
370
  if _absent(response):
335
- return []
336
- return decode_history_answer(response.data)
371
+ return HistoryResult(versions=[], more=False, stale=response.stale)
372
+ versions, more = decode_history_answer(response.data)
373
+ return HistoryResult(versions=versions, more=more, stale=response.stale)
337
374
 
338
375
  # ── Counters, TTL, exists, JSON paths ──────────────────────────────
339
376
 
@@ -373,8 +410,8 @@ class KVOperations:
373
410
  self,
374
411
  key: str | bytes,
375
412
  options: KVExistsOptions | None = None,
376
- ) -> bool:
377
- """Return ``True`` if ``key`` is present without transferring its value."""
413
+ ) -> ExistsResult:
414
+ """Whether ``key`` is present, and its version, without transferring its value."""
378
415
  opts = options or KVExistsOptions()
379
416
  return await kv_exists(self._client, self._client.get_namespace(opts.namespace), key, opts)
380
417
 
@@ -388,7 +425,8 @@ class KVOperations:
388
425
 
389
426
  Returns a :class:`GetJsonResult` whose ``value`` is the parsed JSON,
390
427
  with the document's current version, or ``None`` if the key or path
391
- is missing.
428
+ is missing. A missing key on a halted shard's answer raises
429
+ :class:`StaleNotFoundError` instead.
392
430
  """
393
431
  opts = options or KVJsonOptions()
394
432
  response = await self._client._send_and_check(
@@ -398,10 +436,12 @@ class KVOperations:
398
436
  encode_json_get_body(path, opts.routing_key),
399
437
  allow_not_found=True,
400
438
  )
401
- if _absent(response):
439
+ if _absent(response, stale_raises=True):
402
440
  return None
403
441
  version, document = decode_json_get_answer(response.data)
404
- return GetJsonResult(value=json.loads(document.decode("utf-8")), version=version)
442
+ return GetJsonResult(
443
+ value=json.loads(document.decode("utf-8")), version=version, stale=response.stale
444
+ )
405
445
 
406
446
  async def json_set(
407
447
  self,