blpapi.Element¶

class blpapi.Element¶

Represents an item in a message.

An Element can represent:

A single value of any data type supported by the Bloomberg API
An array of values
A sequence or a choice

The value(s) in an Element can be queried in a number of ways. For an Element which represents a single value or an array of values use the getValueAsBool() etc. functions. For an Element which represents a sequence or choice use getElementAsBool() etc. functions. In addition, for choices and sequences, hasElement() and getElement() are useful.

This example shows how to access the value of a scalar element s as a floating point number:

f = s.getValueAsFloat()

Similarly, this example shows how to retrieve the third value in an array element a, as a floating point number:

f = a.getValueAsFloat(2)

Use numValues() to determine the number of values available. For single values, it will return either 0 or 1. For arrays it will return the actual number of values in the array.

To retrieve values from a complex element types (sequences and choices) use the getElementAs...() family of methods. This example shows how to get the value of the element city in the sequence element address:

city = address.getElementAsString("city")

Note

getElementAsXYZ(name) method is a shortcut to getElement(name).getValueAsXYZ().

The value(s) of an Element can be set in a number of ways. For an Element which represents a single value or an array of values use the setValue() or appendValue() functions. For an element which represents a sequence or a choice use the setElement() functions.

This example shows how to set the value of an Element s:

value=5
s.setValue(value)

This example shows how to append a value to an array element a:

value=5
a.appendValue(value)

To set values in a complex element (a sequence or a choice) use the setElement() family of functions. This example shows how to set the value of the element city in the sequence element address to a string:

address.setElement("city", "New York")

Methods which specify an Element name accept name in two forms: Name or a string. Passing Name is more efficient. However, it requires the Name to have been created in the global name table.

The form which takes a string is less efficient but will not cause a new Name to be created in the global name table. Because all valid Element names will have already been placed in the global name table by the API if the supplied string cannot be found in the global name table the appropriate error or exception can be returned.

The API will convert data types as long as there is no loss of precision involved.

Element objects are always created by the API, never directly by the application.

appendElement()¶

Append a new element to this array Element.

Returns: The newly appended element
Return type: Element
Raises: Exception – If this Element is not an array of sequence or choice Elements.

appendValue(value)¶

Append the specified value to this Elements entries at the end.

Parameters: value – Value to append
Raises: Exception – If this Element’s datatype can’t be initialized from the type of the specified value, or if the current size of this Element (numValues()) is equal to the maximum defined by elementDefinition().maxValues().

This method can process the following types of value without conversion:

boolean
integers
float
string
datetypes (datetime.time, datetime.date or datetime.datetime)
Name

Any other value will be converted to a string with str function and then processed in the same way as string value.

datatype()¶

Returns: Basic data type used to represent a value in this Element.
Return type: int

The possible types are enumerated in DataType.

elementDefinition()¶

Returns: Reference to the read-only element definition object that defines the properties of this elements value.
Return type: SchemaElementDefinition

elements()¶

Returns: Iterator over elements contained in this Element.
Raises: UnsupportedOperationException – If this Element is not a sequence.

getChoice()¶

Returns: The selection name of this element as Element.
Return type: Element
Raises: Exception – If datatype() != DataType.CHOICE

getElement(nameOrIndex)¶

Parameters: nameOrIndex (Name or str or int) – Sub-element identifier
Returns: Sub-element identified by nameOrIndex
Return type: Element
Raises: Exception – If nameOrIndex is a string or a Name and hasElement(nameOrIndex) != True, or if nameOrIndex is an integer and nameOrIndex >= numElements(). Also if this Element is neither a sequence nor a choice.

getElementAsBool(name)¶

Parameters: name (Name or str) – Sub-element identifier
Returns: This element’s sub-element with name as a boolean
Return type: bool
Raises: Exception – If name is neither a Name nor a string, or if this Element is neither a sequence nor a choice, or in case it has no sub-element with the specified name, or in case the element’s value can’t be returned as a boolean.

getElementAsDatetime(name)¶

