flo-python 0.1.3__tar.gz → 0.1.4__tar.gz

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.
Files changed (69) hide show
  1. {flo_python-0.1.3 → flo_python-0.1.4}/.github/flo-ref.env +1 -1
  2. {flo_python-0.1.3 → flo_python-0.1.4}/.github/workflows/ci.yml +1 -1
  3. flo_python-0.1.4/CHANGELOG.md +74 -0
  4. {flo_python-0.1.3 → flo_python-0.1.4}/PKG-INFO +16 -7
  5. {flo_python-0.1.3 → flo_python-0.1.4}/README.md +15 -6
  6. {flo_python-0.1.3 → flo_python-0.1.4}/pyproject.toml +1 -1
  7. {flo_python-0.1.3 → flo_python-0.1.4}/src/flo/__init__.py +15 -3
  8. {flo_python-0.1.3 → flo_python-0.1.4}/src/flo/actions.py +10 -9
  9. {flo_python-0.1.3 → flo_python-0.1.4}/src/flo/exceptions.py +10 -0
  10. {flo_python-0.1.3 → flo_python-0.1.4}/src/flo/kv.py +2 -1
  11. {flo_python-0.1.3 → flo_python-0.1.4}/src/flo/kv_body.py +34 -6
  12. {flo_python-0.1.3 → flo_python-0.1.4}/src/flo/processing.py +63 -35
  13. {flo_python-0.1.3 → flo_python-0.1.4}/src/flo/streams.py +33 -8
  14. {flo_python-0.1.3 → flo_python-0.1.4}/src/flo/types.py +106 -25
  15. {flo_python-0.1.3 → flo_python-0.1.4}/src/flo/wire.py +4 -3
  16. {flo_python-0.1.3 → flo_python-0.1.4}/src/flo/workflows.py +173 -24
  17. {flo_python-0.1.3 → flo_python-0.1.4}/tests/test_kv_ops.py +38 -8
  18. {flo_python-0.1.3 → flo_python-0.1.4}/tests/test_kv_table.py +2 -1
  19. flo_python-0.1.4/tests/test_list_paging.py +227 -0
  20. flo_python-0.1.4/tests/test_list_paging_live.py +157 -0
  21. flo_python-0.1.4/tests/test_missing_answers_live.py +22 -0
  22. flo_python-0.1.4/tests/test_not_found_answers.py +39 -0
  23. flo_python-0.1.4/tests/test_op_codes.py +28 -0
  24. {flo_python-0.1.3 → flo_python-0.1.4}/tests/test_processing_decode.py +45 -4
  25. {flo_python-0.1.3 → flo_python-0.1.4}/tests/test_status_codes.py +12 -0
  26. flo_python-0.1.4/tests/test_stream_delete.py +60 -0
  27. flo_python-0.1.4/tests/test_stream_delete_live.py +24 -0
  28. {flo_python-0.1.3 → flo_python-0.1.4}/tests/test_wire.py +1 -1
  29. flo_python-0.1.4/tests/test_workflow_list_runs.py +110 -0
  30. flo_python-0.1.4/tests/test_workflow_runs_live.py +129 -0
  31. {flo_python-0.1.3 → flo_python-0.1.4}/tests/test_workflows.py +20 -110
  32. flo_python-0.1.3/tests/test_list_paging.py +0 -66
  33. {flo_python-0.1.3 → flo_python-0.1.4}/.github/workflows/release.yml +0 -0
  34. {flo_python-0.1.3 → flo_python-0.1.4}/.gitignore +0 -0
  35. {flo_python-0.1.3 → flo_python-0.1.4}/LICENSE +0 -0
  36. {flo_python-0.1.3 → flo_python-0.1.4}/examples/basic.py +0 -0
  37. {flo_python-0.1.3 → flo_python-0.1.4}/examples/stream_worker.py +0 -0
  38. {flo_python-0.1.3 → flo_python-0.1.4}/examples/test_decorator.py +0 -0
  39. {flo_python-0.1.3 → flo_python-0.1.4}/examples/worker.py +0 -0
  40. {flo_python-0.1.3 → flo_python-0.1.4}/src/flo/client.py +0 -0
  41. {flo_python-0.1.3 → flo_python-0.1.4}/src/flo/kv_txn.py +0 -0
  42. {flo_python-0.1.3 → flo_python-0.1.4}/src/flo/queue.py +0 -0
  43. {flo_python-0.1.3 → flo_python-0.1.4}/src/flo/retry.py +0 -0
  44. {flo_python-0.1.3 → flo_python-0.1.4}/src/flo/worker.py +0 -0
  45. {flo_python-0.1.3 → flo_python-0.1.4}/tests/__init__.py +0 -0
  46. {flo_python-0.1.3 → flo_python-0.1.4}/tests/conftest.py +0 -0
  47. {flo_python-0.1.3 → flo_python-0.1.4}/tests/order-workflow.yaml +0 -0
  48. {flo_python-0.1.3 → flo_python-0.1.4}/tests/test_action_status.py +0 -0
  49. {flo_python-0.1.3 → flo_python-0.1.4}/tests/test_auto_touch.py +0 -0
  50. {flo_python-0.1.3 → flo_python-0.1.4}/tests/test_block_ms.py +0 -0
  51. {flo_python-0.1.3 → flo_python-0.1.4}/tests/test_blocking_deadline.py +0 -0
  52. {flo_python-0.1.3 → flo_python-0.1.4}/tests/test_empty_poll_backoff.py +0 -0
  53. {flo_python-0.1.3 → flo_python-0.1.4}/tests/test_halts.py +0 -0
  54. {flo_python-0.1.3 → flo_python-0.1.4}/tests/test_kv_live.py +0 -0
  55. {flo_python-0.1.3 → flo_python-0.1.4}/tests/test_kv_ttl.py +0 -0
  56. {flo_python-0.1.3 → flo_python-0.1.4}/tests/test_ops_drift.py +0 -0
  57. {flo_python-0.1.3 → flo_python-0.1.4}/tests/test_poll_loops.py +0 -0
  58. {flo_python-0.1.3 → flo_python-0.1.4}/tests/test_protocol_version.py +0 -0
  59. {flo_python-0.1.3 → flo_python-0.1.4}/tests/test_result_resend.py +0 -0
  60. {flo_python-0.1.3 → flo_python-0.1.4}/tests/test_retry.py +0 -0
  61. {flo_python-0.1.3 → flo_python-0.1.4}/tests/test_stream_tier.py +0 -0
  62. {flo_python-0.1.3 → flo_python-0.1.4}/tests/test_stream_trim.py +0 -0
  63. {flo_python-0.1.3 → flo_python-0.1.4}/tests/test_stream_worker_ack.py +0 -0
  64. {flo_python-0.1.3 → flo_python-0.1.4}/tests/test_worker_drain.py +0 -0
  65. {flo_python-0.1.3 → flo_python-0.1.4}/tests/test_worker_info.py +0 -0
  66. {flo_python-0.1.3 → flo_python-0.1.4}/tests/test_worker_info_live.py +0 -0
  67. {flo_python-0.1.3 → flo_python-0.1.4}/tests/test_worker_list.py +0 -0
  68. {flo_python-0.1.3 → flo_python-0.1.4}/tests/test_worker_live.py +0 -0
  69. {flo_python-0.1.3 → flo_python-0.1.4}/tests/test_worker_liveness.py +0 -0
