IPyC Communication Reference

The following outlines how communication links are established and their 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.

Synchronous IPyC Link

class ipyc.IPyCLink(connection: multiprocessing.connection.Connection, client)

Represents an abstracted synchronous socket connection that handles communication between a IPyCHost and a IPyCClient This class is internally managed and typically should not be instantiated on its own.

Parameters

• connection (multiprocessing.connection.Connection) – The managed socket connection.

• client (Union[IPyCHost, IPyCClient]) – The communication object that is responsible for managing this connection.

close()

Closes the socket channel with a peer and attempts to send them EOF. Informs the parent IPyCHost or IPyCClient of the closed connection.

is_active()

bool: Indicates if the socket connection is closed, at EOF, or no longer viable.

poll(timeout=0.0)

Return whether there is any data available to be read from the downstream connection.

Parameters

timeout (Optional[float]) – The number of seconds to wait to see if data is available. If set to None, poll will block forever until data is ready to be read. If set to 0, return a result immediately. Defaults to 0.0.

Returns

True if data is ready to be received, False otherwise.

Return type

bool

receive(encoding='utf-8', return_on_error=False)

Receive a serializable object from the other end. If the object is not a custom serializable object, python’s builtins will be used, otherwise the custom defined deserializer will be used.

Parameters

• encoding (Optional[str]) – The encoding schema of the serialization. If your object serialization results in non UTF-8 encoding characters, a different encoding scheme must be used. The receiving end must also use this same encoding to decode properly. Defaults to utf-8.

• return_on_error (Optional[bool]) – Whether to continue to listen or return if a deserialization error occurred. Otherwise, wait until the next valid deserialization occurs. Defaults to False.

Returns

The object that was sent from the sending end. If the deserialization was not successful and return_on_error was set to True, or EOF was encountered resulting in a closed connection, None is returned.

Return type

Optional[object]

send(serializable_object: object, encoding='utf-8')

Send a serializable object to the receiving end. If the object is not a custom serializable object, python’s builtins will be used. If the object is a custom serializable, the receiving end must also have this object in their list of custom deserializers.

Warning

After the result of serialization, either via custom or builtin, the bytes 0x01 and 0x02 must not appear anywhere. If your payload does contain these bytes or chars, you must substitute them prior to this function call.

Parameters

• serializable_object (object) – The object to be sent to the receiving end.

• encoding (Optional[str]) – The encoding schema of the serialization. If your object serialization results in non UTF-8 encoding characters, a different encoding scheme must be used. The receiving end must also use this same encoding to decode properly. Defaults to utf-8.

Asynchronous IPyC Link

class ipyc.AsyncIPyCLink(reader: asyncio.streams.StreamReader, writer: asyncio.streams.StreamWriter, client)

Represents an abstracted async socket connection that handles communication between a AsyncIPyCHost and a AsyncIPyCClient This class is internally managed and typically should not be instantiated on its own.

Parameters

• reader (asyncio.StreamReader) – The managed inbound data reader.

• writer (asyncio.StreamWriter) – The managed outbound data writer

• client (Union[AsyncIPyCHost, AsyncIPyCClient]) – The communication object that is responsible for managing this connection.

async close()

This function is a coroutine.

Closes all communication channels with a peer and attempts to send them EOF. Informs the parent AsyncIPyCHost or AsyncIPyCClient of the closed connection.

is_active()

bool: Indicates if the communication channels are closed, at EOF, or no longer viable.

async receive(encoding='utf-8', return_on_error=False)

This function is a coroutine.

Receive a serializable object from the other end. If the object is not a custom serializable object, python’s builtins will be used, otherwise the custom defined deserializer will be used.

Parameters

• encoding (Optional[str]) – The encoding schema of the serialization. If your object serialization results in non UTF-8 encoding characters, a different encoding scheme must be used. The receiving end must also use this same encoding to decode properly. Defaults to utf-8.

• return_on_error (Optional[bool]) – Whether to continue to listen or return if a deserialization error occurred. Otherwise, wait until the next valid deserialization occurs. Defaults to False.

Returns

The object that was sent from the sending end. If the deserialization was not successful and return_on_error was set to True, or EOF was encountered resulting in a closed connection, None is returned.

Return type

Optional[object]

async send(serializable_object: object, drain_immediately=True, encoding='utf-8')

This function is a coroutine.

Send a serializable object to the receiving end. If the object is not a custom serializable object, python’s builtins will be used. If the object is a custom serializable, the receiving end must also have this object in their list of custom deserializers.

Warning

After the result of serialization, either via custom or builtin, the bytes 0x01 and 0x02 must not appear anywhere. If your payload does contain these bytes or chars, you must substitute them prior to this function call.

Parameters

• serializable_object (object) – The object to be sent to the receiving end.

• drain_immediately (Optional[bool]) – Whether to flush the output buffer right now or not. Defaults to True.

• encoding (Optional[str]) – The encoding schema of the serialization. If your object serialization results in non UTF-8 encoding characters, a different encoding scheme must be used. The receiving end must also use this same encoding to decode properly. Defaults to utf-8.