https://github.com/thatxliner/aioudp
A better API for Python asynchronous UDP
https://github.com/thatxliner/aioudp
async asyncio python python3 udp udp-client udp-server
Last synced: about 2 months ago
JSON representation
A better API for Python asynchronous UDP
- Host: GitHub
- URL: https://github.com/thatxliner/aioudp
- Owner: ThatXliner
- License: gpl-3.0
- Created: 2021-11-19T00:59:49.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2025-01-01T04:39:53.000Z (4 months ago)
- Last Synced: 2025-03-16T23:19:55.138Z (about 2 months ago)
- Topics: async, asyncio, python, python3, udp, udp-client, udp-server
- Language: Python
- Homepage: https://pypi.org/project/aioudp/
- Size: 410 KB
- Stars: 18
- Watchers: 2
- Forks: 3
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.txt
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# AioUDP
> A better API for asynchronous UDP
[](https://python-poetry.org/)
[](https://github.com/psf/black)
[](https://github.com/astral-sh/ruff)
[](https://pycqa.github.io/isort/)
[](http://mypy-lang.org/)
[](https://codecov.io/gh/ThatXliner/aioudp)
[](https://aioudp.readthedocs.io/en/latest/?badge=latest)
[](https://github.com/ThatXliner/aioudp/actions/workflows/ci.yml)
[](https://pypi.org/project/aioudp)
[](https://pypi.org/project/aioudp)
[](#license)
> [!NOTE]
> This repository is *maintained*, but seems stagnant because it is feature-complete. If you find an issue, please [report it](https://github.com/ThatXliner/aioudp/issues?q=sort:updated-desc+is:issue+is:open).
A [websockets](https://websockets.readthedocs.io/en/stable/index.html)-like API for [UDP](https://en.wikipedia.org/wiki/User_Datagram_Protocol)
Here's an example echo server:
```py
import asyncio
import signal
import aioudp
async def main():
async def handler(connection):
async for message in connection:
await connection.send(message)
loop = asyncio.get_running_loop()
stop = loop.create_future()
# Optional. This is for properly exiting the server when Ctrl-C is pressed
# or when the process is killed/terminated
loop.add_signal_handler(signal.SIGTERM, stop.set_result, None)
loop.add_signal_handler(signal.SIGINT, stop.set_result, None)
# Serve the server
async with aioudp.serve("localhost", 9999, handler):
await stop # Serve forever
if __name__ == '__main__':
asyncio.run(main())
```
And a client to connect to the server:
```py
import asyncio
import aioudp
async def main():
async with aioudp.connect("localhost", 9999) as connection:
await connection.send(b"Hello world!")
assert await connection.recv() == b"Hello world!"
if __name__ == '__main__':
asyncio.run(main())
```
## Installation
You can get this project via `pip`
```bash
$ pip install aioudp
```
Or, if you're using [Poetry](https://python-poetry.org)
```bash
$ poetry add aioudp
```
> [!NOTE]
> This library provides no other abstractions over the existing UDP interface in `asyncio` other than the `async`/`await`-based API. This means there is no implicit protocol handled in this library such as [QUIC](https://en.wikipedia.org/wiki/QUIC). You must write your own, or find another library.
## See also
- [AnyIO](https://anyio.readthedocs.io/en/stable/index.html), a broader asynchronous networking and concurrency library for abstracting over any `async` IO implementation. It has a [similar API](https://anyio.readthedocs.io/en/stable/networking.html#working-with-udp-sockets) (which I didn't know about before I wrote this library)
- [WebSockets](https://websockets.readthedocs.io/en/stable/), a library for Python to interact with WebSockets. Its API heavily inspired the design of AioUDP.
- [QUIC](https://en.wikipedia.org/wiki/QUIC), a faster protocol similar to TCP, built on UDP.
- [AioQUIC](https://github.com/aiortc/aioquic), a Python implementation of QUIC.
## License
This project is licensed under the [GNU GPL v3+](https://github.com/ThatXliner/aioudp/blob/main/LICENSE.txt).
In short, this means you can do anything with it (distribute, modify, sell) but if you were to publish your changes, you must make the source code and build instructions readily available.
If you are a company using this project and want an exception, email me at [[email protected]](mailto:[email protected]) and we can discuss.