blpapi.ProviderSession¶

class blpapi.ProviderSession¶

Bases: blpapi.AbstractSession

This class provides a session that can be used for providing services.

It inherits from AbstractSession. In addition to the AbstractSession functionality a ProviderSession provides the following functions to applications.

A provider can register to provide services using registerService(). Before registering to provide a service the provider must have established its identity. Then the provider can create topics and publish events on topics. It also can get requests from the event queue and send back responses.

After users have registered a service they will start receiving subscription requests (TopicSubscribed message in TOPIC_STATUS) for topics which belong to the service. If the resolver has specified subServiceCode for topics in PermissionResponse, then only providers who have activated the subServiceCode will get the subscription request. Where multiple providers have registered the same service and sub-service code (if any), the provider that registered the highest priority for the sub-service code will receive subscription requests; if multiple providers have registered the same sub-service code with the same priority (or the resolver did not set a sub-service code for the subscription), the subscription request will be routed to one of the providers with the highest service priority.

AUTO_REGISTER_SERVICES = 1¶

DONT_REGISTER_SERVICES = 0¶

__init__(options=None, eventHandler=None, eventDispatcher=None)¶

Constructor.

Parameters

options (SessionOptions) – Options used to construct the sessions
eventHandler (Callable) – Handler for the events generated by this session
eventDispatcher (EventDispatcher) – Dispatcher for the events generated by this session

Raises

InvalidArgumentException – If eventHandler is None and the eventDispatcher is not None

Construct a Session using the optionally specified ‘options’, the optionally specified ‘eventHandler’ and the optionally specified ‘eventDispatcher’.

See SessionOptions for details on what can be specified in the options.

If eventHandler is not None then this Session will operate in asynchronous mode, otherwise the Session will operate in synchronous mode.

If supplied, eventHandler is a callable object that takes two arguments: received event and related session.

If eventDispatcher is None then the Session will create a default EventDispatcher for this Session which will use a single thread for dispatching events. For more control over event dispatching a specific instance of EventDispatcher can be supplied. This can be used to share a single EventDispatcher amongst multiple Session objects.

If an eventDispatcher is supplied which uses more than one thread the Session will ensure that events which should be ordered are passed to callbacks in a correct order. For example, partial response to a request or updates to a single subscription.

Each EventDispatcher uses its own thread or pool of threads so if you want to ensure that a session which receives very large messages and takes a long time to process them does not delay a session that receives small messages and processes each one very quickly then give each one a separate EventDispatcher.

activateSubServiceCodeRange(serviceName, begin, end, priority)¶

Parameters

serviceName (str) – Name of the service
begin (int) – Start of sub-service code range
end (int) – End of sub-service code range
priority (int) – Priority with which to receive subscriptions

Register to receive, with the specified priority, subscriptions for the specified service that the resolver has mapped to a service code between the specified begin and the specified end values, inclusive. Numerically greater values of priority indicate higher priorities.

Note

The behavior of this function is undefined unless service has already been successfully registered, 0 <= begin <= end < (1 << 24), and priority is non-negative.

cancel(correlationId)¶

Cancel correlationId request.

Parameters: correlationId (CorrelationId or [CorrelationId]) – Correlation id associated with the request to cancel

If the specified correlationId identifies a current request then 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.

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

createServiceStatusTopic(service)¶

Create a Service Status Topic which is to be used to provide service status.

Parameters: service (Service) – Service for which to create the topic
Returns: A service status topic
Return type: Topic

On success invoking isValid() on the returned Topic will return False.

createTopics(topicList, resolveMode=0, identity=None)¶

Create the topics in the specified topicList.

Parameters

topicList (TopicList) – List of topics to create
resolveMode (int) – Mode to use for topic resolution
identity (Identity) – Identity to use for authorization

Create the topics in the specified topicList, which must be an object of type TopicList, and update topicList with the results of the creation process. If service needs to be registered, identity should be supplied. Once a call to this function returns, each entry in the topicList will have been updated with a new topic creation status.

Before createTopics() returns one or more RESOLUTION_STATUS events, zero or more SERVICE_STATUS events and one or more TOPIC_STATUS events are generated. If this is an asynchronous ProviderSession then these Events may be processed by the registered eventHandler before createTopics() has returned.

createTopicsAsync(topicList, resolveMode=0, identity=None)¶

Create the topics in the specified topicList.

Parameters

topicList (TopicList) – List of topics to create
resolveMode (int) – Mode to use for topic resolution
identity (Identity) – Identity to use for authorization

Create the topics in the specified topicList, which must be an object of type TopicList, and update topicList with the results of the creation process. If service needs to be registered, identity should be supplied. Once a call to this function returns, each entry in the topicList will have been updated with a new topic creation status.

Before createTopics() returns one or more RESOLUTION_STATUS events, zero or more SERVICE_STATUS events and one or more TOPIC_STATUS events are generated. If this is an asynchronous ProviderSession then these Events may be processed by the registered eventHandler before createTopics() has returned.

deactivateSubServiceCodeRange(serviceName, begin, end)¶

Parameters

