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 the handle using stored dtor

fromPy(value)

Format this EventFormatter‘s underlying Event using value.

Parameters: value (collections.abc.Mapping) – the object used for formatting
Raises: Exception – if value cannot properly format the Event

The value used to format the Event is always a collections.abc.Mapping instance. The keys are Name or str instances, and the values vary depending on the Element being formatted.

If the Element identified by the key is

a complex type, it is formatted using a collections.abc.Mapping whose keys are the names of its sub-Elements.
an array, it is formatted using a collections.abc.Sequence of the Element’s values (see note below for more details).

Otherwise, the Element is formatted using its associated scalar value (e.g. str or int).

Note

Although str, bytes, bytearray, and memoryview are sub-types of collections.abc.Sequence, fromPy() treats them as scalars of type string and will use them to format scalar Elements. If you wish to format an array Element with instances of the aforementioned types, put them in a different collections.abc.Sequence, like list.

For null Elements:

A null complex Element is formatted using an empty collections.abc.Mapping.
A null scalar Element is formatted using None.
An empty array Element is formatted using an empty collections.abc.Sequence.

Note

The behavior is undefined if fromPy() is used to format an Event that has already been formatted. Further formatting after fromPy() is also undefined.

For example, the following SampleOperation has the following BLPAPI representation:

SampleOperation = {
    complexElement = {
        nullElement = {
        }
    }
    scalarArray[] = {
        "value1", "value2"
    }
    complexArray[] = {
        complexArray = {
            value = 1
            message = "msg"
        }
    }
    valueElement = "value"
    nullValueElement =
}

SampleOperation can be created with the following code:

response = service.createResponseEvent(CorrelationId(0))
ef = EventFormatter(response)
ef.appendResponse("SampleOperation")

ef.pushElement("complexElement")
ef.setElementNull("nullElement")
ef.popElement()
ef.pushElement("scalarArray")
ef.appendValue("value1")
ef.appendValue("value2")
ef.popElement()
ef.pushElement("complexArray")
ef.appendElement()
ef.setElement("value", 1)
ef.setElement("message", "msg")
ef.popElement()
ef.popElement()
ef.setElement("valueElement", "value")
ef.setElementNull("nullValueElement")

fromPy() can be used to format SampleOperation the same way:

response = service.createResponseEvent(CorrelationId(0))
ef = EventFormatter(response)
ef.appendResponse("SampleOperation")
sampleResponseAsDict = {
    "complexElement": {
        "nullElement": {
        }
    },
    "scalarArray": [
        "value1", "value2"
    ],
    "complexArray": [
        {
            "value": 1
            "message": "msg"
        }
    ],
    "valueElement": "value",
    "nullValueElement": None
}
ef.fromPy(sampleResponseAsDict)

popElement(): Undo the most recent call to pushElement() or appendElement() on this EventFormatter and return the context of the EventFormatter to where it was before the call to pushElement() or appendElement(). 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.