@@ -1,4 +1,4 @@
1
1
  # The flo commit the live tests run against: CI checks floruntime/flo out at
2
2
  # this commit, builds it and starts it. Bump it in the same commit as
3
3
  # TABLE_HASH, so the SDK and the server agree.
4
- FLO_REF=51735a8132c7826b175e53a9b690d120dd9cf52d
4
+ FLO_REF=3614d952e56553b3a32d86e644f85c8dbc48f825
@@ -91,7 +91,7 @@ jobs:
91
91
  echo "FLO_BINARY=$RUNNER_TEMP/flo-bin/bin/flo" >> "$GITHUB_ENV"
92
92
  echo "FLO_OPS_JSON=$RUNNER_TEMP/flo-bin/gen/ops.json" >> "$GITHUB_ENV"
93
93
  mkdir -p flo-data flo-expiry-data
94
- ./flo-bin/bin/flo server start --port 4453 --data-dir "$RUNNER_TEMP/flo-data" > flo-server.log 2>&1 &
94
+ ./flo-bin/bin/flo server start --port 4453 --data-dir "$RUNNER_TEMP/flo-data" --shards 12 > flo-server.log 2>&1 &
95
95
  # A second server that removes a worker a second after its last
96
96
  # heartbeat, for the re-register test.
97
97
  printf '[workers]\nheartbeat_timeout_ms = 1000\nremove_after_ms = 1000\n' > flo-fast-expiry.toml
