pe.app

Packet Engine Application

Application layer that sits on top of the Packet Engine Client and provides a higher level abstraction over the low level packet engine interface. Included is higher level connection handling and monitoring support.

Exceptions

NotConnectedError

Raised when an attempt is made to operate on the Packet Engine before

Classes

Application

Top level application object for interacting with the Packet Engine.

Module Contents

exception pe.app.NotConnectedError

Bases: Exception

Raised when an attempt is made to operate on the Packet Engine before connecting to the server or after disconnecting from it.

class pe.app.Application

Top level application object for interacting with the Packet Engine.

This is the focal point for clients using the high-level API to interact with the packet engine. Most client applications should use an instance of this class to interact with the packet engine, rather than using the low-level API directly.

start(host, port)

Start the packet engine client, connecting to the specified server.

Exceptions raised by a failed attempt to connect to the server are not translated, and are allowed to propagate to the client, hence the exceptions documented here.

Parameters:

host (str) – Host on which PE server is running.
port (int) – Port to connect to on PE server.

Raises:

socket.gaierror – if the server name cannot be resolved. The most common cause is an incorrect host name.
ConnectionRefusedError – if the server refuses the attempt to connect. The most common cause is an incorrect port number.

stop(): Stop the packet engine client, and disconnect from the server.

property connected_to_server

Determine whether or not the client is currently connected to the PE

server. Readonly.

Returns:: True if currently connected; False otherwise.
Return type:: bool

property version_info

Retrieve the currently cached version information. The version

information is cached automatically when first connecting to the

server. Readonly.

Returns:: Major and minor version information.
Return type:: tuple(int, int)

get_port_info()

Retrieve the currently cached port information. The port information is cached automatically when first connecting to the server.

Returns:: List of available ports.
Return type:: list[str]

get_port_caps(port)

Retrieve the currently cached port capabilities for the specified port. The port capabilities are cached automatically when first connecting to the server.

Parameters:: port (int) – Port for which capabilities are to be retrieved.
Returns:: Capabilities for the specified port.
Return type:: PortCaps

property engine

Retrieve the current packet engine instance. This can be used to

interact with the server using the lower level API. Readonly.

Returns:: Packet engine instance.
Return type:: PacketEngine

send_unproto(port, call_from, call_to, data, via=None)

Send an unproto (UI) message to the specified port. The message may be specified either as a UTF-8 string or as a byte sequence. To send to a destination via one or more intermediaries, specify a list of those intermediaries.

Parameters:

port (int) – Port to which the unproto message is to be sent.
call_from (str) – Callsign of sender.
call_to (str) – Callsign of destination, or list of destinations separated by spaces.
data (str or bytes or bytearray) – The message to be sent.
via (list(str) or None) – List of intermediary destinations. Optional.

Raises:

NotConnectedError – if not yet connected to the server.
ValueError – if the data is of an invalid type.

register_callsigns(calls)

Register one or more callsigns for use with the server. This must be called before the callsign is used to initiate a connection. Registration is not complete until the corresponding response is received from the server.

Parameters:: callsign (str or list[str]) – Callsign(s) to register.

is_callsign_registered(call)

Determine whether or not the specified callsign has already been registered.

Parameters:: callsign (str) – Callsign to be checked.
Returns:: True if the callsign has been registed; False otherwise.
Return type:: bool

open_connection(port, call_from, call_to, via=None)

Open a new connected mode session with the specified station. The Connection instance returned will actually be an instance of the defined subclass.

Parameters:

port (int) – Port to use for new connection.
call_from (str) – Source for new connection.
call_to (str) – Destination for new connection.
via (list(str) or None) – List of intermediary destinations. Optional.

Returns:

A new connection instance.

Return type:

Connection

Raises:

NotConnectedError – if not yet connected to the server.

use_monitor(monitor)

Set the Monitor instance to use, when monitoring is enabled. If this is not set, enabling monitoring will have no effect.

Parameters:: monitor (Monitor) – The monitor instance to use.

property enable_monitoring

Determine or set the current state of monitoring. Setting this property

enables or disables monitoring; setting it to its current state is

a no-op.

Type:: bool

property enable_debug_output

Determine or set the current state of debugging output for receive

handlers. When debug output is enabled, each response received from

the server will be logged at the debug level.

Type:: bool

use_custom_handler(handler)

Set an application-specific receive handler. The handler will be added at the end of the chain created by the Application object. This method must be called before calling start().

Parameters:: handler (ReceiveHandler) – The custom receive handler.