blpapi.EventFormatter

class blpapi.EventFormatter

EventFormatter is used to populate Events for publishing.

An EventFormatter is created from an Event obtained from createPublishEvent() on Service. Once the Message or Messages have been appended to the Event using the EventFormatter the Event can be published using publish() on the ProviderSession.

EventFormatter objects cannot be copied to ensure that there is no ambiguity about what happens if two EventFormatters are both formatting the same Event.

The EventFormatter supports appending message of the same type multiple times in the same Event. However the EventFormatter supports write once only to each field. It is an error to call setElement() or pushElement() for the same name more than once at a particular level of the schema when creating a message.

__init__(event)

Create an EventFormatter to create Messages in the specified event.

Parameters

event (Event) – Event to be formatted

An Event may only be referenced by one EventFormatter at any time. Attempting to create a second EventFormatter referencing the same Event will result in an exception being raised.

appendElement()

appendMessage(messageType, topic, sequenceNumber=None)

Append an (empty) message to the Event referenced by this EventFormatter

Parameters

• messageType (Name or str) – Type of the message

• topic (Topic) – Topic to publish the message under

• sequenceNumber (int) – Sequence number of the message

After a message has been appended its elements can be set using the various setElement() methods.

Note

It is expected that sequenceNumber is greater (unless the value wrapped or None is specified) than the last value used in any previous message on this topic, otherwise the behavior is undefined.

appendRecapMessage(topic, correlationId=None, sequenceNumber=None, fragmentType=0)

Append a (empty) recap message to the Event referenced by this EventFormatter.

Parameters

• topic (Topic) – Topic to publish under

• correlationId (CorrelationId) – Specify if recap message added in response to a TOPIC_RECAP message

• sequenceNumber (int) – Sequence number of the message

• fragmentType (int) – Type of the message fragment

Specify the optional correlationId if this recap message is added in response to a TOPIC_RECAP message.

After a message has been appended its elements can be set using the various setElement() methods. It is an error to create append a recap message to an Admin event.

Single-tick recap messages should have fragmentType set to Message.FRAGMENT_NONE. Multi-tick recaps can have either Message.FRAGMENT_START, Message.FRAGMENT_INTERMEDIATE, or Message.FRAGMENT_END as the fragmentType.

Note

It is expected that sequenceNumber is greater (unless the value wrapped or None is specified) than the last value used in any previous message on this topic, otherwise the behavior is undefined.

appendResponse(operationName)

Append an (empty) response message for the specified operationName.

Parameters

operationName (Name or str) – Name of the operation whose response type to use

Append an (empty) response message for the specified operationName (e.g. ReferenceDataRequest) that will be sent in response to the previously received operation request. After a message for this operation has been appended its elements can be set using the setElement() method. Only one response can be appended.

Note

The behavior is undefined unless the Event is currently empty.

Note

For PermissionRequest messages, use the PermissionResponse operation name.

appendValue(value)

Parameters

value (bool or str or int or float or datetime or Name) – Value to append

destroy()

Destroy this EventFormatter object.

popElement()

Undo the most recent call to pushElement() on this EventFormatter.

Undo the most recent call to pushElement() on this EventFormatter and return the context of the EventFormatter to where it was before the call to pushElement(). Once popElement() has been called it is invalid to attempt to re-visit the same context.

pushElement(name)

Change the level at which this EventFormatter is operating.

Parameters

name (Name or str) – Name of the element that is used to determine the level

After this returns the context of the EventFormatter is set to the element name in the schema and any calls to setElement() or pushElement() are applied at that level.

If name represents an array of scalars then appendValue() must be used to add values.

If name represents an array of complex types then appendElement() creates the first entry and sets the context of the EventFormatter to that element.

Calling appendElement() again will create another entry.

If the name is invalid for the current message, if appendMessage() has never been called or if the element identified by name has already been set an exception is raised.

Note

The element name must identify either a choice, a sequence or an array at the current level of the schema or the behavior is undefined.

setElement(name, value)

Set an element in the Event referenced by this EventFormatter.

Parameters

• name (Name or str) – Name of the element to set

• value (bool or str or int or float or datetime or Name) – Value to set the element to

If the name is invalid for the current message, or if appendMessage() has never been called, or if the element identified by name has already been set, an exception will be raised.

Note

Clients wishing to format and publish null values (e.g. for the purpose of cache management) should not use this function; use setElementNull() instead.

setElementNull(name)

Create a null element with the specified name.

Parameters

name (Name or str) – Name of the element

Note

Whether or not fields containing null values are published to subscribers depends on the details of the service and schema configuration.