flo-python 0.1.4__py3-none-any.whl → 0.1.6__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,12 +39,14 @@ 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,
49
51
  NoNamespaceError,
50
52
  NonRetryableError,
@@ -54,10 +56,12 @@ from .exceptions import (
54
56
  OverloadedError,
55
57
  PayloadTooLargeError,
56
58
  ProtocolError,
59
+ QueueFullError,
57
60
  RateLimitedError,
58
61
  RequestTimeoutError,
59
62
  ServerError,
60
63
  StaleNotFoundError,
64
+ StaleReportError,
61
65
  TableMismatchError,
62
66
  UnauthorizedError,
63
67
  UnavailableError,
@@ -69,11 +73,13 @@ from .exceptions import (
69
73
  from .kv_txn import Transaction, TxnFinishedError, TxnUnsupportedOpError
70
74
  from .processing import ProcessingOperations
71
75
  from .retry import DEFAULT_RETRY_POLICY, RetryPolicy
76
+ from .ts import TSOperations
72
77
  from .types import (
73
- AckOptions,
74
78
  ActionDeleteOptions,
79
+ ActionInfo,
75
80
  ActionInvokeOptions,
76
81
  ActionInvokeResult,
82
+ ActionListEntry,
77
83
  ActionListOptions,
78
84
  ActionListResult,
79
85
  ActionRegisterOptions,
@@ -81,16 +87,25 @@ from .types import (
81
87
  ActionStatusOptions,
82
88
  ActionType,
83
89
  Condition,
90
+ DeadLetter,
84
91
  DeleteOptions,
85
92
  DequeueOptions,
86
93
  DequeueResult,
87
94
  DlqListOptions,
88
- DlqRequeueOptions,
95
+ DlqPage,
89
96
  EnqueueOptions,
90
97
  ExistsResult,
98
+ FloQLPoint,
99
+ FloQLSeries,
91
100
  GetJsonResult,
92
101
  GetOptions,
93
102
  GetResult,
103
+ GroupMemberState,
104
+ GroupReadResult,
105
+ GroupRecord,
106
+ GroupRefusal,
107
+ GroupReportResult,
108
+ GroupTouchResult,
94
109
  HistoryOptions,
95
110
  HistoryResult,
96
111
  IncrResult,
@@ -103,15 +118,18 @@ from .types import (
103
118
  KVMGetOptions,
104
119
  Message,
105
120
  MGetEntry,
106
- NackOptions,
107
121
  OpCode,
108
122
  OptionTag,
123
+ PeekedMessage,
109
124
  PeekOptions,
125
+ PeekResult,
110
126
  PendingEntry,
111
127
  ProcessingCancelOptions,
112
128
  ProcessingListEntry,
113
129
  ProcessingListOptions,
114
130
  ProcessingListResult,
131
+ ProcessingRemoveOptions,
132
+ ProcessingRuntime,
115
133
  ProcessingStatusOptions,
116
134
  ProcessingStatusResult,
117
135
  ProcessingStopOptions,
@@ -119,8 +137,15 @@ from .types import (
119
137
  ProcessingSyncOptions,
120
138
  ProcessingSyncResult,
121
139
  ProcessKind,
140
+ PurgeOptions,
122
141
  PutOptions,
123
142
  PutResult,
143
+ QueueFailOptions,
144
+ QueueRefusal,
145
+ QueueRefusalReason,
146
+ QueueReportOptions,
147
+ QueueReportResult,
148
+ QueueTouchResult,
124
149
  Ran,
125
150
  Reason,
126
151
  RunStatus,
@@ -130,10 +155,14 @@ from .types import (
130
155
  StorageTier,
131
156
  StreamAppendOptions,
132
157
  StreamAppendResult,
133
- StreamClaimResult,
134
158
  StreamDeleteOptions,
135
159
  StreamGroupAckOptions,
136
- StreamGroupJoinOptions,
160
+ StreamGroupCreateOptions,
161
+ StreamGroupEntry,
162
+ StreamGroupInfo,
163
+ StreamGroupListResult,
164
+ StreamGroupMember,
165
+ StreamGroupMembersResult,
137
166
  StreamGroupNackOptions,
138
167
  StreamGroupReadOptions,
139
168
  StreamID,
@@ -145,6 +174,16 @@ from .types import (
145
174
  StreamTrimOptions,
146
175
  StreamTrimResult,
147
176
  TaskAssignment,
177
+ TSAggregation,
178
+ TSBucket,
179
+ TSInfo,
180
+ TSOrder,
181
+ TSPoint,
182
+ TSQueryOptions,
183
+ TSReadOptions,
184
+ TSReadResult,
185
+ TSWriteOptions,
186
+ TSWriteResult,
148
187
  VersionEntry,
149
188
  WaitFor,
150
189
  WorkerAwaitOptions,
@@ -158,7 +197,6 @@ from .types import (
158
197
  WorkerProcess,
159
198
  WorkerRegisterOptions,
160
199
  WorkerStatus,
161
- WorkerTouchOptions,
162
200
  WorkerType,
163
201
  WorkflowCancelOptions,
164
202
  WorkflowCreateOptions,
@@ -177,6 +215,9 @@ from .types import (
177
215
  WorkflowStatusOptions,
178
216
  WorkflowSyncOptions,
179
217
  WorkflowSyncResult,
218
+ datetime_from_ns,
219
+ ns_from_datetime,
220
+ ns_from_timedelta,
180
221
  )
181
222
  from .worker import (
182
223
  ActionContext,
@@ -190,7 +231,7 @@ from .worker import (
190
231
  )
191
232
  from .workflows import WorkflowOperations
192
233
 
193
- __version__ = "0.1.4"
234
+ __version__ = "0.1.6"
194
235
 
195
236
  __all__ = [
196
237
  "Transaction",
@@ -250,12 +291,16 @@ __all__ = [
250
291
  "BadRequestError",
251
292
  "ConflictError",
252
293
  "UnauthorizedError",
294
+ "GroupHeldFullError",
253
295
  "OverloadedError",
296
+ "QueueFullError",
254
297
  "OutcomePendingError",
255
298
  "StaleNotFoundError",
299
+ "StaleReportError",
256
300
  "UnavailableError",
257
301
  "RateLimitedError",
258
302
  "InternalServerError",
303
+ "LimitError",
259
304
  "GenericServerError",
260
305
  "is_connection_error",
261
306
  # Types
@@ -271,6 +316,7 @@ __all__ = [
271
316
  "DequeueResult",
272
317
  # Options
273
318
  "Condition",
319
+ "DeadLetter",
274
320
  "GetOptions",
275
321
  "WaitFor",
276
322
  "PutOptions",
@@ -279,18 +325,29 @@ __all__ = [
279
325
  "HistoryOptions",
280
326
  "EnqueueOptions",
281
327
  "DequeueOptions",
282
- "AckOptions",
283
- "NackOptions",
284
328
  "DlqListOptions",
285
- "DlqRequeueOptions",
329
+ "DlqPage",
286
330
  "PeekOptions",
331
+ "PurgeOptions",
332
+ "QueueFailOptions",
333
+ "QueueRefusal",
334
+ "QueueRefusalReason",
335
+ "QueueReportOptions",
336
+ "QueueReportResult",
337
+ "QueueTouchResult",
338
+ "PeekedMessage",
339
+ "PeekResult",
287
340
  # Stream types
288
341
  "StreamID",
289
342
  "StorageTier",
290
343
  "StreamRecord",
291
344
  "StreamAppendResult",
292
345
  "StreamReadResult",
293
- "StreamClaimResult",
346
+ "GroupRecord",
347
+ "GroupReadResult",
348
+ "GroupRefusal",
349
+ "GroupReportResult",
350
+ "GroupTouchResult",
294
351
  "PendingEntry",
295
352
  "StreamInfo",
296
353
  # Stream options
@@ -300,9 +357,15 @@ __all__ = [
300
357
  "StreamTrimResult",
301
358
  "StreamInfoOptions",
302
359
  "StreamDeleteOptions",
303
- "StreamGroupJoinOptions",
360
+ "StreamGroupCreateOptions",
361
+ "StreamGroupInfo",
304
362
  "StreamGroupReadOptions",
305
363
  "StreamGroupAckOptions",
364
+ "StreamGroupEntry",
365
+ "StreamGroupListResult",
366
+ "StreamGroupMember",
367
+ "StreamGroupMembersResult",
368
+ "GroupMemberState",
306
369
  "StreamGroupNackOptions",
307
370
  # Action types
308
371
  "ActionType",
@@ -315,6 +378,8 @@ __all__ = [
315
378
  "ActionInvokeOptions",
316
379
  "ActionStatusOptions",
317
380
  "ActionListOptions",
381
+ "ActionListEntry",
382
+ "ActionInfo",
318
383
  "ActionDeleteOptions",
319
384
  # Worker types
320
385
  "TaskAssignment",
@@ -329,7 +394,6 @@ __all__ = [
329
394
  # Worker options
330
395
  "WorkerRegisterOptions",
331
396
  "WorkerAwaitOptions",
332
- "WorkerTouchOptions",
333
397
  "WorkerCompleteOptions",
334
398
  "WorkerFailOptions",
335
399
  "WorkerListOptions",
@@ -363,5 +427,23 @@ __all__ = [
363
427
  "ProcessingStatusResult",
364
428
  "ProcessingListEntry",
365
429
  "ProcessingListResult",
430
+ "ProcessingRemoveOptions",
431
+ "ProcessingRuntime",
432
+ "FloQLPoint",
433
+ "FloQLSeries",
434
+ "TSOrder",
435
+ "TSAggregation",
436
+ "TSBucket",
437
+ "TSInfo",
438
+ "TSQueryOptions",
439
+ "ns_from_timedelta",
440
+ "TSPoint",
441
+ "TSReadOptions",
442
+ "TSReadResult",
443
+ "TSWriteOptions",
444
+ "TSWriteResult",
445
+ "datetime_from_ns",
446
+ "ns_from_datetime",
447
+ "TSOperations",
366
448
  "ProcessingSyncResult",
367
449
  ]
flo/actions.py CHANGED
@@ -10,15 +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,
14
15
  decode_action_list_answer,
15
16
  decode_action_status_answer,
17
+ decode_await_answer,
18
+ decode_empty_answer,
19
+ decode_touch_answer,
16
20
  decode_worker_info_answer,
17
21
  decode_worker_list_answer,
22
+ encode_await_body,
23
+ encode_complete_body,
24
+ encode_fail_body,
25
+ encode_touch_body,
18
26
  encode_worker_list_body,
19
27
  )
20
28
  from .types import (
21
29
  ActionDeleteOptions,
30
+ ActionInfo,
22
31
  ActionInvokeOptions,
23
32
  ActionInvokeResult,
24
33
  ActionListOptions,
@@ -28,7 +37,7 @@ from .types import (
28
37
  ActionStatusOptions,
29
38
  ActionType,
30
39
  OpCode,
31
- OptionTag,
40
+ TaskAssignment,
32
41
  WorkerAwaitOptions,
33
42
  WorkerAwaitResult,
34
43
  WorkerCompleteOptions,
@@ -38,19 +47,12 @@ from .types import (
38
47
  WorkerListResult,
39
48
  WorkerRegisterOptions,
40
49
  WorkerStatus,
41
- WorkerTouchOptions,
42
50
  )
43
51
  from .wire import (
44
- OptionsBuilder,
45
- parse_task_assignment,
46
52
  serialize_action_invoke_value,
47
53
  serialize_action_list_value,
48
54
  serialize_action_register_value,
49
- serialize_worker_await_value,
50
- serialize_worker_complete_value,
51
- serialize_worker_fail_value,
52
55
  serialize_worker_register_value,
53
- serialize_worker_touch_value,
54
56
  )
55
57
 
56
58
  if TYPE_CHECKING:
@@ -86,7 +88,7 @@ class ActionOperations:
86
88
  value = serialize_action_register_value(
87
89
  action_type=action_type,
88
90
  timeout_ms=opts.timeout_ms,
89
- max_retries=opts.max_retries,
91
+ max_attempts=opts.max_attempts,
90
92
  owner=opts.owner,
91
93
  )
92
94
 
@@ -180,8 +182,23 @@ class ActionOperations:
180
182
  serialize_action_list_value(limit=opts.limit, cursor=opts.cursor),
181
183
  )
182
184
 
183
- names, cursor = decode_action_list_answer(response.data)
184
- return ActionListResult(names=names, cursor=cursor)
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)
185
202
 
186
203
  async def delete(
187
204
  self,
@@ -306,128 +323,94 @@ class WorkerOperations:
306
323
  async def await_task(
307
324
  self,
308
325
  worker_id: str,
309
- task_types: list[str],
326
+ actions: list[str],
310
327
  options: WorkerAwaitOptions | None = None,
311
328
  ) -> WorkerAwaitResult:
312
- """Wait for a task assignment.
313
-
314
- Args:
315
- worker_id: Worker identifier.
316
- task_types: Task types to listen for.
317
- 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.
318
331
 
319
332
  Returns:
320
- WorkerAwaitResult with task if available.
333
+ WorkerAwaitResult whose task is None if no run was ready in time.
321
334
  """
322
335
  opts = options or WorkerAwaitOptions()
323
- namespace = self._client.get_namespace(opts.namespace)
324
-
325
- value = serialize_worker_await_value(task_types)
326
-
327
- options_builder = OptionsBuilder()
328
- if opts.block_ms is not None:
329
- options_builder.add_u32(OptionTag.BLOCK_MS, opts.block_ms)
330
-
331
336
  response = await self._client._send_and_check(
332
337
  OpCode.ACTION_AWAIT,
333
- namespace,
338
+ self._client.get_namespace(opts.namespace),
334
339
  worker_id.encode("utf-8"),
335
- value,
336
- options_builder.build(),
340
+ encode_await_body(actions, opts.block_ms, opts.request_key),
337
341
  )
342
+ return WorkerAwaitResult(task=decode_await_answer(response.data))
338
343
 
339
- # Parse task assignment response - if empty, no task available
340
- if not response.data:
341
- 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.
342
348
 
343
- # Parse task assignment
344
- task = parse_task_assignment(response.data)
345
- return WorkerAwaitResult(task=task)
346
-
347
- async def touch(
348
- self,
349
- worker_id: str,
350
- action_name: str,
351
- task_id: str,
352
- options: WorkerTouchOptions | None = None,
353
- ) -> None:
354
- """Extend task lease (heartbeat).
349
+ Returns:
350
+ When the lease runs out without another touch, in Unix ms.
355
351
 
356
- Args:
357
- worker_id: Worker identifier.
358
- action_name: Action name for routing.
359
- task_id: Task identifier to extend.
360
- options: Optional touch options (extend_ms).
352
+ Raises:
353
+ StaleReportError: The run moved on from this delivery.
361
354
  """
362
- opts = options or WorkerTouchOptions()
363
- namespace = self._client.get_namespace(opts.namespace)
364
-
365
- value = serialize_worker_touch_value(action_name, task_id, opts.extend_ms)
366
-
367
- await self._client._send_and_check(
355
+ response = await self._client._send_and_check(
368
356
  OpCode.ACTION_TOUCH,
369
- namespace,
370
- worker_id.encode("utf-8"),
371
- value,
357
+ task.namespace,
358
+ task.run.encode("utf-8"),
359
+ encode_touch_body(worker_id, task),
372
360
  )
361
+ return decode_touch_answer(response.data)
373
362
 
374
363
  async def complete(
375
364
  self,
376
365
  worker_id: str,
377
- action_name: str,
378
- task_id: str,
379
- result: bytes,
366
+ task: TaskAssignment,
367
+ result: bytes = b"",
380
368
  options: WorkerCompleteOptions | None = None,
381
369
  ) -> None:
382
- """Complete a task successfully.
370
+ """Complete a task: its run is done, with this result.
383
371
 
384
- Args:
385
- worker_id: Worker identifier.
386
- action_name: Action name for routing.
387
- task_id: Task identifier to complete.
388
- result: Result data from the task.
389
- 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.
390
378
  """
391
379
  opts = options or WorkerCompleteOptions()
392
- namespace = self._client.get_namespace(opts.namespace)
393
-
394
- value = serialize_worker_complete_value(action_name, task_id, result, opts.outcome)
395
-
396
- await self._client._send_and_check(
380
+ response = await self._client._send_and_check(
397
381
  OpCode.ACTION_COMPLETE,
398
- namespace,
399
- worker_id.encode("utf-8"),
400
- value,
382
+ task.namespace,
383
+ task.run.encode("utf-8"),
384
+ encode_complete_body(worker_id, task, opts.outcome, result),
401
385
  )
386
+ decode_empty_answer("action.complete", response.data)
402
387
 
403
388
  async def fail(
404
389
  self,
405
390
  worker_id: str,
406
- action_name: str,
407
- task_id: str,
408
- error_message: str,
391
+ task: TaskAssignment,
392
+ error: str = "",
409
393
  options: WorkerFailOptions | None = None,
410
394
  ) -> None:
411
- """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.
412
398
 
413
- Args:
414
- worker_id: Worker identifier.
415
- action_name: Action name for routing.
416
- task_id: Task identifier that failed.
417
- error_message: Error message describing the failure.
418
- 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.
419
403
  """
420
404
  opts = options or WorkerFailOptions()
421
- namespace = self._client.get_namespace(opts.namespace)
422
-
423
- value = serialize_worker_fail_value(action_name, task_id, error_message, opts.retry)
424
-
425
- await self._client._send_and_check(
405
+ response = await self._client._send_and_check(
426
406
  OpCode.ACTION_FAIL,
427
- namespace,
428
- worker_id.encode("utf-8"),
429
- 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
+ ),
430
412
  )
413
+ decode_empty_answer("action.fail", response.data)
431
414
 
432
415
  async def list(
433
416
  self,