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.
- {flo_python-0.1.5 → flo_python-0.1.6}/.github/flo-ref.env +1 -1
- {flo_python-0.1.5 → flo_python-0.1.6}/CHANGELOG.md +60 -1
- {flo_python-0.1.5 → flo_python-0.1.6}/PKG-INFO +141 -3
- {flo_python-0.1.5 → flo_python-0.1.6}/README.md +140 -2
- {flo_python-0.1.5 → flo_python-0.1.6}/pyproject.toml +1 -1
- {flo_python-0.1.5 → flo_python-0.1.6}/src/flo/__init__.py +33 -1
- {flo_python-0.1.5 → flo_python-0.1.6}/src/flo/client.py +2 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/src/flo/exceptions.py +26 -7
- {flo_python-0.1.5 → flo_python-0.1.6}/src/flo/kv.py +5 -14
- {flo_python-0.1.5 → flo_python-0.1.6}/src/flo/kv_body.py +2 -1
- {flo_python-0.1.5 → flo_python-0.1.6}/src/flo/processing.py +16 -3
- {flo_python-0.1.5 → flo_python-0.1.6}/src/flo/streams.py +14 -1
- flo_python-0.1.6/src/flo/ts.py +465 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/src/flo/types.py +189 -6
- {flo_python-0.1.5 → flo_python-0.1.6}/src/flo/worker.py +68 -16
- flo_python-0.1.6/tests/test_not_found_answers.py +113 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_processing_decode.py +29 -1
- {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_processing_live.py +36 -1
- flo_python-0.1.6/tests/test_read_not_found_live.py +78 -0
- flo_python-0.1.6/tests/test_ts_live.py +259 -0
- flo_python-0.1.6/tests/test_ts_ops.py +467 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_wire.py +1 -1
- flo_python-0.1.6/tests/test_worker_close.py +278 -0
- flo_python-0.1.6/tests/test_worker_close_live.py +97 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_worker_drain.py +6 -2
- flo_python-0.1.5/tests/test_not_found_answers.py +0 -38
- {flo_python-0.1.5 → flo_python-0.1.6}/.github/workflows/ci.yml +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/.github/workflows/release.yml +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/.gitignore +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/LICENSE +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/examples/basic.py +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/examples/stream_worker.py +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/examples/test_decorator.py +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/examples/worker.py +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/src/flo/actions.py +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/src/flo/kv_txn.py +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/src/flo/queue.py +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/src/flo/retry.py +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/src/flo/wire.py +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/src/flo/workflows.py +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/tests/__init__.py +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/tests/conftest.py +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/tests/order-workflow.yaml +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_action_ops.py +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_action_status.py +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_actions_live.py +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_auto_touch.py +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_block_ms.py +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_blocking_deadline.py +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_empty_poll_backoff.py +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_group_ops.py +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_groups_live.py +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_halts.py +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_kv_live.py +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_kv_ops.py +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_kv_table.py +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_kv_ttl.py +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_list_paging.py +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_list_paging_live.py +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_missing_answers_live.py +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_op_codes.py +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_ops_drift.py +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_poll_loops.py +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_protocol_version.py +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_queue_live.py +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_queue_ops.py +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_reconnect_cancel.py +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_result_resend.py +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_retry.py +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_status_codes.py +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_stream_delete.py +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_stream_delete_live.py +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_stream_tier.py +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_stream_trim.py +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_stream_worker_ack.py +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_worker_info.py +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_worker_info_live.py +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_worker_list.py +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_worker_live.py +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_worker_liveness.py +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_workflow_list_runs.py +0 -0
- {flo_python-0.1.5 → flo_python-0.1.6}/tests/test_workflow_runs_live.py +0 -0
- {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=
|
|
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
|
-
## [
|
|
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.
|
|
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
|
|
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,
|
|
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
|
|
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,
|
|
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) |
|
|
@@ -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.
|
|
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
|
|
187
|
-
|
|
188
|
-
that
|
|
189
|
-
|
|
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),
|
|
254
|
-
|
|
255
|
-
it; a stream worker logs it and
|
|
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
|
-
|
|
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
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
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
|
}
|