SOUP API Reference

Soup

The SoupBinTCP protocol is a simple, lightweight, and fast protocol that provides reliable, ordered, and error-checked delivery of messages between client and server. It is designed for high-performance market data and order entry applications. The protocol is based on the TCP/IP protocol suite and uses TCP as its transport protocol.

This module provides a SoupBinTCP client implementation that can be used to connect to the SoupBinTCP servers.

Though SoupBinTCP is meant for latency sensitive applications, there are numerous times when the client application is not latency sensitive and would like to talk to the soup server, Say in testing or writing a monitoring tool.

In such cases, the client application can use the SoupBinTCP client provided by this module.

exception nasdaq_protocols.soup.InvalidSoupMessage

Bases: ValueError

Raised when an invalid soup message is received.

class nasdaq_protocols.soup.LoginRejectReason(value)

Bases: Enum

Login Reject Reason sent from server in case of login failure.

classmethod get(reason)

Get the LoginRejectReason enum value from the given reason.

Parameters:

reason (str)

class nasdaq_protocols.soup.SoupMessage

Bases: Serializable[SoupMessage]

Base class for all soup messages.

Given raw bytes use this class to unpack the bytes to the corresponding soup message:

input_bytes = b'Atest      2                   '
len, soup_msg = SoupMessage.from_bytes(input_bytes)
type(soup_msg)
to_bytes()

Pack the soup message to binary format

Returns:

tuple of length and bytes

Return type:

tuple[int, bytes]

classmethod from_bytes(bytes_)

unpacks the bytes to the corresponding soup message

Parameters:

bytes – bytes to unpack

Returns:

tuple of length and soup message

Return type:

tuple[int, Type[SoupMessage]]

class nasdaq_protocols.soup.LoginRequest(user, password, session, sequence)

Bases: SoupMessage

SoupBinTCP Login Request Message.

Parameters:

  • user (str) – Username to login

  • password (str) – Password to login

  • session (str) – Name of the session to join [Default=’’] .

  • sequence (str) – The sequence number. [Default=1]

to_bytes()

Pack the soup message to binary format

Returns:

Return type:

tuple[int, bytes]

class nasdaq_protocols.soup.LoginAccepted(session_id, sequence)

Bases: SoupMessage

SoupBinTCP Login Accepted Message.

Parameters:

  • session_id (str) – Name of the session joined [Default=’’] .

  • sequence (int) – The next sequence number.

to_bytes()

Pack the soup message to binary format :return: bytes

Return type:

tuple[int, bytes]

class nasdaq_protocols.soup.LoginRejected(reason)

Bases: SoupMessage

SoupBinTCP Login Rejected Message.

Parameters:

reason (LoginRejectReason) – Reason for login failure. Refer LoginRejectReason

to_bytes()

Pack the soup message to binary format :return: bytes

Return type:

tuple[int, bytes]

class nasdaq_protocols.soup.SequencedData(data)

Bases: SoupMessage

SoupBinTCP Sequenced Data Message.

Parameters:

data (bytes) – The application payload sent by the server.

to_bytes()

Pack the soup message to binary format :return: bytes

Return type:

tuple[int, bytes]

class nasdaq_protocols.soup.UnSequencedData(data)

Bases: SoupMessage

SoupBinTCP Unsequenced Data Message.

Parameters:

data (bytes) – The application payload to be sent to server.

to_bytes()

Pack the soup message to binary format :return: bytes

Return type:

tuple[int, bytes]

class nasdaq_protocols.soup.Debug(msg)

Bases: SoupMessage

SoupBinTCP Debug Message.

Parameters:

msg (str) – The debug message.

to_bytes()

Pack the soup message to binary format :return: bytes

Return type:

tuple[int, bytes]

class nasdaq_protocols.soup.ClientHeartbeat

Bases: SoupMessage

SoupBinTCP Client Heartbeat Message.

class nasdaq_protocols.soup.ServerHeartbeat

Bases: SoupMessage

SoupBinTCP Server Heartbeat Message.

class nasdaq_protocols.soup.EndOfSession

Bases: SoupMessage

SoupBinTCP End of Session Message.

This message is sent from server to indicate the soup stream is now closed.

class nasdaq_protocols.soup.LogoutRequest

