Skip to main content

WebSocket library for Trio

Project description

Trio WebSocket

This library implements both server and client aspects of the the WebSocket protocol, striving for safety, correctness, and ergonomics. It is based on the wsproto project, which is a Sans-IO state machine that implements the majority of the WebSocket protocol, including framing, codecs, and events. This library handles I/O using the Trio framework. This library passes the Autobahn Test Suite.

This README contains a brief introduction to the project. Full documentation is available here.

PyPI Python Versions Build Status Read the Docs Join chatroom

Status

This project is on life-support maintenance. If you're interested in helping to maintain and contribute, please reach out on Gitter or contribute in issues and pull requests.

Alternatives

If you happen to only need a server, using Quart via the quart-trio extension may suffice. While trio-websocket is more flexible, Quart covers both HTTP and WebSocket within a single framework, and serving both from the same port is straightforward. There has yet to be a performance comparison.

Installation

This library requires Python 3.8 or greater. To install from PyPI:

pip install trio-websocket

Client Example

This example demonstrates how to open a WebSocket URL:

import trio
from sys import stderr
from trio_websocket import open_websocket_url


async def main():
    try:
        async with open_websocket_url('wss://echo.websocket.org') as ws:
            await ws.send_message('hello world!')
            message = await ws.get_message()
            print('Received message: %s' % message)
    except OSError as ose:
        print('Connection attempt failed: %s' % ose, file=stderr)

trio.run(main)

The WebSocket context manager connects automatically before entering the block and disconnects automatically before exiting the block. The full API offers a lot of flexibility and additional options.

Server Example

A WebSocket server requires a bind address, a port, and a coroutine to handle incoming connections. This example demonstrates an "echo server" that replies to each incoming message with an identical outgoing message.

import trio
from trio_websocket import serve_websocket, ConnectionClosed

async def echo_server(request):
    ws = await request.accept()
    while True:
        try:
            message = await ws.get_message()
            await ws.send_message(message)
        except ConnectionClosed:
            break

async def main():
    await serve_websocket(echo_server, '127.0.0.1', 8000, ssl_context=None)

trio.run(main)

The server's handler echo_server(…) receives a connection request object. This object can be used to inspect the client's request and modify the handshake, then it can be exchanged for an actual WebSocket object ws. Again, the full API offers a lot of flexibility and additional options.

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

trio_websocket-0.12.2.tar.gz (33.5 kB view details)

Uploaded Source

Built Distribution

trio_websocket-0.12.2-py3-none-any.whl (21.2 kB view details)

Uploaded Python 3

File details

Details for the file trio_websocket-0.12.2.tar.gz.

File metadata

  • Download URL: trio_websocket-0.12.2.tar.gz
  • Upload date:
  • Size: 33.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.8.18

File hashes

Hashes for trio_websocket-0.12.2.tar.gz
Algorithm Hash digest
SHA256 22c72c436f3d1e264d0910a3951934798dcc5b00ae56fc4ee079d46c7cf20fae
MD5 d46fc1eddcd2b3bcb704d4cba65ad663
BLAKE2b-256 d13c8b4358e81f2f2cfe71b66a267f023a91db20a817b9425dd964873796980a

See more details on using hashes here.

File details

Details for the file trio_websocket-0.12.2-py3-none-any.whl.

File metadata

File hashes

Hashes for trio_websocket-0.12.2-py3-none-any.whl
Algorithm Hash digest
SHA256 df605665f1db533f4a386c94525870851096a223adcb97f72a07e8b4beba45b6
MD5 2fe4cc5012f888de9e5895ee270a0bb3
BLAKE2b-256 c719eb640a397bba49ba49ef9dbe2e7e5c04202ba045b6ce2ec36e9cadc51e04

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