blpapi.EventFormatter

class blpapi.EventFormatter(event)

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

Return type:: None

appendMessage(messageType, topic, sequenceNumber=None)

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

Parameters:

messageType – Type of the message
topic – Topic to publish the message under
sequenceNumber – 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.

Note

Please use Name over str where possible for name. Name objects should be initialized once and then reused in order to minimize lookup cost.

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

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

Parameters:

topic – Topic to publish under
correlationId – Specify if recap message added in response to a TOPIC_RECAP message
sequenceNumber – Sequence number of the message
fragmentType – 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) – 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.

Return type:: None

Note

The behavior is undefined unless the Event is currently empty.

Note

For PermissionRequest messages, use the PermissionResponse operation name.

Note

Please use Name over str where possible for operationName. Name objects should be initialized once and then reused in order to minimize lookup cost.

appendValue(value)

Parameters:: value (bool or str or int or float or datetime or Name) – Value to append
Return type:: None

destroy()

Destroy the handle using stored dtor

Return type:: None

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

Return type:: None

Note

Although str, 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.

Note

Although bytes is sub-type of collections.abc.Sequence, fromPy() treats it as a scalar of type bytes and will use it to format scalar Element. Arrays of bytes are not supported.

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

Please use Name over str where possible for MappingType key. Name objects should be initialized once and then reused in order to minimize lookup cost.

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.

Return type:: None

pushElement(name)

Change the level at which this EventFormatter is operating.

Parameters:: name (Name) – 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.

Return type:: None

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.

Note

Please use Name over str where possible for name. Name objects should be initialized once and then reused in order to minimize lookup cost.

setElement(name, value)

Set an element in the Event referenced by this EventFormatter.

Parameters:

name (Name) – Name of the element to set
value (bool or str or bytes 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.

Return type:: None

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.

Note

Please use Name over str where possible for name. Name objects should be initialized once and then reused in order to minimize lookup cost.

setElementNull(name)

Create a null element with the specified name.

Parameters:: name (Name) – Name of the element
Return type:: None

Note

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

Note

Please use Name over str where possible for name. Name objects should be initialized once and then reused in order to minimize lookup cost.