Bases: SoupMessage

SoupBinTCP Logout Request Message.

This message is initiated by the client to sever for graceful session logoff.

class nasdaq_protocols.soup.SoupSessionId(host='nohost', port=0, session_type='norole', user='nouser', session='nosession')

Bases: SessionId

Identifier for a soup session.

Parameters:

  • session_type (str) – The type of the session, either ‘client’ or ‘server’.

  • user (str) – The username.

  • session (str) – The session id.

  • host (str)

  • port (int)

update(msg, transport=None)

Update the session id with the more information as and when it is available.

Parameters:

  • msg (LoginRequest | LoginAccepted) – LoginRequest or LoginAccepted message.

  • transport (Transport | None) – asyncio.Transport object.

Returns:

self

class nasdaq_protocols.soup.SoupSession(on_msg_coro=None, on_close_coro=None, session_id=NOTHING, *, dispatch_on_connect=True, sequence=1, client_heartbeat_interval=10, server_heartbeat_interval=10)

Bases: AsyncSession, ABC

Base class for SoupBinTCP[server, client] session.

Parameters:

  • on_msg_coro (Callable[[Any], Awaitable[None]]) – Coroutine to be called when a message is received.

  • on_close_coro (Callable[[], Coroutine]) – Coroutine to be called when the session is closed.

  • sequence (int) – The sequence number. [Default=1]

  • client_heartbeat_interval (int) – The client heartbeat interval in seconds. [Default=10]

  • server_heartbeat_interval (int) – The server heartbeat interval in seconds. [Default=10]

  • session_id (SoupSessionId) – The session id.

  • dispatch_on_connect (bool)

send_msg(msg)

Send a soup message to the server.

Parameters:

msg (SoupMessage) – SoupMessage object.

Return type:

None

send_debug(text)

Send a debug message to the peer.

Parameters:

text (str) – debug text

Return type:

None

logout()

Logout.

The session is closed after sending the logout request. :return:

Return type:

None

class nasdaq_protocols.soup.SoupClientSession(on_msg_coro=None, on_close_coro=None, session_id=NOTHING, dispatch_on_connect=False, *, sequence=1, client_heartbeat_interval=10, server_heartbeat_interval=10)

Bases: SoupSession

SoupBinTCP client session.

Upon successful connecting to the soup server, the client session is instantiated.

Parameters:

  • on_msg_coro (Callable[[Any], Awaitable[None]])

  • on_close_coro (Callable[[], Coroutine])

  • session_id (SoupSessionId)

  • dispatch_on_connect (bool)

  • sequence (int)

  • client_heartbeat_interval (int)

  • server_heartbeat_interval (int)

async login(msg)

Login to the soup server.

This is supposed to be the first message to be sent to server upon connection successful.

Parameters:

msg (LoginRequest) – LoginRequest message.

Returns:

self

Raises:

ConnectionRefusedError – If the server rejects the login request.

send_unseq_data(data)

Send unsequenced data to the server. :param data: application payload

Parameters:

data (bytes)

class nasdaq_protocols.soup.SoupServerSession(on_close_coro=None, session_id=NOTHING, *, dispatch_on_connect=True, sequence=1, client_heartbeat_interval=10, server_heartbeat_interval=10)

Bases: SoupSession

Base class for all soup server sessions.

Any class that implements a soup server session must inherit from this class. and implement the following methods:

  • on_login

  • on_unsequenced

Parameters:

  • on_close_coro (Callable[[], Coroutine])

  • session_id (SoupSessionId)

  • dispatch_on_connect (bool)

  • sequence (int)

  • client_heartbeat_interval (int)

  • server_heartbeat_interval (int)

abstract async on_login(msg)

Handle the login request from the client.

Parameters:

msg (LoginRequest) – LoginRequest message.

Returns:

LoginAccepted or LoginRejected message.

Return type:

LoginAccepted | LoginRejected

abstract async on_unsequenced(msg)

Handle the unsequenced data from the client.

Parameters:

msg (UnSequencedData) – UnSequencedData message.

Return type:

None

send_seq_msg(data)

Send sequenced data to the client.

Parameters:

data (bytes) – application payload

Return type:

None

end_session()

End the session.

async send_heartbeat()

