blpapi.AbstractSession

class blpapi.AbstractSession(handle=None, dtor=None)

A common interface shared between publish and consumer sessions.

This class provides an abstract session which defines shared interface between publish and consumer requests for Bloomberg.

Sessions manage access to services either by requests and responses or subscriptions. A Session can dispatch events and replies in either a synchronous or asynchronous mode. The mode of a Session is determined when it is constructed and cannot be changed subsequently.

A Session is asynchronous if an eventHandler argument is supplied when it is constructed. The nextEvent() method may not be called. All incoming events are delivered to the eventHandler supplied on construction.

If supplied, eventHandler must be a callable object that takes two arguments: received Event and related session.

A Session is synchronous if an eventHandler argument is not supplied when it is constructed. The nextEvent() method must be called to read incoming events.

Several methods in Session take a CorrelationId parameter. The application may choose to supply its own CorrelationId values or allow the Session to create values. If the application supplies its own CorrelationId values it must manage their lifetime such that the same value is not reused for more than one operation at a time. The lifetime of a CorrelationId begins when it is supplied in a method invoked on a Session and ends either when it is explicitly cancelled using cancel() or unsubscribe(), when a RESPONSE Event (not a PARTIAL_RESPONSE) containing it is received or when a SUBSCRIPTION_STATUS Event which indicates that the subscription it refers to has been terminated is received.

When using an asynchronous Session, the application must be aware that because the callbacks are generated from another thread, they may be processed before the call which generates them has returned. For example, the SESSION_STATUS Event generated by a startAsync() may be processed before startAsync() has returned (even though startAsync() itself will not block).

This becomes more significant when Session generated CorrelationIds are in use. For example, if a call to subscribe() which returns a Session generated CorrelationId has not completed before the first Events which contain that CorrelationId arrive the application may not be able to interpret those events correctly. For this reason, it is preferable to use user generated CorrelationIds when using asynchronous Sessions. This issue does not arise when using a synchronous Session as long as the calls to subscribe() etc are made on the same thread as the calls to nextEvent().

cancel(correlationId)

Cancel request(s) with a single correlationId or a list.

Parameters:

correlationId (Union[CorrelationId, Sequence[CorrelationId]]) – Correlation id(s) associated with the request(s) to cancel

For all specified correlationId values that identify an ongoing request cancel that request.

Once this call returns the specified correlationId will not be seen in any subsequent Message obtained from a MessageIterator by calling next(). However, any Message currently pointed to by a MessageIterator when cancel() is called is not affected even if it has the specified correlationId. Also any Message where a reference has been retained by the application may still contain the correlationId. For these reasons, although technically an application is free to re-use correlationId as soon as this method returns it is preferable not to aggressively re-use correlation IDs, particularly with an asynchronous Session.

Return type:

None

createIdentity()

Create an Identity which is valid but has not been authorized.

Returns:

Identity which is valid but has not been authorized

Return type:

Identity

destroy()

Destroy the handle using stored dtor

Return type:

None

generateAuthorizedIdentity(authOptions, correlationId=None)

Generates an authorized Identity with the specified authOptions and correlationId.

Parameters:

  • authOptions – Used to generate the Identity.

  • correlationId – Optional. Will identify the messages associated with the generated Identity.

Returns:

Identifies the aforementioned events and the generated Identity.

Return type:

CorrelationId

If this is an asynchronous session then an Event may be delivered to the registered EventHandler before generateAuthorizedIdentity() has returned.

One or more Event.AUTHORIZATION_STATUS events, zero or more Event.TOKEN_STATUS events, and zero or more Event.SERVICE_STATUS events are generated.

The behavior is undefined if either authOptions or correlationId is None.

generateToken(correlationId=None, eventQueue=None, authId=None, ipAddress=None)

Generate a token to be used for authorization.

Parameters:

  • correlationId – Correlation id to be associated with the request

  • eventQueue – Event queue on which to receive Events related to this request

  • authId – The id used for authentication

  • ipAddress – IP of the machine used for authentication

Returns:

The correlation id used to identify the Events generated as a result of this call

Return type:

CorrelationId

Raises:

InvalidArgumentException – If the authentication options in SessionOptions or the arguments to the function are invalid.

The authId and ipAddress must be provided together and can only be provided if the authentication mode is MANUAL.

getAuthorizedIdentity(correlationId=None)

Returns the authorized Identity associated with correlationId. If correlationId is not given, returns the session identity.

Parameters:

correlationId (Optional[CorrelationId]) – Optional. Associated with an Identity.

Returns:

the Identity associated with correlationId.

Return type:

Identity

Raises:

NotFoundException – If there is no Identity associated with correlationId, if the associated Identity is not authorized, or if correlationId is not given and the session identity is not authorized.

getService(serviceName)

Return a Service object representing the service.

Parameters:

serviceName (str) – Name of the service to retrieve

Returns:

Service identified by the service name

Return type:

Service

Raises:

InvalidStateException – If the service identified by the specified serviceName is not open already

The serviceName must contain a fully qualified service name. That is, it must be of the form //<namespace>/<service-name>.

openService(serviceName)

Open the service identified by the specified serviceName.

Parameters:

serviceName (str) – Name of the service

Return type:

bool

Returns:

True if the service is opened successfully, False otherwise.

Attempt to open the service identified by the specified serviceName and block until the service is either opened successfully or has failed to be opened. Return True if the service is opened successfully and False if the service cannot be successfully opened.

The serviceName must contain a fully qualified service name. That is, it must be of the form //<namespace>/<service-name>.

Before openService() returns a SERVICE_STATUS Event is generated. If this is an asynchronous Session then this Event may be processed by the registered eventHandler before openService() has returned.

openServiceAsync(serviceName, correlationId=None)

Begin the process to open the service and return immediately.

Parameters:

  • serviceName (str) – Name of the service

  • correlationId (Optional[CorrelationId]) – Correlation id to associate with events generated as a result of this call

Returns:

The correlation id used to identify the Events generated as a result of this call

Return type:

CorrelationId

Begin the process to open the service identified by the specified serviceName and return immediately. The optional specified correlationId is used to track Events generated as a result of this call.

The serviceName must contain a fully qualified service name. That is, it must be of the form //<namespace>/<service-name>.

The application must monitor events for a SERVICE_STATUS Event which will be generated once the service has been successfully opened or the opening has failed.

sendAuthorizationRequest(request, identity, correlationId=None, eventQueue=None)

Send the specified authorizationRequest.

Parameters:

  • request – Authorization request to send

  • identity – Identity to update with the results

  • correlationId – Correlation id to associate with the request

  • eventQueue – Event queue on which the events related to this request will arrive

Returns:

The correlation id used to identify the Events generated as a result of this call

Return type:

CorrelationId

Send the specified authorizationRequest and update the specified identity with the results. If the optionally specified correlationId is supplied, it is used; otherwise create a CorrelationId. The actual CorrelationId used is returned. If the optionally specified eventQueue is supplied all Events relating to this Request will arrive on that EventQueue.

The underlying user information must remain valid until the Request has completed successfully or failed.

A successful request will generate zero or more PARTIAL_RESPONSE Messages followed by exactly one RESPONSE Message. Once the final RESPONSE Message has been received the specified identity will have been updated to contain the users entitlement information and the CorrelationId associated with the request may be re-used. If the request fails at any stage a REQUEST_STATUS will be generated, the specified identity will not be modified and the CorrelationId may be re-used.

The identity supplied must have been returned from this Session’s createIdentity() method and must not be the session identity.