Parameters: name (Name or str) – Sub-element identifier
Returns: This element’s sub-element with name as one of the datetime types
Return type: datetime.time or datetime.date or datetime.datetime
Raises: Exception – If name is neither a Name nor a string, or if this Element is neither a sequence nor a choice, or in case it has no sub-element with the specified name, or in case the element’s value can’t be returned as a datetime.

getElementAsFloat(name)¶

Parameters: name (Name or str) – Sub-element identifier
Returns: This element’s sub-element with name as a float
Return type: float
Raises: Exception – If name is neither a Name nor a string, or if this Element is neither a sequence nor a choice, or in case it has no sub-element with the specified name, or in case the element’s value can’t be returned as a float.

getElementAsInteger(name)¶

Parameters: name (Name or str) – Sub-element identifier
Returns: This element’s sub-element with name as an integer
Return type: int
Raises: Exception – If name is neither a Name nor a string, or if this Element is neither a sequence nor a choice, or in case it has no sub-element with the specified name, or in case the element’s value can’t be returned as an integer.

getElementAsName(name)¶

Parameters: name (Name or str) – Sub-element identifier
Returns: This element’s sub-element with name as a Name
Return type: Name
Raises: Exception – If name is neither a Name nor a string, or if this Element is neither a sequence nor a choice, or in case it has no sub-element with the specified name, or in case the element’s value can’t be returned as a Name.

getElementAsString(name)¶

Parameters: name (Name or str) – Sub-element identifier
Returns: This element’s sub-element with name as a string
Return type: str
Raises: Exception – If name is neither a Name nor a string, or if this Element is neither a sequence nor a choice, or in case it has no sub-element with the specified name, or in case the element’s value can’t be returned as a string.

getElementValue(name)¶

Parameters: name (Name or str) – Sub-element identifier
Returns: This element’s sub-element with name defined by its datatype
Raises: Exception – If name is neither a Name nor a string, or if this Element is neither a sequence nor a choice, or in case it has no sub-element with the specified name.

getValue(index=0)¶

Parameters

index (int) – Index of the value in the element

Returns

indexth entry in the Element defined by this element’s datatype.

Raises

InvalidConversionException – If the data type of this Element is either a sequence or a choice.
IndexOutOfRangeException – If index >= numValues().

getValueAsBool(index=0)¶

Parameters

index (int) – Index of the value in the element

Returns

indexth entry in the Element as a boolean.

Return type

bool

Raises

InvalidConversionException – If the data type of this Element cannot be converted to a boolean.
IndexOutOfRangeException – If index >= numValues().

getValueAsDatetime(index=0)¶

Parameters

index (int) – Index of the value in the element

Returns

indexth entry in the Element as one of the datetime types.

Return type

datetime.time or datetime.date or datetime.datetime

Raises

InvalidConversionException – If the data type of this Element cannot be converted to a datetime.
IndexOutOfRangeException – If index >= numValues().

getValueAsElement(index=0)¶

Parameters

index (int) – Index of the value in the element

Returns

indexth entry in the Element as a Element.

Return type

Element

Raises

InvalidConversionException – If the data type of this Element cannot be converted to an Element.
IndexOutOfRangeException – If index >= numValues().

getValueAsFloat(index=0)¶

Parameters

index (int) – Index of the value in the element

Returns

indexth entry in the Element as a float.

Return type

float

Raises

InvalidConversionException – If the data type of this Element cannot be converted to an float.
IndexOutOfRangeException – If index >= numValues().

getValueAsInteger(index=0)¶

Parameters

index (int) – Index of the value in the element

Returns

indexth entry in the Element as a integer

Return type

int

Raises

InvalidConversionException – If the data type of this Element cannot be converted to an integer.
IndexOutOfRangeException – If index >= numValues().

getValueAsName(index=0)¶

Parameters

index (int) – Index of the value in the element

Returns

indexth entry in the Element as a Name.

Return type

Name

Raises

InvalidConversionException – If the data type of this Element cannot be converted to a Name.
IndexOutOfRangeException – If index >= numValues().

