Skip to content

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()

SDK Reference