Asynchronous IPyC Reference

The following outlines the async clients and their methods for async IPyC use.

Note

This module uses the Python logging module to log diagnostic and errors in an output independent way. If the logging module is not configured, these logs will not be output anywhere. See Setting Up Logging for more information on how to set up and use the logging module with IPyC.

Async IPyC Host

class ipyc.AsyncIPyCHost(ip_address: str = 'localhost', port: int = 9999, loop=None)

Represents an abstracted async socket listener that connects with and listens to AsyncIPyCClient clients. A number of options can be passed to the AsyncIPyCHost.

Parameters

  • ip_address (Optional[str]) – The IP address start listening on. This defaults to localhost.

  • port (Optional[int]) – The port the listener binds to. This defaults to 9999. Check your system to make sure this port is not used by another service. To use multiple AsyncIPyCHost hosts, ensure the ports are different between instantiations.

  • loop (Optional[asyncio.AbstractEventLoop]) – The asyncio.AbstractEventLoop to use for asynchronous operations. Defaults to None, in which case the default event loop is used via asyncio.get_event_loop().

loop

The event loop that the client uses for asynchronous events.

Type

asyncio.AbstractEventLoop

add_connection_handler(coro)

Wrapped decorator for the on_connect() method.

Parameters

coro (coroutine) – The coroutine handler to be called when a new connection is made to the listener

Raises

TypeError – The coroutine passed is not actually a coroutine or does not contain enough arguments.

async close()

This function is a coroutine.

Closes all AsyncIPyCLink connections and stops the internal listener.

property connections

Returns the set of all active AsyncIPyCLink connections the host is handling.

Type

set

is_closed()

bool: Indicates if the underlying socket listener is closed or no longer listening.

on_connect(coro)

A decorator that registers a coroutine to execute when a connection is made to the listener.

The decorated function must be a coroutine and possess one parameter for the AsyncIPyCLink connection link that is supplied on connection; if not, a TypeError is raised.

Parameters

coro (coroutine) – The coroutine handler to be called when a new connection is made to the listener

Example

host = AsyncIPyCHost()

@host.on_connect
async def connectionMade(link: AsyncIPyCLink):
    print('A connection was made!')
Raises

TypeError – The coroutine passed is not actually a coroutine or does not contain enough arguments.

remove_connection_handler(coro)

Removes a connection handler from the internal listener dispatcher.

Parameters

coro (coroutine) – The coroutine handler to be removed.

run(*args)

A blocking call that begins server listening and abstracts away the asyncio event loop initialisation and handling.

If you want more control over the event loop then this function should not be used. Use the start() coroutine instead.

Any arguments supplied is directly passed to the start() coroutine. See it’s documentation for use.

Warning

This function must be the last function to call due to the fact that it is blocking. That means that anything being called after this function or executed will not happen until this host closes or terminates.

async start(*args)

This function is a coroutine.

A shorthand coroutine for asyncio.start_server(). Any arguments supplied are passed to asyncio.start_server() and afterward to asyncio.loop.create_server(). See the asyncio documentation for these arguments and their use.

Async IPyC Client

class ipyc.AsyncIPyCClient(ip_address: str = 'localhost', port: int = 9999, loop=None)

Represents an abstracted async socket client that connects to and communicates with AsyncIPyCHost hosts. A number of options can be passed to the AsyncIPyCClient.

Parameters
loop

The event loop that the client uses for asynchronous events.

Type

asyncio.AbstractEventLoop

async close()

This function is a coroutine.

Closes the AsyncIPyCLink connection and stops the client connection.

async connect(*args) → ipyc.links.AsyncIPyCLink

This function is a coroutine.

A shorthand coroutine for asyncio.open_connection(). Any arguments supplied are directly passed to this method; See the asyncio documentation for these arguments and their use.

Returns

The connection that has been established with a AsyncIPyCHost.

Return type

AsyncIPyCLink

property connections

Returns the set of all active AsyncIPyCLink connections the client is handling. The number of connections is always either one or none.

Type

set