blpapi.SessionOptions

class blpapi.SessionOptions

Options which the user can specify when creating a session.

To use non-default options on a Session, create a SessionOptions instance and set the required options and then supply it when creating a Session.

The class attributes represent the possible options for how to connect to the API.

AUTO = 0: Automatic (desktop if available otherwise server)

DAPI = 1: Always connect to the desktop API

SAPI = 2: Always connect to the server API

__init__(): Create a SessionOptions with all options set to the defaults

allowMultipleCorrelatorsPerMsg()

Return type:: bool
Returns:: The value of the allow multiple correlators per message option.

applicationIdentityKey()

Return type:: str
Returns:: The application identity key (AIK) which uniquely identifies this application for this session.

authenticationOptions()

Return type:: str
Returns:: Authentication options in a string.

autoRestartOnDisconnection()

Return type:: bool
Returns:: Whether automatically restart connection if disconnected.

bandwidthSaveModeDisabled()

Return type:: bool
Returns:: Whether bandwidth saving measures are disabled.

clientMode()

Return type:: int
Returns:: The value of the client mode option.

connectTimeout()

Return type:: int
Returns:: The value of the connection timeout option.

defaultKeepAliveInactivityTime()

Return type:: int
Returns:: The interval (in milliseconds) a connection has to remain inactive (receive no data) before a keep alive probe will be sent.

defaultKeepAliveResponseTimeout()

Return type:: int
Returns:: The time (in milliseconds) the library will wait for response to a keep alive probe before declaring it lost.

defaultServices()

Return type:: str
Returns:: All default services in one string, separated by ;.

defaultSubscriptionService()

Return type:: str
Returns:: The default subscription service.

defaultTopicPrefix()

Return type:: str
Returns:: The default topic prefix.

destroy()

Destroy the handle using stored dtor

Return type:: None

flushPublishedEventsTimeout()

Return type:: int
Returns:: The timeout, in milliseconds, for ProviderSession to flush published events before stopping. The default value is 2000.

getServerAddress(index)

Return type:: Tuple[str, int, Optional[Socks5Config]]
Returns:: Server name, port and optional SOCKS5 proxy configuration indexed by index.

keepAliveEnabled()

Return type:: bool
Returns:: True if the keep-alive mechanism is enabled; otherwise return False.

maxEventQueueSize()

Return type:: int
Returns:: The value of maximum outstanding undelivered events that the session is configured with.

maxPendingRequests()

Return type:: int
Returns:: The value of the maximum pending request option.

numServerAddresses()

Return type:: int
Returns:: The number of server addresses.

numStartAttempts()

Return type:: int
Returns:: The maximum number of attempts to start a session.

recordSubscriptionDataReceiveTimes()

Return type:: bool
Returns:: Whether the receipt time (accessed via Message.timeReceived()) should be recorded for subscription data messages.

removeServerAddress(index)

Remove the server address at the specified index.

Parameters:: index (int) – Index to remove the address at
Return type:: None

serverAddresses()

Return type:: Iterator
Returns:: Iterator over server addresses for this SessionOptions.

serverHost()

Return type:: str
Returns:: The server host option in this SessionOptions instance.

serverPort()

Return type:: int
Returns:: The server port that this session connects to.

serviceCheckTimeout()

Return type:: int
Returns:: The value of the service check timeout option in this SessionOptions instance in milliseconds.

serviceDownloadTimeout()

Return type:: int
Returns:: The value of the service download timeout option in this SessionOptions instance in milliseconds.

setAllowMultipleCorrelatorsPerMsg(allowMultipleCorrelatorsPerMsg)

Associate more than one CorrelationId with a Message.

Parameters:: allowMultipleCorrelatorsPerMsg (bool) – Value to set the option to

Set whether the Session is allowed to associate more than one CorrelationId with a Message to the specified allowMultipleCorrelatorsPerMsg. The default is False. This means that if you have multiple subscriptions which overlap (that is a particular Message is relevant to all of them) you will be presented with the same message multiple times when you use the MessageIterator, each time with a different CorrelationId. If you specify True for this then a Message may be presented with multiple CorrelationId‘s.

Return type:: None

setApplicationIdentityKey(applicationIdentityKey)

Sets the application identity key (AIK) which uniquely identifies: this application for this session.

Parameters:: applicationIdentityKey (str) – The application identity key to set.
Return type:: None

setAuthenticationOptions(authOptions)

Set the specified authOptions as the authentication options.

Parameters:: authOptions (str) – The options used during authentication.
Return type:: None

setAutoRestartOnDisconnection(autoRestart)

Set whether automatically restarting connection if disconnected.

Parameters:: autoRestart (bool) – Whether to automatically restart if disconnected
Return type:: None

setBandwidthSaveModeDisabled(isDisabled)

Specify whether to disable bandwidth saving measures.

Parameters:: isDisabled (bool) – Whether to disable bandwidth saving measures.
Return type:: None

setClientMode(clientMode)

Set how to connect to the API. The default is AUTO.

