Package 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:

- NULL
- BOOL
- UBYTE
- USHORT
- SHORT
- UINT
- INT
- ULONG
- LONG
- FLOAT
- DOUBLE
- BINARY
- STRING
- SYMBOL

The following types of compound values are supported:

- DESCRIBED
- ARRAY
- LIST
- MAP

Instance Methods

__del__(self) | source code

__init__(self, capacity=16) | source code

clear(self) Clears the data object. | source code

copy(self, src) | source code

decode(self, encoded) Decodes the first value from supplied AMQP data and returns the number of bytes consumed. | source code

dump(self) | source code

encode(self) Returns a representation of the data encoded in AMQP format. | source code

encoded_size(self) Returns the size in bytes needed to encode the data in AMQP format. | 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

format(self) | 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

get_binary(self) If the current node is binary, returns its value, returns "" otherwise. | source code

get_bool(self) If the current node is a boolean, returns its value, returns False otherwise. | source code

get_byte(self) If the current node is a signed byte, 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_decimal128(self) If the current node is a decimal128, 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_dict(self) | source code

get_double(self) If the current node is a double, 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_int(self) If the current node is a signed int, returns its value, returns 0 otherwise. | source code

get_list(self) If the current node is a list, return the number of elements, otherwise return zero. | source code

get_long(self) If the current node is an signed long, returns its value, returns 0 otherwise. | source code

get_map(self) If the current node is a map, return the number of child elements, otherwise return zero. | source code

get_object(self) | 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

get_py_described(self) | source code

get_sequence(self) | source code

get_short(self) If the current node is a signed short, returns its value, returns 0 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

get_timestamp(self) If the current node is a timestamp, returns its value, returns 0 otherwise. | source code

get_ubyte(self) If the current node is an unsigned byte, 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_ulong(self) If the current node is an unsigned long, 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_uuid(self) If the current node is a UUID, returns its value, returns None otherwise. | 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

lookup(self, name) | source code

narrow(self) | 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

put_array(self, described, element_type) Puts an array value. | source code

put_binary(self, b) Puts a binary value. | source code

put_bool(self, b) Puts a boolean value. | source code

put_byte(self, b) Puts a signed byte value. | source code

put_char(self, c) Puts a char value. | source code

put_decimal128(self, d) Puts a decimal128 value. | source code

put_decimal32(self, d) Puts a decimal32 value. | source code

put_decimal64(self, d) Puts a decimal64 value. | source code

put_described(self) Puts a described value. | source code

put_dict(self, d) | source code

put_double(self, d) Puts a double value. | source code

put_float(self, f) Puts a float value. | source code

put_int(self, i) Puts a signed int value. | source code

put_list(self) Puts a list value. | source code

put_long(self, l) Puts a signed long value. | source code

put_map(self) Puts a map value. | source code

put_null(self) Puts a null value. | source code

put_object(self, obj) | source code

put_py_array(self, a) | source code

put_py_described(self, d) | source code

put_sequence(self, s) | source code

put_short(self, s) Puts a signed short value. | source code

put_string(self, s) Puts a unicode value. | source code

put_symbol(self, s) Puts a symbolic value. | source code

put_timestamp(self, t) Puts a timestamp value. | source code

put_ubyte(self, ub) Puts an unsigned byte value. | source code

put_uint(self, ui) Puts an unsigned int value. | source code

put_ulong(self, ul) Puts an unsigned long value. | source code

put_ushort(self, us) Puts an unsigned short value. | source code

put_uuid(self, u) Puts a UUID value. | source code

rewind(self) Clears current node and sets the parent to the root node. | source code

type(self) Returns the type of the current node. | source code

widen(self) | source code

Class Methods

type_name(type) | source code

Class Variables
| ARRAY = `23`
| BINARY = `19`
| BOOL = `2`
| BYTE = `4`
| CHAR = `9`
| DECIMAL128 = `17`
| DECIMAL32 = `15`
| DECIMAL64 = `16`
| DESCRIBED = `22`
| DOUBLE = `14`
| FLOAT = `13`
| INT = `8`
| LIST = `24`
| LONG = `11`
| MAP = `25`
| NULL = `1`
| SHORT = `6`
| STRING = `20`
| SYMBOL = `21`
| TIMESTAMP = `12`
| UBYTE = `3`
| UINT = `7`
| ULONG = `10`
| USHORT = `5`
| UUID = `18`
| get_mappings = ``{`1`:` <__builtin__.function object>`,` 2`:` <__builti`...``
| put_mappings = ``{`<type 'int'>`:` <__builtin__.function object>`,` <`...``
| type_names = ``{`1`:` `'``null``'``,` 2`:` `'``bool``'``,` 3`:` `'``ubyte``'``,` 4`:` `'``byte``'``,` 5`:` `...``

Method Details

### 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

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

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

### 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_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.

### 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()
    >>> data.next()
    >>> print data.get_symbol()
    >>> data.next()
    >>> print data.get_string()
    >>> data.exit()

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

### 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_binary(self, b)

source code

Puts a binary value.

Parameters:
  - `b` (binary) - a binary value

### put_bool(self, b)

source code

Puts a boolean value.

Parameters:
  - `b` - a boolean value

### put_byte(self, b)

source code

Puts a signed byte value.

Parameters:
  - `b` - an integral value

### put_char(self, c)

source code

Puts a char value.

Parameters:
  - `c` - a single character

### put_decimal128(self, d)

source code

Puts a decimal128 value.

Parameters:
  - `d` - a decimal128 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_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_double(self, d)

source code

Puts a double value.

Parameters:
  - `d` - a floating point value.

### put_float(self, f)

source code

Puts a float value.

Parameters:
  - `f` - a floating point value

### put_int(self, i)

source code

Puts a signed int value.

Parameters:
  - `i` - an integral value

### 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_long(self, l)

source code

Puts a signed long value.

Parameters:
  - `l` - an integral value

### 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_short(self, s)

source code

Puts a signed short value.

Parameters:
  - `s` - an integral 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

### put_timestamp(self, t)

source code

Puts a timestamp value.

Parameters:
  - `t` - an integral value

### put_ubyte(self, ub)

source code

Puts an unsigned byte value.

Parameters:
  - `ub` - an integral value

### put_uint(self, ui)

source code

Puts an unsigned int value.

Parameters:
  - `ui` - an integral value

### put_ulong(self, ul)

source code

Puts an unsigned long value.

Parameters:
  - `ul` - an integral value

### put_ushort(self, us)

source code

Puts an unsigned short value.

Parameters:
  - `us` - an integral value.

### put_uuid(self, u)

source code

Puts a UUID value.

Parameters:
  - `u` - a uuid value

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

Class Variable Details

### get_mappings

Value:

      {1: <__builtin__.function object>,
       2: <__builtin__.function object>,
       3: <__builtin__.function object>,
       4: <__builtin__.function object>,
       5: <__builtin__.function object>,
       6: <__builtin__.function object>,
       7: <__builtin__.function object>,
       8: <__builtin__.function object>,
      ...

### put_mappings

Value:

      {<type 'int'>: <__builtin__.function object>,
       <type 'long'>: <__builtin__.function object>,
       <type 'float'>: <__builtin__.function object>,
       <type 'unicode'>: <__builtin__.function object>,
       <type 'NoneType'>: <__builtin__.function object>,
       <type 'bool'>: <__builtin__.function object>,
       <type 'tuple'>: <__builtin__.function object>,
       <type 'dict'>: <__builtin__.function object>,
      ...

### type_names

Value:

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