Welcome to anysocks’ documentation!

anysocks is an easy and simple WebSocket client library built on top of anyio. Hence, you can freely choose between asyncio, trio, and curio backends and integrate it easily into existing applications regardless of the asynchronous I/O framework they use.

Get started

anysocks requires Python 3.5+.

Generally speaking, it is best to use the latest versions of both, anysocks and Python. Due to bug-fixes and new features, anysocks may run more stable and is more intuitive for you to use.

Installation

There are multiple ways of installing anysocks:

# The latest release from PyPI
pip install anysocks

# The cutting edge development version from GitHub:
pip install git+https://github.com/clamor-py/anysocks@master#egg=anysocks

Basic example

Here’s a simple example on connecting to an echo server:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
import anyio
from anysocks import open_connection


async def main():
    async with open_connection('ws://echo.websocket.org') as con:
        print('Connection established!')

        # First, let's send some text to the server.
        text = input('What to send? ')
        await con.send(text)

        # Now, we receive and verify the server's response.
        message = await con.get_message()
        assert message == text, "Received {}, expected {}".format(message, text)

    print('Connection closed with code {}'.format(con.close_code.value))

anyio.run(main)

Logging

If you’re having issues with your program and don’t understand what anysocks is doing, enable logging for verbose output.

import logging

logger = logging.getLogger('anysocks')
logger.setLevel(logging.DEBUG)
logger.addHandler(logging.StreamHandler())

The log contains:

  • Sending and receiving frames (DEBUG, WARNING for unknown frame types)

  • Event dispatch handling (DEBUG)

  • Connection openings and closures (INFO)

Limitations

anysocks currently has a few limitations users have to deal with.

  • There may be more than one connection to a given IP address in a CONNECTING state.

  • The client doesn’t support connecting through a proxy.

  • You cannot fragment outgoing messages. They are always sent in a single frame.

  • Currently no support for WebSocket servers.

  • anysocks limits how many bytes can be received (4kB). One would have to patch the RECEIVE_BYTES constant in anysocks.websocket.

API Reference

A comprehensive documentation of anysocks’ public API.

Meta information

anysocks has some variables containing meta information about the project itself.

anysocks.__author__

The author of the library.

anysocks.__copyright__

A string holding copyright information.

anysocks.__docformat__

The format of the documentation style.

anysocks.__license__

The license of this project.

anysocks.__title__

The actual project name.

anysocks.__version__

The version of the library, e.g. 0.1.2-alpha0.

Client

The heart of this library. It provides convenience functions to quickly establish a new WebSocket client connection without having to worry about deep logic.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
import anyio
from anysocks import open_connection


async def main():
    async with open_connection('ws://echo.websocket.org') as con:
        print('Connection established!')

        # First, let's send some text to the server.
        text = input('What to send? ')
        await con.send(text)

        # Now, we receive and verify the server's response.
        message = await con.get_message()
        assert message == text, "Received {}, expected {}".format(message, text)

    print('Connection closed with code {}'.format(con.close_code.value))

anyio.run(main)

open_connection

create_websocket

WebSocket

anysocks.websocket wraps around WebSocket connections and provides a comfortable abstractions of the protocol to easily send and receive messages. It however becomes uncomfortable if you want to use this module manually.

WebSocketConnection

Exceptions

Keeping a WebSocket connection alive may lead to issues. These can have various reasons, like network errors or server issues. Fortunately, anysocks.exceptions provides a few useful exception classes that give you information about what is going on.

AnySocksError

HandshakeError

ConnectionRejected

ConnectionClosed

Indices and tables