serviceName (str) – Name of the service
begin (int) – Start of sub-service code range
end (int) – End of sub-service code range

De-register to receive subscriptions for the specified service that the resolver has mapped to a service code between the specified begin and the specified end values, inclusive.

Note

The behavior of this function is undefined unless service has already been successfully registered and 0 <= begin <= end < (1 << 24).

deleteTopic(topic)¶

Remove one reference from the specified ‘topic’.

Parameters: topic (Topic) – Topic to remove the reference from

If this function has been called the same number of times that topic was created by createTopics, then topic is deleted: a TopicDeleted message is delivered, preceded by TopicUnsubscribed and TopicDeactivated if topic was subscribed.

Note

The behavior of this function is undefined if topic has already been deleted the same number of times that it has been created. Further, the behavior is undefined if a provider attempts to publish a message on a deleted topic.

deleteTopics(topics)¶

Delete each topic in the specified topics container.

Parameters: deleteTopics ([Topic]) – Topics to delete

See deleteTopic() above for additional details.

deregisterService(serviceName)¶

De-register the service, including all registered parts.

Parameters: serviceName (str) – Service to de-register
Returns: False if the service is not registered nor in pending registration, True otherwise.
Return type: bool

The identity in the service registration is reused to verify permissions for deregistration. If the service is in pending registration, cancel the pending registration. If the service is registered, send a deregistration request; generate TOPIC_STATUS events containing a TopicUnsubscribed message for each subscribed topic, a TopicDeactivated message for each active topic and a TopicDeleted for each created topic; generate ~Event.REQUEST_STATUS events containing a RequestFailure message for each pending incoming request; and generate a SERVICE_STATUS event containing a ServiceDeregistered message. All published events on topics created on this service will be ignored after this method returns.

destroy()¶: Destructor.

flushPublishedEvents(timeoutMsecs)¶

Wait at most timeoutMsecs milliseconds for all the published events to be sent through the underlying channel.

Parameters: timeoutMsecs (int) – Timeout threshold in milliseconds
Returns: True if all the published events have been sent, False otherwise
Return type: bool

The method returns either as soon as all the published events have been sent out or when it has waited timeoutMsecs milliseconds. The behavior is undefined unless the specified timeoutMsecs is a non-negative value. When timeoutMsecs is 0, the method checks if all the published events have been sent and returns without waiting.

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

Generate a token to be used for authorization.

Parameters

correlationId (CorrelationId) – Correlation id to be associated with the request
eventQueue (EventQueue) – Event queue on which to receive Events related to this request
authId (str) – The id used for authentication
ipAddress (str) – 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.

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

getTopic(message)¶

Find a previously created Topic based on the message.

Parameters: message (Message) – Message to get the topic from
Returns: The topic the message was published on
Return type: Topic

The message must be one of the following types: TopicCreated, TopicActivated, TopicDeactivated, TopicSubscribed, TopicUnsubscribed, TopicRecap. If the message is not valid then invoking isValid() on the returned Topic will return False.

nextEvent(timeout=0)¶

Parameters: timeout (int) – Timeout threshold in milliseconds
Returns: Next available event for this session
Return type: Event
Raises: InvalidStateException – If invoked on a session created in asynchronous mode

If there is no Event available this will block for up to the specified timeout milliseconds for an Event to arrive. A value of 0 for timeout (the default) indicates nextEvent() should not timeout and will not return until the next Event is available.

If nextEvent() returns due to a timeout it will return an event of type TIMEOUT.

openService(serviceName)¶

Open the service identified by the specified serviceName.

Parameters: serviceName (str) – Name of the service
Returns: service identified by the specified serviceName.
Return type: Service

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

publish(event)¶

Publish the specified event.

Parameters: event (Event) – Event to publish

registerService(uri, identity=None, options=None)¶

Attempt to register the service and block until it is done.

Parameters

uri (str) – Name of the service
identity (Identity) – Identity used to verify permissions to provide the service being registered
options (ServiceRegistrationOptions) – Options used to register the service

Returns

True if the service registered successfully, False otherwise

Return type

bool

Attempt to register the service identified by the specified uri and block until the service is either registered successfully or has failed to be registered. The optionally specified identity is used to verify permissions to provide the service being registered. The optionally specified options is used to specify the group ID and service priority of the service being registered.

The uri must begin with a full qualified service name. That is it must begin with //<namespace>/<service-name>[/]. Any portion of the uri after the service name is ignored.

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

registerServiceAsync(uri, identity=None, correlationId=None, options=None)¶

Begin the process of registering the service immediately.

Parameters

uri (str) – Name of the service
identity (Identity) – Identity used to verify permissions to provide the service being registered
correlationId (CorrelationId) – Correlation id to associate with this operation
options (ServiceRegistrationOptions) – Options used to register the service

Returns

Correlation id associated with events generated by this operation

Return type

CorrelationId

Begin the process of registering the service identified by the specified uri and return immediately. The optionally specified identity is used to verify permissions to provide the service being registered. The optionally specified correlationId is used to track Events generated as a result of this call. The actual correlationId that will identify Events generated as a result of this call is returned. The optionally specified options is used to specify the group ID and service priority of the service being registered.

