Skip to main content

A Python 3 asyncio datagram library

Project description


A Python 3.8+ asyncio helper library for UDP datagram clients and servers.


This is working, but still under continuous development, so there may be breaking changes.


This package provides a simple asyncio API for UDP datagrams, following a similar pattern to the TCP streams API.

A UDP server is started by calling start_udp_server which is analogous to the start_server function provided by asyncio. This returns a DatagramServer, which provides methods for reading (read), writing (sendto), and closing (close and wait_closed). This differs from the TCP variant which provides a callback when a client connects with a read and write stream. This is because UDP is connection-less so there is no connect (or disconnect) event. Also the data is sent and received in packets, so there seems to eb no benefit to provide separate read and write stream.

The following creates a server, reads then writes some data.

server = await start_udp_server(('', 8000))

data, addr = await server.recvfrom()
print(f"Received {data} from {addr}")
server.sendto(b"Hello", addr)

await server.wait_closed()

A UDP client is started by calling open_udp_connection which is analogous to the open_connection function provided by the asyncio library for TCP, which returns a DatagramClient. This provides similar functionality to the server, however the addr is not present when reading or writing, as the socket is bound to the server address when it is created.

client = await open_udp_connection(('', 8000))

client.send(b"Hello, World!")
data = await client.recv()
print(f"Received {data}")

await client.wait_closed()


Install using pip.

pip install jetblack-datagram

Getting Started

To create an echo server:

import asyncio

from jetblack_datagram import start_udp_server

async def main():
    server = await start_udp_server(('', 9999))

    count = 0
    while count < 5:
        count += 1
        data, addr = await server.recvfrom()
        print(f"Received {data!r} from {addr}")
        print(f"Send {data!r} to {addr}")
        server.sendto(data, addr)

    print("Waiting for server to close")
    await server.wait_closed()


if __name__ == '__main__':

To create an echo client:

import asyncio

from jetblack_datagram import open_udp_connection

async def main():
    client = await open_udp_connection(('', 9999))

    print("Sending data")
    client.send(b"Hello, World!")
    print("reading data")
    data = await client.recv()
    print(f"Received {data!r}")

    print("closing client")
    print("waiting for client to close")
    await client.wait_closed()

if __name__ == '__main__':


The UDP protocol is connection-less, so unlike TCP it makes no sense to provide a reader for each server connection, or to provide a callback for connections.


The following methods are common for both clients and servers.

  • close() -> None
  • async wait_closed() -> None


The following methods are specific to the server.

  • sendto(data: bytes, addr: Union[Address, str]) -> None
  • async recvfrom() -> Tuple[bytes, Address]


The following methods are specific to the client.

  • send(data: bytes) -> None
  • async recv() -> bytes


There is a helper to create the server and the client.

For the server:

async def start_udp_server(
        addr: Address,
        loop: Optional[AbstractEventLoop] = None,
        maxreadqueue: int = 0
) -> DatagramServer:

For the client:

async def open_udp_connection(
        addr: Address,
        loop: Optional[AbstractEventLoop] = None,
        maxreadqueue: int = 0
) -> DatagramClient:

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

jetblack-datagram-0.4.1.tar.gz (8.7 kB view hashes)

Uploaded Source

Built Distribution

jetblack_datagram-0.4.1-py3-none-any.whl (8.7 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page