Module proton :: Class Data
[frames] | no frames]

Class Data

source code

The Data class provides an interface for decoding, extracting, creating, and encoding arbitrary AMQP data. A Data object contains a tree of AMQP values. Leaf nodes in this tree correspond to scalars in the AMQP type system such as ints or strings. Non-leaf nodes in this tree correspond to compound values in the AMQP type system such as lists, maps, arrays, or described values. The root node of the tree is the Data object itself and can have an arbitrary number of children.

A Data object maintains the notion of the current sibling node and a current parent node. Siblings are ordered within their parent. Values are accessed and/or added by using the next, prev, enter, and exit methods to navigate to the desired location in the tree and using the supplied variety of put_*/get_* methods to access or add a value of the desired type.

The put_* methods will always add a value after the current node in the tree. If the current node has a next sibling the put_* method will overwrite the value on this node. If there is no current node or the current node has no next sibling then one will be added. The put_* methods always set the added/modified node to the current node. The get_* methods read the value of the current node and do not change which node is current.

The following types of scalar values are supported:

The following types of compound values are supported:

Instance Methods
 
__init__(self, capacity=16) source code
 
__del__(self) source code
 
clear(self)
Clears the data object.
source code
 
rewind(self)
Clears current node and sets the parent to the root node.
source code
 
next(self)
Advances the current node to its next sibling and returns its type.
source code
 
prev(self)
Advances the current node to its previous sibling and returns its type.
source code
 
enter(self)
Sets the parent node to the current node and clears the current node.
source code
 
exit(self)
Sets the current node to the parent node and the parent node to its own parent.
source code
 
lookup(self, name) source code
 
narrow(self) source code
 
widen(self) source code
 
type(self)
Returns the type of the current node.
source code
 
encode(self)
Returns a representation of the data encoded in AMQP format.
source code
 
decode(self, encoded)
Decodes the first value from supplied AMQP data and returns the number of bytes consumed.
source code
 
put_list(self)
Puts a list value.
source code
 
put_map(self)
Puts a map value.
source code
 
put_array(self, described, element_type)
Puts an array value.
source code
 
put_described(self)
Puts a described value.
source code
 
put_null(self)
Puts a null value.
source code
 
put_bool(self, b)
Puts a boolean value.
source code
 
put_ubyte(self, ub)
Puts an unsigned byte value.
source code
 
put_byte(self, b)
Puts a signed byte value.
source code
 
put_ushort(self, us)
Puts an unsigned short value.
source code
 
put_short(self, s)
Puts a signed short value.
source code
 
put_uint(self, ui)
Puts an unsigned int value.
source code
 
put_int(self, i)
Puts a signed int value.
source code
 
put_char(self, c)
Puts a char value.
source code
 
put_ulong(self, ul)
Puts an unsigned long value.
source code
 
put_long(self, l)
Puts a signed long value.
source code
 
put_timestamp(self, t)
Puts a timestamp value.
source code
 
put_float(self, f)
Puts a float value.
source code
 
put_double(self, d)
Puts a double value.
source code
 
put_decimal32(self, d)
Puts a decimal32 value.
source code
 
put_decimal64(self, d)
Puts a decimal64 value.
source code
 
put_decimal128(self, d)
Puts a decimal128 value.
source code
 
put_uuid(self, u)
Puts a UUID value.
source code
 
put_binary(self, b)
Puts a binary value.
source code
 
put_string(self, s)
Puts a unicode value.
source code
 
put_symbol(self, s)
Puts a symbolic value.
source code
 
get_list(self)
If the current node is a list, return the number of elements, otherwise return zero.
source code
 
get_map(self)
If the current node is a map, return the number of child elements, otherwise return zero.
source code
 
get_array(self)
If the current node is an array, return a tuple of the element count, a boolean indicating whether the array is described, and the type of each element, otherwise return (0, False, None).
source code
 
is_described(self)
Checks if the current node is a described value.
source code
 
is_null(self)
Checks if the current node is a null.
source code
 
get_bool(self)
If the current node is a boolean, returns its value, returns False otherwise.
source code
 
get_ubyte(self)
If the current node is an unsigned byte, returns its value, returns 0 otherwise.
source code
 
get_byte(self)
If the current node is a signed byte, returns its value, returns 0 otherwise.
source code
 
get_ushort(self)
If the current node is an unsigned short, returns its value, returns 0 otherwise.
source code
 
get_short(self)
If the current node is a signed short, returns its value, returns 0 otherwise.
source code
 
get_uint(self)
If the current node is an unsigned int, returns its value, returns 0 otherwise.
source code
 
get_int(self)
If the current node is a signed int, returns its value, returns 0 otherwise.
source code
 
get_char(self)
If the current node is a char, returns its value, returns 0 otherwise.
source code
 
get_ulong(self)
If the current node is an unsigned long, returns its value, returns 0 otherwise.
source code
 
get_long(self)
If the current node is an signed long, returns its value, returns 0 otherwise.
source code
 
get_timestamp(self)
If the current node is a timestamp, returns its value, returns 0 otherwise.
source code
 
get_float(self)
If the current node is a float, returns its value, raises 0 otherwise.
source code
 
