Skip to main content

A Python 3 asyncio datagram library

Project description

jetblack-datagram

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

Status

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

Overview

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(('0.0.0.0', 8000))

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

server.close()
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(('127.0.0.1', 8000))

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

client.close()
await client.wait_closed()

Installation

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(('127.0.0.1', 9999))

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

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

    print("Done")

if __name__ == '__main__':
    asyncio.run(main())

To create an echo client:

import asyncio

from jetblack_datagram import open_udp_connection


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

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

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


if __name__ == '__main__':
    asyncio.run(main())

Usage

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.

Common

The following methods are common for both clients and servers.

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

Server

The following methods are specific to the server.

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

Client

The following methods are specific to the client.

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

Helpers

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

Uploaded Source

Built Distribution

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

Uploaded Python 3

File details

Details for the file jetblack-datagram-0.4.1.tar.gz.

File metadata

  • Download URL: jetblack-datagram-0.4.1.tar.gz
  • Upload date:
  • Size: 8.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.1.1 CPython/3.8.5 Linux/5.6.0-1031-oem

File hashes

Hashes for jetblack-datagram-0.4.1.tar.gz
Algorithm Hash digest
SHA256 30af74180e77c8fc311ded02150d8fa766d14ece7e8fad96dd348eaabbd77c18
MD5 16f010f0d927e59d61a8fb345f0a771e
BLAKE2b-256 242021e760ba808339ef5a407b8e1c7d09ebc8132eb038eeaef0c126e3fcac20

See more details on using hashes here.

File details

Details for the file jetblack_datagram-0.4.1-py3-none-any.whl.

File metadata

  • Download URL: jetblack_datagram-0.4.1-py3-none-any.whl
  • Upload date:
  • Size: 8.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.1.1 CPython/3.8.5 Linux/5.6.0-1031-oem

File hashes

Hashes for jetblack_datagram-0.4.1-py3-none-any.whl
Algorithm Hash digest
SHA256 ed3f90645db983c6cf790337392a045a847ad68f60e631bf6f898dd19be40cef
MD5 af64ca7ed51cdce0a0f4ac55662b732f
BLAKE2b-256 e21548ed01f3338b7af229521aa11a7c085398bac58c2f26ca738d49020765cd

See more details on using hashes here.

Supported by

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