@@ -0,0 +1,74 @@
1
+ # Changelog
2
+
3
+ All notable changes to the Flo Python SDK will be documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
+
8
+ ## [Unreleased]
9
+
10
+ The op table hash moves with the server in this release: this SDK talks only
11
+ to the flo it pins, and the pin lands with the release.
12
+ The server's op table hash is now `0xc751512225a42d04` (`TABLE_HASH`).
13
+
14
+ ### Added
15
+
16
+ - `NoNamespaceError` for status `NO_NAMESPACE` (14), its own error rather
17
+ than a `NotFoundError` (a missing key)
18
+ - `WorkflowListRunsOptions.search`: only runs whose id, workflow, step,
19
+ input or tags hold it, ignoring case
20
+ - `WorkflowListRunsResult` carries a run list's page (`runs` of
21
+ `WorkflowRunEntry`: `run_id`, `workflow`, `status`, `created_at`) with
22
+ `cursor` and `has_more`
23
+ - `Reason.ADMIN_ONLY` (30): the op is served only on a node's admin socket
24
+ - `ActionListOptions.cursor` and `ActionListResult.has_more`: `action.list`
25
+ pages
26
+ - `stream.delete` (`STREAM_DELETE`, 0x140) deletes a stream's records and
27
+ metadata; a missing stream succeeds, and one that still has records raises
28
+ `ConflictError` unless `StreamDeleteOptions(force=True)`
29
+
30
+ ### Changed
31
+
32
+ - `action.list` returns the page's action names (`ActionListResult.names`)
33
+ and the next page's cursor; it returned an empty list whatever the server
34
+ answered
35
+ - A `kv.scan` cursor holds the shard and the last key returned, so it may be
36
+ up to 4098 bytes (was 64); its length prefix is a u16 in the request and
37
+ the answer
38
+ - `NAMESPACE_ENSURE` (0x016) is a known op code; shards send it to each
39
+ other, and no client API sends it
40
+
41
+ ### Breaking
42
+
43
+ - Listing workers in a namespace never created raises `NoNamespaceError`, so
44
+ a list right after starting a worker there can raise it until the worker
45
+ has registered (the write that creates the namespace).
46
+ - `workflow.history` of a missing run, and a
47
+ `NOT_FOUND` answer to `stream.append`, `read`, `info`, `group_join`,
48
+ `group_leave`, `group_read`, `group_pending` or `group_claim`, raise
49
+ `NotFoundError`; the refusal's body was parsed as the answer
50
+ (`workflow.history` of a missing run returned it as the history)
51
+ - The cluster op codes are the server's: `CLUSTER_PROMOTE` (0x032),
52
+ `CLUSTER_REMOVE` (0x033) and `CLUSTER_REPAIR_SKIP` (0x034, admin socket
53
+ only) replace `CLUSTER_JOIN`, `CLUSTER_LEAVE`, `CLUSTER_TRANSFER_LEADER`,
54
+ `CLUSTER_ADD_NODE` and `CLUSTER_REMOVE_NODE`, which the server never
55
+ served. No client API sends them
56
+ - `NAMESPACE_CONFIG_SET` and `NAMESPACE_CONFIG_GET` (0x014, 0x015) are gone:
57
+ the server retired them
58
+ - `ActionListResult.actions` is now `ActionListResult.names`, and
59
+ `ActionInfo` is gone: the action list carries names only
60
+ - `processing.list` returns a `ProcessingListResult` (`jobs`, `cursor`,
61
+ `has_more`) in place of a bare list, so a caller can page past the first
62
+ page with `ProcessingListOptions.cursor`; it dropped the server's cursor
63
+ - `workflow.list_definitions` returns a `WorkflowListDefinitionsResult`
64
+ (`definitions` of `WorkflowDefinitionEntry`, `cursor`, `has_more`) in place of
65
+ the raw answer bytes
66
+ - `workflow.list_runs` returns a `WorkflowListRunsResult` in place of the raw
67
+ answer bytes, newest first, and refuses a malformed answer.
68
+ `WorkflowListRunsOptions.status_filter` is now `status`. A page can come
69
+ back short with more after it: page until `has_more` is False
70
+ - `stream.info` of a stream that doesn't exist raises `NotFoundError`; the
71
+ server answered it with zeros
72
+ - A read, list or scan in a namespace that was never created raises
73
+ `NoNamespaceError`; the server answered it as a missing key or an empty
74
+ page. A write still creates the namespace
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: flo-python
3
- Version: 0.1.3
3
+ Version: 0.1.4
4
4
  Summary: Python SDK for the Flo distributed systems platform
5
5
  Project-URL: Homepage, https://github.com/floruntime/flo-python
6
6
  Project-URL: Documentation, https://github.com/floruntime/flo-python#readme
@@ -139,7 +139,7 @@ while True:
139
139
  result = await client.kv.scan("user:", opts)
140
140
  for name in result.names:
141
141
  print(name)
