blpapi.test.MessageFormatter

class blpapi.test.MessageFormatter(handle)

MessageFormatter is used to populate/format a message. It supports writing only once to each field. Attempting to set an already set element will fail.

Note that the behavior is undefined if:

A message is formatted with formatMessageJson() or formatMessageXml() or formatMessageDict() is further formatted.
A message formatted with set*() or append*() is further formatted using formatMessageJson() or formatMessageXml() or formatMessageDict().

Currently, the JSON and XML formatting methods have some known limitations:

The parsers can not differentiate complex field types (sequences, choices, arrays) that are empty with complex field types that are missing / null. These fields are dropped and absent in the message contents.
Enumerations of type “Datetime”, or any “Datetime” element with timezone offset or sub-microsecond precision (e.g. nanoseconds) are not supported.

appendElement()

Create an array blpapi.Element and append it to the blpapi.Element on which this MessageFormatter is operating.

Raises:: Exception – If the schema of the blpapi.Message is flat or the current blpapi.Element to which this new blpapi.Element is being appended is not an array, a sequence or a choice.
Return type:: None

appendValue(value)

Append the specified value to the element on which this MessageFormatter is operating.

Parameters:: value (Union[Name, str, bytes, bool, int, float, datetime, date, time, None]) – The value to append.
Raises:: Exception – If the schema of the message is flat or the current element to which value is appended is not an array.
Return type:: None

destroy()

Destroy the handle using stored dtor

Return type:: None

formatMessageDict(dictMessage)

Format the blpapi.Message from its dict representation.

Parameters:: dictMessage (dict) – A dictionary representing the content used to format the message.
Raises:: Exception – If the method fails to format the blpapi.Message.

The behavior is undefined if further formatting is done using this MessageFormatter.

Return type:: None

formatMessageJson(jsonMessage)

Format the blpapi.Message from its JSON representation.

Parameters:: jsonMessage (str) – A JSON-formatted str representing the content used to format the message.
Raises:: Exception – If the method fails to format the blpapi.Message.

The behavior is undefined if further formatting is done using this MessageFormatter.

Return type:: None

formatMessageXml(xmlMessage)

Format the blpapi.Message from its XML representation.

Parameters:: xmlMessage (str) – An XML-formatted str representing the content used to format the message.
Raises:: Exception – If the method fails to format the blpapi.Message.

The behavior is undefined if further formatting is done using this MessageFormatter.

Return type:: None

popElement()

Undo the most recent call to pushElement() or appendElement() on this MessageFormatter and return the context of the MessageFormatter 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 MessageFormatter is operating to the element specified by name.

After this returns, the context of the MessageFormatter is set to the element specified by name in the schema and any calls to setElement() or meth: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() must be used.

Parameters:: name (Name) – Specifies the blpapi.Element on which to operate. The element must identify either a choice, a sequence or an array at the current level of the schema or the behavior is undefined.
Raises:: Exception – If the name is invalid for the current message or if the element identified by name has already been set.
Return type:: None

Note

Please use blpapi.Name over str where possible for name. blpapi.Name objects should be initialized once and then reused as each blpapi.Name instance refers to an entry in a global static table which grows in an unbounded manner.

setElement(name, value)

Set the element with the specified name to the specified value in the current blpapi.Message referenced by this MessageFormatter.

Parameters:

name (Name) – Identifies the element which will be set to value.
value (Union[Name, str, bytes, bool, int, float, datetime, date, time, None]) – The value to assign to the specified element.

Raises:

Exception – An exception is raised if any of the following are true: - The name is invalid for the current message - The element identified by name has already been set - The value cannot be assigned to the element identified by name

Return type:

None

Note

Please use blpapi.Name over str where possible for name. blpapi.Name objects should be initialized once and then reused as each blpapi.Name instance refers to an entry in a global static table which grows in an unbounded manner.