flo-python 0.1.0.dev4__py3-none-any.whl → 0.1.2__py3-none-any.whl

{flo_python-0.1.0.dev4.dist-info → flo_python-0.1.2.dist-info}/METADATA

@@ -1,18 +1,17 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: flo-python
-Version: 0.1.0.dev4
+Version: 0.1.2
 Summary: Python SDK for the Flo distributed systems platform
 Project-URL: Homepage, https://github.com/floruntime/flo-python
 Project-URL: Documentation, https://github.com/floruntime/flo-python#readme
 Project-URL: Repository, https://github.com/floruntime/flo-python
 Author: Flo Team
-License-Expression: MIT
+License-Expression: Apache-2.0
 License-File: LICENSE
 Keywords: async,distributed-systems,flo,kv-store,queue
 Classifier: Development Status :: 3 - Alpha
 Classifier: Framework :: AsyncIO
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
@@ -24,6 +23,7 @@ Requires-Python: >=3.10
 Provides-Extra: dev
 Requires-Dist: mypy>=1.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest-timeout>=2.1; extra == 'dev'
 Requires-Dist: pytest>=7.0; extra == 'dev'
 Requires-Dist: ruff>=0.1; extra == 'dev'
 Description-Content-Type: text/markdown
@@ -35,7 +35,7 @@ Python SDK for the [Flo](https://github.com/floruntime) distributed systems plat
 ## Installation
 
 ```bash
-pip install flo
+pip install flo-python
 ```
 
 ## Quick Start
@@ -62,9 +62,9 @@ asyncio.run(main())
 ## Features
 
 - **KV Store**: Versioned key-value storage with MVCC, TTL, and optimistic locking
-- **Queues**: Priority-based task queues with visibility timeout and dead letter queues
+- **Queues**: Priority task queues (currently at-most-once: dequeue hands each message out once)
 - **Streams**: Append-only logs with consumer groups for distributed processing
-- **Actions**: Registered tasks with configurable timeouts, retries, and idempotency
+- **Actions**: Registered tasks with configurable timeouts and retries
 - **Workers**: Distributed task execution with lease management and heartbeats
 - **Async/await**: Native asyncio support for high-performance applications
 - **Type hints**: Full type annotations for IDE support
@@ -74,18 +74,20 @@ asyncio.run(main())
 ### Get
 
 ```python
-from flo import GetOptions
+from flo import GetOptions, WaitFor
 
 # Simple get
 value = await client.kv.get("key")
 if value is not None:
     print(value.decode())
 
-# Blocking get - wait up to 5 seconds for value to appear
-value = await client.kv.get("key", GetOptions(block_ms=5000))
+# Wait up to 2 seconds for the key to exist (answers at once if it does)
+# (wait_ms is at most 300000; the client waits timeout_ms on top of it;
+# 0 means don't wait)
+value = await client.kv.get("key", GetOptions(wait_ms=2000))
 
-# Blocking get - wait indefinitely (0 = infinite)
-value = await client.kv.get("key", GetOptions(block_ms=0))
+# Wait up to 2 seconds for the key's next version
+value = await client.kv.get("key", GetOptions(wait_ms=2000, wait_for=WaitFor.CHANGE))
 
 # Get with namespace override
 value = await client.kv.get("key", GetOptions(namespace="other"))
@@ -94,28 +96,34 @@ value = await client.kv.get("key", GetOptions(namespace="other"))
 ### Put
 
 ```python
-from flo import PutOptions
+from flo import Condition, PutOptions
 
 # Simple put
 await client.kv.put("key", b"value")
 
 # Put with TTL (expires in 1 hour)
-await client.kv.put("session:abc", b"data", PutOptions(ttl_seconds=3600))
+await client.kv.put("session:abc", b"data", PutOptions(ttl_ms=3_600_000))
 
 # Put with CAS (optimistic locking)
 await client.kv.put("counter", b"2", PutOptions(cas_version=1))
 
 # Put only if key doesn't exist
-await client.kv.put("key", b"value", PutOptions(if_not_exists=True))
+await client.kv.put("key", b"value", PutOptions(condition=Condition.IF_ABSENT))
 
 # Put only if key exists
-await client.kv.put("key", b"value", PutOptions(if_exists=True))
+await client.kv.put("key", b"value", PutOptions(condition=Condition.IF_PRESENT))
 ```
 
 ### Delete
 
 ```python
-await client.kv.delete("key")
+from flo import DeleteOptions
+
+# Returns whether the key existed; deleting a missing key is not an error
+existed = await client.kv.delete("key")
+
+# Delete only at a known version
+await client.kv.delete("lock:resource", DeleteOptions(cas_version=held_version))
 ```
 
 ### Scan
@@ -123,19 +131,29 @@ await client.kv.delete("key")
 ```python
 from flo import ScanOptions
 
-# Scan all keys with prefix
+# Names of keys with a prefix ("" for all), up to 1024 per page by default
 result = await client.kv.scan("user:")
-for entry in result.entries:
-    print(f"{entry.key.decode()}: {entry.value.decode()}")
+for name in result.names:
+    print(name)
 
-# Paginated scan
-result = await client.kv.scan("user:", ScanOptions(limit=100))
-while result.has_more:
-    # Process entries...
+# Next pages: the cursor is None on the last page (limit is 1..1024)
+while result.cursor is not None:
     result = await client.kv.scan("user:", ScanOptions(cursor=result.cursor, limit=100))
+```
 
-# Keys only (more efficient when you don't need values)
-result = await client.kv.scan("user:", ScanOptions(keys_only=True))
+### MGet
+
+```python
+# One entry per key, in order (at most 256 keys of at most 4096 bytes each)
+for e in await client.kv.mget(["user:1", "user:2"]):
+    if e.found:
+        print(e.key, e.version, e.value)
+
+# Keys all written with one routing key: look them all up on its shard
+# (without it, each key is looked up on its own shard)
+from flo import KVMGetOptions
+
+await client.kv.mget(["user:1:name", "user:1:email"], KVMGetOptions(routing_key="user:1"))
 ```
 
 ### History
@@ -143,10 +161,51 @@ result = await client.kv.scan("user:", ScanOptions(keys_only=True))
 ```python
 from flo import HistoryOptions
 
-# Get version history for a key
+# Versions newest first (limit 1..65, default 10), each with its write time in ms;
+# empty for a missing key
 history = await client.kv.history("user:123", HistoryOptions(limit=10))
 for entry in history:
-    print(f"v{entry.version} at {entry.timestamp}: {entry.value.decode()}")
+    print(f"v{entry.version} at {entry.at_ms}: {entry.value.decode()}")
+```
+
+### Counters, TTL and exists
+
+```python
+from flo import KVExpireOptions, KVIncrOptions
+
+res = await client.kv.incr("visits")  # +1
+res = await client.kv.incr("visits", KVIncrOptions(delta=-5))
+print(res.value, res.version)
+
+# Set a key's TTL in ms; 0 clears it. cas_version makes lease renewal race-free.
+await client.kv.expire("session:abc", 60_000)
+await client.kv.expire("lease", 30_000, KVExpireOptions(cas_version=lease_version))
+await client.kv.expire("session:abc", 0)
+
+if await client.kv.exists("session:abc"):
+    ...
+```
+
+### JSON documents
+
+```python
+# Path defaults to "$" (the whole document)
+await client.kv.json_set("user:1", "$", b'{"name": "Ada", "tags": []}')
+doc = await client.kv.json_get("user:1", "$.name")  # GetJsonResult or None
+await client.kv.json_del("user:1", "$.tags")  # returns the new version
+await client.kv.json_del("user:1")  # "$" deletes the key: returns None
+```
+
+### Transactions
+
+```python
+# Every op inside is routed by the transaction's routing key
+async with await client.kv.begin("user:123") as txn:
+    await txn.put("user:123:name", b"Jane")
+    await txn.incr("user:123:visits")
+    await txn.expire("user:123:session", 60_000)
+    result = await txn.commit()
+    print(result.commit_index, result.op_count)
 ```
 
 ## Queue Operations
@@ -159,18 +218,16 @@ from flo import EnqueueOptions
 # Simple enqueue
 seq = await client.queue.enqueue("tasks", b'{"task": "process"}')
 
-# With priority (higher = more urgent, 0-255)
+# With priority (0-255, lower is taken first; default 0)
 seq = await client.queue.enqueue("tasks", payload, EnqueueOptions(priority=10))
-
-# With delay (message invisible for 60 seconds)
-seq = await client.queue.enqueue("tasks", payload, EnqueueOptions(delay_ms=60000))
-
-# With deduplication key
-seq = await client.queue.enqueue("tasks", payload, EnqueueOptions(dedup_key="task-123"))
 ```
 
 ### Dequeue
 
+Queues are currently at-most-once: a dequeue acknowledges each message as it
+hands it out. A message is not redelivered in normal operation, even if the
+consumer crashes while handling it, so handle failures in your own code.
+
 ```python
 from flo import DequeueOptions
 
@@ -181,69 +238,25 @@ for msg in result.messages:
 
 # Long polling (wait up to 30s for messages)
 result = await client.queue.dequeue("tasks", 10, DequeueOptions(block_ms=30000))
-
-# Custom visibility timeout (message invisible for 60s)
-result = await client.queue.dequeue("tasks", 10, DequeueOptions(visibility_timeout_ms=60000))
 ```
 
-### Ack/Nack
+### Ack/Nack and the Dead Letter Queue
 
-```python
-from flo import NackOptions
-
-result = await client.queue.dequeue("tasks", 10)
-for msg in result.messages:
-    try:
-        process(msg.payload)
-        # Acknowledge successful processing
-        await client.queue.ack("tasks", [msg.seq])
-    except Exception:
-        # Retry the message
-        await client.queue.nack("tasks", [msg.seq])
-        # Or send to DLQ
-        await client.queue.nack("tasks", [msg.seq], NackOptions(to_dlq=True))
-```
-
-### Dead Letter Queue
-
-```python
-from flo import DlqListOptions
-
-# List DLQ messages
-result = await client.queue.dlq_list("tasks", DlqListOptions(limit=100))
-for msg in result.messages:
-    print(f"Failed message {msg.seq}: {msg.payload}")
-
-# Requeue DLQ messages
-seqs = [msg.seq for msg in result.messages]
-await client.queue.dlq_requeue("tasks", seqs)
-```
+`queue.ack`, `queue.nack`, `queue.dlq_list` and `queue.dlq_requeue` exist, but
+while queues are at-most-once they do nothing useful: a dequeued message is
+already acknowledged, so ack and nack have no effect on it, nack does not
+retry it, and messages don't reach the DLQ in normal use.
 
 ### Peek
 
 ```python
-# Peek at messages without creating leases (no visibility timeout)
+# Peek at messages without removing them
 result = await client.queue.peek("tasks", 5)
 for msg in result.messages:
     print(f"Message {msg.seq}: {msg.payload}")
 # Messages remain visible to other consumers
 ```
 
-### Touch (Lease Renewal)
-
-```python
-# Renew lease on messages during long-running processing
-result = await client.queue.dequeue("tasks", 1)
-msg = result.messages[0]
-
-# Long running task - periodically touch to prevent visibility timeout
-for chunk in process_in_chunks(msg.payload):
-    await process_chunk(chunk)
-    await client.queue.touch("tasks", [msg.seq])  # Renew lease
-
-await client.queue.ack("tasks", [msg.seq])
-```
-
 ## Stream Operations
 
 Streams are append-only logs ideal for event sourcing, activity feeds, and real-time data pipelines.
@@ -359,15 +372,14 @@ from flo import ActionInvokeOptions
 result = await client.action.invoke(
     "process-image",
     b'{"image_url": "https://example.com/image.jpg"}',
-    ActionInvokeOptions(priority=10)
 )
 print(f"Run ID: {result.run_id}")
 
-# Invoke with idempotency key (prevents duplicate runs)
+# Route the run only to workers registered with matching labels
 result = await client.action.invoke(
     "process-image",
-    payload,
-    ActionInvokeOptions(idempotency_key="order-123-image")
+    b'{"image_url": "https://example.com/image.jpg"}',
+    ActionInvokeOptions(labels={"gpu": True}),
 )
 ```
 
@@ -375,9 +387,11 @@ result = await client.action.invoke(
 
 ```python
 status = await client.action.status(result.run_id)
-print(f"Status: {status.status}")
-if status.result:
-    print(f"Result: {status.result}")
+print(f"Status: {status.status.name}, attempt {status.attempt}")
+if status.output is not None:
+    print(f"Output: {status.output!r}")
+if status.error_message is not None:
+    print(f"Error: {status.error_message}")
 ```
 
 ### List and Delete Actions
@@ -453,14 +467,14 @@ await client.worker.touch(
 
 ```python
 import asyncio
-from flo import FloClient
+from flo import ActionRegisterOptions, FloClient
 
 async def run_worker():
     async with FloClient("localhost:9000", namespace="myapp") as client:
         # Create an action worker from the client
-        worker = client.new_action_worker(concurrency=5)
+        worker = client.new_action_worker(concurrency=5, auto_touch=True)
 
-        @worker.action("process-image")
+        @worker.action("process-image", ActionRegisterOptions(timeout_ms=60000))
         async def process_image(ctx):
             data = ctx.json()
             result = await do_processing(data)
@@ -471,6 +485,14 @@ async def run_worker():
 asyncio.run(run_worker())
 ```
 
+The worker registers each action with the server when it starts, with exactly the options given (the server's defaults when none: a 30 s timeout, 3 attempts). Registering replaces the action's settings, so workers that register one action with different options leave it with whichever registered last.
+
+A run whose handler goes past the action's `timeout_ms` without touching it is taken back and run again, by this worker or another. `auto_touch=True` touches each run every third of its action's timeout while the handler runs; it's off by default. Without it, call `await ctx.touch()` from long handlers. The worker also stops any handler after its own `action_timeout` (300 s by default) whatever the action's `timeout_ms`, so raise it for actions that run longer.
+
+Delivery is at-least-once: a result lost to a dropped connection is resent, and one that never arrives lets the lease run out, so a handler may see the same task or record again. `worker.stop()` waits for running handlers, and their results are still sent.
+
+An action worker heartbeats every 30 s, reporting the handlers it is running. One the server removed after missed heartbeats registers again, with the same options, when its next heartbeat is answered not found. One the server has drained stops taking work, and `start()` returns once its running handlers finish.
+
 ### StreamWorker Example
 
 ```python
@@ -506,9 +528,12 @@ client = FloClient(
     namespace="myapp",      # Default namespace for all operations
     timeout_ms=5000,        # Connection and operation timeout
     debug=True,             # Enable debug logging
+    retry=RetryPolicy(),    # Retries of refused, not-run requests (the default)
 )
 ```
 
+A call that times out or is cancelled drops the connection; call `reconnect()` before reusing the client (workers do this themselves).
+
 ### Namespaces
 
 Each operation can override the default namespace:
@@ -545,6 +570,8 @@ except FloError as e:
     print(f"Flo error: {e}")
 ```
 
+A call that times out (`RequestTimeoutError`, also an `asyncio.TimeoutError`) or is cancelled drops the connection; call `reconnect()` before reusing the client (workers do this themselves).
+
 ### Error Types
 
 | Error | Description |
@@ -553,11 +580,51 @@ except FloError as e:
 | `BadRequestError` | Invalid request parameters |
 | `ConflictError` | CAS version mismatch |
 | `UnauthorizedError` | Authentication failed |
-| `OverloadedError` | Server is overloaded |
-| `InternalServerError` | Server internal error |
+| `OverloadedError` | Server is overloaded, and the client's retries ran out |
+| `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) |
+| `InternalServerError` | Server internal error; not retryable (may mean committed but not applied) |
+| `GenericServerError` | Any other error status, including one this SDK doesn't know (`status_code` carries it) |
 | `ConnectionFailedError` | Failed to connect |
+| `RequestTimeoutError` | No response within the timeout |
 | `InvalidChecksumError` | Response CRC32 mismatch |
 
+### Retries
+
+When the server refuses a request as `overloaded` or `unavailable` and says it
+didn't run it (`error.ran == Ran.NO`), the client sends it again itself, as a
+new request, after a jittered wait. Because the server never ran it, this is
+safe for writes too. Any other refusal, or one that may have run, comes
+straight back.
+
+| `RetryPolicy` field | Default | |
+|---|---|---|
+| `max_attempts` | 4 | Tries in all, the first included; 1 turns retrying off |
+| `initial_backoff_ms` | 50 | Ceiling of the first wait, in ms; it doubles each retry |
+| `max_backoff_ms` | 1000 | Largest ceiling, in ms |
+
+Each wait is uniform between 0 and its ceiling, so with the defaults a refused
+request is given back after at most about 350 ms of waiting. A negative backoff
+counts as 0, and a `max_backoff_ms` below `initial_backoff_ms` as
+`initial_backoff_ms`. The request goes again on the same connection; the server
+routes it afresh. Other calls on the client are not held up by the wait.
+
+The action and stream workers use their client's policy, and wait the same way
+between failed polls, from 100 ms up to 5 s, starting again from 100 ms after a
+poll that succeeds; `stop()` cuts the wait short. A stream worker retries a
+group join refused this way instead of stopping.
+
+```python
+from flo import FloClient, RetryPolicy
+
+# Up to 8 tries, waiting at most 2 s between them
+client = FloClient("localhost:9000", retry=RetryPolicy(
+    max_attempts=8, initial_backoff_ms=100, max_backoff_ms=2000,
+))
+
+# No retries
+client = FloClient("localhost:9000", retry=RetryPolicy(max_attempts=1))
+```
+
 ## Requirements
 
 - Python 3.10+
@@ -565,4 +632,4 @@ except FloError as e:
 
 ## License
 
-MIT
+Apache-2.0 - see [LICENSE](LICENSE) for details.

flo_python-0.1.2.dist-info/RECORD

@@ -0,0 +1,19 @@
+flo/__init__.py,sha256=4zwv03hg6JTNTvy8n7p3k2KTS8Y2dW1UoLSR9Mrjb4c,7932
+flo/actions.py,sha256=hHtfcmaDRHt0rm2-DNRPT2r3Xm6FmV8XKqSvCa7tHW4,12009
+flo/client.py,sha256=0JxnT_dgiJIgpsmykQiCtnjMQLTcRlzA2sd4BZ_Y6ns,22309
+flo/exceptions.py,sha256=Ab71lT63i9s_0Q55IE7IIjp-ejAcuUPD-7QcMs2dLmM,8509
+flo/kv.py,sha256=4Y0PT9XK_AHouRlxFAPWZOtMYpwN6rN8Ny7HwP1Li8o,15755
+flo/kv_body.py,sha256=k-Xeq_9LjqyuXCdqo7I65RfDyBJKc0SROHc887AS2YE,19073
+flo/kv_txn.py,sha256=MkEoONiZz092IbFPHNScxEl_Ltr2TIwHwczche4lx9c,8399
+flo/processing.py,sha256=jN8PhUahsTdYleNptMovE7kE9WLLrOqUu6UVbzULjns,8536
+flo/queue.py,sha256=BoYekudiTAxB6PLpEft1j1sdW4A6rGB8A_MZZ15qjlw,8483
+flo/retry.py,sha256=L8dawQa2qaOKbKm4WBGmo9ERs3krARTOZJ2u9OHUhV4,4479
+flo/streams.py,sha256=RIdZIyww-1FXjJpDNfw_sBhjXjgScqt1EZEsXmE6TXc,17444
+flo/types.py,sha256=LqsVbcWrhPp7FzE8LURwIy2LBQem9hIMhr6SgZ8f_gg,33469
+flo/wire.py,sha256=zkBWTkFIdjuXFJ76RtecKe_69CKi5IDqvulvtg_p-JQ,33550
+flo/worker.py,sha256=uboWk9bWsVrcnrRcTJgPaEQNc_EThYEeFqTUtnl_-90,56330
+flo/workflows.py,sha256=8Z5mhq2UOAnjV_Ef261mcWlj4Z5yGCwrFbxjey0ICoU,15050
+flo_python-0.1.2.dist-info/METADATA,sha256=4DsaVXkbzi5QweSmnYZ_rn9rJVdNPRERRfJp3MPm_1s,19611
+flo_python-0.1.2.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+flo_python-0.1.2.dist-info/licenses/LICENSE,sha256=ti77D_daMo24gEINF1J7388qriJ5r5GjuJUo0b0k27o,11344
+flo_python-0.1.2.dist-info/RECORD,,

{flo_python-0.1.0.dev4.dist-info → flo_python-0.1.2.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.29.0
+Generator: hatchling 1.32.4
 Root-Is-Purelib: true
 Tag: py3-none-any