142
- if result.cursor is None or not result.names:
142
+ if result.cursor is None:
143
143
  break
144
144
  opts = ScanOptions(cursor=result.cursor, limit=100)
145
145
  ```
@@ -411,11 +411,19 @@ if status.error_message is not None:
411
411
  ```python
412
412
  from flo import ActionListOptions
413
413
 
414
- # List all actions
415
- actions = await client.action.list()
414
+ # List the namespace's actions a page at a time
415
+ opts = ActionListOptions(limit=100)
416
+ while True:
417
+ page = await client.action.list(opts)
418
+ for name in page.names:
419
+ print(name)
420
+ if page.cursor is None:
421
+ break
422
+ opts = ActionListOptions(limit=100, cursor=page.cursor)
416
423
 
417
- # List with prefix filter
418
- actions = await client.action.list(ActionListOptions(prefix="process-"))
424
+ # Only actions whose names start with a prefix (needs the next server
425
+ # release; the current one lists every action)
426
+ page = await client.action.list(ActionListOptions(prefix="process-"))
419
427
 
420
428
  # Delete an action
421
429
  await client.action.delete("process-image")
@@ -456,7 +464,7 @@ while True:
456
464
  page = await client.worker.list(opts)
457
465
  for w in page.workers:
458
466
  print(w.worker_id, w.status)
459
- if page.cursor is None or not page.workers:
467
+ if page.cursor is None:
460
468
  break
461
469
  opts = WorkerListOptions(limit=100, action="process-image", cursor=page.cursor)
462
470
  ```
@@ -619,6 +627,7 @@ A call that times out (`RequestTimeoutError`, also an `asyncio.TimeoutError`) or
619
627
  | Error | Description |
620
628
  |-------|-------------|
621
629
  | `NotFoundError` | Key or resource not found |
630
+ | `NoNamespaceError` | Status `NO_NAMESPACE` (14), not a `NotFoundError`: a read, list or scan in a namespace that was never created (a write creates it) |
622
631
  | `BadRequestError` | Invalid request parameters |
623
632
  | `ConflictError` | CAS version mismatch |
624
633
  | `UnauthorizedError` | Authentication failed |
@@ -108,7 +108,7 @@ while True:
108
108
  result = await client.kv.scan("user:", opts)
109
109
  for name in result.names:
110
110
  print(name)
111
- if result.cursor is None or not result.names:
111
+ if result.cursor is None:
112
112
  break
113
113
  opts = ScanOptions(cursor=result.cursor, limit=100)
114
114
  ```
@@ -380,11 +380,19 @@ if status.error_message is not None:
380
380
  ```python
381
381
  from flo import ActionListOptions
382
382
 
383
- # List all actions
384
- actions = await client.action.list()
383
+ # List the namespace's actions a page at a time
384
+ opts = ActionListOptions(limit=100)
385
+ while True:
386
+ page = await client.action.list(opts)
387
+ for name in page.names:
388
+ print(name)
389
+ if page.cursor is None:
390
+ break
391
+ opts = ActionListOptions(limit=100, cursor=page.cursor)
385
392
 
386
- # List with prefix filter
387
- actions = await client.action.list(ActionListOptions(prefix="process-"))
393
+ # Only actions whose names start with a prefix (needs the next server
394
+ # release; the current one lists every action)
395
+ page = await client.action.list(ActionListOptions(prefix="process-"))
388
396
 
389
397
  # Delete an action
390
398
  await client.action.delete("process-image")
@@ -425,7 +433,7 @@ while True:
425
433
  page = await client.worker.list(opts)
426
434
  for w in page.workers:
427
435
  print(w.worker_id, w.status)
428
- if page.cursor is None or not page.workers:
436
+ if page.cursor is None:
429
437
  break
430
438
  opts = WorkerListOptions(limit=100, action="process-image", cursor=page.cursor)
431
439
  ```
@@ -588,6 +596,7 @@ A call that times out (`RequestTimeoutError`, also an `asyncio.TimeoutError`) or
588
596
  | Error | Description |
589
597
  |-------|-------------|
590
598
  | `NotFoundError` | Key or resource not found |
599
+ | `NoNamespaceError` | Status `NO_NAMESPACE` (14), not a `NotFoundError`: a read, list or scan in a namespace that was never created (a write creates it) |
591
600
  | `BadRequestError` | Invalid request parameters |
592
601
  | `ConflictError` | CAS version mismatch |
593
602
  | `UnauthorizedError` | Authentication failed |
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "flo-python"
7
- version = "0.1.3"
7
+ version = "0.1.4"
8
8
  description = "Python SDK for the Flo distributed systems platform"