The uri must begin with a full qualified service name. That is it must begin with //<namespace>/<service-name>[/]. Any portion of the uri after the service name is ignored.

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

resolve(resolutionList, resolveMode=0, identity=None)¶

Resolve the topics in the specified resolutionList.

Parameters

resolutionList (ResolutionList) – List of topics to resolve
resolveMode (int) – Mode to resolve in
identity (Identity) – Identity used for authorization

Resolve the topics in the specified resolutionList, which must be an object of type ResolutionList, and update the resolutionList with the results of the resolution process. If the specified resolveMode is DONT_REGISTER_SERVICES (the default) then all the services referenced in the topics in the resolutionList must already have been registered using registerService(). If resolveMode is AUTO_REGISTER_SERVICES then the specified identity should be supplied and ProviderSession will automatically attempt to register any services reference in the topics in the resolutionList that have not already been registered. Once resolve() returns each entry in the resolutionList will have been updated with a new status.

Before resolve() returns one or more RESOLUTION_STATUS events and, if resolveMode is AUTO_REGISTER_SERVICES, zero or more SERVICE_STATUS events are generated. If this is an asynchronous ProviderSession then these Events may be processed by the registered eventHandler before resolve() has returned.

resolveAsync(resolutionList, resolveMode=0, identity=None)¶

Begin the resolution of the topics in the specified list.

Parameters

resolutionList (ResolutionList) – List of topics to resolve
resolveMode (int) – Mode to resolve in
identity (Identity) – Identity used for authorization

Begin the resolution of the topics in the specified resolutionList, which must be an object of type ResolutionList. If the specified resolveMode is DONT_REGISTER_SERVICES (the default) then all the services referenced in the topics in the resolutionList must already have been registered using registerService(). If resolveMode is AUTO_REGISTER_SERVICES then the specified identity should be supplied and ProviderSession will automatically attempt to register any services reference in the topics in the resolutionList that have not already been registered.

One or more RESOLUTION_STATUS events will be delivered with the results of the resolution. These events may be generated before or after resolveAsync() returns. If AUTO_REGISTER_SERVICES is specified SERVICE_STATUS events may also be generated before or after resolveAsync() returns.

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

Send the specified authorizationRequest.

Parameters

request (Request) – Authorization request to send
identity (Identity) – Identity to update with the results
correlationId (CorrelationId) – Correlation id to associate with the request
eventQueue (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.

sendResponse(event, isPartialResponse=False)¶

Send the response event for previously received request.

Parameters

event (Event) – Response event to send
isPartialResponse (bool) – Whether the response is partial or not

start()¶

Start this Session in synchronous mode.

Returns: True if the Session started successfully, False otherwise.
Return type: bool

Attempt to start this Session and block until the Session has started or failed to start. Before start() returns a SESSION_STATUS Event is generated. A Session may only be started once.

startAsync()¶

Start this Session in asynchronous mode.

Returns: True if the process to start a Session began successfully, False otherwise.
Return type: bool

Attempt to begin the process to start this Session. The application must monitor events for a SESSION_STATUS Event which will be generated once the Session has started or if it fails to start. The SESSION_STATUS Event may be processed by the registered eventHandler before startAsync() has returned. A Session may only be started once.

stop()¶

Stop operation of this Session and wait until it stops.

Returns: True if the Session stopped successfully, False otherwise.
Return type: bool

Stop operation of this Session and block until all callbacks to eventHandler objects relating to this Session which are currently in progress have completed (including the callback to handle the SESSION_STATUS Event this call generates). Once this returns no further callbacks to eventHandlers will occur. If stop() is called from within an eventHandler callback it is silently converted to a stopAsync() in order to prevent deadlock. Once a Session has been stopped it can only be destroyed.

stopAsync()¶

Begin the process to stop this Session and return immediately.

Returns: True if the process to stop a Session began successfully, False otherwise.
Return type: bool

The application must monitor events for a SESSION_STATUS Event which will be generated once the Session has been stopped. After this SESSION_STATUS Event no further callbacks to eventHandlers will occur. Once a Session has been stopped it can only be destroyed.

terminateSubscriptionsOnTopic(topic, message=None)¶

Delete the specified topic (See deleteTopic() for additional details).

Parameters

topic (Topic) – Topic to delete
message (Message) – Message to convey additional information to subscribers regarding the termination

Furthermore, proactively terminate all current subscriptions on topic. The optionally specified message can be used to convey additional information to subscribers regarding the termination. This message is contained in the description of reason in a SubscriptionTerminated message.

terminateSubscriptionsOnTopics(topics, message=None)¶

Terminate subscriptions on the specified topics.

Parameters

topics ([Topic]) – Topics to delete
message (Message) – Message to convey additional information to subscribers regarding the termination

See terminateSubscriptionsOnTopic() for additional details.

tryNextEvent()¶

Returns: Next available event for this session
Return type: Event

If there are Events available for the session, return the next Event If there is no event available for the Session, return None. This method never blocks.