getValueAsString(index=0)¶

Parameters

index (int) – Index of the value in the element

Returns

indexth entry in the Element as a string.

Return type

str

Raises

InvalidConversionException – If the data type of this Element cannot be converted to a string.
IndexOutOfRangeException – If index >= numValues().

hasElement(name, excludeNullElements=False)¶

Parameters

name (Name or str) – Name of the element
excludeNullElements (bool) – Whether to exclude null elements

Returns

True if this Element is a choice or sequence (isComplexType() == True) and it contains an Element with the specified name.

Return type

bool

Raises

Exception – If name is neither a Name nor a string.

isArray()¶

Returns: True if this element is an array.
Return type: bool

This element is an array if elementDefinition().maxValues()>1 or if elementDefinition().maxValues()==UNBOUNDED.

isComplexType()¶

Returns: True if datatype()==DataType.SEQUENCE or datatype()==DataType.CHOICE and False otherwise.
Return type: bool

isNull()¶

Returns: True if this Element has a null value.
Return type: bool

isNullValue(position=0)¶

Parameters: position (int) – Position of the sub-element
Returns: True if the value of the sub-element at the position is a null value.
Return type: bool
Raises: Exception – If position >= numElements().

isReadOnly()¶

Returns: True if this Element cannot be modified.
Return type: bool

isValid()¶

Returns: True if this Element is valid.
Return type: bool

name()¶

Returns: If this Element is part of a sequence or choice Element, then return the Name of this Element within the sequence or choice Element that owns it. If this Element is not part of a sequence Element (that is it is an entire Request or Message) then return the Name of the Request or Message.
Return type: Name

numElements()¶

Returns: Number of elements in this element.
Return type: int

The number of elements is 0 if isComplexType() returns False, and no greater than 1 if the DataType is CHOICE; if the DataType is SEQUENCE this may return any number (including 0).

numValues()¶

Returns: Number of values contained by this element.
Return type: int

The number of values is 0 if isNull() returns True, and no greater than 1 if isComplexType() returns True. The value returned will always be in the range defined by elementDefinition().minValues() and elementDefinition().maxValues().

setChoice(selectionName)¶

Set this Element’s active element to selectionName.

Parameters: selectionName (Name or str) – Name of the element to set the active choice
Returns: The newly active element
Return type: Element
Raises: Exception – If selectionName is neither a Name nor a string, or if this Element is not a choice.

setElement(name, value)¶

Set this Element’s sub-element with ‘name’ to the specified ‘value’.

Parameters

name (Name or str) – Sub-element identifier
value – Value to set the sub-element to

Raises

Exception – If name is neither a Name nor a string, or if this element has no sub-element with the specified name, or if the Element identified by the specified name cannot be initialized from the type of the specified value.

This method can process the following types of value without conversion:

boolean
integers
float
string
datetypes (datetime.time, datetime.date or datetime.datetime)
Name

Any other value will be converted to a string with str function and then processed in the same way as string value.

setValue(value, index=0)¶

Set the specified indexth entry in this Element to the value.

Parameters

index (int) – Index of the sub-element
value – Value to set the sub-element to

Raises

Exception – If this Element’s datatype can’t be initialized with the type of the specified value, or if index >= numValues().

This method can process the following types of value without conversion:

boolean
integers
float
string
datetypes (datetime.time, datetime.date or datetime.datetime)
Name

Any other value will be converted to a string with str function and then processed in the same way as string value.

toString(level=0, spacesPerLevel=4)¶

Format this Element to the string at the specified indentation level.

Parameters

level (int) – Indentation level
spacesPerLevel (int) – Number of spaces per indentation level for this and all nested objects

Returns

This element formatted as a string

Return type

str

If level is negative, suppress indentation of the first line. If spacesPerLevel is negative, format the entire output on one line, suppressing all but the initial indentation (as governed by level).

values()¶

Returns: Iterator over values contained in this Element.

If isComplexType() returns True for this Element, the empty iterator is returned.