Python Client Library
Overview
A Python client library for interacting with the Virtufin.Api Gateway service via gRPC.
Installation
From Gitea PyPI Registry
Set up authentication with a Gitea personal access token (scope: read:packages):
export PIP_USERNAME=<your-gitea-username>
export PIP_PASSWORD=<your-gitea-token>
pip install virtufin-api \
--index-url https://pypi.haenerconsulting.com/api/packages/virtufin/pypi/simple/ \
--extra-index-url https://pypi.org/simple
From Local Source
export PYTHONPATH=/path/to/virtufin-api/src/python
Or install the package. The client requires the generated protobuf stubs in the same directory:
import sys
sys.path.insert(0, '/path/to/virtufin-api/src/python')
from virtufin.api.client import ApiClient
Quick Start
Async Client (Required)
import asyncio
from virtufin.api.client import ApiClient
async def main():
async with ApiClient(host="localhost", grpc_port=5002) as client:
services = await client.list_services_async()
print(f"Services: {services}")
asyncio.run(main())
Note: This library is async-only. All methods return coroutines and must be awaited.
ApiClient
Async-only client using grpc.aio channels.
Constructor
client = ApiClient(host="localhost", grpc_port=5002)
| Parameter | Type | Default | Description |
|---|---|---|---|
| host | str | "localhost" | gRPC server hostname |
| grpc_port | int | 5002 | Native gRPC server port |
Async Context Manager
async with ApiClient() as client:
services = await client.list_services_async()
# Channel automatically closed on exit
Properties
client.gateway # GatewayClient for service invocation
client.state # StateClient (the state methods below are shortcuts to it)
client.pubsub # PubsubClient for publish/subscribe
client.trigger # TriggerClient for cron triggers
client.config # ConfigClient for the service registry
Methods (all async)
await client.list_services_async()
await client.list_methods_async(service)
await client.get_method_schema_async(service, method, type=None) # type: "input" (default) or "output"
await client.invoke_async(service, method, request_data)
await client.save_state_async(service, key, value, etag=None)
await client.get_state_async(service, key)
await client.get_bulk_state_async(service, keys)
await client.query_state_async(service, query, limit=0)
await client.delete_state_async(service, key)
await client.delete_bulk_state_async(service, keys)
await client.close()
Example: List Services
async with ApiClient() as client:
services = await client.list_services_async()
print(services)
Example: State Management
async with ApiClient() as client:
# Save state
result = await client.save_state_async("workmanager", "mykey", "myvalue")
print(f"Saved: {result['success']}")
# Get state
state = await client.get_state_async("workmanager", "mykey")
print(f"Value: {state['value']}, Etag: {state['etag']}")
# Get several keys in one round trip
items = await client.get_bulk_state_async("workmanager", ["key1", "key2"])
print(f"Bulk state: {items}")
Example: Subscribe to Events
from virtufin.api.client import ApiClient
async def main():
async with ApiClient() as client:
# Errors and cancellation surface as exceptions from the loop.
async for event in client.pubsub.subscribe_async_iter(topics=["sys.api.state.saved"]):
print(f"Event: {event.topic}")
asyncio.run(main())
PubsubClient
High-level pub/sub operations via client.pubsub. All methods are async.
Methods
# Publish async — returns {"success": bool, "status": str, "message": str}
await client.pubsub.publish_async(topic, cloudevent)
# Subscribe - returns async generator yielding PubsubEvent
async for event in client.pubsub.subscribe_async_iter(topic):
print(f"Received: {event.topic} - {event.data_as_text()}")
# Request-reply: publish and await correlated response
result = await client.pubsub.publish_with_result_async(
topic="requests",
cloudevent=cloudevent,
reply_topic="responses",
timeout=10.0,
)
print(f"Response: {result.data_as_json()}")
# Topics seen at the gateway, sorted: [{"topic", "last_published", "last_subscribed"}]
topics = await client.pubsub.list_topics_async()
# Several events in one call: {"success", "published", "failed_indexes", ...}
result = await client.pubsub.publish_events_async([("topic-a", ce1), ("topic-b", ce2)])
# To unsubscribe, cancel (break out of) the async iteration.
Parameters for publish_with_result_async:
- topic — Topic to publish the request to
- cloudevent — The CloudEvent message (cloudevents_pb2.CloudEvent)
- reply_topic — Topic to listen for the correlated response on
- timeout — Maximum wait time in seconds (default: 30.0)
- correlation_id — Optional correlation ID (auto-generated UUID if omitted)
Returns: The matching PubsubEvent with a correlationid matching the request.
Raises: TimeoutError if no response arrives within the timeout.
Note on broadcast semantics: Pubsub.Subscribe is a per-API-process broadcast subscription — multiple in-process callers on the same topic all receive every message (per the Pub/Sub Topics spec §Subscription Implementation Pattern). If you want a single in-process handler to receive each message, use pubsub.subscribe_async_with_handler (it manages one subscription per topic). If you want multiple in-process handlers each receiving every message, just call pubsub.subscribe_async(topic) multiple times.
Resource usage: publish_with_result_async shares one persistent gRPC Subscribe stream per reply topic across all callers (started lazily on first use, reconnecting with backoff if it drops) and demuxes responses by correlationid. The underlying Dapr subscription is created once and stays warm; per-call cost is one pending future. Readers are cancelled by ApiClient.close() (or leaving the async with block).
PubsubEvent
event.topic # Topic name
event.data # Raw bytes
event.data_as_text() # Decode as UTF-8 string
event.data_as_json() # Decode as JSON object
event.cloudevent # The CloudEvent proto (cloudevents_pb2.CloudEvent): type, source, ...
event.message_id # Unique message ID
event.metadata # CloudEvent attributes (e.g. event.metadata["time"])
Example: Pub/Sub
from virtufin.api import cloudevents_pb2
import uuid
from datetime import datetime, timezone
async with ApiClient() as client:
topic = "my-topic"
# Subscribe
async def collect():
async for event in client.pubsub.subscribe_async_iter(topic):
print(f"Received: {event.data_as_text()}")
sub_task = asyncio.create_task(collect())
# Publish events
for i in range(5):
cloudevent = cloudevents_pb2.CloudEvent(
id=str(uuid.uuid4()),
source="urn:my-app",
type="my-event",
data=cloudevents_pb2.CloudEvent.CloudEventData(
text_data=f"Message {i}"
),
)
await client.pubsub.publish_async(topic, cloudevent)
await asyncio.sleep(1)
sub_task.cancel()
try:
await sub_task
except asyncio.CancelledError:
pass
Example: Request-Reply
from virtufin.api import cloudevents_pb2
import uuid
async with ApiClient() as client:
request_topic = "worker-commands"
reply_topic = "worker-responses"
cloudevent = cloudevents_pb2.CloudEvent(
id=str(uuid.uuid4()),
source="urn:my-app",
type="my-command",
data=cloudevents_pb2.CloudEvent.CloudEventData(
text_data='{"command": "status"}'
),
)
# Publish a command and wait for the correlated response
response = await client.pubsub.publish_with_result_async(
topic=request_topic,
cloudevent=cloudevent,
reply_topic=reply_topic,
timeout=10.0,
)
print(f"Got response: {response.data_as_json()}")
GatewayClient
Low-level gateway operations via client.gateway. All methods are async.
Dynamic Service Access
The client.gateway.<service> accessor returns a proxy that resolves method
names dynamically to Gateway.InvokeJson calls. Any RPC on any backend
service (workmanager, custom services) can be invoked
this way without importing the backend's proto or generated stub.
async with ApiClient() as client:
services = await client.list_services_async()
print(f"Available services: {services}")
Dynamic Dispatch Examples
WorkManager
async with ApiClient() as client:
workmanager = client.gateway.workmanager
# ListWorkers — no request fields; returns {"workers": [...]}
workers = await workmanager.ListWorkers()
for w in workers["workers"]:
print(f" {w['id']}: {w['status']} ({w['language']})")
# CreateWorker — CodeSource oneof (url | content), mime_type, topic, group
create_result = await workmanager.CreateWorker({
"code_source": {"url": "https://example.com/worker.py"},
"mime_type": "text/x-python",
"topic": "worker-commands",
})
worker_id = create_result["id"]
# StartWorker — id field
await workmanager.StartWorker({"id": worker_id})
A WebSocket connection (WebSocketFeed worker)
A WebSocket connection is a WebSocketFeed worker
of the WorkManager: create and start it, talk to it with InvokeWorkerCommand
(serve, send, publish, unpublish, status), remove it with DeleteWorker; a feed serving market topics takes its topics and topicitems from a market-data-devkit venue preset (feeds.config, or feeds.resolve/feeds.apply in Python).
import base64, json
async with ApiClient() as client:
workmanager = client.gateway.workmanager
# CreateWorker — the feed package, its config (url, publishtopic, ...)
feed = await workmanager.CreateWorker({
"code_source": {"url": "<Virtufin.Worker.WebSocketFeed .nupkg URL>"},
"mime_type": "application/x-dotnet-dll",
"topics": ["wrk.websocketfeed.command.{worker_id}"],
"config": {"url": "wss://stream.example.com/feed", "autoreload": "false",
"publishtopic": "x.examples.feed"},
"tags": {"name": "example-feed"},
})
feed_id = feed["id"]
await workmanager.StartWorker({"id": feed_id})
# InvokeWorkerCommand — payload is bytes (base64 in JSON); returns {"outputs": [...]}
await workmanager.InvokeWorkerCommand({
"id": feed_id,
"command": "send",
"payload": base64.b64encode(json.dumps({"op": "ping"}).encode()).decode(),
})
status = await workmanager.InvokeWorkerCommand({"id": feed_id, "command": "status"})
# DeleteWorker — closes the socket
await workmanager.DeleteWorker({"id": feed_id})
Note: Service clients are async — they return coroutines that must be awaited.
The Gateway.InvokeJson RPC serializes the request dict to JSON, the backend
service unmarshals it to the typed proto request, runs the RPC, and marshals
the typed proto response back to JSON. See the
proto-to-client-mapping spec
§Layer 4 (Dynamic dispatch) for the full call chain.
Error Handling
import grpc
async with ApiClient() as client:
try:
result = await client.invoke_async("unknown-service", "UnknownMethod", {})
except grpc.RpcError as e:
print(f"gRPC error {e.code()}: {e.details()}")
except ValueError as e:
print(f"Gateway error: {e}")
Dependencies
pip install grpcio grpcio-reflection protobuf
Generated protobuf stubs must be in the same directory:
- gateway_pb2.py
- gateway_pb2_grpc.py
- state_pb2.py
- state_pb2_grpc.py
- pubsub_pb2.py
- pubsub_pb2_grpc.py
Generate with:
python scripts/create_client.py --output src/python
Thread Safety
The client is not thread-safe. Use separate instances for concurrent access:
# Not recommended - share across threads
client = ApiClient()
# Recommended - separate instance per thread/task
async def handle_request():
async with ApiClient() as client:
return await client.list_services_async()