get_double(self)
If the current node is a double, returns its value, returns 0 otherwise.
source code
 
get_decimal32(self)
If the current node is a decimal32, returns its value, returns 0 otherwise.
source code
 
get_decimal64(self)
If the current node is a decimal64, returns its value, returns 0 otherwise.
source code
 
get_decimal128(self)
If the current node is a decimal128, returns its value, returns 0 otherwise.
source code
 
get_uuid(self)
If the current node is a UUID, returns its value, returns None otherwise.
source code
 
get_binary(self)
If the current node is binary, returns its value, returns "" otherwise.
source code
 
get_string(self)
If the current node is a string, returns its value, returns "" otherwise.
source code
 
get_symbol(self)
If the current node is a symbol, returns its value, returns "" otherwise.
source code
 
copy(self, src) source code
 
format(self) source code
 
dump(self) source code
 
put_dict(self, d) source code
 
get_dict(self) source code
 
put_sequence(self, s) source code
 
get_sequence(self) source code
 
get_py_described(self) source code
 
put_py_described(self, d) source code
 
get_py_array(self)
If the current node is an array, return an Array object representing the array and its contents.
source code
 
put_py_array(self, a) source code
 
put_object(self, obj) source code
 
get_object(self) source code
Class Methods
 
type_name(type) source code
Class Variables
  NULL = 1
A null value.
  BOOL = 2
A boolean value.
  UBYTE = 3
An unsigned byte value.
  BYTE = 4
A signed byte value.
  USHORT = 5
An unsigned short value.
  SHORT = 6
A short value.
  UINT = 7
An unsigned int value.
  INT = 8
A signed int value.
  CHAR = 9
A character value.
  ULONG = 10
An unsigned long value.
  LONG = 11
A signed long value.
  TIMESTAMP = 12
A timestamp value.
  FLOAT = 13
A float value.
  DOUBLE = 14
A double value.
  DECIMAL32 = 15
A DECIMAL32 value.
  DECIMAL64 = 16
A DECIMAL64 value.
  DECIMAL128 = 17
A DECIMAL128 value.
  UUID = 18
A UUID value.
  BINARY = 19
A binary string.
  STRING = 20
A unicode string.
  SYMBOL = 21
A symbolic string.
  DESCRIBED = 22
A described value.
  ARRAY = 23
An array value.
  LIST = 24
A list value.
  MAP = 25
