1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
|
.. _types:
##########
AMQP Types
##########
These tables summarize the various AMQP types and their Python API equivalents as used in the API.
|
============
Scalar Types
============
|
+------------+-------------------+---------------------------+------------------------------------------------------------------------+
| AMQP Type | Proton C API Type | Proton Python API Type | Description |
+============+===================+===========================+========================================================================+
| null | PN_NONE | ``None`` | Indicates an empty value. |
+------------+-------------------+---------------------------+------------------------------------------------------------------------+
| boolean | PN_BOOL | ``bool`` | Represents a true or false value. |
+------------+-------------------+---------------------------+------------------------------------------------------------------------+
| ubyte | PN_UBYTE | :class:`proton.ubyte` | Integer in the range :math:`0` to :math:`2^8 - 1` inclusive. |
+------------+-------------------+---------------------------+------------------------------------------------------------------------+
| byte | PN_BYTE | :class:`proton.byte` | Integer in the range :math:`-(2^7)` to :math:`2^7 - 1` inclusive. |
+------------+-------------------+---------------------------+------------------------------------------------------------------------+
| ushort | PN_USHORT | :class:`proton.ushort` | Integer in the range :math:`0` to :math:`2^{16} - 1` inclusive. |
+------------+-------------------+---------------------------+------------------------------------------------------------------------+
| short | PN_SHORT | :class:`proton.short` | Integer in the range :math:`-(2^{15})` to :math:`2^{15} - 1` inclusive.|
+------------+-------------------+---------------------------+------------------------------------------------------------------------+
| uint | PN_UINT | :class:`proton.uint` | Integer in the range :math:`0` to :math:`2^{32} - 1` inclusive. |
+------------+-------------------+---------------------------+------------------------------------------------------------------------+
| int | PN_INT | :class:`proton.int32` | Integer in the range :math:`-(2^{31})` to :math:`2^{31} - 1` inclusive.|
+------------+-------------------+---------------------------+------------------------------------------------------------------------+
| char | PN_CHAR | :class:`proton.char` | A single Unicode character. |
+------------+-------------------+---------------------------+------------------------------------------------------------------------+
| ulong | PN_ULONG | :class:`proton.ulong` | Integer in the range :math:`0` to :math:`2^{64} - 1` inclusive. |
+------------+-------------------+---------------------------+------------------------------------------------------------------------+
| long | PN_LONG | ``int`` or ``long`` | Integer in the range :math:`-(2^{63})` to :math:`2^{63} - 1` inclusive.|
+------------+-------------------+---------------------------+------------------------------------------------------------------------+
| timestamp | PN_TIMESTAMP | :class:`proton.timestamp` | An absolute point in time with millisecond precision. |
+------------+-------------------+---------------------------+------------------------------------------------------------------------+
| float | PN_FLOAT | :class:`proton.float32` | 32-bit floating point number (IEEE 754-2008 binary32). |
+------------+-------------------+---------------------------+------------------------------------------------------------------------+
| double | PN_DOUBLE | ``double`` | 64-bit floating point number (IEEE 754-2008 binary64). |
+------------+-------------------+---------------------------+------------------------------------------------------------------------+
| decimal32 | PN_DECIMAL32 | :class:`proton.decimal32` | 32-bit decimal number (IEEE 754-2008 decimal32). |
+------------+-------------------+---------------------------+------------------------------------------------------------------------+
| decimal64 | PN_DECIMAL64 | :class:`proton.decimal64` | 64-bit decimal number (IEEE 754-2008 decimal64). |
+------------+-------------------+---------------------------+------------------------------------------------------------------------+
| decimal128 | PN_DECIMAL128 | :class:`proton.decimal128`| 128-bit decimal number (IEEE 754-2008 decimal128). |
+------------+-------------------+---------------------------+------------------------------------------------------------------------+
| uuid | PN_UUID | ``uuid.UUID`` | A universally unique identifier as defined by RFC-4122 section 4.1.2. |
+------------+-------------------+---------------------------+------------------------------------------------------------------------+
| binary | PN_BINARY | ``bytes`` | A sequence of octets. |
+------------+-------------------+---------------------------+------------------------------------------------------------------------+
| string | PN_STRING | ``str`` | A sequence of Unicode characters. |
+------------+-------------------+---------------------------+------------------------------------------------------------------------+
| symbol | PN_SYMBOL | :class:`proton.symbol` | Symbolic values from a constrained domain. |
+------------+-------------------+---------------------------+------------------------------------------------------------------------+
|
==============
Compound Types
==============
|
+-----------+-------------------+---------------------------+-----------------------------------------------------+
| AMQP Type | Proton C API Type | Proton Python API Type | Description |
+===========+===================+===========================+=====================================================+
| array | PN_ARRAY | :class:`proton.Array` | A sequence of values of a single type. |
+-----------+-------------------+---------------------------+-----------------------------------------------------+
| list | PN_LIST | ``list`` | A sequence of polymorphic values. |
+-----------+-------------------+---------------------------+-----------------------------------------------------+
| map | PN_MAP | ``dict`` | A polymorphic mapping from distinct keys to values. |
+-----------+-------------------+---------------------------+-----------------------------------------------------+
|
=================
Specialized Types
=================
The following classes implement specialized or restricted types to help
enforce type restrictions in the AMQP specification.
|
+-------------------------------+------------------------------------------------------------------------------------+------------------------------------------------+
| Proton Python API Type | Description | Where used in API |
+===============================+====================================================================================+================================================+
| :class:`proton.SymbolList` | A ``list`` that only accepts :class:`proton.symbol` elements. However, will | :attr:`proton.Connection.desired_capabilities` |
| | silently convert strings to symbols. | :attr:`proton.Connection.offered_capabilities` |
+-------------------------------+------------------------------------------------------------------------------------+------------------------------------------------+
| :class:`proton.PropertyDict` | A ``dict`` that only accppts :class:`proton.symbol` keys. However, will silently | :attr:`proton.Connection.properties` |
| | convert strings to symbols. | |
+-------------------------------+------------------------------------------------------------------------------------+------------------------------------------------+
| :class:`proton.AnnotationDict`| A ``dict`` that only accppts :class:`proton.symbol` or :class:`proton.ulong` keys. | :attr:`proton.Message.annotations` |
| | However, will silently convert strings to symbols. | :attr:`proton.Message.instructions` |
+-------------------------------+------------------------------------------------------------------------------------+------------------------------------------------+
|
These types would typically be used where the the above attributes are set. They will silently convert strings to symbols,
but will raise an error if a not-allowed type is used. For example:
>>> from proton import symbol, ulong, Message, AnnotationDict
>>> msg = Message()
>>> msg.annotations = AnnotationDict({'one':1, symbol('two'):2, ulong(3):'three'})
>>> msg.annotations
AnnotationDict({symbol('one'): 1, symbol('two'): 2, ulong(3): 'three'})
>>> m.instructions = AnnotationDict({'one':1, symbol('two'):2, ulong(3):'three', 4:'four'})
...
KeyError: "invalid non-symbol key: <class 'int'>: 4"
>>> m.instructions
>>>
|
