pak.io.connection

Contains io.Connection.

class Connection(*, reader=None, writer=None, ctx)

Bases: ABC

A connection between two Packet sources.

This class models a protocol structure that is relatively common, where there is a stream of incoming Packets that aren’t expected to be any specific type of Packet.

This may not model your protocol structure adequately. This in particular may be the case if you are not able to read and send data asynchronously. In such a case, you should not use this class.

Parameters:

• reader (asyncio.StreamReader or None) – The stream for incoming data.

• writer (asyncio.StreamWriter or None) – The stream for outgoing data.

• ctx (Packet.Context) – The context for incoming and outgoing Packets.

reader

The stream for incoming data.

Type:

asyncio.StreamReader or None

writer

The stream for outgoing data.

Type:

asyncio.StreamWriter or None

ctx

The context for incoming and outgoing Packets.

This should always be passed to Packet operations, such as Packet.unpack() and Packet.pack().

Type:

Packet.Context

Examples

A Connection can be used in an async with statement, like so:

connection = ...

async with connection:
    ...

This will make sure that connection is closed by the end of the of the async with statement.

is_closing()

Gets whether the Connection is closed or in the process of closing.

Returns:

Whether the Connection is closed or in the process of closing.

Return type:

bool

close()

Closes the Connection.

This method should be used along with the wait_closed() method.

async wait_closed()

Waits until the Connection is closed.

create_packet(packet_cls, /, **fields)

Creates a Packet for the Connection.

The ctx attribute is used to create the Packet.

Parameters:

• packet_cls (subclass of Packet) – The Packet to create.

• **fields – The names and corresponding values of the Packet to create.

Returns:

The created Packet.

Return type:

Packet

async read_data(size)

Reads incoming data out of the reader attribute.

Parameters:

size (int) – How many bytes to read.

Returns:

The incoming data.

If EOF is reached on the reader attribute and size bytes cannot be read, then None is returned.

Return type:

bytes or None

abstract async _read_next_packet()

Reads the next incoming Packet.

Note

In your implementation, you do not need to ensure that reading is atomic.

See also

read_data()

Returns:

The next incoming Packet.

If None, then that means that there is no next Packet and that continuously_read_packets() should end. This should be when EOF is reached on the reader attribute, which will be when read_data() returns None.

Return type:

Packet or None

async continuously_read_packets()

Continuously reads and yields all incoming Packets.

Note

This must be iterated over for watch_for_packet() to function.

This will continue to yield Packets until the Connection is closed or EOF is reached.

Warning

This method should not be called twice concurrently.

Doing so may cause data to be read incorrectly.

Yields:

Packet – An incoming Packet.

Examples

connection = ...

async for packet in connection.continuously_read_packets():
    ...

async watch_for_packet(packet_cls)

Watches for a specific type of Packet from the incoming stream of Packets.

Requires continuously_read_packets() to be iterated over.

Parameters:

packet_cls (subclass of Packet) – The type of Packet to watch for.

Returns:

The specified incoming Packet.

Returns None when the Connection is closed or EOF is reached.

Return type:

Packet or None

is_watching_for_packet(packet_cls)

Gets whether a specific type of Packet is being watched for.

See also

watch_for_packet()

Parameters:

packet_cls (subclass of Packet) – The type of Packet to check.

Returns:

Whether packet_cls is being watched for.

Return type:

bool

async write_data(data)

Writes outgoing data to the writer attribute.

Parameters:

data (bytes) – The data to write.

async write_packet(packet_cls, /, **fields)

Writes an outgoing Packet.

This method uses create_packet() to create the Packet to write. It then passes it to write_packet_instance().

If you have an already created Packet you wish to write, then you should use write_packet_instance().

Parameters:

• packet_cls (subclass of Packet) – The type of Packet to write.

• **fields – The names and corresponding values of the Packet to write.

abstract async write_packet_instance(packet)

Writes an outgoing Packet instance.

Warning

In most cases, the write_packet() method should be used instead. This method should only be used if you have a pre-existing Packet instance.

Note

In your implementation, writes should be atomic.

It is thus recommended to only write data in one fell swoop.

See also

write_data()

Parameters:

packet (Packet) – The Packet to write.