A map value.
  type_names = {1: 'null', 2: 'bool', 3: 'ubyte', 4: 'byte', 5: ...
  put_mappings = {None.__class__: lambda s, _: s.put_null(), boo...
  get_mappings = {NULL: lambda s: None, BOOL: get_bool, BYTE: ge...
Method Details

rewind(self)

source code 

Clears current node and sets the parent to the root node. Clearing the current node sets it _before_ the first node, calling next() will advance to the first node.

next(self)

source code 

Advances the current node to its next sibling and returns its type. If there is no next sibling the current node remains unchanged and None is returned.

prev(self)

source code 

Advances the current node to its previous sibling and returns its type. If there is no previous sibling the current node remains unchanged and None is returned.

enter(self)

source code 

Sets the parent node to the current node and clears the current node. Clearing the current node sets it _before_ the first child, call next() advances to the first child.

decode(self, encoded)

source code 

Decodes the first value from supplied AMQP data and returns the number of bytes consumed.

Parameters:
  • encoded (binary) - AMQP encoded binary data

put_list(self)

source code 

Puts a list value. Elements may be filled by entering the list node and putting element values.

>>> data = Data()
>>> data.put_list()
>>> data.enter()
>>> data.put_int(1)
>>> data.put_int(2)
>>> data.put_int(3)
>>> data.exit()

put_map(self)

source code 

Puts a map value. Elements may be filled by entering the map node and putting alternating key value pairs.

>>> data = Data()
>>> data.put_map()
>>> data.enter()
>>> data.put_string("key")
>>> data.put_string("value")
>>> data.exit()

put_array(self, described, element_type)

source code 

Puts an array value. Elements may be filled by entering the array node and putting the element values. The values must all be of the specified array element type. If an array is described then the first child value of the array is the descriptor and may be of any type.

>>> data = Data()
>>>
>>> data.put_array(False, Data.INT)
>>> data.enter()
>>> data.put_int(1)
>>> data.put_int(2)
>>> data.put_int(3)
>>> data.exit()
>>>
>>> data.put_array(True, Data.DOUBLE)
>>> data.enter()
>>> data.put_symbol("array-descriptor")
>>> data.put_double(1.1)
>>> data.put_double(1.2)
>>> data.put_double(1.3)
>>> data.exit()
Parameters:
  • described (bool) - specifies whether the array is described
  • element_type (int) - the type of the array elements

put_described(self)

source code 

Puts a described value. A described node has two children, the descriptor and the value. These are specified by entering the node and putting the desired values.

>>> data = Data()
>>> data.put_described()
>>> data.enter()
>>> data.put_symbol("value-descriptor")
>>> data.put_string("the value")
>>> data.exit()

put_bool(self, b)

source code 

Puts a boolean value.

Parameters:
  • b - a boolean value

put_ubyte(self, ub)

source code 

Puts an unsigned byte value.

Parameters:
  • ub - an integral value

put_byte(self, b)

source code 

Puts a signed byte value.

Parameters:
  • b - an integral value

put_ushort(self, us)

source code 

Puts an unsigned short value.

Parameters:
  • us - an integral value.

put_short(self, s)

source code 

Puts a signed short value.

Parameters:
  • s - an integral value

put_uint(self, ui)

source code 

Puts an unsigned int value.

Parameters:
  • ui - an integral value

put_int(self, i)

source code 

Puts a signed int value.

Parameters:
  • i - an integral value

put_char(self, c)

source code 

Puts a char value.

Parameters:
  • c - a single character

put_ulong(self, ul)

source code 

Puts an unsigned long value.

Parameters:
  • ul - an integral value

put_long(self, l)

source code 

Puts a signed long value.

Parameters:
  • l - an integral value

put_timestamp(self, t)

source code 

Puts a timestamp value.

Parameters:
  • t - an integral value

put_float(self, f)

source code 

Puts a float value.

Parameters:
  • f - a floating point value

put_double(self, d)

source code 

Puts a double value.

Parameters:
  • d - a floating point value.

put_decimal32(self, d)

source code 

Puts a decimal32 value.

Parameters:
  • d - a decimal32 value

put_decimal64(self, d)

source code 

Puts a decimal64 value.

Parameters:
  • d - a decimal64 value

put_decimal128(self, d)

source code 

Puts a decimal128 value.

Parameters:
  • d - a decimal128 value

put_uuid(self, u)

source code 

Puts a UUID value.

Parameters:
  • u - a uuid value

put_binary(self, b)

source code 

Puts a binary value.

Parameters:
  • b (binary) - a binary value

put_string(self, s)

source code 

Puts a unicode value.

Parameters:
  • s (unicode) - a unicode value

put_symbol(self, s)

source code 

Puts a symbolic value.

Parameters:
  • s (string) - the symbol name

get_list(self)

source code 

If the current node is a list, return the number of elements, otherwise return zero. List elements can be accessed by entering the list.

>>> count = data.get_list()
>>> data.enter()
>>> for i in range(count):
...   type = data.next()
...   if type == Data.STRING:
...     print data.get_string()
...   elif type == ...:
...     ...
>>> data.exit()

get_map(self)

source code 

If the current node is a map, return the number of child elements, otherwise return zero. Key value pairs can be accessed by entering the map.

>>> count = data.get_map()
>>> data.enter()
>>> for i in range(count/2):
...   type = data.next()
...   if type == Data.STRING:
...     print data.get_string()
...   elif type == ...:
...     ...
>>> data.exit()

get_array(self)

source code 

If the current node is an array, return a tuple of the element count, a boolean indicating whether the array is described, and the type of each element, otherwise return (0, False, None). Array data can be accessed by entering the array.

>>> # read an array of strings with a symbolic descriptor
>>> count, described, type = data.get_array()
>>> data.enter()
>>> data.next()
>>> print "Descriptor:", data.get_symbol()
>>> for i in range(count):
...    data.next()
...    print "Element:", data.get_string()
>>> data.exit()

is_described(self)

source code 

Checks if the current node is a described value. The descriptor and value may be accessed by entering the described value.

>>> # read a symbolically described string
>>> assert data.is_described() # will error if the current node is not described
>>> data.enter()
>>> print data.get_symbol()
>>> print data.get_string()
>>> data.exit()

get_py_array(self)

source code 

If the current node is an array, return an Array object representing the array and its contents. Otherwise return None. This is a convenience wrapper around get_array, enter, etc.


Class Variable Details

type_names

Value:
{1: 'null',
 2: 'bool',
 3: 'ubyte',
 4: 'byte',
 5: 'ushort',
 6: 'short',
 7: 'uint',
 8: 'int',
...

put_mappings

Value:
{None.__class__: lambda s, _: s.put_null(), bool: put_bool, dict: put_\
dict, list: put_sequence, tuple: put_sequence, unicode: put_string, by\
tes: put_binary, symbol: put_symbol, int: put_long, char: put_char, lo\
ng: put_long, ulong: put_ulong, timestamp: put_timestamp, float: put_d\
ouble, uuid.UUID: put_uuid, Described: put_py_described, Array: put_py\
_array}

get_mappings

Value:
{NULL: lambda s: None, BOOL: get_bool, BYTE: get_byte, UBYTE: get_ubyt\
e, SHORT: get_short, USHORT: get_ushort, INT: get_int, UINT: get_uint,\
 CHAR: get_char, LONG: get_long, ULONG: get_ulong, TIMESTAMP: get_time\
stamp, FLOAT: get_float, DOUBLE: get_double, DECIMAL32: get_decimal32,\
 DECIMAL64: get_decimal64, DECIMAL128: get_decimal128, UUID: get_uuid,\
 BINARY: get_binary, STRING: get_string, SYMBOL: get_symbol, DESCRIBED\
: get_py_described, ARRAY: get_py_array, LIST: get_sequence, MAP: get_\
dict}