flo-python 0.1.6__tar.gz → 0.1.7__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 (85) hide show
  1. {flo_python-0.1.6 → flo_python-0.1.7}/.github/flo-ref.env +1 -1
  2. {flo_python-0.1.6 → flo_python-0.1.7}/CHANGELOG.md +59 -0
  3. {flo_python-0.1.6 → flo_python-0.1.7}/PKG-INFO +90 -7
  4. {flo_python-0.1.6 → flo_python-0.1.7}/README.md +89 -6
  5. {flo_python-0.1.6 → flo_python-0.1.7}/pyproject.toml +1 -1
  6. {flo_python-0.1.6 → flo_python-0.1.7}/src/flo/__init__.py +31 -1
  7. {flo_python-0.1.6 → flo_python-0.1.7}/src/flo/kv_body.py +264 -1
  8. {flo_python-0.1.6 → flo_python-0.1.7}/src/flo/queue.py +67 -72
  9. {flo_python-0.1.6 → flo_python-0.1.7}/src/flo/retry.py +13 -0
  10. {flo_python-0.1.6 → flo_python-0.1.7}/src/flo/streams.py +186 -0
  11. {flo_python-0.1.6 → flo_python-0.1.7}/src/flo/types.py +209 -24
  12. {flo_python-0.1.6 → flo_python-0.1.7}/src/flo/wire.py +7 -3
  13. {flo_python-0.1.6 → flo_python-0.1.7}/src/flo/worker.py +35 -5
  14. {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_action_ops.py +0 -57
  15. {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_action_status.py +12 -3
  16. {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_actions_live.py +1 -1
  17. flo_python-0.1.7/tests/test_dead_letters.py +361 -0
  18. flo_python-0.1.7/tests/test_dead_letters_live.py +307 -0
  19. {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_ops_drift.py +23 -0
  20. {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_result_resend.py +95 -2
  21. flo_python-0.1.7/tests/test_stream_settings.py +73 -0
  22. {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_stream_trim.py +4 -2
  23. {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_wire.py +1 -1
  24. {flo_python-0.1.6 → flo_python-0.1.7}/.github/workflows/ci.yml +0 -0
  25. {flo_python-0.1.6 → flo_python-0.1.7}/.github/workflows/release.yml +0 -0
  26. {flo_python-0.1.6 → flo_python-0.1.7}/.gitignore +0 -0
  27. {flo_python-0.1.6 → flo_python-0.1.7}/LICENSE +0 -0
  28. {flo_python-0.1.6 → flo_python-0.1.7}/examples/basic.py +0 -0
  29. {flo_python-0.1.6 → flo_python-0.1.7}/examples/stream_worker.py +0 -0
  30. {flo_python-0.1.6 → flo_python-0.1.7}/examples/test_decorator.py +0 -0
  31. {flo_python-0.1.6 → flo_python-0.1.7}/examples/worker.py +0 -0
  32. {flo_python-0.1.6 → flo_python-0.1.7}/src/flo/actions.py +0 -0
  33. {flo_python-0.1.6 → flo_python-0.1.7}/src/flo/client.py +0 -0
  34. {flo_python-0.1.6 → flo_python-0.1.7}/src/flo/exceptions.py +0 -0
  35. {flo_python-0.1.6 → flo_python-0.1.7}/src/flo/kv.py +0 -0
  36. {flo_python-0.1.6 → flo_python-0.1.7}/src/flo/kv_txn.py +0 -0
  37. {flo_python-0.1.6 → flo_python-0.1.7}/src/flo/processing.py +0 -0
  38. {flo_python-0.1.6 → flo_python-0.1.7}/src/flo/ts.py +0 -0
  39. {flo_python-0.1.6 → flo_python-0.1.7}/src/flo/workflows.py +0 -0
  40. {flo_python-0.1.6 → flo_python-0.1.7}/tests/__init__.py +0 -0
  41. {flo_python-0.1.6 → flo_python-0.1.7}/tests/conftest.py +0 -0
  42. {flo_python-0.1.6 → flo_python-0.1.7}/tests/order-workflow.yaml +0 -0
  43. {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_auto_touch.py +0 -0
  44. {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_block_ms.py +0 -0
  45. {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_blocking_deadline.py +0 -0
  46. {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_empty_poll_backoff.py +0 -0
  47. {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_group_ops.py +0 -0
  48. {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_groups_live.py +0 -0
  49. {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_halts.py +0 -0
  50. {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_kv_live.py +0 -0
  51. {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_kv_ops.py +0 -0
  52. {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_kv_table.py +0 -0
  53. {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_kv_ttl.py +0 -0
  54. {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_list_paging.py +0 -0
  55. {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_list_paging_live.py +0 -0
  56. {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_missing_answers_live.py +0 -0
  57. {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_not_found_answers.py +0 -0
  58. {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_op_codes.py +0 -0
  59. {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_poll_loops.py +0 -0
  60. {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_processing_decode.py +0 -0
  61. {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_processing_live.py +0 -0
  62. {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_protocol_version.py +0 -0
  63. {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_queue_live.py +0 -0
  64. {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_queue_ops.py +0 -0
  65. {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_read_not_found_live.py +0 -0
  66. {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_reconnect_cancel.py +0 -0
  67. {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_retry.py +0 -0
  68. {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_status_codes.py +0 -0
  69. {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_stream_delete.py +0 -0
  70. {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_stream_delete_live.py +0 -0
  71. {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_stream_tier.py +0 -0
  72. {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_stream_worker_ack.py +0 -0
  73. {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_ts_live.py +0 -0
  74. {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_ts_ops.py +0 -0
  75. {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_worker_close.py +0 -0
  76. {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_worker_close_live.py +0 -0
  77. {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_worker_drain.py +0 -0
  78. {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_worker_info.py +0 -0
  79. {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_worker_info_live.py +0 -0
  80. {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_worker_list.py +0 -0
  81. {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_worker_live.py +0 -0
  82. {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_worker_liveness.py +0 -0
  83. {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_workflow_list_runs.py +0 -0
  84. {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_workflow_runs_live.py +0 -0
  85. {flo_python-0.1.6 → flo_python-0.1.7}/tests/test_workflows.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=ad198c29bde7011cdd7d87d4bcd861d5addcf9c9
4
+ FLO_REF=1fd555dcec49985f3bb533ca0a6fb4b95e749341
@@ -5,6 +5,65 @@ All notable changes to the Flo Python SDK will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
+ ## [0.1.7] - 2026-11-18
9
+
10
+ Works with flo v0.1.0-dev.19.
11
+
12
+ The server's op table hash is now `0xac07f1f7338c66bd` (`TABLE_HASH`).
13
+
14
+ ### Added
15
+
16
+ - `stream.group_steal(stream, group, consumer, records, min_idle_ms)`: take
17
+ records another consumer holds and has left idle that long, each with a new
18
+ delivery and lease, its failures kept. It answers a `GroupStealResult`, a
19
+ delivery acked, nacked or touched as a read's, with `refused` for the
20
+ records it didn't take (`NOT_IDLE` for one its holder touched within the
21
+ idle time)
22
+ - A consumer group's dead letters: `stream.group_dlq_list` (a page, oldest
23
+ dead first, with each one's deliveries, failures, `dead_at_ms` and last
24
+ error; page by the opaque `cursor`), `group_dlq_requeue` (ready again,
25
+ failures reset) and `group_dlq_delete` (with `dry_run`). Requeue and delete
26
+ name up to 100 records by id, or take the oldest with `all`, a batch of up to
27
+ `limit`; they answer `applied`, `refused` (with why and the server's words)
28
+ and `more`
29
+ - `queue.dlq_requeue` and `queue.dlq_delete` (with `dry_run`), by seq or
30
+ `all`, answering a `DlqResult` as the group's do
31
+ - `QueueRefusalReason.NOT_DEAD` (6) and `NOT_IDLE` (7): a requeue or delete
32
+ of one that isn't dead, and a steal of one that isn't idle.
33
+ `GroupRefusal.reason` carries the server's words where it gives them
34
+ - `ActionRunStatus.held`: why a run's lease, past due, isn't ended yet (its
35
+ end waits for room on the calling workflow's shard)
36
+ - `stream.create` (partitions, retention by age and count) and `stream.alter`
37
+ (retention); `StreamInfo.retention_age_s` and `retention_count`
38
+
39
+ ### Changed
40
+
41
+ - A worker's complete, fail, ack or nack refused overloaded without being
42
+ run (after the client's own retries) is sent again with a capped backoff
43
+ until the server takes it or answers otherwise, and logged; it used to be
44
+ dropped. A complete or fail that ends a run a workflow step called is
45
+ refused so while the server's writes to the workflow's shard are queued
46
+ full, and the run's lease doesn't run out meanwhile; an ack's or nack's
47
+ lease keeps running, so a long overload can deliver the records again. A
48
+ stopping worker gives up after a couple of seconds, a backoff wait
49
+ included
50
+ - An alter of a stream an append made succeeds; it used to be not found.
51
+ After an alter a create must name the stream's settings as altered, or it
52
+ raises `ConflictError`; a create whose name hashes as another stream's does
53
+ too
54
+ - A workflow step whose action isn't registered waits for one, up to the
55
+ server's missing-action wait, instead of failing at once
56
+
57
+ ### Breaking
58
+
59
+ - `queue.dlq_list` sends the new op: `DlqPage` is `messages` and `cursor`
60
+ (a `DlqCursor`, `None` on the last page), replacing `total`, `has_more` and
61
+ `last_seq`; `DlqListOptions.after` takes the cursor, and `limit` defaults
62
+ to 20. `DeadLetter` gains `failures`, `dead_at_ms` and `error`, and loses
63
+ `moved_at_ms`. A queue that doesn't exist raises `NotFoundError`
64
+ - The old dead letter op codes (0x176..0x178) are gone; `OpCode.QUEUE_DLQ_*`
65
+ are the server's 0x185..0x187
66
+
8
67
  ## [0.1.6] - 2026-11-16
9
68
 
10
69
  The op table hash moves with the server in this release: this SDK talks only
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: flo-python
3
- Version: 0.1.6
3
+ Version: 0.1.7
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
@@ -306,15 +306,32 @@ result = await client.queue.dequeue("tasks", 10, DequeueOptions(ack=True))
306
306
  `queue.purge` removes every message of a queue, ready, leased and dead, and
307
307
  returns how many.
308
308
 
309
- `queue.dlq_list` reads a page of dead letters, oldest first (`limit` 1..100):
309
+ `queue.dlq_list` reads a page of dead letters, oldest dead first (`limit`
310
+ 1..100, default 20), each with up to 4 KiB of its payload (`size` is its
311
+ length), its deliveries and failures, when it died and its last error. Page
312
+ with the answer's opaque `cursor` until it is `None`.
313
+
314
+ `queue.dlq_requeue` makes dead letters ready again at once, failures reset;
315
+ `queue.dlq_delete` deletes them for good (`dry_run` says how many it would).
316
+ Each names up to 100 by seq, or takes the oldest dead with `all`, a batch of
317
+ up to `limit`: `more` says others remain. One that isn't dead comes back in
318
+ `refused` as `NOT_DEAD`, one not there as `GONE`; the call itself succeeds.
319
+ A queue that doesn't exist raises `NotFoundError`.
310
320
 
311
321
  ```python
312
- from flo import DlqListOptions
322
+ from flo import DlqDeleteOptions, DlqListOptions, DlqRequeueOptions
313
323
 
314
324
  page = await client.queue.dlq_list("tasks", DlqListOptions(limit=100))
315
- print(f"{page.total} dead letters")
316
- while page.has_more:
317
- page = await client.queue.dlq_list("tasks", DlqListOptions(after=page.last_seq))
325
+ while True:
326
+ for msg in page.messages:
327
+ print(msg.seq, msg.failures, msg.error)
328
+ if page.cursor is None:
329
+ break
330
+ page = await client.queue.dlq_list("tasks", DlqListOptions(after=page.cursor))
331
+
332
+ await client.queue.dlq_requeue("tasks", [msg.seq])
333
+ while (await client.queue.dlq_delete("tasks", options=DlqDeleteOptions(all=True))).more:
334
+ pass
318
335
  ```
319
336
 
320
337
  ### Peek
@@ -401,7 +418,8 @@ read that can take nothing new for either raises `GroupHeldFullError` (an
401
418
  `OverloadedError`, reason `GROUP_HELD_FULL`; the message says which cap).
402
419
  Reading again won't help until room is made, so the client doesn't retry it.
403
420
  At the group's cap, acks and nacks make room, but dead records count too and
404
- stay until the group is deleted or a trim of the stream cuts them. At the
421
+ stay until they are requeued or deleted, the group is deleted, or a trim of
422
+ the stream cuts them. At the
405
423
  shard's cap, this group's own acks free room, as do other groups and queues on
406
424
  the shard draining.
407
425
 
@@ -463,6 +481,60 @@ members = await client.stream.group_members("events", "processors") # consumers
463
481
  await client.stream.group_delete("events", "processors")
464
482
  ```
465
483
 
484
+ A group's dead letters list a page at a time, oldest dead first, each with its
485
+ deliveries, failures, when it died and its last error; requeue and delete
486
+ take them by id or `all`, as a queue's do (`NOT_DEAD` for one that isn't).
487
+
488
+ ```python
489
+ from flo import GroupDlqDeleteOptions, GroupDlqListOptions
490
+
491
+ page = await client.stream.group_dlq_list("events", "processors", GroupDlqListOptions(limit=50))
492
+ await client.stream.group_dlq_requeue("events", "processors", [d.id for d in page.dead])
493
+ await client.stream.group_dlq_delete(
494
+ "events", "processors", options=GroupDlqDeleteOptions(all=True, dry_run=True)
495
+ )
496
+ ```
497
+
498
+ `group_steal` is an operator's command: it takes records another consumer
499
+ holds and has left idle for at least `min_idle_ms` (idle is the time since
500
+ its holder last read, stole or touched it), each with a new delivery and
501
+ lease, its failures kept. Name each record with the deliveries its holder has
502
+ (a read's records, or `group_pending`'s entries). The result is a delivery,
503
+ acked, nacked or touched as a read's; records it didn't take come back in
504
+ `refused` (`NOT_IDLE` for one touched within the idle time). A read takes
505
+ expired records by itself, so a steal is for records whose holder is stuck
506
+ but still touching them, or to move work sooner than the lease.
507
+
508
+ ```python
509
+ pending = await client.stream.group_pending("events", "processors", "worker-1")
510
+ stolen = await client.stream.group_steal("events", "processors", "worker-2", pending, 60_000)
511
+ await client.stream.group_ack("events", "processors", stolen)
512
+ ```
513
+
514
+ ### Stream Settings
515
+
516
+ An append creates a stream with no settings. `create` gives one its
517
+ partitions and retention (records older than `retention_age_s`, or past
518
+ `retention_count`, are trimmed); `alter` changes its retention, each setting
519
+ given replacing the stream's, on a stream an append made as on one a create
520
+ made. `info` answers the settings.
521
+
522
+ Once a stream has settings, from a create or an alter, a create that names
523
+ the same ones succeeds (a retry), and one that names others raises
524
+ `ConflictError` ("the stream exists with other settings"): after an alter, a
525
+ create must name the settings as altered. A create of a stream an append made
526
+ and nothing altered gives it the settings named. A create whose name hashes
527
+ as another stream's raises `ConflictError` too; choose another name.
528
+
529
+ ```python
530
+ from flo import StreamAlterOptions, StreamCreateOptions
531
+
532
+ await client.stream.create("events", StreamCreateOptions(retention_age_s=86_400))
533
+ await client.stream.alter("events", StreamAlterOptions(retention_count=1_000_000))
534
+ info = await client.stream.info("events")
535
+ print(info.retention_age_s, info.retention_count)
536
+ ```
537
+
466
538
  ## Time-Series Operations
467
539
 
468
540
  Every time and window is Unix nanoseconds, a Python `int`. A point's
@@ -638,6 +710,8 @@ if status.error_message is not None:
638
710
  print(f"Error: {status.error_message}")
639
711
  if status.outcome is not None: # None for success
640
712
  print(f"Outcome: {status.outcome}")
713
+ if status.held is not None: # why a past-due lease isn't ended yet
714
+ print(f"Held: {status.held}")
641
715
 
642
716
  # An action's definition, its runs by status and its completed runs' latency
643
717
  info = await client.action.info("process-image")
@@ -814,6 +888,15 @@ async def run_stream_worker():
814
888
  asyncio.run(run_stream_worker())
815
889
  ```
816
890
 
891
+ A worker's complete, fail, ack or nack refused overloaded without being run
892
+ (once the client's own retries are spent) is sent again with a capped backoff
893
+ until the server takes it or answers otherwise, and logged each time. A
894
+ complete or fail that ends a run a workflow step called is refused so while
895
+ the server's queue of writes to the workflow's shard is full; meanwhile the
896
+ run's lease doesn't run out, and `action.status` says why in `held`. An ack's
897
+ or nack's lease keeps running, so a long overload can deliver the records
898
+ again. A stopping worker gives up on it after a couple of seconds.
899
+
817
900
  A stream worker acks each record its handler returns from and nacks each one
818
901
  its handler raises on, naming the read's delivery. A record whose handler runs
819
902
  past the group's lease is read again elsewhere unless `auto_touch=True`, which
@@ -275,15 +275,32 @@ result = await client.queue.dequeue("tasks", 10, DequeueOptions(ack=True))
275
275
  `queue.purge` removes every message of a queue, ready, leased and dead, and
276
276
  returns how many.
277
277
 
278
- `queue.dlq_list` reads a page of dead letters, oldest first (`limit` 1..100):
278
+ `queue.dlq_list` reads a page of dead letters, oldest dead first (`limit`
279
+ 1..100, default 20), each with up to 4 KiB of its payload (`size` is its
280
+ length), its deliveries and failures, when it died and its last error. Page
281
+ with the answer's opaque `cursor` until it is `None`.
282
+
283
+ `queue.dlq_requeue` makes dead letters ready again at once, failures reset;
284
+ `queue.dlq_delete` deletes them for good (`dry_run` says how many it would).
285
+ Each names up to 100 by seq, or takes the oldest dead with `all`, a batch of
286
+ up to `limit`: `more` says others remain. One that isn't dead comes back in
287
+ `refused` as `NOT_DEAD`, one not there as `GONE`; the call itself succeeds.
288
+ A queue that doesn't exist raises `NotFoundError`.
279
289
 
280
290
  ```python
281
- from flo import DlqListOptions
291
+ from flo import DlqDeleteOptions, DlqListOptions, DlqRequeueOptions
282
292
 
283
293
  page = await client.queue.dlq_list("tasks", DlqListOptions(limit=100))
284
- print(f"{page.total} dead letters")
285
- while page.has_more:
286
- page = await client.queue.dlq_list("tasks", DlqListOptions(after=page.last_seq))
294
+ while True:
295
+ for msg in page.messages:
296
+ print(msg.seq, msg.failures, msg.error)
297
+ if page.cursor is None:
298
+ break
299
+ page = await client.queue.dlq_list("tasks", DlqListOptions(after=page.cursor))
300
+
301
+ await client.queue.dlq_requeue("tasks", [msg.seq])
302
+ while (await client.queue.dlq_delete("tasks", options=DlqDeleteOptions(all=True))).more:
303
+ pass
287
304
  ```
288
305
 
289
306
  ### Peek
@@ -370,7 +387,8 @@ read that can take nothing new for either raises `GroupHeldFullError` (an
370
387
  `OverloadedError`, reason `GROUP_HELD_FULL`; the message says which cap).
371
388
  Reading again won't help until room is made, so the client doesn't retry it.
372
389
  At the group's cap, acks and nacks make room, but dead records count too and
373
- stay until the group is deleted or a trim of the stream cuts them. At the
390
+ stay until they are requeued or deleted, the group is deleted, or a trim of
391
+ the stream cuts them. At the
374
392
  shard's cap, this group's own acks free room, as do other groups and queues on
375
393
  the shard draining.
376
394
 
@@ -432,6 +450,60 @@ members = await client.stream.group_members("events", "processors") # consumers
432
450
  await client.stream.group_delete("events", "processors")
433
451
  ```
434
452
 
453
+ A group's dead letters list a page at a time, oldest dead first, each with its
454
+ deliveries, failures, when it died and its last error; requeue and delete
455
+ take them by id or `all`, as a queue's do (`NOT_DEAD` for one that isn't).
456
+
457
+ ```python
458
+ from flo import GroupDlqDeleteOptions, GroupDlqListOptions
459
+
460
+ page = await client.stream.group_dlq_list("events", "processors", GroupDlqListOptions(limit=50))
461
+ await client.stream.group_dlq_requeue("events", "processors", [d.id for d in page.dead])
462
+ await client.stream.group_dlq_delete(
463
+ "events", "processors", options=GroupDlqDeleteOptions(all=True, dry_run=True)
464
+ )
465
+ ```
466
+
467
+ `group_steal` is an operator's command: it takes records another consumer
468
+ holds and has left idle for at least `min_idle_ms` (idle is the time since
469
+ its holder last read, stole or touched it), each with a new delivery and
470
+ lease, its failures kept. Name each record with the deliveries its holder has
471
+ (a read's records, or `group_pending`'s entries). The result is a delivery,
472
+ acked, nacked or touched as a read's; records it didn't take come back in
473
+ `refused` (`NOT_IDLE` for one touched within the idle time). A read takes
474
+ expired records by itself, so a steal is for records whose holder is stuck
475
+ but still touching them, or to move work sooner than the lease.
476
+
477
+ ```python
478
+ pending = await client.stream.group_pending("events", "processors", "worker-1")
479
+ stolen = await client.stream.group_steal("events", "processors", "worker-2", pending, 60_000)
480
+ await client.stream.group_ack("events", "processors", stolen)
481
+ ```
482
+
483
+ ### Stream Settings
484
+
485
+ An append creates a stream with no settings. `create` gives one its
486
+ partitions and retention (records older than `retention_age_s`, or past
487
+ `retention_count`, are trimmed); `alter` changes its retention, each setting
488
+ given replacing the stream's, on a stream an append made as on one a create
489
+ made. `info` answers the settings.
490
+
491
+ Once a stream has settings, from a create or an alter, a create that names
492
+ the same ones succeeds (a retry), and one that names others raises
493
+ `ConflictError` ("the stream exists with other settings"): after an alter, a
494
+ create must name the settings as altered. A create of a stream an append made
495
+ and nothing altered gives it the settings named. A create whose name hashes
496
+ as another stream's raises `ConflictError` too; choose another name.
497
+
498
+ ```python
499
+ from flo import StreamAlterOptions, StreamCreateOptions
500
+
501
+ await client.stream.create("events", StreamCreateOptions(retention_age_s=86_400))
502
+ await client.stream.alter("events", StreamAlterOptions(retention_count=1_000_000))
503
+ info = await client.stream.info("events")
504
+ print(info.retention_age_s, info.retention_count)
505
+ ```
506
+
435
507
  ## Time-Series Operations
436
508
 
437
509
  Every time and window is Unix nanoseconds, a Python `int`. A point's
@@ -607,6 +679,8 @@ if status.error_message is not None:
607
679
  print(f"Error: {status.error_message}")
608
680
  if status.outcome is not None: # None for success
609
681
  print(f"Outcome: {status.outcome}")
682
+ if status.held is not None: # why a past-due lease isn't ended yet
683
+ print(f"Held: {status.held}")
610
684
 
611
685
  # An action's definition, its runs by status and its completed runs' latency
612
686
  info = await client.action.info("process-image")
@@ -783,6 +857,15 @@ async def run_stream_worker():
783
857
  asyncio.run(run_stream_worker())
784
858
  ```
785
859
 
860
+ A worker's complete, fail, ack or nack refused overloaded without being run
861
+ (once the client's own retries are spent) is sent again with a capped backoff
862
+ until the server takes it or answers otherwise, and logged each time. A
863
+ complete or fail that ends a run a workflow step called is refused so while
864
+ the server's queue of writes to the workflow's shard is full; meanwhile the
865
+ run's lease doesn't run out, and `action.status` says why in `held`. An ack's
866
+ or nack's lease keeps running, so a long overload can deliver the records
867
+ again. A stopping worker gives up on it after a couple of seconds.
868
+
786
869
  A stream worker acks each record its handler returns from and nacks each one
787
870
  its handler raises on, naming the read's delivery. A record whose handler runs
788
871
  past the group's lease is read again elsewhere unless `auto_touch=True`, which
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "flo-python"
7
- version = "0.1.6"
7
+ version = "0.1.7"
8
8
  description = "Python SDK for the Flo distributed systems platform"
9
9
  readme = "README.md"
10
10
  license = "Apache-2.0"
@@ -91,8 +91,12 @@ from .types import (
91
91
  DeleteOptions,
92
92
  DequeueOptions,
93
93
  DequeueResult,
94
+ DlqCursor,
95
+ DlqDeleteOptions,
94
96
  DlqListOptions,
95
97
  DlqPage,
98
+ DlqRequeueOptions,
99
+ DlqResult,
96
100
  EnqueueOptions,
97
101
  ExistsResult,
98
102
  FloQLPoint,
@@ -100,11 +104,19 @@ from .types import (
100
104
  GetJsonResult,
101
105
  GetOptions,
102
106
  GetResult,
107
+ GroupDeadLetter,
108
+ GroupDlqCursor,
109
+ GroupDlqDeleteOptions,
110
+ GroupDlqListOptions,
111
+ GroupDlqPage,
112
+ GroupDlqRequeueOptions,
113
+ GroupDlqResult,
103
114
  GroupMemberState,
104
115
  GroupReadResult,
105
116
  GroupRecord,
106
117
  GroupRefusal,
107
118
  GroupReportResult,
119
+ GroupStealResult,
108
120
  GroupTouchResult,
109
121
  HistoryOptions,
110
122
  HistoryResult,
@@ -153,8 +165,10 @@ from .types import (
153
165
  ScanResult,
154
166
  StatusCode,
155
167
  StorageTier,
168
+ StreamAlterOptions,
156
169
  StreamAppendOptions,
157
170
  StreamAppendResult,
171
+ StreamCreateOptions,
158
172
  StreamDeleteOptions,
159
173
  StreamGroupAckOptions,
160
174
  StreamGroupCreateOptions,
@@ -165,6 +179,7 @@ from .types import (
165
179
  StreamGroupMembersResult,
166
180
  StreamGroupNackOptions,
167
181
  StreamGroupReadOptions,
182
+ StreamGroupStealOptions,
168
183
  StreamID,
169
184
  StreamInfo,
170
185
  StreamInfoOptions,
@@ -231,7 +246,7 @@ from .worker import (
231
246
  )
232
247
  from .workflows import WorkflowOperations
233
248
 
234
- __version__ = "0.1.6"
249
+ __version__ = "0.1.7"
235
250
 
236
251
  __all__ = [
237
252
  "Transaction",
@@ -325,6 +340,21 @@ __all__ = [
325
340
  "HistoryOptions",
326
341
  "EnqueueOptions",
327
342
  "DequeueOptions",
343
+ "DlqCursor",
344
+ "DlqResult",
345
+ "DlqRequeueOptions",
346
+ "DlqDeleteOptions",
347
+ "GroupStealResult",
348
+ "GroupDeadLetter",
349
+ "GroupDlqCursor",
350
+ "GroupDlqPage",
351
+ "GroupDlqResult",
352
+ "StreamCreateOptions",
353
+ "StreamAlterOptions",
354
+ "StreamGroupStealOptions",
355
+ "GroupDlqListOptions",
356
+ "GroupDlqRequeueOptions",
357
+ "GroupDlqDeleteOptions",
328
358
  "DlqListOptions",
329
359
  "DlqPage",
330
360
  "PeekOptions",