flo-python 0.1.5__tar.gz → 0.1.6__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 (83) hide show
  1. {flo_python-0.1.5 → flo_python-0.1.6}/.github/flo-ref.env +1 -1
  2. {flo_python-0.1.5 → flo_python-0.1.6}/CHANGELOG.md +60 -1
  3. {flo_python-0.1.5 → flo_python-0.1.6}/PKG-INFO +141 -3
  4. {flo_python-0.1.5 → flo_python-0.1.6}/README.md +140 -2
  5. {flo_python-0.1.5 → flo_python-0.1.6}/pyproject.toml +1 -1
  6. {flo_python-0.1.5 → flo_python-0.1.6}/src/flo/__init__.py +33 -1
  7. {flo_python-0.1.5 → flo_python-0.1.6}/src/flo/client.py +2 -0
  8. {flo_python-0.1.5 → flo_python-0.1.6}/src/flo/exceptions.py +26 -7
  9. {flo_python-0.1.5 → flo_python-0.1.6}/src/flo/kv.py +5 -14
  10. {flo_python-0.1.5 → flo_python-0.1.6}/src/flo/kv_body.py +2 -1
  11. {flo_python-0.1.5 → flo_python-0.1.6}/src/flo/processing.py +16 -3
  12. {flo_python-0.1.5 → flo_python-0.1.6}/src/flo/streams.py +14 -1
  13. flo_python-0.1.6/src/flo/ts.py +465 -0
  14. {flo_python-0.1.5 → flo_python-0.1.6}/src/flo/types.py +189 -6
  15. {flo_python-0.1.5 → flo_python-0.1.6}/src/flo/worker.py +68 -16
  16. flo_python-0.1.6/tests/test_not_found_answers.py +113 -0
  17. {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_processing_decode.py +29 -1
  18. {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_processing_live.py +36 -1
  19. flo_python-0.1.6/tests/test_read_not_found_live.py +78 -0
  20. flo_python-0.1.6/tests/test_ts_live.py +259 -0
  21. flo_python-0.1.6/tests/test_ts_ops.py +467 -0
  22. {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_wire.py +1 -1
  23. flo_python-0.1.6/tests/test_worker_close.py +278 -0
  24. flo_python-0.1.6/tests/test_worker_close_live.py +97 -0
  25. {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_worker_drain.py +6 -2
  26. flo_python-0.1.5/tests/test_not_found_answers.py +0 -38
  27. {flo_python-0.1.5 → flo_python-0.1.6}/.github/workflows/ci.yml +0 -0
  28. {flo_python-0.1.5 → flo_python-0.1.6}/.github/workflows/release.yml +0 -0
  29. {flo_python-0.1.5 → flo_python-0.1.6}/.gitignore +0 -0
  30. {flo_python-0.1.5 → flo_python-0.1.6}/LICENSE +0 -0
  31. {flo_python-0.1.5 → flo_python-0.1.6}/examples/basic.py +0 -0
  32. {flo_python-0.1.5 → flo_python-0.1.6}/examples/stream_worker.py +0 -0
  33. {flo_python-0.1.5 → flo_python-0.1.6}/examples/test_decorator.py +0 -0
  34. {flo_python-0.1.5 → flo_python-0.1.6}/examples/worker.py +0 -0
  35. {flo_python-0.1.5 → flo_python-0.1.6}/src/flo/actions.py +0 -0
  36. {flo_python-0.1.5 → flo_python-0.1.6}/src/flo/kv_txn.py +0 -0
  37. {flo_python-0.1.5 → flo_python-0.1.6}/src/flo/queue.py +0 -0
  38. {flo_python-0.1.5 → flo_python-0.1.6}/src/flo/retry.py +0 -0
  39. {flo_python-0.1.5 → flo_python-0.1.6}/src/flo/wire.py +0 -0
  40. {flo_python-0.1.5 → flo_python-0.1.6}/src/flo/workflows.py +0 -0
  41. {flo_python-0.1.5 → flo_python-0.1.6}/tests/__init__.py +0 -0
  42. {flo_python-0.1.5 → flo_python-0.1.6}/tests/conftest.py +0 -0
  43. {flo_python-0.1.5 → flo_python-0.1.6}/tests/order-workflow.yaml +0 -0
  44. {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_action_ops.py +0 -0
  45. {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_action_status.py +0 -0
  46. {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_actions_live.py +0 -0
  47. {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_auto_touch.py +0 -0
  48. {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_block_ms.py +0 -0
  49. {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_blocking_deadline.py +0 -0
  50. {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_empty_poll_backoff.py +0 -0
  51. {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_group_ops.py +0 -0
  52. {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_groups_live.py +0 -0
  53. {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_halts.py +0 -0
  54. {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_kv_live.py +0 -0
  55. {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_kv_ops.py +0 -0
  56. {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_kv_table.py +0 -0
  57. {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_kv_ttl.py +0 -0
  58. {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_list_paging.py +0 -0
  59. {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_list_paging_live.py +0 -0
  60. {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_missing_answers_live.py +0 -0
  61. {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_op_codes.py +0 -0
  62. {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_ops_drift.py +0 -0
  63. {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_poll_loops.py +0 -0
  64. {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_protocol_version.py +0 -0
  65. {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_queue_live.py +0 -0
  66. {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_queue_ops.py +0 -0
  67. {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_reconnect_cancel.py +0 -0
  68. {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_result_resend.py +0 -0
  69. {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_retry.py +0 -0
  70. {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_status_codes.py +0 -0
  71. {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_stream_delete.py +0 -0
  72. {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_stream_delete_live.py +0 -0
  73. {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_stream_tier.py +0 -0
  74. {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_stream_trim.py +0 -0
  75. {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_stream_worker_ack.py +0 -0
  76. {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_worker_info.py +0 -0
  77. {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_worker_info_live.py +0 -0
  78. {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_worker_list.py +0 -0
  79. {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_worker_live.py +0 -0
  80. {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_worker_liveness.py +0 -0
  81. {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_workflow_list_runs.py +0 -0
  82. {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_workflow_runs_live.py +0 -0
  83. {flo_python-0.1.5 → flo_python-0.1.6}/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=fd771c1dcae467644a0c4e506ee2211f9bc05fee
4
+ FLO_REF=ad198c29bde7011cdd7d87d4bcd861d5addcf9c9
@@ -5,7 +5,66 @@ 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
- ## [Unreleased]
8
+ ## [0.1.6] - 2026-11-16
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 `0x17f3632347cd6dd9` (`TABLE_HASH`).
13
+
14
+ ### Added
15
+
16
+ - `client.ts`: `write`, `read` (one page), `iter_points` (every page) and
17
+ `floql`. A read takes `field`, `tags`, `from_ns`/`to_ns` (inclusive),
18
+ `limit` (1..4096) and `order` (`TSOrder.OLDEST_FIRST` or `NEWEST_FIRST`),
19
+ and answers the points of every matching series merged by time, then
20
+ write order, with an opaque cursor that is `None` on the last page. A
21
+ page goes on strictly past the cursor, so no point is read twice or
22
+ skipped; page until the cursor is `None`, not until a page is short
23
+ - Times are Unix ns `int`s: `TSWriteOptions.time_ns` (`OptionTag.TS_TIMESTAMP_NS`,
24
+ 0x67, an i64; none or 0 is the server's time), `TSWriteResult.time_ns`,
25
+ `TSPoint.time_ns`, `FloQLPoint.time_ns`. `ns_from_datetime` and
26
+ `datetime_from_ns` (and `TSPoint.time`) convert at the microsecond
27
+ - `ts.query` (`TSQueryOptions`: `from_ns`, `to_ns`, a `window` as ns or a
28
+ `timedelta`, and `TSAggregation`) answers `TSBucket`s with `start_ns`;
29
+ `ts.info` answers a `TSInfo` with `oldest_ns` and `newest_ns`.
30
+ `ns_from_timedelta` converts exactly
31
+ - `ProcessingRuntime.late_edge_ms` and `late_points`: at least that many of
32
+ a job's TS source points came in later than the edge at or above its
33
+ lateness window, so its sources never read them; both `None` for a job
34
+ with no TS source
35
+ - `ActionWorker.close(timeout=30.0)` and `StreamWorker.close(timeout=30.0)`
36
+ wait up to `timeout` for `start()` to return, so in-flight completes,
37
+ fails, acks, nacks and hand-backs are sent before the connections close
38
+
39
+ ### Changed
40
+
41
+ - `stream.read` of a stream that doesn't exist (never created, or deleted)
42
+ raises `NotFoundError`, as the server now answers; an existing stream
43
+ with nothing to read is still empty, and a blocking read of a stream not
44
+ created yet still waits for its first append. `ts.read` and `iter_points`
45
+ raise `NotFoundError` when no series of the field matches. A consumer
46
+ that may start before its stream or series exists catches it and starts
47
+ again. A not found answered stale (by a node that may be behind) is
48
+ `StaleNotFoundError`, as for `kv.get`: the stream or series may exist, so
49
+ read again
50
+ - A stream worker whose read is answered not found fails `start()` with
51
+ `NotFoundError` instead of retrying as if the stream were empty
52
+ - A worker task cancelled while its handler runs waits (up to the handler
53
+ timeout) for the handler to end before handing the work back; a cancel
54
+ aimed at the task while a timed-out handler ends is no longer swallowed
55
+ - A FloQL answer of more than 4096 raw points is refused by the server
56
+ (`BadRequestError`, with its text); aggregate, narrow, or page with
57
+ `ts.read`
58
+
59
+ ### Breaking
60
+
61
+ - `OptionTag.TS_TIMESTAMP` is `TS_TIMESTAMP_NS`: the server reads it as ns,
62
+ so a time sent as ms lands near 1970. A time before 1970 is refused
63
+ - `OptionTag.TS_FROM_MS`, `TS_TO_MS` and `TS_WINDOW_MS` are `TS_FROM_NS`,
64
+ `TS_TO_NS` and `TS_WINDOW_NS`, i64s of ns. Every time-series time and
65
+ window is ns; no ms remains in the time-series API
66
+
67
+ ## [0.1.5] - 2026-11-15
9
68
 
10
69
  The op table hash moves with the server in this release: this SDK talks only
11
70
  to the flo it pins, and the pin lands with the release.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: flo-python
3
- Version: 0.1.5
3
+ Version: 0.1.6
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
@@ -65,6 +65,7 @@ asyncio.run(main())
65
65
  - **KV Store**: Versioned key-value storage with MVCC, TTL, and optimistic locking
66
66
  - **Queues**: Priority task queues, at-least-once: a dequeue leases its messages until they're completed
67
67
  - **Streams**: Append-only logs with consumer groups for distributed processing
68
+ - **Time series**: Points in nanoseconds, read a page at a time either way, and FloQL
68
69
  - **Actions**: Registered tasks with configurable timeouts and retries
69
70
  - **Workers**: Distributed task execution with lease management and heartbeats
70
71
  - **Async/await**: Native asyncio support for high-performance applications
@@ -374,6 +375,15 @@ result = await client.stream.read("events", StreamReadOptions(tail=True, count=1
374
375
  result = await client.stream.read("events", StreamReadOptions(start=last, block_ms=30000))
375
376
  ```
376
377
 
378
+ A read of a stream that doesn't exist (never created or appended to, or
379
+ deleted) raises `NotFoundError`, while one that exists with nothing to read is
380
+ empty. A blocking read (`block_ms` > 0) of a stream not created yet waits for
381
+ its first append instead. A consumer that may start before its stream exists
382
+ catches `NotFoundError` and starts again. `StaleNotFoundError` (a
383
+ `NotFoundError`) is a not found from a node that may be behind: the stream may
384
+ exist but this node hasn't seen it yet, so read again rather than treat it as
385
+ gone.
386
+
377
387
  ### Consumer Groups
378
388
 
379
389
  Consumer groups let many consumers work through a stream, each record leased
@@ -392,7 +402,8 @@ read that can take nothing new for either raises `GroupHeldFullError` (an
392
402
  Reading again won't help until room is made, so the client doesn't retry it.
393
403
  At the group's cap, acks and nacks make room, but dead records count too and
394
404
  stay until the group is deleted or a trim of the stream cuts them. At the
395
- shard's cap, other groups and queues on the shard draining makes room.
405
+ shard's cap, this group's own acks free room, as do other groups and queues on
406
+ the shard draining.
396
407
 
397
408
  A group's lease (`ack_timeout_ms`, 5 s to 12 h, 30 s by default) and
398
409
  `max_deliver` (1 to 255) are fixed when it is created; the first read of a
@@ -452,6 +463,129 @@ members = await client.stream.group_members("events", "processors") # consumers
452
463
  await client.stream.group_delete("events", "processors")
453
464
  ```
454
465
 
466
+ ## Time-Series Operations
467
+
468
+ Every time and window is Unix nanoseconds, a Python `int`. A point's
469
+ measurement is the request key; its field defaults to `value`, and its tags
470
+ (`"k=v,k2=v2"` or a dict) name the series.
471
+
472
+ ### Write
473
+
474
+ ```python
475
+ import time
476
+ from flo import TSWriteOptions
477
+
478
+ r = await client.ts.write("cpu", 0.42, TSWriteOptions(tags={"host": "a"}, time_ns=time.time_ns()))
479
+ print(r.time_ns) # the point's time, in ns
480
+
481
+ # No time (or 0): the server's time, answered in r.time_ns.
482
+ await client.ts.write("cpu", 0.40, TSWriteOptions(tags={"host": "a"}))
483
+ ```
484
+
485
+ A time before 1970 is refused (`BadRequestError`), and a value that isn't
486
+ finite is refused before it is sent.
487
+
488
+ ### Read
489
+
490
+ `ts.read` answers one page: the points of every series that matches the
491
+ field and tag filter, merged by time and then by write order, oldest first or
492
+ `TSOrder.NEWEST_FIRST`, at most `limit` (1..4096, 4096 by default), within
493
+ `from_ns`..`to_ns` (inclusive) when given. Ask again with the page's cursor
494
+ until it is `None`; a short page doesn't mean the last one. A page goes on
495
+ strictly after the cursor (before it, newest first), so a point there for the
496
+ whole read is read exactly once. The cursor is opaque bytes.
497
+
498
+ ```python
499
+ from flo import TSOrder, TSReadOptions
500
+
501
+ opts = TSReadOptions(tags="host=a", limit=1000)
502
+ while True:
503
+ page = await client.ts.read("cpu", opts)
504
+ for p in page.points:
505
+ print(p.time_ns, p.value)
506
+ if page.cursor is None:
507
+ break
508
+ opts.cursor = page.cursor
509
+
510
+ # Or let the iterator page: every point, newest first.
511
+ async for p in client.ts.iter_points("cpu", TSReadOptions(order=TSOrder.NEWEST_FIRST)):
512
+ print(p.time_ns, p.value)
513
+
514
+ # The latest point.
515
+ latest = await client.ts.read("cpu", TSReadOptions(limit=1, order=TSOrder.NEWEST_FIRST))
516
+ ```
517
+
518
+ A tag filter that isn't `key=value` pairs, or a cursor that isn't one a page
519
+ answered, is refused (`BadRequestError`), as is an empty measurement name. A
520
+ read that matches no series of the field (a measurement never written, or a
521
+ tag filter no series has) raises `NotFoundError`; a series with no points in
522
+ the range is an empty page. A refusal on any page, `NotFoundError` included,
523
+ is raised from `iter_points` rather than ending it; a reader that may start
524
+ before its series exists catches `NotFoundError` and starts again. As for
525
+ streams, `StaleNotFoundError` means the series may exist but this node hasn't
526
+ seen it yet: read again.
527
+
528
+ `datetime` helpers convert at the edges, to the microsecond (`datetime` holds
529
+ no finer): `ns_from_datetime(dt)` takes an aware `datetime`, and
530
+ `datetime_from_ns(ns)` and `TSPoint.time` give one in UTC. The ns `int` stays
531
+ the exact value.
532
+
533
+ ### Query and info
534
+
535
+ ```python
536
+ from datetime import timedelta
537
+ from flo import TSAggregation, TSQueryOptions
538
+
539
+ # One value per 5-minute window; each bucket's start is Unix ns.
540
+ buckets = await client.ts.query("cpu", TSQueryOptions(
541
+ from_ns=start_ns, to_ns=end_ns, window=timedelta(minutes=5), aggregation=TSAggregation.MAX))
542
+ for b in buckets:
543
+ print(b.start_ns, b.value)
544
+
545
+ info = await client.ts.info("cpu")
546
+ print(info.series, info.points, info.oldest_ns, info.newest_ns)
547
+ ```
548
+
549
+ A query's window is an `int` of ns or a `timedelta` (exact to its
550
+ microsecond); without one, the server's minute. Windows start at multiples of
551
+ the width from the epoch, and only windows holding a point are answered. A
552
+ range holding points in more than 1024 windows is refused (`BadRequestError`,
553
+ with the server's text): widen the window or narrow the range. `ts.info` of a
554
+ measurement with no series raises `NotFoundError`.
555
+
556
+ ### FloQL
557
+
558
+ ```python
559
+ series = await client.ts.floql("cpu[1h] | avg()")
560
+ for s in series:
561
+ for p in s.points:
562
+ print(s.key, p.time_ns, p.value)
563
+ ```
564
+
565
+ In the query text, a bare number in a range is epoch milliseconds and
566
+ durations (`5m`, `30s`) are as FloQL writes them; the answer's times are ns.
567
+ FloQL doesn't page: an answer of more than 4096 raw points is refused
568
+ (`BadRequestError`, with the server's text). Aggregate them, narrow the
569
+ query, or page through them with `ts.read`.
570
+
571
+ ## Processing
572
+
573
+ ```python
574
+ job_id = await client.processing.submit(open("pipeline.yaml").read())
575
+ status = await client.processing.status(job_id)
576
+ print(status.status, status.runtime.records_in, status.runtime.late_points)
577
+ ```
578
+
579
+ A TS source reads its field up to its `lateness_ms` window behind the
580
+ field's newest point (30 s by default, at most a day; 0 reads with no
581
+ window), so it lags by up to the window. A point that arrives later than
582
+ that is never read by the source, and is counted: `runtime.late_points`
583
+ says at least that many of the job's source points came in more than
584
+ `runtime.late_edge_ms` behind their field's newest. The server counts at
585
+ fixed edges (0 s, 1 s, 5 s, 15 s, 30 s, 1 m, 5 m, 1 h), against the smallest
586
+ at or above the job's largest window. Both are `None` for a job with no TS
587
+ source, or a window past an hour.
588
+
455
589
  ## Action Operations
456
590
 
457
591
  Actions are registered tasks that can be invoked and executed by workers.
@@ -649,6 +783,10 @@ Both workers register in the worker registry and heartbeat every 30 s, reporting
649
783
 
650
784
  `worker.drain()` stops taking work and lets the running handlers finish, heartbeats going on; the server is told, so it assigns the worker nothing more, and `start()` returns once the last handler has reported. A drain started on the server does the same. Neither waits out `block_ms`: `drain()` interrupts the worker's own poll connection, so an action worker's held await and a stream worker's held read end at once. A drain started on the server answers an action worker's held await at once, refused as `WORKER_DRAINING`; it doesn't wake a stream worker's held group read, so a stream worker learns of it from its next heartbeat (every 30 s) and only then interrupts its read and leaves. `worker.stop()` ends polling at once, also mid-reconnect or mid-drain; running handlers still finish, and a stream worker hands back (abandons) the records of its last batch it hasn't started, as it does if its task is cancelled: they are ready again at once, and spend none of their attempts. A record whose handler is cancelled while the worker stops (or whose task the worker's cancellation cuts short) is abandoned the same way, so a rolling restart doesn't dead-letter it at `max_deliver` 1; a handler that raises, `CancelledError` included, while the worker isn't stopping is nacked. Either one before or during `start()` ends that run, and a worker can be started again afterwards.
651
785
 
786
+ `await worker.close()` stops the worker. close() waits up to 30 s (timeout=) for the running loop to send its completes, acks and hand-backs, then closes the client; anything unsent is redelivered when its lease expires.
787
+
788
+ A stream worker whose read is answered not found fails `start()` with `NotFoundError` rather than reading on as if the stream were empty. A worker that may start before its stream exists catches it and starts again.
789
+
652
790
  ### StreamWorker Example
653
791
 
654
792
  ```python
@@ -761,7 +899,7 @@ A call that times out (`RequestTimeoutError`, also an `asyncio.TimeoutError`) or
761
899
  | `QueueFullError` | An `OverloadedError` with reason `QUEUE_FULL`: an enqueue found the queue, or its shard's queues and groups, at their caps, and the client's retries ran out |
762
900
  | `GroupHeldFullError` | An `OverloadedError` with reason `GROUP_HELD_FULL`: a group read took nothing new because the group is at its cap (records out and dead together) or the shard's queues and groups are at theirs. Never retried |
763
901
  | `UnavailableError` | No leader, or the shard isn't taking writes or is offline, and the client's retries ran out (the message says why, and whether an operator must act first) |
764
- | `StaleNotFoundError` | `kv.get` or `kv.json_get` found no key, but a halted or read-blocked shard answered: absent only as of the entry it couldn't apply |
902
+ | `StaleNotFoundError` | A `NotFoundError` from a node that may be behind (a halted or read-blocked shard, or a follower that couldn't reach the leader): `kv.get` or `kv.json_get` found no key, or `stream.read`, `ts.read` or `ts.iter_points` no stream or series, but it may exist. Read again rather than treat it as gone |
765
903
  | `LimitError` | Status `LIMIT` (15): the node or shard is at one of its limits; `reason` says which (`TOO_MANY_ACTIONS`, `MEMORY_BUDGET`, `TOO_MANY_WORKFLOW_DEFINITIONS`, `TOO_MANY_WORKFLOW_RUNS`). It didn't run. Terminal, never retried (see below) |
766
904
  | `OutcomePendingError` | The write committed but hasn't applied: its shard halted at or before it (reason `SHARD_HALTED`, ran `UNKNOWN`; the message says whether it applies when the shard resumes). Never retried |
767
905
  | `InternalServerError` | Server internal error; not retryable (may mean committed but not applied) |
@@ -34,6 +34,7 @@ asyncio.run(main())
34
34
  - **KV Store**: Versioned key-value storage with MVCC, TTL, and optimistic locking
35
35
  - **Queues**: Priority task queues, at-least-once: a dequeue leases its messages until they're completed
36
36
  - **Streams**: Append-only logs with consumer groups for distributed processing
37
+ - **Time series**: Points in nanoseconds, read a page at a time either way, and FloQL
37
38
  - **Actions**: Registered tasks with configurable timeouts and retries
38
39
  - **Workers**: Distributed task execution with lease management and heartbeats
39
40
  - **Async/await**: Native asyncio support for high-performance applications
@@ -343,6 +344,15 @@ result = await client.stream.read("events", StreamReadOptions(tail=True, count=1
343
344
  result = await client.stream.read("events", StreamReadOptions(start=last, block_ms=30000))
344
345
  ```
345
346
 
347
+ A read of a stream that doesn't exist (never created or appended to, or
348
+ deleted) raises `NotFoundError`, while one that exists with nothing to read is
349
+ empty. A blocking read (`block_ms` > 0) of a stream not created yet waits for
350
+ its first append instead. A consumer that may start before its stream exists
351
+ catches `NotFoundError` and starts again. `StaleNotFoundError` (a
352
+ `NotFoundError`) is a not found from a node that may be behind: the stream may
353
+ exist but this node hasn't seen it yet, so read again rather than treat it as
354
+ gone.
355
+
346
356
  ### Consumer Groups
347
357
 
348
358
  Consumer groups let many consumers work through a stream, each record leased
@@ -361,7 +371,8 @@ read that can take nothing new for either raises `GroupHeldFullError` (an
361
371
  Reading again won't help until room is made, so the client doesn't retry it.
362
372
  At the group's cap, acks and nacks make room, but dead records count too and
363
373
  stay until the group is deleted or a trim of the stream cuts them. At the
364
- shard's cap, other groups and queues on the shard draining makes room.
374
+ shard's cap, this group's own acks free room, as do other groups and queues on
375
+ the shard draining.
365
376
 
366
377
  A group's lease (`ack_timeout_ms`, 5 s to 12 h, 30 s by default) and
367
378
  `max_deliver` (1 to 255) are fixed when it is created; the first read of a
@@ -421,6 +432,129 @@ members = await client.stream.group_members("events", "processors") # consumers
421
432
  await client.stream.group_delete("events", "processors")
422
433
  ```
423
434
 
435
+ ## Time-Series Operations
436
+
437
+ Every time and window is Unix nanoseconds, a Python `int`. A point's
438
+ measurement is the request key; its field defaults to `value`, and its tags
439
+ (`"k=v,k2=v2"` or a dict) name the series.
440
+
441
+ ### Write
442
+
443
+ ```python
444
+ import time
445
+ from flo import TSWriteOptions
446
+
447
+ r = await client.ts.write("cpu", 0.42, TSWriteOptions(tags={"host": "a"}, time_ns=time.time_ns()))
448
+ print(r.time_ns) # the point's time, in ns
449
+
450
+ # No time (or 0): the server's time, answered in r.time_ns.
451
+ await client.ts.write("cpu", 0.40, TSWriteOptions(tags={"host": "a"}))
452
+ ```
453
+
454
+ A time before 1970 is refused (`BadRequestError`), and a value that isn't
455
+ finite is refused before it is sent.
456
+
457
+ ### Read
458
+
459
+ `ts.read` answers one page: the points of every series that matches the
460
+ field and tag filter, merged by time and then by write order, oldest first or
461
+ `TSOrder.NEWEST_FIRST`, at most `limit` (1..4096, 4096 by default), within
462
+ `from_ns`..`to_ns` (inclusive) when given. Ask again with the page's cursor
463
+ until it is `None`; a short page doesn't mean the last one. A page goes on
464
+ strictly after the cursor (before it, newest first), so a point there for the
465
+ whole read is read exactly once. The cursor is opaque bytes.
466
+
467
+ ```python
468
+ from flo import TSOrder, TSReadOptions
469
+
470
+ opts = TSReadOptions(tags="host=a", limit=1000)
471
+ while True:
472
+ page = await client.ts.read("cpu", opts)
473
+ for p in page.points:
474
+ print(p.time_ns, p.value)
475
+ if page.cursor is None:
476
+ break
477
+ opts.cursor = page.cursor
478
+
479
+ # Or let the iterator page: every point, newest first.
480
+ async for p in client.ts.iter_points("cpu", TSReadOptions(order=TSOrder.NEWEST_FIRST)):
481
+ print(p.time_ns, p.value)
482
+
483
+ # The latest point.
484
+ latest = await client.ts.read("cpu", TSReadOptions(limit=1, order=TSOrder.NEWEST_FIRST))
485
+ ```
486
+
487
+ A tag filter that isn't `key=value` pairs, or a cursor that isn't one a page
488
+ answered, is refused (`BadRequestError`), as is an empty measurement name. A
489
+ read that matches no series of the field (a measurement never written, or a
490
+ tag filter no series has) raises `NotFoundError`; a series with no points in
491
+ the range is an empty page. A refusal on any page, `NotFoundError` included,
492
+ is raised from `iter_points` rather than ending it; a reader that may start
493
+ before its series exists catches `NotFoundError` and starts again. As for
494
+ streams, `StaleNotFoundError` means the series may exist but this node hasn't
495
+ seen it yet: read again.
496
+
497
+ `datetime` helpers convert at the edges, to the microsecond (`datetime` holds
498
+ no finer): `ns_from_datetime(dt)` takes an aware `datetime`, and
499
+ `datetime_from_ns(ns)` and `TSPoint.time` give one in UTC. The ns `int` stays
500
+ the exact value.
501
+
502
+ ### Query and info
503
+
504
+ ```python
505
+ from datetime import timedelta
506
+ from flo import TSAggregation, TSQueryOptions
507
+
508
+ # One value per 5-minute window; each bucket's start is Unix ns.
509
+ buckets = await client.ts.query("cpu", TSQueryOptions(
510
+ from_ns=start_ns, to_ns=end_ns, window=timedelta(minutes=5), aggregation=TSAggregation.MAX))
511
+ for b in buckets:
512
+ print(b.start_ns, b.value)
513
+
514
+ info = await client.ts.info("cpu")
515
+ print(info.series, info.points, info.oldest_ns, info.newest_ns)
516
+ ```
517
+
518
+ A query's window is an `int` of ns or a `timedelta` (exact to its
519
+ microsecond); without one, the server's minute. Windows start at multiples of
520
+ the width from the epoch, and only windows holding a point are answered. A
521
+ range holding points in more than 1024 windows is refused (`BadRequestError`,
522
+ with the server's text): widen the window or narrow the range. `ts.info` of a
523
+ measurement with no series raises `NotFoundError`.
524
+
525
+ ### FloQL
526
+
527
+ ```python
528
+ series = await client.ts.floql("cpu[1h] | avg()")
529
+ for s in series:
530
+ for p in s.points:
531
+ print(s.key, p.time_ns, p.value)
532
+ ```
533
+
534
+ In the query text, a bare number in a range is epoch milliseconds and
535
+ durations (`5m`, `30s`) are as FloQL writes them; the answer's times are ns.
536
+ FloQL doesn't page: an answer of more than 4096 raw points is refused
537
+ (`BadRequestError`, with the server's text). Aggregate them, narrow the
538
+ query, or page through them with `ts.read`.
539
+
540
+ ## Processing
541
+
542
+ ```python
543
+ job_id = await client.processing.submit(open("pipeline.yaml").read())
544
+ status = await client.processing.status(job_id)
545
+ print(status.status, status.runtime.records_in, status.runtime.late_points)
546
+ ```
547
+
548
+ A TS source reads its field up to its `lateness_ms` window behind the
549
+ field's newest point (30 s by default, at most a day; 0 reads with no
550
+ window), so it lags by up to the window. A point that arrives later than
551
+ that is never read by the source, and is counted: `runtime.late_points`
552
+ says at least that many of the job's source points came in more than
553
+ `runtime.late_edge_ms` behind their field's newest. The server counts at
554
+ fixed edges (0 s, 1 s, 5 s, 15 s, 30 s, 1 m, 5 m, 1 h), against the smallest
555
+ at or above the job's largest window. Both are `None` for a job with no TS
556
+ source, or a window past an hour.
557
+
424
558
  ## Action Operations
425
559
 
426
560
  Actions are registered tasks that can be invoked and executed by workers.
@@ -618,6 +752,10 @@ Both workers register in the worker registry and heartbeat every 30 s, reporting
618
752
 
619
753
  `worker.drain()` stops taking work and lets the running handlers finish, heartbeats going on; the server is told, so it assigns the worker nothing more, and `start()` returns once the last handler has reported. A drain started on the server does the same. Neither waits out `block_ms`: `drain()` interrupts the worker's own poll connection, so an action worker's held await and a stream worker's held read end at once. A drain started on the server answers an action worker's held await at once, refused as `WORKER_DRAINING`; it doesn't wake a stream worker's held group read, so a stream worker learns of it from its next heartbeat (every 30 s) and only then interrupts its read and leaves. `worker.stop()` ends polling at once, also mid-reconnect or mid-drain; running handlers still finish, and a stream worker hands back (abandons) the records of its last batch it hasn't started, as it does if its task is cancelled: they are ready again at once, and spend none of their attempts. A record whose handler is cancelled while the worker stops (or whose task the worker's cancellation cuts short) is abandoned the same way, so a rolling restart doesn't dead-letter it at `max_deliver` 1; a handler that raises, `CancelledError` included, while the worker isn't stopping is nacked. Either one before or during `start()` ends that run, and a worker can be started again afterwards.
620
754
 
755
+ `await worker.close()` stops the worker. close() waits up to 30 s (timeout=) for the running loop to send its completes, acks and hand-backs, then closes the client; anything unsent is redelivered when its lease expires.
756
+
757
+ A stream worker whose read is answered not found fails `start()` with `NotFoundError` rather than reading on as if the stream were empty. A worker that may start before its stream exists catches it and starts again.
758
+
621
759
  ### StreamWorker Example
622
760
 
623
761
  ```python
@@ -730,7 +868,7 @@ A call that times out (`RequestTimeoutError`, also an `asyncio.TimeoutError`) or
730
868
  | `QueueFullError` | An `OverloadedError` with reason `QUEUE_FULL`: an enqueue found the queue, or its shard's queues and groups, at their caps, and the client's retries ran out |
731
869
  | `GroupHeldFullError` | An `OverloadedError` with reason `GROUP_HELD_FULL`: a group read took nothing new because the group is at its cap (records out and dead together) or the shard's queues and groups are at theirs. Never retried |
732
870
  | `UnavailableError` | No leader, or the shard isn't taking writes or is offline, and the client's retries ran out (the message says why, and whether an operator must act first) |
733
- | `StaleNotFoundError` | `kv.get` or `kv.json_get` found no key, but a halted or read-blocked shard answered: absent only as of the entry it couldn't apply |
871
+ | `StaleNotFoundError` | A `NotFoundError` from a node that may be behind (a halted or read-blocked shard, or a follower that couldn't reach the leader): `kv.get` or `kv.json_get` found no key, or `stream.read`, `ts.read` or `ts.iter_points` no stream or series, but it may exist. Read again rather than treat it as gone |
734
872
  | `LimitError` | Status `LIMIT` (15): the node or shard is at one of its limits; `reason` says which (`TOO_MANY_ACTIONS`, `MEMORY_BUDGET`, `TOO_MANY_WORKFLOW_DEFINITIONS`, `TOO_MANY_WORKFLOW_RUNS`). It didn't run. Terminal, never retried (see below) |
735
873
  | `OutcomePendingError` | The write committed but hasn't applied: its shard halted at or before it (reason `SHARD_HALTED`, ran `UNKNOWN`; the message says whether it applies when the shard resumes). Never retried |
736
874
  | `InternalServerError` | Server internal error; not retryable (may mean committed but not applied) |
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "flo-python"
7
- version = "0.1.5"
7
+ version = "0.1.6"
8
8
  description = "Python SDK for the Flo distributed systems platform"
9
9
  readme = "README.md"
10
10
  license = "Apache-2.0"
@@ -73,6 +73,7 @@ from .exceptions import (
73
73
  from .kv_txn import Transaction, TxnFinishedError, TxnUnsupportedOpError
74
74
  from .processing import ProcessingOperations
75
75
  from .retry import DEFAULT_RETRY_POLICY, RetryPolicy
76
+ from .ts import TSOperations
76
77
  from .types import (
77
78
  ActionDeleteOptions,
78
79
  ActionInfo,
@@ -94,6 +95,8 @@ from .types import (
94
95
  DlqPage,
95
96
  EnqueueOptions,
96
97
  ExistsResult,
98
+ FloQLPoint,
99
+ FloQLSeries,
97
100
  GetJsonResult,
98
101
  GetOptions,
99
102
  GetResult,
@@ -171,6 +174,16 @@ from .types import (
171
174
  StreamTrimOptions,
172
175
  StreamTrimResult,
173
176
  TaskAssignment,
177
+ TSAggregation,
178
+ TSBucket,
179
+ TSInfo,
180
+ TSOrder,
181
+ TSPoint,
182
+ TSQueryOptions,
183
+ TSReadOptions,
184
+ TSReadResult,
185
+ TSWriteOptions,
186
+ TSWriteResult,
174
187
  VersionEntry,
175
188
  WaitFor,
176
189
  WorkerAwaitOptions,
@@ -202,6 +215,9 @@ from .types import (
202
215
  WorkflowStatusOptions,
203
216
  WorkflowSyncOptions,
204
217
  WorkflowSyncResult,
218
+ datetime_from_ns,
219
+ ns_from_datetime,
220
+ ns_from_timedelta,
205
221
  )
206
222
  from .worker import (
207
223
  ActionContext,
@@ -215,7 +231,7 @@ from .worker import (
215
231
  )
216
232
  from .workflows import WorkflowOperations
217
233
 
218
- __version__ = "0.1.5"
234
+ __version__ = "0.1.6"
219
235
 
220
236
  __all__ = [
221
237
  "Transaction",
@@ -413,5 +429,21 @@ __all__ = [
413
429
  "ProcessingListResult",
414
430
  "ProcessingRemoveOptions",
415
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",
416
448
  "ProcessingSyncResult",
417
449
  ]
@@ -114,6 +114,7 @@ class FloClient:
114
114
  from .processing import ProcessingOperations
115
115
  from .queue import QueueOperations
116
116
  from .streams import StreamOperations
117
+ from .ts import TSOperations
117
118
  from .workflows import WorkflowOperations
118
119
 
119
120
  self.kv = KVOperations(self)
@@ -123,6 +124,7 @@ class FloClient:
123
124
  self.worker = WorkerOperations(self)
124
125
  self.workflow = WorkflowOperations(self)
125
126
  self.processing = ProcessingOperations(self)
127
+ self.ts = TSOperations(self)
126
128
 
127
129
  if debug:
128
130
  logging.basicConfig(level=logging.DEBUG)
@@ -183,10 +183,12 @@ class NotFoundError(ServerError):
183
183
 
184
184
 
185
185
  class StaleNotFoundError(NotFoundError):
186
- """A halted or read-blocked shard didn't have the key, as of the entry
187
- it couldn't apply (``stale`` is True). It may exist since: a write after
188
- that entry hasn't applied. kv.get and kv.json_get raise it rather than report the key
189
- absent."""
186
+ """A node answered not found from state it knows may be behind (``stale``
187
+ is True): a halted or read-blocked shard, as of the entry it couldn't
188
+ apply, or a follower that couldn't reach the leader. It may exist: read
189
+ again rather than treat it as gone. kv.get and kv.json_get raise it
190
+ rather than report the key absent; stream.read, ts.read and
191
+ ts.iter_points raise it for the stream or series."""
190
192
 
191
193
  stale = True
192
194
 
@@ -250,9 +252,10 @@ class GroupHeldFullError(OverloadedError):
250
252
  names which cap. At the group's cap (records ready, leased and dead
251
253
  together), acks and nacks make room, but dead records stay until the
252
254
  group is deleted or a trim of the stream cuts them. At the shard's cap
253
- (its queues and groups together), other groups and queues draining makes
254
- room. Reading again won't help until then, so the client never retries
255
- it; a stream worker logs it and backs off."""
255
+ (its queues and groups together), this group's own acks free room, as do
256
+ other groups and queues on the shard draining. Reading again won't help
257
+ until then, so the client never retries it; a stream worker logs it and
258
+ backs off."""
256
259
 
257
260
 
258
261
  class RateLimitedError(ServerError):
@@ -329,6 +332,22 @@ def is_connection_error(exc: BaseException) -> bool:
329
332
  return isinstance(exc, (UnexpectedEofError, NotConnectedError, RequestTimeoutError, OSError))
330
333
 
331
334
 
335
+ def not_found_error(status: StatusCode, data: bytes, stale: bool) -> ServerError:
336
+ """The error a not-found answer raises. On a stale answer, a thing not
337
+ found (reason NOT_FOUND) is a StaleNotFoundError: the node hadn't seen it
338
+ yet, so it may exist."""
339
+ try:
340
+ raise_for_status(status, data)
341
+ except ServerError as e:
342
+ e.stale = stale
343
+ if stale and e.reason == Reason.NOT_FOUND:
344
+ found = StaleNotFoundError(str(e))
345
+ found.reason, found.ran = e.reason, e.ran
346
+ return found
347
+ return e
348
+ raise AssertionError("a not-found answer always raises") # pragma: no cover
349
+
350
+
332
351
  def raise_for_status(status: StatusCode, data: bytes = b"") -> None:
333
352
  """Raise appropriate exception for non-OK status codes.
334
353
 
@@ -8,9 +8,8 @@ from typing import TYPE_CHECKING, Any
8
8
 
9
9
  from .exceptions import (
10
10
  IncompleteResponseError,
11
- ServerError,
12
11
  StaleNotFoundError,
13
- raise_for_status,
12
+ not_found_error,
14
13
  )
15
14
  from .kv_body import (
16
15
  decode_delete_answer,
@@ -79,18 +78,10 @@ def _absent(response: RawResponse, *, stale_raises: bool = False) -> bool:
79
78
  absent."""
80
79
  if not response.is_not_found():
81
80
  return False
82
- try:
83
- raise_for_status(response.status, response.data)
84
- except ServerError as e:
85
- e.stale = response.stale
86
- if e.reason != Reason.NOT_FOUND:
87
- raise
88
- if stale_raises and response.stale:
89
- stale = StaleNotFoundError(str(e))
90
- stale.reason, stale.ran = e.reason, e.ran
91
- raise stale from None
92
- return True
93
- return False # pragma: no cover - raise_for_status always raises here
81
+ e = not_found_error(response.status, response.data, response.stale)
82
+ if e.reason != Reason.NOT_FOUND or (stale_raises and isinstance(e, StaleNotFoundError)):
83
+ raise e
84
+ return True
94
85
 
95
86
 
96
87
  async def kv_get(
@@ -1,6 +1,6 @@
1
1
  """The ops on the server's op table: KV, the action reports and reads,
2
2
  worker.list and worker.info, stream group reads, the queue's dequeue,
3
- reports and peek, and processing.remove.
3
+ reports and peek, ts.read and ts.info, and processing.remove.
4
4
 
5
5
  The request is ``[namespace][key][body]``, the body coded by the op's
6
6
  schema, field by field in order. An optional field is a presence byte then
@@ -123,6 +123,7 @@ _TABLE_OPS = frozenset(
123
123
  OpCode.QUEUE_COMPLETE,
124
124
  OpCode.QUEUE_FAIL,
125
125
  OpCode.QUEUE_TOUCH,
126
+ OpCode.TS_READ,
126
127
  OpCode.TS_INFO,
127
128
  OpCode.PROCESSING_REMOVE,
128
129
  }