flo-python 0.1.3__py3-none-any.whl → 0.1.5__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
@@ -39,13 +39,16 @@ from .exceptions import (
39
39
  ConnectionFailedError,
40
40
  FloError,
41
41
  GenericServerError,
42
+ GroupHeldFullError,
42
43
  IncompleteResponseError,
43
44
  InternalServerError,
44
45
  InvalidChecksumError,
45
46
  InvalidEndpointError,
46
47
  InvalidMagicError,
47
48
  KeyTooLargeError,
49
+ LimitError,
48
50
  NamespaceTooLargeError,
51
+ NoNamespaceError,
49
52
  NonRetryableError,
50
53
  NotConnectedError,
51
54
  NotFoundError,
@@ -53,10 +56,12 @@ from .exceptions import (
53
56
  OverloadedError,
54
57
  PayloadTooLargeError,
55
58
  ProtocolError,
59
+ QueueFullError,
56
60
  RateLimitedError,
57
61
  RequestTimeoutError,
58
62
  ServerError,
59
63
  StaleNotFoundError,
64
+ StaleReportError,
60
65
  TableMismatchError,
61
66
  UnauthorizedError,
62
67
  UnavailableError,
@@ -69,11 +74,11 @@ from .kv_txn import Transaction, TxnFinishedError, TxnUnsupportedOpError
69
74
  from .processing import ProcessingOperations
70
75
  from .retry import DEFAULT_RETRY_POLICY, RetryPolicy
71
76
  from .types import (
72
- AckOptions,
73
77
  ActionDeleteOptions,
74
78
  ActionInfo,
75
79
  ActionInvokeOptions,
76
80
  ActionInvokeResult,
81
+ ActionListEntry,
77
82
  ActionListOptions,
78
83
  ActionListResult,
79
84
  ActionRegisterOptions,
@@ -81,16 +86,23 @@ from .types import (
81
86
  ActionStatusOptions,
82
87
  ActionType,
83
88
  Condition,
89
+ DeadLetter,
84
90
  DeleteOptions,
85
91
  DequeueOptions,
86
92
  DequeueResult,
87
93
  DlqListOptions,
88
- DlqRequeueOptions,
94
+ DlqPage,
89
95
  EnqueueOptions,
90
96
  ExistsResult,
91
97
  GetJsonResult,
92
98
  GetOptions,
93
99
  GetResult,
100
+ GroupMemberState,
101
+ GroupReadResult,
102
+ GroupRecord,
103
+ GroupRefusal,
104
+ GroupReportResult,
105
+ GroupTouchResult,
94
106
  HistoryOptions,
95
107
  HistoryResult,
96
108
  IncrResult,
@@ -103,14 +115,18 @@ from .types import (
103
115
  KVMGetOptions,
104
116
  Message,
105
117
  MGetEntry,
106
- NackOptions,
107
118
  OpCode,
108
119
  OptionTag,
120
+ PeekedMessage,
109
121
  PeekOptions,
122
+ PeekResult,
110
123
  PendingEntry,
111
124
  ProcessingCancelOptions,
112
125
  ProcessingListEntry,
113
126
  ProcessingListOptions,
127
+ ProcessingListResult,
128
+ ProcessingRemoveOptions,
129
+ ProcessingRuntime,
114
130
  ProcessingStatusOptions,
115
131
  ProcessingStatusResult,
116
132
  ProcessingStopOptions,
@@ -118,8 +134,15 @@ from .types import (
118
134
  ProcessingSyncOptions,
119
135
  ProcessingSyncResult,
120
136
  ProcessKind,
137
+ PurgeOptions,
121
138
  PutOptions,
122
139
  PutResult,
140
+ QueueFailOptions,
141
+ QueueRefusal,
142
+ QueueRefusalReason,
143
+ QueueReportOptions,
144
+ QueueReportResult,
145
+ QueueTouchResult,
123
146
  Ran,
124
147
  Reason,
125
148
  RunStatus,
@@ -129,9 +152,14 @@ from .types import (
129
152
  StorageTier,
130
153
  StreamAppendOptions,
131
154
  StreamAppendResult,
132
- StreamClaimResult,
155
+ StreamDeleteOptions,
133
156
  StreamGroupAckOptions,
134
- StreamGroupJoinOptions,
157
+ StreamGroupCreateOptions,
158
+ StreamGroupEntry,
159
+ StreamGroupInfo,
160
+ StreamGroupListResult,
161
+ StreamGroupMember,
162
+ StreamGroupMembersResult,
135
163
  StreamGroupNackOptions,
136
164
  StreamGroupReadOptions,
137
165
  StreamID,
@@ -156,16 +184,19 @@ from .types import (
156
184
  WorkerProcess,
157
185
  WorkerRegisterOptions,
158
186
  WorkerStatus,
159
- WorkerTouchOptions,
160
187
  WorkerType,
161
188
  WorkflowCancelOptions,
162
189
  WorkflowCreateOptions,
190
+ WorkflowDefinitionEntry,
163
191
  WorkflowDisableOptions,
164
192
  WorkflowEnableOptions,
165
193
  WorkflowGetDefinitionOptions,
166
194
  WorkflowHistoryOptions,
167
195
  WorkflowListDefinitionsOptions,
196
+ WorkflowListDefinitionsResult,
168
197
  WorkflowListRunsOptions,
198
+ WorkflowListRunsResult,
199
+ WorkflowRunEntry,
169
200
  WorkflowSignalOptions,
170
201
  WorkflowStartOptions,
171
202
  WorkflowStatusOptions,
@@ -184,7 +215,7 @@ from .worker import (
184
215
  )
185
216
  from .workflows import WorkflowOperations
186
217
 
187
- __version__ = "0.1.3"
218
+ __version__ = "0.1.5"
188
219
 
189
220
  __all__ = [
190
221
  "Transaction",
@@ -240,15 +271,20 @@ __all__ = [
240
271
  "BlockTooLongError",
241
272
  "ServerError",
242
273
  "NotFoundError",
274
+ "NoNamespaceError",
243
275
  "BadRequestError",
244
276
  "ConflictError",
245
277
  "UnauthorizedError",
278
+ "GroupHeldFullError",
246
279
  "OverloadedError",
280
+ "QueueFullError",
247
281
  "OutcomePendingError",
248
282
  "StaleNotFoundError",
283
+ "StaleReportError",
249
284
  "UnavailableError",
250
285
  "RateLimitedError",
251
286
  "InternalServerError",
287
+ "LimitError",
252
288
  "GenericServerError",
253
289
  "is_connection_error",
254
290
  # Types
@@ -264,6 +300,7 @@ __all__ = [
264
300
  "DequeueResult",
265
301
  # Options
266
302
  "Condition",
303
+ "DeadLetter",
267
304
  "GetOptions",
268
305
  "WaitFor",
269
306
  "PutOptions",
@@ -272,18 +309,29 @@ __all__ = [
272
309
  "HistoryOptions",
273
310
  "EnqueueOptions",
274
311
  "DequeueOptions",
275
- "AckOptions",
276
- "NackOptions",
277
312
  "DlqListOptions",
278
- "DlqRequeueOptions",
313
+ "DlqPage",
279
314
  "PeekOptions",
315
+ "PurgeOptions",
316
+ "QueueFailOptions",
317
+ "QueueRefusal",
318
+ "QueueRefusalReason",
319
+ "QueueReportOptions",
320
+ "QueueReportResult",
321
+ "QueueTouchResult",
322
+ "PeekedMessage",
323
+ "PeekResult",
280
324
  # Stream types
281
325
  "StreamID",
282
326
  "StorageTier",
283
327
  "StreamRecord",
284
328
  "StreamAppendResult",
285
329
  "StreamReadResult",
286
- "StreamClaimResult",
330
+ "GroupRecord",
331
+ "GroupReadResult",
332
+ "GroupRefusal",
333
+ "GroupReportResult",
334
+ "GroupTouchResult",
287
335
  "PendingEntry",
288
336
  "StreamInfo",
289
337
  # Stream options
@@ -292,14 +340,20 @@ __all__ = [
292
340
  "StreamTrimOptions",
293
341
  "StreamTrimResult",
294
342
  "StreamInfoOptions",
295
- "StreamGroupJoinOptions",
343
+ "StreamDeleteOptions",
344
+ "StreamGroupCreateOptions",
345
+ "StreamGroupInfo",
296
346
  "StreamGroupReadOptions",
297
347
  "StreamGroupAckOptions",
348
+ "StreamGroupEntry",
349
+ "StreamGroupListResult",
350
+ "StreamGroupMember",
351
+ "StreamGroupMembersResult",
352
+ "GroupMemberState",
298
353
  "StreamGroupNackOptions",
299
354
  # Action types
300
355
  "ActionType",
301
356
  "RunStatus",
302
- "ActionInfo",
303
357
  "ActionRunStatus",
304
358
  "ActionInvokeResult",
305
359
  "ActionListResult",
@@ -308,6 +362,8 @@ __all__ = [
308
362
  "ActionInvokeOptions",
309
363
  "ActionStatusOptions",
310
364
  "ActionListOptions",
365
+ "ActionListEntry",
366
+ "ActionInfo",
311
367
  "ActionDeleteOptions",
312
368
  # Worker types
313
369
  "TaskAssignment",
@@ -322,7 +378,6 @@ __all__ = [
322
378
  # Worker options
323
379
  "WorkerRegisterOptions",
324
380
  "WorkerAwaitOptions",
325
- "WorkerTouchOptions",
326
381
  "WorkerCompleteOptions",
327
382
  "WorkerFailOptions",
328
383
  "WorkerListOptions",
@@ -336,7 +391,11 @@ __all__ = [
336
391
  "WorkflowCancelOptions",
337
392
  "WorkflowHistoryOptions",
338
393
  "WorkflowListRunsOptions",
394
+ "WorkflowListRunsResult",
395
+ "WorkflowRunEntry",
339
396
  "WorkflowListDefinitionsOptions",
397
+ "WorkflowListDefinitionsResult",
398
+ "WorkflowDefinitionEntry",
340
399
  "WorkflowDisableOptions",
341
400
  "WorkflowEnableOptions",
342
401
  "WorkflowSyncOptions",
@@ -351,5 +410,8 @@ __all__ = [
351
410
  "ProcessingSyncOptions",
352
411
  "ProcessingStatusResult",
353
412
  "ProcessingListEntry",
413
+ "ProcessingListResult",
414
+ "ProcessingRemoveOptions",
415
+ "ProcessingRuntime",
354
416
  "ProcessingSyncResult",
355
417
  ]
flo/actions.py CHANGED
@@ -10,14 +10,24 @@ For a higher-level API, see `Worker` in worker.py.
10
10
  from typing import TYPE_CHECKING
11
11
 
12
12
  from .kv_body import (
13
+ decode_action_info_answer,
13
14
  decode_action_invoke_answer,
15
+ decode_action_list_answer,
14
16
  decode_action_status_answer,
17
+ decode_await_answer,
18
+ decode_empty_answer,
19
+ decode_touch_answer,
15
20
  decode_worker_info_answer,
16
21
  decode_worker_list_answer,
22
+ encode_await_body,
23
+ encode_complete_body,
24
+ encode_fail_body,
25
+ encode_touch_body,
17
26
  encode_worker_list_body,
18
27
  )
19
28
  from .types import (
20
29
  ActionDeleteOptions,
30
+ ActionInfo,
21
31
  ActionInvokeOptions,
22
32
  ActionInvokeResult,
23
33
  ActionListOptions,
@@ -27,7 +37,7 @@ from .types import (
27
37
  ActionStatusOptions,
28
38
  ActionType,
29
39
  OpCode,
30
- OptionTag,
40
+ TaskAssignment,
31
41
  WorkerAwaitOptions,
32
42
  WorkerAwaitResult,
33
43
  WorkerCompleteOptions,
@@ -37,19 +47,12 @@ from .types import (
37
47
  WorkerListResult,
38
48
  WorkerRegisterOptions,
39
49
  WorkerStatus,
40
- WorkerTouchOptions,
41
50
  )
42
51
  from .wire import (
43
- OptionsBuilder,
44
- parse_task_assignment,
45
52
  serialize_action_invoke_value,
46
53
  serialize_action_list_value,
47
54
  serialize_action_register_value,
48
- serialize_worker_await_value,
49
- serialize_worker_complete_value,
50
- serialize_worker_fail_value,
51
55
  serialize_worker_register_value,
52
- serialize_worker_touch_value,
53
56
  )
54
57
 
55
58
  if TYPE_CHECKING:
@@ -85,7 +88,7 @@ class ActionOperations:
85
88
  value = serialize_action_register_value(
86
89
  action_type=action_type,
87
90
  timeout_ms=opts.timeout_ms,
88
- max_retries=opts.max_retries,
91
+ max_attempts=opts.max_attempts,
89
92
  owner=opts.owner,
90
93
  )
91
94
 
@@ -159,28 +162,43 @@ class ActionOperations:
159
162
  self,
160
163
  options: ActionListOptions | None = None,
161
164
  ) -> ActionListResult:
162
- """List registered actions.
165
+ """List a page of the namespace's registered actions.
163
166
 
164
167
  Args:
165
- options: Optional list options.
168
+ options: The page's limit and cursor (the last page's ``cursor``;
169
+ None starts).
166
170
 
167
171
  Returns:
168
- ActionListResult with list of actions.
172
+ ActionListResult with the page's action names and the next
173
+ page's cursor, None on the last page.
169
174
  """
170
175
  opts = options or ActionListOptions()
171
176
  namespace = self._client.get_namespace(opts.namespace)
172
177
 
173
- value = serialize_action_list_value(limit=opts.limit)
174
-
175
- await self._client._send_and_check(
178
+ response = await self._client._send_and_check(
176
179
  OpCode.ACTION_LIST,
177
180
  namespace,
178
181
  (opts.prefix or "").encode("utf-8"),
179
- value,
182
+ serialize_action_list_value(limit=opts.limit, cursor=opts.cursor),
180
183
  )
181
184
 
182
- # Parse list response - format TBD based on server implementation
183
- return ActionListResult(actions=[])
185
+ actions, cursor = decode_action_list_answer(response.data)
186
+ return ActionListResult(actions=actions, cursor=cursor)
187
+
188
+ async def info(self, name: str, namespace: str | None = None) -> ActionInfo:
189
+ """An action's definition, its runs by status and how long its
190
+ completed runs took.
191
+
192
+ Raises:
193
+ NotFoundError: No action has that name.
194
+ """
195
+ response = await self._client._send_and_check(
196
+ OpCode.ACTION_INFO,
197
+ self._client.get_namespace(namespace),
198
+ name.encode("utf-8"),
199
+ b"",
200
+ )
201
+ return decode_action_info_answer(response.data)
184
202
 
185
203
  async def delete(
186
204
  self,
@@ -305,128 +323,94 @@ class WorkerOperations:
305
323
  async def await_task(
306
324
  self,
307
325
  worker_id: str,
308
- task_types: list[str],
326
+ actions: list[str],
309
327
  options: WorkerAwaitOptions | None = None,
310
328
  ) -> WorkerAwaitResult:
311
- """Wait for a task assignment.
312
-
313
- Args:
314
- worker_id: Worker identifier.
315
- task_types: Task types to listen for.
316
- options: Optional await options (block_ms).
329
+ """Wait up to ``block_ms`` for a run of one of ``actions`` (the first
330
+ tried first), and take it.
317
331
 
318
332
  Returns:
319
- WorkerAwaitResult with task if available.
333
+ WorkerAwaitResult whose task is None if no run was ready in time.
320
334
  """
321
335
  opts = options or WorkerAwaitOptions()
322
- namespace = self._client.get_namespace(opts.namespace)
323
-
324
- value = serialize_worker_await_value(task_types)
325
-
326
- options_builder = OptionsBuilder()
327
- if opts.block_ms is not None:
328
- options_builder.add_u32(OptionTag.BLOCK_MS, opts.block_ms)
329
-
330
336
  response = await self._client._send_and_check(
331
337
  OpCode.ACTION_AWAIT,
332
- namespace,
338
+ self._client.get_namespace(opts.namespace),
333
339
  worker_id.encode("utf-8"),
334
- value,
335
- options_builder.build(),
340
+ encode_await_body(actions, opts.block_ms, opts.request_key),
336
341
  )
342
+ return WorkerAwaitResult(task=decode_await_answer(response.data))
337
343
 
338
- # Parse task assignment response - if empty, no task available
339
- if not response.data:
340
- return WorkerAwaitResult(task=None)
344
+ async def touch(self, worker_id: str, task: TaskAssignment) -> int:
345
+ """Keep a task. With half its lease or less left, its lease runs a
346
+ full lease from now (up to 12 h from its delivery); with more left,
347
+ nothing changes. Touch at least every half lease.
341
348
 
342
- # Parse task assignment
343
- task = parse_task_assignment(response.data)
344
- return WorkerAwaitResult(task=task)
345
-
346
- async def touch(
347
- self,
348
- worker_id: str,
349
- action_name: str,
350
- task_id: str,
351
- options: WorkerTouchOptions | None = None,
352
- ) -> None:
353
- """Extend task lease (heartbeat).
349
+ Returns:
350
+ When the lease runs out without another touch, in Unix ms.
354
351
 
355
- Args:
356
- worker_id: Worker identifier.
357
- action_name: Action name for routing.
358
- task_id: Task identifier to extend.
359
- options: Optional touch options (extend_ms).
352
+ Raises:
353
+ StaleReportError: The run moved on from this delivery.
360
354
  """
361
- opts = options or WorkerTouchOptions()
362
- namespace = self._client.get_namespace(opts.namespace)
363
-
364
- value = serialize_worker_touch_value(action_name, task_id, opts.extend_ms)
365
-
366
- await self._client._send_and_check(
355
+ response = await self._client._send_and_check(
367
356
  OpCode.ACTION_TOUCH,
368
- namespace,
369
- worker_id.encode("utf-8"),
370
- value,
357
+ task.namespace,
358
+ task.run.encode("utf-8"),
359
+ encode_touch_body(worker_id, task),
371
360
  )
361
+ return decode_touch_answer(response.data)
372
362
 
373
363
  async def complete(
374
364
  self,
375
365
  worker_id: str,
376
- action_name: str,
377
- task_id: str,
378
- result: bytes,
366
+ task: TaskAssignment,
367
+ result: bytes = b"",
379
368
  options: WorkerCompleteOptions | None = None,
380
369
  ) -> None:
381
- """Complete a task successfully.
370
+ """Complete a task: its run is done, with this result.
382
371
 
383
- Args:
384
- worker_id: Worker identifier.
385
- action_name: Action name for routing.
386
- task_id: Task identifier to complete.
387
- result: Result data from the task.
388
- options: Optional complete options.
372
+ Sending it again after it applied answers ok, so a report whose
373
+ answer was lost can be resent unchanged.
374
+
375
+ Raises:
376
+ StaleReportError: The run moved on from this delivery, or was
377
+ completed with another result.
389
378
  """
390
379
  opts = options or WorkerCompleteOptions()
391
- namespace = self._client.get_namespace(opts.namespace)
392
-
393
- value = serialize_worker_complete_value(action_name, task_id, result, opts.outcome)
394
-
395
- await self._client._send_and_check(
380
+ response = await self._client._send_and_check(
396
381
  OpCode.ACTION_COMPLETE,
397
- namespace,
398
- worker_id.encode("utf-8"),
399
- value,
382
+ task.namespace,
383
+ task.run.encode("utf-8"),
384
+ encode_complete_body(worker_id, task, opts.outcome, result),
400
385
  )
386
+ decode_empty_answer("action.complete", response.data)
401
387
 
402
388
  async def fail(
403
389
  self,
404
390
  worker_id: str,
405
- action_name: str,
406
- task_id: str,
407
- error_message: str,
391
+ task: TaskAssignment,
392
+ error: str = "",
408
393
  options: WorkerFailOptions | None = None,
409
394
  ) -> None:
410
- """Fail a task.
395
+ """Fail a task: its run is ready again after ``delay_ms``, unless its
396
+ attempts are spent or ``retry`` is False. With ``abandoned`` it is
397
+ handed back untried, and no failure is counted.
411
398
 
412
- Args:
413
- worker_id: Worker identifier.
414
- action_name: Action name for routing.
415
- task_id: Task identifier that failed.
416
- error_message: Error message describing the failure.
417
- options: Optional fail options (retry flag).
399
+ Sending it again after it applied answers ok.
400
+
401
+ Raises:
402
+ StaleReportError: The run moved on from this delivery.
418
403
  """
419
404
  opts = options or WorkerFailOptions()
420
- namespace = self._client.get_namespace(opts.namespace)
421
-
422
- value = serialize_worker_fail_value(action_name, task_id, error_message, opts.retry)
423
-
424
- await self._client._send_and_check(
405
+ response = await self._client._send_and_check(
425
406
  OpCode.ACTION_FAIL,
426
- namespace,
427
- worker_id.encode("utf-8"),
428
- value,
407
+ task.namespace,
408
+ task.run.encode("utf-8"),
409
+ encode_fail_body(
410
+ worker_id, task, error.encode("utf-8"), opts.retry, opts.abandoned, opts.delay_ms
411
+ ),
429
412
  )
413
+ decode_empty_answer("action.fail", response.data)
430
414
 
431
415
  async def list(
432
416
  self,