Send heartbeat to the client.

This is called automatically by the session when the heartbeat interval expires. :meta private:

async nasdaq_protocols.soup.connect_async(remote, user, passwd, session_id='', sequence=1, on_msg_coro=None, on_close_coro=None, session_factory=None, client_heartbeat_interval=10, server_heartbeat_interval=10)

Connect to the SoupBinTCP server and login.

Using :param sequence the client can specify the sequence number of the next message it expects to receive. The server will then send all messages with sequence numbers greater than the specified sequence number.

To connect to the start of the stream, specify sequence=1, which is the default. To connect to the end of the stream, specify sequence=0, new messages will be received. To connect to a specific message, specify the sequence number of the message.

Parameters:

  • remote (tuple[str, int]) – tuple of host and port

  • user (str) – Username to login

  • passwd (str) – Password to login

  • session_id (str) – Name of the session to join [Default=’’] .

  • sequence (int) – The sequence number. [Default=1]

  • on_msg_coro (Callable[[Any], Awaitable[None]] | None) – callback, message from server.

  • on_close_coro (Callable[[], Coroutine] | None) – callback, connection closed .

  • session_factory (Callable[[], SoupClientSession] | None) – Factory to create a SoupClientSession.

  • client_heartbeat_interval (int) – seconds between client heartbeats.

  • server_heartbeat_interval (int) – seconds between server heartbeats.

Returns:

SoupClientSession

Return type:

SoupClientSession

Soup Session

class nasdaq_protocols.soup.session.SoupSessionId(host='nohost', port=0, session_type='norole', user='nouser', session='nosession')

Bases: SessionId

Identifier for a soup session.

Parameters:

  • session_type (str) – The type of the session, either ‘client’ or ‘server’.

  • user (str) – The username.

  • session (str) – The session id.

  • host (str)

  • port (int)

update(msg, transport=None)

Update the session id with the more information as and when it is available.

Parameters:

  • msg (LoginRequest | LoginAccepted) – LoginRequest or LoginAccepted message.

  • transport (Transport | None) – asyncio.Transport object.

Returns:

self

class nasdaq_protocols.soup.session.SoupClientSession(on_msg_coro=None, on_close_coro=None, session_id=NOTHING, dispatch_on_connect=False, *, sequence=1, client_heartbeat_interval=10, server_heartbeat_interval=10)

Bases: SoupSession

SoupBinTCP client session.

Upon successful connecting to the soup server, the client session is instantiated.

Parameters:

  • on_msg_coro (Callable[[Any], Awaitable[None]])

  • on_close_coro (Callable[[], Coroutine])

  • session_id (SoupSessionId)

  • dispatch_on_connect (bool)

  • sequence (int)

  • client_heartbeat_interval (int)

  • server_heartbeat_interval (int)

dispatch_on_connect: bool
async login(msg)

Login to the soup server.

This is supposed to be the first message to be sent to server upon connection successful.

Parameters:

msg (LoginRequest) – LoginRequest message.

Returns:

self

Raises:

ConnectionRefusedError – If the server rejects the login request.

send_unseq_data(data)

Send unsequenced data to the server. :param data: application payload

Parameters:

data (bytes)

SessionType: ClassVar[str] = 'client'
log = <Logger SoupClientSession (WARNING)>
class nasdaq_protocols.soup.session.SoupServerSession(on_close_coro=None, session_id=NOTHING, *, dispatch_on_connect=True, sequence=1, client_heartbeat_interval=10, server_heartbeat_interval=10)

Bases: SoupSession

Base class for all soup server sessions.

Any class that implements a soup server session must inherit from this class. and implement the following methods:

  • on_login

  • on_unsequenced

Parameters:

  • on_close_coro (Callable[[], Coroutine])

  • session_id (SoupSessionId)

  • dispatch_on_connect (bool)

  • sequence (int)

  • client_heartbeat_interval (int)

  • server_heartbeat_interval (int)

abstract async on_login(msg)

Handle the login request from the client.

Parameters:

msg (LoginRequest) – LoginRequest message.

Returns:

LoginAccepted or LoginRejected message.

Return type:

LoginAccepted | LoginRejected

abstract async on_unsequenced(msg)

Handle the unsequenced data from the client.