9
9
  readme = "README.md"
10
10
  license = "Apache-2.0"
@@ -46,6 +46,7 @@ from .exceptions import (
46
46
  InvalidMagicError,
47
47
  KeyTooLargeError,
48
48
  NamespaceTooLargeError,
49
+ NoNamespaceError,
49
50
  NonRetryableError,
50
51
  NotConnectedError,
51
52
  NotFoundError,
@@ -71,7 +72,6 @@ from .retry import DEFAULT_RETRY_POLICY, RetryPolicy
71
72
  from .types import (
72
73
  AckOptions,
73
74
  ActionDeleteOptions,
74
- ActionInfo,
75
75
  ActionInvokeOptions,
76
76
  ActionInvokeResult,
77
77
  ActionListOptions,
@@ -111,6 +111,7 @@ from .types import (
111
111
  ProcessingCancelOptions,
112
112
  ProcessingListEntry,
113
113
  ProcessingListOptions,
114
+ ProcessingListResult,
114
115
  ProcessingStatusOptions,
115
116
  ProcessingStatusResult,
116
117
  ProcessingStopOptions,
@@ -130,6 +131,7 @@ from .types import (
130
131
  StreamAppendOptions,
131
132
  StreamAppendResult,
132
133
  StreamClaimResult,
134
+ StreamDeleteOptions,
133
135
  StreamGroupAckOptions,
134
136
  StreamGroupJoinOptions,
135
137
  StreamGroupNackOptions,
@@ -160,12 +162,16 @@ from .types import (
160
162
  WorkerType,
161
163
  WorkflowCancelOptions,
162
164
  WorkflowCreateOptions,
165
+ WorkflowDefinitionEntry,
163
166
  WorkflowDisableOptions,
164
167
  WorkflowEnableOptions,
165
168
  WorkflowGetDefinitionOptions,
166
169
  WorkflowHistoryOptions,
167
170
  WorkflowListDefinitionsOptions,
171
+ WorkflowListDefinitionsResult,
168
172
  WorkflowListRunsOptions,
173
+ WorkflowListRunsResult,
174
+ WorkflowRunEntry,
169
175
  WorkflowSignalOptions,
170
176
  WorkflowStartOptions,
171
177
  WorkflowStatusOptions,
@@ -184,7 +190,7 @@ from .worker import (
184
190
  )
185
191
  from .workflows import WorkflowOperations
186
192
 
187
- __version__ = "0.1.3"
193
+ __version__ = "0.1.4"
188
194
 
189
195
  __all__ = [
190
196
  "Transaction",
@@ -240,6 +246,7 @@ __all__ = [
240
246
  "BlockTooLongError",
241
247
  "ServerError",
242
248
  "NotFoundError",
249
+ "NoNamespaceError",
243
250
  "BadRequestError",
244
251
  "ConflictError",
245
252
  "UnauthorizedError",
@@ -292,6 +299,7 @@ __all__ = [
292
299
  "StreamTrimOptions",
293
300
  "StreamTrimResult",
294
301
  "StreamInfoOptions",
302
+ "StreamDeleteOptions",
295
303
  "StreamGroupJoinOptions",
296
304
  "StreamGroupReadOptions",
297
305
  "StreamGroupAckOptions",
@@ -299,7 +307,6 @@ __all__ = [
299
307
  # Action types
300
308
  "ActionType",
301
309
  "RunStatus",
302
- "ActionInfo",
303
310
  "ActionRunStatus",
304
311
  "ActionInvokeResult",
305
312
  "ActionListResult",
@@ -336,7 +343,11 @@ __all__ = [
336
343
  "WorkflowCancelOptions",
337
344
  "WorkflowHistoryOptions",
338
345
  "WorkflowListRunsOptions",
346
+ "WorkflowListRunsResult",
347
+ "WorkflowRunEntry",
339
348
  "WorkflowListDefinitionsOptions",
349
+ "WorkflowListDefinitionsResult",
350
+ "WorkflowDefinitionEntry",
340
351
  "WorkflowDisableOptions",
341
352
  "WorkflowEnableOptions",
342
353
  "WorkflowSyncOptions",
@@ -351,5 +362,6 @@ __all__ = [
351
362
  "ProcessingSyncOptions",
352
363
  "ProcessingStatusResult",
353
364
  "ProcessingListEntry",
365
+ "ProcessingListResult",
354
366
  "ProcessingSyncResult",
355
367
  ]
@@ -11,6 +11,7 @@ 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,
15
16
  decode_worker_info_answer,
16
17
  decode_worker_list_answer,
@@ -159,28 +160,28 @@ class ActionOperations:
159
160
  self,
160
161
  options: ActionListOptions | None = None,
161
162
  ) -> ActionListResult:
162
- """List registered actions.
163
+ """List a page of the namespace's registered actions.
163
164
 
164
165
  Args:
165
- options: Optional list options.
166
+ options: The page's limit and cursor (the last page's ``cursor``;
167
+ None starts).
166
168
 
167
169
  Returns:
168
- 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.
169
172
  """
170
173
  opts = options or ActionListOptions()
171
174
  namespace = self._client.get_namespace(opts.namespace)
172
175
 
173
- value = serialize_action_list_value(limit=opts.limit)
174
-
175
- await self._client._send_and_check(
176
+ response = await self._client._send_and_check(
176
177
  OpCode.ACTION_LIST,
177
178
  namespace,
178
179
  (opts.prefix or "").encode("utf-8"),
179
- value,
180
+ serialize_action_list_value(limit=opts.limit, cursor=opts.cursor),
180
181
  )
181
182
 
182
- # Parse list response - format TBD based on server implementation
183
- return ActionListResult(actions=[])
183
+ names, cursor = decode_action_list_answer(response.data)
184
+ return ActionListResult(names=names, cursor=cursor)
184
185
 
185
186
  async def delete(
186
187
  self,
@@ -191,6 +191,15 @@ class StaleNotFoundError(NotFoundError):
191
191
  stale = True
192
192
 
193
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
+
194
203
  class BadRequestError(ServerError):
195
204
  """Invalid request parameters."""
196
205
 
@@ -311,6 +320,7 @@ def _error_for(status: StatusCode, message: str) -> ServerError:
311
320
 
312
321
  error_map: dict[StatusCode, Callable[[str], ServerError]] = {
313
322
  StatusCode.NOT_FOUND: NotFoundError,
323
+ StatusCode.NO_NAMESPACE: NoNamespaceError,
314
324
  StatusCode.BAD_REQUEST: BadRequestError,
315
325
  StatusCode.CONFLICT: ConflictError,
316
326
  StatusCode.UNAUTHORIZED: UnauthorizedError,
@@ -207,6 +207,7 @@ class KVOperations:
207
207
  when it has none. ``stale`` says a halted shard answered.
208
208
 
209
209
  Raises:
210
+ NoNamespaceError: The namespace was never created.
210
211
  StaleNotFoundError: A halted shard had no such key as of the entry
211
212
  it halted at; it may exist since.
212
213
 
@@ -323,7 +324,7 @@ class KVOperations:
323
324
  result = await client.kv.scan("user:", opts)
324
325
  for name in result.names:
325
326
  print(name)
326
- if result.cursor is None or not result.names:
327
+ if result.cursor is None:
327
328
  break
328
329
  opts = ScanOptions(cursor=result.cursor)
329
330
  """
@@ -39,7 +39,9 @@ from .types import (
39
39
  _MAX_ROUTING_KEY = 4096
40
40
  _MAX_JSON_PATH = 1024
41
41
  _MAX_JSON_DOCUMENT = 252_819
42
- _MAX_SCAN_CURSOR = 64
42
+ # A scan's cursor: the shard it stopped on (u16), then the last key it
43
+ # returned; its length prefix is a u16.
44
+ _MAX_SCAN_CURSOR = 2 + 4096
43
45
  MAX_SCAN = 1024
44
46
  MAX_MGET = 256
45
47
  # The most bytes of mget key elements (each [len:u16][key]) in one request:
@@ -47,6 +49,7 @@ MAX_MGET = 256
47
49
  MAX_MGET_KEYS_BYTES = 253_848
48
50
  MAX_HISTORY = 65
49
51
  MAX_WORKER_LIST = 1024
52
+ MAX_ACTION_LIST = 1024
50
53
  MAX_WORKER_PROCESSES = 1024
51
54
  _MAX_WORKER_ID = 4096
52
55
  # The longest TTL whose nanoseconds fit a u64.
@@ -175,10 +178,9 @@ def encode_delete_body(
175
178
 
176
179
  def encode_scan_body(limit: int, cursor: bytes | None) -> bytes:
177
180
  """kv.scan's request: limit, cursor (empty for the first page)."""
178
- cursor = cursor or b""
179
- if len(cursor) > _MAX_SCAN_CURSOR:
180
- raise ValidationError(f"scan cursor is {len(cursor)} bytes, at most {_MAX_SCAN_CURSOR}")
181
- return _limit("scan limit", limit, MAX_SCAN) + bytes([len(cursor)]) + cursor
181
+ return _limit("scan limit", limit, MAX_SCAN) + _bytes16(
182
+ "scan cursor", cursor or b"", _MAX_SCAN_CURSOR
183
+ )
182
184
 
183
185
 
184
186
  def encode_history_body(limit: int, before_version: int | None, routing_key: str | None) -> bytes:
@@ -370,7 +372,7 @@ def decode_scan_answer(data: bytes) -> tuple[list[str], bytes | None]:
370
372
  names = [a.bytes16().decode("utf-8") for _ in range(a.u16())]
371
373
  except UnicodeDecodeError as e:
372
374
  raise IncompleteResponseError("kv.scan answer has a name that isn't UTF-8") from e
373
- cursor = a.bytes8() if a.present() else None
375
+ cursor = a.bytes16() if a.present() else None
374
376
  a.done()
375
377
  return names, cursor
376
378
 
@@ -522,6 +524,32 @@ def decode_action_invoke_answer(data: bytes) -> str:
522
524
  return run_id.decode("utf-8")
523
525
 
524
526
 
527
+ def decode_action_list_answer(data: bytes) -> tuple[list[str], bytes | None]:
528
+ """action.list's answer: [count:u32]([name_len:u16][name][value_len:u32][value])*
529
+ [has_more:u8][cursor_len:u16][cursor]. Returns the names and the next
530
+ page's cursor, None on the last page; the values aren't read."""
531
+ op = "action.list"
532
+ a = _Answer(op, data)
533
+ count = a.u32()
534
+ if count > MAX_ACTION_LIST:
535
+ raise IncompleteResponseError(f"{op} answer lists {count} actions")
536
+ names = []
537
+ for _ in range(count):
538
+ try:
539
+ names.append(a.bytes16().decode("utf-8"))
540
+ except UnicodeDecodeError as e:
541
+ raise IncompleteResponseError(f"{op} answer has a name that isn't UTF-8") from e
542
+ a.bytes32()
543
+ has_more = a.flag()
544
+ cursor = a.bytes16()
545
+ a.done()
546
+ if has_more and not cursor:
547
+ raise IncompleteResponseError(f"{op} answer has more pages but no cursor")
548
+ if not has_more and cursor:
549
+ raise IncompleteResponseError(f"{op} answer has a cursor on its last page")
550
+ return names, cursor if has_more else None
551
+
552
+
525
553
  _E = TypeVar("_E", WorkerType, WorkerStatus, ProcessKind)
526
554
 
527
555
 
@@ -17,6 +17,7 @@ from .types import (
17
17
  ProcessingCancelOptions,
18
18
  ProcessingListEntry,
19
19
  ProcessingListOptions,
20
+ ProcessingListResult,
20
21
  ProcessingStatusOptions,
21
22
  ProcessingStatusResult,
22
23
  ProcessingStopOptions,
@@ -29,6 +30,8 @@ if TYPE_CHECKING:
29
30
  from .client import FloClient
30
31
 
31
32
  _PROCESSING_STATUS_NAMES = ["running", "stopped", "cancelled", "failed", "completed"]
33
+ # The most jobs one list page holds.
34
+ _MAX_PROCESSING_LIST = 1024
32
35
 
33
36
 
34
37
  class ProcessingOperations:
@@ -62,7 +65,11 @@ class ProcessingOperations:
62
65
  async def status(
63
66
  self, job_id: str, options: ProcessingStatusOptions | None = None
64
67
  ) -> ProcessingStatusResult | None:
65
- """Get the status of a processing job. Returns None if not found."""
68
+ """Get the status of a processing job. Returns None if not found.
69
+
70
+ Raises:
71
+ NoNamespaceError: The namespace was never created.
72
+ """
66
73
  opts = options or ProcessingStatusOptions()
67
74
  namespace = self._client.get_namespace(opts.namespace)
68
75
 
@@ -81,14 +88,22 @@ class ProcessingOperations:
81
88
 
82
89
  return _parse_processing_status(resp.data)
83
90
 
84
- async def list(self, options: ProcessingListOptions | None = None) -> list[ProcessingListEntry]:
85
- """List processing jobs."""
91
+ async def list(self, options: ProcessingListOptions | None = None) -> ProcessingListResult:
92
+ """List a page of the namespace's processing jobs.
93
+
94
+ Args:
95
+ options: The page's limit and cursor (the last page's ``cursor``;
96
+ None starts).
97
+
98
+ Returns:
99
+ ProcessingListResult with the page's jobs and the next page's
100
+ cursor, None on the last page.
101
+ """
86
102
  opts = options or ProcessingListOptions()
87
103
  namespace = self._client.get_namespace(opts.namespace)
88
104
 
89
105
  # Wire format: [limit:u32][cursor...]
90
- cursor = opts.cursor or b""
91
- value = struct.pack("<I", opts.limit) + cursor
106
+ value = struct.pack("<I", opts.limit) + (opts.cursor or b"")
92
107
 
93
108
  resp = await self._client._send_and_check(
94
109
  OpCode.PROCESSING_LIST,
@@ -97,7 +112,8 @@ class ProcessingOperations:
97
112
  value,
98
113
  )
99
114
 
100
- return _parse_processing_list(resp.data)
115
+ entries, next_cursor = _parse_processing_list(resp.data)
116
+ return ProcessingListResult(jobs=entries, cursor=next_cursor)
101
117
 
102
118
  async def stop(self, job_id: str, options: ProcessingStopOptions | None = None) -> None:
103
119
  """Gracefully stop a processing job."""
@@ -217,50 +233,62 @@ def _parse_processing_status(data: bytes) -> ProcessingStatusResult:
217
233
  )
218
234
 
219
235
 
220
- def _parse_processing_list(data: bytes) -> list[ProcessingListEntry]:
221
- """Parse binary wire format for processing job list.
236
+ def _parse_processing_list(data: bytes) -> tuple[list[ProcessingListEntry], bytes | None]:
237
+ """Parse binary wire format for processing job list: the page's jobs and
238
+ the next page's cursor, None on the last page.
222
239
 
223
240
  Wire format: [count:u32]([name_len:u16][name][job_id_len:u16][job_id]
224
241
  [status_len:u16][status][created_at:i64])*
242
+ [has_more:u8][cursor_len:u16][cursor]
243
+ A failed job's status reads "FAILED: <reason>".
225
244
  """
226
- if len(data) < 4:
227
- return []
228
-
229
- (count,) = struct.unpack_from("<I", data, 0)
230
- pos = 4
231
- results: list[ProcessingListEntry] = []
245
+ pos = 0
232
246
 
233
- def read_u16() -> int:
247
+ def take(n: int) -> bytes:
234
248
  nonlocal pos
235
- v: int = struct.unpack_from("<H", data, pos)[0]
236
- pos += 2
237
- return v
249
+ if pos + n > len(data):
250
+ raise IncompleteResponseError("processing.list answer is truncated")
251
+ b = data[pos : pos + n]
252
+ pos += n
253
+ return b
238
254
 
239
255
  def read_str() -> str:
240
- n = read_u16()
241
- nonlocal pos
242
- s = data[pos : pos + n].decode("utf-8")
243
- pos += n
244
- return s
256
+ (n,) = struct.unpack("<H", take(2))
257
+ raw = take(n)
258
+ try:
259
+ return raw.decode("utf-8")
260
+ except UnicodeDecodeError as e:
261
+ raise IncompleteResponseError(
262
+ "processing.list answer has a field that isn't UTF-8"
263
+ ) from e
245
264
 
265
+ (count,) = struct.unpack("<I", take(4))
266
+ if count > _MAX_PROCESSING_LIST:
267
+ raise IncompleteResponseError(f"processing.list answer lists {count} jobs")
268
+ entries: list[ProcessingListEntry] = []
246
269
  for _ in range(count):
247
270
  name = read_str()
248
271
  job_id = read_str()
249
272
  status = read_str()
250
-
251
- (created_at,) = struct.unpack_from("<q", data, pos)
252
- pos += 8
253
-
254
- results.append(
255
- ProcessingListEntry(
256
- name=name,
257
- job_id=job_id,
258
- status=status,
259
- created_at=created_at,
260
- )
273
+ (created_at,) = struct.unpack("<q", take(8))
274
+ entries.append(
275
+ ProcessingListEntry(name=name, job_id=job_id, status=status, created_at=created_at)
261
276
  )
262
277
 
263
- return results
278
+ has_more = take(1)[0]
279
+ if has_more > 1:
280
+ raise IncompleteResponseError(f"processing.list answer has a has_more of {has_more}")
281
+ (cursor_len,) = struct.unpack("<H", take(2))
282
+ cursor = take(cursor_len)
283
+ if pos != len(data):
284
+ raise IncompleteResponseError(
285
+ f"processing.list answer has {len(data) - pos} bytes after the cursor"
286
+ )
287
+ if has_more and not cursor:
288
+ raise IncompleteResponseError("processing.list answer has more pages but no cursor")
289
+ if not has_more and cursor:
290
+ raise IncompleteResponseError("processing.list answer has a cursor on its last page")
291
+ return entries, cursor if has_more else None
264
292
 
265
293
 
266
294
  # =============================================================================