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()¶

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

authenticationOptions()¶

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

autoRestartOnDisconnection()¶

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

bandwidthSaveModeDisabled()¶

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

clientMode()¶

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

connectTimeout()¶

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

defaultKeepAliveInactivityTime()¶

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

defaultKeepAliveResponseTimeout()¶

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

defaultServices()¶

Returns: All default services in one string.
Return type: str

defaultSubscriptionService()¶

Returns: The default subscription service.
Return type: str

defaultTopicPrefix()¶

Returns: The default topic prefix.
Return type: str

destroy()¶: Destroy this SessionOptions.

flushPublishedEventsTimeout()¶

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

getServerAddress(index)¶

Returns: Server name and port indexed by index.
Return type: (str, int)

keepAliveEnabled()¶

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

maxEventQueueSize()¶

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

maxPendingRequests()¶

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

numServerAddresses()¶

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

numStartAttempts()¶

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

recordSubscriptionDataReceiveTimes()¶

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

removeServerAddress(index)¶

Remove the server address at the specified index.

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

serverAddresses()¶

Returns: Iterator over server addresses for this SessionOptions.

serverHost()¶

Returns

The server host option in this SessionOptions: instance.

Return type

str

serverPort()¶

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

serviceCheckTimeout()¶

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

serviceDownloadTimeout()¶

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

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.

setAuthenticationOptions(authOptions)¶

Set the specified authOptions as the authentication options.

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

setAutoRestartOnDisconnection(autoRestart)¶

Set whether automatically restarting connection if disconnected.

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

setBandwidthSaveModeDisabled(isDisabled)¶

Specify whether to disable bandwidth saving measures.

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

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.

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.

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.

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.

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 ([str]) – The default services

DEPRECATED

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

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.

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/.

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.

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.

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.

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.

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.

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.

setServerAddress(serverHost, serverPort, index)¶

Set the server address at the specified index.

Parameters

serverHost (str) – Server host
serverPort (int) – Server port
index (int) – Index to set the address at

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

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.

setServerPort(serverPort)¶

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

Parameters: serverPort (int) – Server port

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

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.

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.

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 (AuthOptions) – the authorization options to use for the session identity.
correlationId (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().

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().

setTlsOptions(tlsOptions)¶

Set the TLS options

Parameters: tlsOptions (TlsOptions) – The TLS options

slowConsumerWarningHiWaterMark()¶

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

slowConsumerWarningLoWaterMark()¶

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

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

Returns

This object formatted as a string

Return type

str

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).