Parameters:: clientMode (int) – The client mode

Set how to connect to the API. The default is AUTO which will try to connect to the desktop API but fall back to the server API if the desktop is not available. DAPI always connects to the desktop API and will fail if it is not available. SAPI always connects to the server API and will fail if it is not available.

Return type:: None

setConnectTimeout(timeoutMilliSeconds)

Set the connection timeout in milliseconds.

Parameters:: timeoutMilliSeconds (int) – Timeout threshold in milliseconds

Set the connection timeout in milliseconds when connecting to the API. The default is 5000 milliseconds. Behavior is not defined unless the specified timeoutMilliSeconds is in range of [1 .. 120000] milliseconds.

Return type:: None

setDefaultKeepAliveInactivityTime(inactivityMsecs)

Set the amount of time that no traffic can be received before the keep-alive mechanism is triggered.

Parameters:: inactivityMsecs (int) – Amount of time in milliseconds

Set to the specified inactivityMsecs the amount of time that no traffic can be received on a connection before the ping-based keep-alive mechanism is triggered; if no traffic is received for this duration then a keep-alive ping is sent to the remote end to solicit a response. If inactivityMsecs == 0, then no keep-alive pings will be sent. The behavior of this function is undefined unless inactivityMsecs is a non-negative value. The default value is 20,000 milliseconds.

Return type:: None

Note

Not all back-end connections provide ping-based keep-alives; this option is ignored by such connections.

setDefaultKeepAliveResponseTimeout(timeoutMsecs)

Set the timeout for terminating the connection due to inactivity.

Parameters:: timeoutMsecs (int) – Timeout threshold in milliseconds

When a keep-alive ping is sent, wait for the specified timeoutMsecs to receive traffic (of any kind) before terminating the connection due to inactivity. If timeoutMsecs == 0, then connections are never terminated due to the absence of traffic after a keep-alive ping. The behavior of this function is undefined unless timeoutMsecs is a non-negative value. The default value is 5,000 milliseconds.

Return type:: None

Note

that not all back-end connections provide support for ping-based keep-alives; this option is ignored by such connections.

setDefaultServices(defaultServices)

Set the default service for the session.

Parameters:: defaultServices (Sequence[str]) – The default services

DEPRECATED

Set the default service for the session. This function is deprecated; see setDefaultSubscriptionService().

Return type:: None

setDefaultSubscriptionService(defaultSubscriptionService)

Set the default service for subscriptions.

Parameters:: defaultSubscriptionService (str) – Identifier for the service to be used as default

Set the default service for subscriptions which do not specify a subscription server to the specified defaultSubscriptionService. The behavior is undefined unless defaultSubscriptionService matches the regular expression ^//[-_.a-zA-Z0-9]+/[-_.a-zA-Z0-9]+$. The default is //blp/mktdata.

Return type:: None

setDefaultTopicPrefix(prefix)

Set the default topic prefix.

Parameters:: prefix (str) – The topic prefix to set

Set the default topic prefix to be used when a subscription does not specify a prefix to the specified prefix. The default is /ticker/.

Return type:: None

setFlushPublishedEventsTimeout(timeoutMsecs)

Parameters:: timeoutMsecs (int) – Timeout threshold in milliseconds

Set the timeout, in milliseconds, for ProviderSession to flush published events before stopping. The behavior is not defined unless the specified timeoutMsecs is a positive value. The default value is 2000.

Return type:: None

setKeepAliveEnabled(isEnabled)

Set whether to enable keep-alive pings.

Parameters:: isEnabled (bool) – Whether to enable keep-alive pings

If the specified isEnabled is False, then disable all keep-alive mechanisms, both from the client to the server and from the server to the client; otherwise enable keep-alive pings both from the client to the server (as configured by setDefaultKeepAliveInactivityTime() and setDefaultKeepAliveResponseTimeout() if the connection supports ping-based keep-alives), and from the server to the client as specified by the server configuration.

Return type:: None

setMaxEventQueueSize(eventQueueSize)

Set the maximum number of outstanding undelivered events per session.

Parameters:: eventQueueSize (int) – Maximum number of outstanding undelivered events

Set the maximum number of outstanding undelivered events per session to the specified eventQueueSize. All subsequent events delivered over the network will be dropped by the session if the number of outstanding undelivered events is eventQueueSize, the specified threshold. The default value is 10000.

Return type:: None

setMaxPendingRequests(maxPendingRequests)

Set the maximum number of requests which can be pending.

Parameters:: maxPendingRequests (int) – Maximum number of pending requests

Set the maximum number of requests which can be pending to the specified maxPendingRequests. The default is 1024.

Return type:: None

setNumStartAttempts(numStartAttempts)

Set the maximum number of attempts to start a session.

Set the maximum number of attempts to start a session by connecting a server.

Return type:: None

setRecordSubscriptionDataReceiveTimes(shouldRecord)

Parameters:: shouldRecord (bool) – Whether to record the receipt time