Parameters:

msg (UnSequencedData) – UnSequencedData message.

Return type:

None

send_seq_msg(data)

Send sequenced data to the client.

Parameters:

data (bytes) – application payload

Return type:

None

end_session()

End the session.

async send_heartbeat()

Send heartbeat to the client.

This is called automatically by the session when the heartbeat interval expires. :meta private:

Soup Messages

nasdaq_protocols.soup.core module contains the implementation of the soup messages.

exception nasdaq_protocols.soup.core.InvalidSoupMessage

Bases: ValueError

Raised when an invalid soup message is received.

class nasdaq_protocols.soup.core.LoginRejectReason(value)

Bases: Enum

Login Reject Reason sent from server in case of login failure.

classmethod get(reason)

Get the LoginRejectReason enum value from the given reason.

Parameters:

reason (str)

class nasdaq_protocols.soup.core.SoupMessage

Bases: Serializable[SoupMessage]

Base class for all soup messages.

Given raw bytes use this class to unpack the bytes to the corresponding soup message:

input_bytes = b'Atest      2                   '
len, soup_msg = SoupMessage.from_bytes(input_bytes)
type(soup_msg)
to_bytes()

Pack the soup message to binary format

Returns:

tuple of length and bytes

Return type:

tuple[int, bytes]

classmethod from_bytes(bytes_)

unpacks the bytes to the corresponding soup message

Parameters:

bytes – bytes to unpack

Returns:

tuple of length and soup message

Return type:

tuple[int, Type[SoupMessage]]

class nasdaq_protocols.soup.core.LoginRequest(user, password, session, sequence)

Bases: SoupMessage

SoupBinTCP Login Request Message.

Parameters:

  • user (str) – Username to login

  • password (str) – Password to login

  • session (str) – Name of the session to join [Default=’’] .

  • sequence (str) – The sequence number. [Default=1]

to_bytes()

Pack the soup message to binary format

Returns:

Return type:

tuple[int, bytes]

class nasdaq_protocols.soup.core.LoginAccepted(session_id, sequence)

Bases: SoupMessage

SoupBinTCP Login Accepted Message.

Parameters:

  • session_id (str) – Name of the session joined [Default=’’] .

  • sequence (int) – The next sequence number.

to_bytes()

Pack the soup message to binary format :return: bytes

Return type:

tuple[int, bytes]

class nasdaq_protocols.soup.core.LoginRejected(reason)

Bases: SoupMessage

SoupBinTCP Login Rejected Message.

Parameters:

reason (LoginRejectReason) – Reason for login failure. Refer LoginRejectReason

to_bytes()

Pack the soup message to binary format :return: bytes

Return type:

tuple[int, bytes]

class nasdaq_protocols.soup.core.SequencedData(data)

Bases: SoupMessage

SoupBinTCP Sequenced Data Message.

Parameters:

data (bytes) – The application payload sent by the server.

to_bytes()

Pack the soup message to binary format :return: bytes

Return type:

tuple[int, bytes]

class nasdaq_protocols.soup.core.UnSequencedData(data)

Bases: SoupMessage

SoupBinTCP Unsequenced Data Message.

Parameters:

data (bytes) – The application payload to be sent to server.

to_bytes()

Pack the soup message to binary format :return: bytes

Return type:

tuple[int, bytes]

class nasdaq_protocols.soup.core.Debug(msg)

Bases: SoupMessage

SoupBinTCP Debug Message.

Parameters:

msg (str) – The debug message.

to_bytes()

Pack the soup message to binary format :return: bytes

Return type:

tuple[int, bytes]

class nasdaq_protocols.soup.core.ClientHeartbeat

Bases: SoupMessage

SoupBinTCP Client Heartbeat Message.

class nasdaq_protocols.soup.core.ServerHeartbeat

Bases: SoupMessage

SoupBinTCP Server Heartbeat Message.

class nasdaq_protocols.soup.core.EndOfSession

Bases: SoupMessage

SoupBinTCP End of Session Message.

This message is sent from server to indicate the soup stream is now closed.

class nasdaq_protocols.soup.core.LogoutRequest

Bases: SoupMessage

SoupBinTCP Logout Request Message.

This message is initiated by the client to sever for graceful session logoff.