aioactioncable: async Action Cable client library

aioactioncable is a python library for building Ruby on Rails Action Cable clients.

The library is based on websockets and asyncio.

aioactioncable is thus an async Rails Action Cable client library.

Installation

$ python3 -m pip install aioactioncable

aioactioncable requires Python 3 and therefore needs to be installed using the Python 3 version of pip.

Requirements

• Python >= 3.7
• websockets

Usage

In addition to managing websockets connections, Action Cable servers manage multiple channels, that clients can subscribe to.

Here is a code example to connect to an Action Cable server, subscribe to a channel and receive messages on that channel:

#!/usr/bin/env python3

import aioactioncable
import asyncio
import json

def process(msg, identifier)
  msg_json = json.loads(msg)
  print(f'Message received on {json.dumps(identifier)}')
  ...

async def ac_recv(uri, identifier):
  async with aioactioncable.connect(uri) as acconnect:
    subscription = await acconnect.subscribe(identifier)
    async for msg in subscription:
      process(msg, identifier)

asyncio.run(ac_recv('wss://example.app', {'channel': 'ChatChannel'}))

All the code examples below must be run in an asyncio event loop. Examples are built "chronologically", object created in Connect section is reused in Subscribe section, and so on.

Connect to an Action Cable server

import aioactioncable

acconnect = aioactioncable.connect(uri)

aioactioncable Connect object is an async context manager, you can thus use it in an async with statement:

import aioactioncable
import asyncio

async with aioactioncable.connect('wss://example.app') as acconnect:
  ...

Subscribe to an Action Cable channel

subscription = await acconnect.subscribe({'channel': 'ChatChannel'})

Recv messages on an Action Cable channel

Receive next message on subscription channel:

msg = await subscription.recv()

Subscription object is an iterable, you can thus iterate over to recv messages in an async for loop:

async for msg in subscription:
  ...

Send messages on an Action Cable channel

await subscription.send({'action': 'create', 'chatRoom': 'climbing'})

Unsubscribe from an Action Cable channel

await subscription.unsubscribe()

Close an Action Cable server connection

Explicit close of the connection is not needed if it is done in an async with statement.

Otherwise:

await acconnect.close()

License

aioactioncable is distributed under the MIT license.

Contributions

Contributions are very welcome!

Feel free to open an issue for any bug report.

Feel free to propose bug fixes or features via a Pull Request.