Set whether the receipt time (accessed via Message.timeReceived()) should be recorded for subscription data messages. By default, the receipt time for these messages is not recorded.

Return type:: None

setServerAddress(serverHost, serverPort, index, socks5Config=None)

Set the server address at the specified index.

Parameters:

serverHost (str) – Server host
serverPort (int) – Server port. Must be between 1 and 65535
index (int) – Index to set the address at
socks5Config (Optional[Socks5Config]) – Optional. SOCKS5 proxy configuration

Set the server address at the specified index using the specified serverHost and serverPort.

Return type:: None

setServerHost(serverHost)

Set the API server host to connect to when using the server API.

Parameters:: serverHost (str) – Server host

Set the API server host to connect to when using the server API to the specified serverHost. The server host is either a hostname or an IPv4 address (that is, a.b.c.d). The default is 127.0.0.1.

Return type:: None

setServerPort(serverPort)

Set the port to connect to when using the server API.

Parameters:: serverPort (int) – Server port. Must be between 1 and 65535

Set the port to connect to when using the server API to the specified serverPort. The default is 8194.

Return type:: None

setServiceCheckTimeout(timeoutMsecs)

Parameters:: timeoutMsecs (int) – Timeout threshold in milliseconds

Set the timeout, in milliseconds, when opening a service for checking what version of the schema should be downloaded. The behavior is not defined unless timeoutMsecs is a positive value. The default timeout is 60,000 milliseconds.

Return type:: None

setServiceDownloadTimeout(timeoutMsecs)

Parameters:: timeoutMsecs (int) – Timeout threshold in milliseconds

Set the timeout, in milliseconds, when opening a service for downloading the service schema. The behavior is not defined unless the specified timeoutMsecs is a positive value. The default timeout is 120,000 milliseconds.

Return type:: None

setSessionIdentityOptions(authOptions, correlationId=None)

Sets the specified authOptions as the AuthOptions for the session identity, enabling automatic authorization of the session identity during startup.

Parameters:

authOptions (Optional[AuthOptions]) – the authorization options to use for the session identity.
correlationId (Optional[CorrelationId]) – Optional. Used to identify the messages associated with the session identity.

Returns:

The actual CorrelationId that identifies the messages associated with the session identity.

Return type:

CorrelationId

The session identity lifetime is tied to the session’s lifetime, so it is guaranteed that the session identity will remain authorized during the entire duration of the session. The identity will be authorized before the session starts. The session will terminate if the identity fails to authorize or is revoked.

The session identity is used to send requests and make subscriptions if no other identity is provided.

By default the session identity is not authorized.

It is possible to pass None as authOptions, to reset this value to its default state.

setSlowConsumerWarningHiWaterMark(hiWaterMark)

Set the point at which “slow consumer” events will be generated.

Parameters:: hiWaterMark (float) – Fraction of maxEventQueueSize()

Set the point at which “slow consumer” events will be generated, using the specified hiWaterMark as a fraction of maxEventQueueSize(); the default value is 0.75. A warning event will be generated when the number of outstanding undelivered events passes above hiWaterMark * maxEventQueueSize(). The behavior of the function is undefined unless 0.0 < hiWaterMark <= 1.0. Further, at the time that Session.start() is called, it must be the case that slowConsumerWarningLoWaterMark() * maxEventQueueSize() < slowConsumerWarningHiWaterMark() * maxEventQueueSize().

Return type:: None

setSlowConsumerWarningLoWaterMark(loWaterMark)

Set the point at which “slow consumer cleared” events will be generated

Parameters:: loWaterMark (float) – Fraction of maxEventQueueSize()

Set the point at which “slow consumer cleared” events will be generated, using the specified loWaterMark as a fraction of maxEventQueueSize(); the default value is 0.5. A warning cleared event will be generated when the number of outstanding undelivered events drops below loWaterMark * maxEventQueueSize. The behavior of the function is undefined unless 0.0 <= loWaterMark < 1.0. Further, at the time that Session.start() is called, it must be the case that slowConsumerWarningLoWaterMark() * maxEventQueueSize() < slowConsumerWarningHiWaterMark() * maxEventQueueSize().

Return type:: None

setTlsOptions(tlsOptions)

Set the TLS options

Parameters:: tlsOptions (TlsOptions) – The TLS options
Return type:: None

slowConsumerWarningHiWaterMark()

Return type:: float
Returns:: The fraction of maxEventQueueSize() at which “slow consumer” event will be generated.

slowConsumerWarningLoWaterMark()

Return type:: float
Returns:: The fraction of maxEventQueueSize() at which “slow consumer cleared” event will be generated.

toString(level=0, spacesPerLevel=4)

Format this SessionOptions to the string.

Parameters:

level (int) – Indentation level
spacesPerLevel (int) – Number of spaces per indentation level for this and all nested objects

Return type:

str

Returns:

This object formatted as a string

If level is negative, suppress indentation of the first line. If spacesPerLevel is negative, format the entire output on one line, suppressing all but the initial indentation (as governed by level).