pyroh

A friendly, asyncio-like Python wrapper for iroh.

Pyroh wraps iroh's rust bindings via pyo3 and integrates with asyncio using the standard StreamReader/StreamWriter interface.

Requirements

• Python ≥ 3.14

Installation

pip install pyroh

To build from source:

maturin develop

Quickstart

import asyncio
import pyroh

ALPN = b"myapp/1"

async def handle_connection(conn: pyroh.Connection) -> None:
    reader, writer = await conn.accept_bi()
    data = await reader.read(1024)
    print(f"server got: {data!r}")
    writer.write(b"hello back")
    writer.close()
    await writer.wait_closed()

async def main():
    # Bind a server endpoint. A fresh keypair is generated automatically.
    server = await pyroh.Endpoint.bind(alpns=[ALPN])
    async with server:
        srv = server.start_server(handle_connection)

        # Bind a client endpoint and connect by full address or ticket.
        # By default, this hangs until the endpoint is online.
        # You can disable this behavior by doing
        # `endpoint = await pyroh.Endpoint.bind(wait_online=False)`
        # and then awaiting `endpoint.wait_online()` later
        client = await pyroh.Endpoint.bind(alpns=[ALPN])
        async with client:
            conn = await client.connect(server.ticket, alpn=ALPN)
            async with conn:
                reader, writer = await conn.open_bi()
                writer.write(b"hello")
                writer.close()
                response = await reader.read(1024)
                print(f"client got: {response!r}")

        srv.close()

asyncio.run(main())

You can view more examples in the examples folder

API

pyroh.Endpoint

The main entry point. Represents a local QUIC endpoint.

endpoint = await pyroh.Endpoint.bind(
    alpns=[b"myapp/1"],  # ALPNs to accept; default is [b"pyroh/1"]
    key=None,            # 32-byte secret key, or None to generate a fresh one
    wait_online=True,    # if False, return immediately and call wait_online() manually
)

Properties

Methods

pyroh.EndpointAddr

Represents full dial information (node ID + optional relay/direct addresses).

Class methods

pyroh.Connection

A QUIC connection to a remote peer. Connections multiplex streams — open as many as you need without the overhead of new connections.

Methods

pyroh.Server

Returned by endpoint.start_server(handler). Accepts connections in a background task.