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
Built Distribution
Hashes for jetblack_datagram-0.4.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | f8be2f35932d93dfea986f1998b26f97eca94a4fe9ecffba3fae6ac5dccb350b |
|
MD5 | da878c71a2fbe04794bb87d76f25c496 |
|
BLAKE2b-256 | 7a7d657ed6a36b120159753656c0d3235bb8a87c111b2978a2da97687eba8d33 |