Module proton

Module Summary


AnnotationDict([e, raise_on_error]) A dictionary that only takes symbol or ulong types as a key.
Condition(name[, description, info]) An AMQP Condition object.
Connection([impl]) A representation of an AMQP connection.
Data([capacity]) The Data class provides an interface for decoding, extracting, creating, and encoding arbitrary AMQP data.
Delivery(impl) Tracks and/or records the delivery of a message over a link.
Disposition(impl, local) A delivery state.
Endpoint Abstract class from which Connection, Session and Link are derived, and which defines the state of these classes.
Event(impl, number, clsname, context) Notification of a state change in the protocol engine.
EventType([name, number, method]) Connects an event number to an event name, and is used internally by Event to represent all known event types.
Link(impl) A representation of an AMQP link (a unidirectional channel for transferring messages), of which there are two concrete implementations, Sender and Receiver.
Message([body]) The Message class is a mutable holder of message content.
PropertyDict([e, raise_on_error]) A dictionary that only takes symbol types as a key.
Receiver(impl) A link over which messages are received.
SASL(transport) The SASL layer is responsible for establishing an authenticated and/or encrypted tunnel over which AMQP frames are passed between peers.
Sender(impl) A link over which messages are sent.
Session(impl) A container of links
SSL An SSL session associated with a transport.
SSLDomain(mode) An SSL configuration domain, used to hold the SSL configuration for one or more SSL sessions.
SSLSessionDetails(session_id) Unique identifier for the SSL session.
SymbolList([t, raise_on_error]) A list that can only hold symbol elements.
Terminus(impl) A source or target for messages.
Transport([mode, _impl]) A network channel supporting an AMQP connection.
Url([url, defaults]) DEPRECATED Simple URL parser/constructor.

Exceptions


ConnectionException An exception class raised when exceptions or errors related to a connection arise.
DataException The DataException class is the root of the Data exception hierarchy.
LinkException An exception class raised when exceptions or errors related to a link arise.
MessageException The MessageException class is the root of the message exception hierarchy.
ProtonException The root of the proton exception hierarchy.
SessionException An exception class raised when exceptions or errors related to a session arise.
SSLUnavailable An exception class raised when exceptions or errors related to SSL availability arise.
SSLException An exception class raised when exceptions or errors related to SSL usage arise.
Timeout A timeout exception indicates that a blocking operation has timed out.
Interrupt An interrupt exception indicates that a blocking operation was interrupted.
TransportException An exception class raised when exceptions or errors related to the AMQP transport arise.

AMQP Types


Array An AMQP array, a sequence of AMQP values of a single type.
byte The byte AMQP type.
char The char AMQP type.
Described A described AMQP type.
decimal32 The decimal32 AMQP type.
decimal64 The decimal64 AMQP type.
decimal128 The decimal128 AMQP type.
float32 The float AMQP type.
int32 The signed int AMQP type.
short The short AMQP type.
symbol The symbol AMQP type.
timestamp The timestamp AMQP type.
ubyte The unsigned byte AMQP type.
uint The unsigned int AMQP type.
ulong The ulong AMQP type.
ushort The unsigned short AMQP type.

Module Detail

class proton.AnnotationDict(e=None, raise_on_error=True, **kwargs)[source]

Bases: proton._data.RestrictedKeyDict

A dictionary that only takes symbol or ulong types as a key. However, if a string key is provided, it will be silently converted into a symbol key.

>>> from proton import symbol, ulong, AnnotationDict
>>> a = AnnotationDict(one=1, two=2)
>>> a[ulong(3)] = 'three'
>>> b = AnnotationDict({'one':1, symbol('two'):2, ulong(3):'three'})
>>> c = AnnotationDict(zip([symbol('one'), 'two', ulong(3)], [1, 2, 'three']))
>>> d = AnnotationDict([('one', 1), (symbol('two'), 2), (ulong(3), 'three')])
>>> e = AnnotationDict(a)
>>> a == b == c == d == e
True

By default, non-string, non-symbol and non-ulong keys cause a KeyError to be raised:

>>> AnnotationDict({'one': 1, 2: 'two'})
  ...
KeyError: "invalid non-symbol key: <type 'int'>: 2"

but by setting raise_on_error=False, non-string, non-symbol and non-ulong keys will be ignored:

>>> AnnotationDict({'one': 1, 2: 'two'}, raise_on_error=False)
AnnotationDict({2: 'two', symbol(u'one'): 1})
Parameters:
  • e (dict or list of tuple or zip object) – Initialization for dict
  • raise_on_error (bool) – If True, will raise an KeyError if a non-string, non-symbol or non-ulong is encountered as a key in the initialization, or in a subsequent operation which adds such an key. If False, non-strings, non-ulongs and non-symbols will be added as keys to the dictionary without an error.
  • kwargs – Keyword args for initializing a dict of the form key1=val1, key2=val2, …
clear() → None. Remove all items from D.
copy() → a shallow copy of D
fromkeys(S[, v]) → New dict with keys from S and values equal to v.

v defaults to None.

get(k[, d]) → D[k] if k in D, else d. d defaults to None.
has_key(k) → True if D has a key k, else False
items() → list of D's (key, value) pairs, as 2-tuples
iteritems() → an iterator over the (key, value) items of D
iterkeys() → an iterator over the keys of D
itervalues() → an iterator over the values of D
keys() → list of D's keys
pop(k[, d]) → v, remove specified key and return the corresponding value.

If key is not found, d is returned if given, otherwise KeyError is raised

popitem() → (k, v), remove and return some (key, value) pair as a

2-tuple; but raise KeyError if D is empty.

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D
update(e=None, **kwargs)

Equivalent to dict.update(), but it was needed to call __setitem__() instead of dict.__setitem__().

values() → list of D's values
viewitems() → a set-like object providing a view on D's items
viewkeys() → a set-like object providing a view on D's keys
viewvalues() → an object providing a view on D's values

class proton.Condition(name, description=None, info=None)[source]

An AMQP Condition object. Conditions hold exception information pertaining to the closing of an AMQP endpoint such as a Connection, Session, or Link. Conditions also hold similar information pertaining to deliveries that have reached terminal states. Connections, Sessions, Links, and Deliveries may all have local and remote conditions associated with them.

The local condition may be modified by the local endpoint to signal a particular condition to the remote peer. The remote condition may be examined by the local endpoint to detect whatever condition the remote peer may be signaling. Although often conditions are used to indicate errors, not all conditions are errors per/se, e.g. conditions may be used to redirect a connection from one host to another.

Every condition has a short symbolic name, a longer description, and an additional info map associated with it. The name identifies the formally defined condition, and the map contains additional information relevant to the identified condition.

Variables:
  • name (str) – The name of the condition.
  • description (str) – A description of the condition.
  • info (Data) – A data object that holds the additional information associated with the condition. The data object may be used both to access and to modify the additional information associated with the condition.

class proton.Connection(impl=<built-in function pn_connection>)[source]

Bases: proton._wrapper.Wrapper, proton._endpoints.Endpoint

A representation of an AMQP connection.

LOCAL_ACTIVE = 2
LOCAL_CLOSED = 4
LOCAL_UNINIT = 1
REMOTE_ACTIVE = 16
REMOTE_CLOSED = 32
REMOTE_UNINIT = 8
close()[source]

Closes the connection.

In more detail, this moves the local state of the connection to the CLOSED state and triggers a close frame to be sent to the peer. A connection is fully closed once both peers have closed it.

connected_address

The address for this connection.

Type:str
connection

Get this connection.

Type:Connection
container

The container name for this connection object.

Type:str
desired_capabilities

Desired capabilities as a list of symbols. The AMQP 1.0 specification restricts this list to symbol elements only. It is possible to use the special list subclass SymbolList which will by default enforce this restriction on construction. In addition, if string types are used, this class will be silently convert them into symbols.

Type:list containing symbol.
error

Additional error information associated with the connection.

Whenever a connection operation fails (i.e. returns an error code), additional error details can be obtained using this property. The returned value is the error code defined by Proton in pn_error_t (see error.h).

Type:int
free()[source]

Releases this connection object.

When a connection object is released, all Session and Link objects associated with this connection are also released and all Delivery objects are settled.

handler

Handler for events.

Getter:Get the event handler, or return None if no handler has been set.
Setter:Set the event handler.
Type:Handler or None
hostname

Set the name of the host (either fully qualified or relative) to which this connection is connecting to. This information may be used by the remote peer to determine the correct back-end service to connect the client to. This value will be sent in the Open performative, and will be used by SSL and SASL layers to identify the peer.

Type:str

Retrieve the first link that matches the given state mask.

Examines the state of each link owned by the connection and returns the first link that matches the given state mask. If state contains both local and remote flags, then an exact match against those flags is performed. If state contains only local or only remote flags, then a match occurs if any of the local or remote flags are set respectively. state==0 matches all links.

Parameters:mask (int) – State mask to match
Returns:The first link owned by the connection that matches the mask, else None if no link matches.
Return type:Link or None
offered_capabilities

Offered capabilities as a list of symbols. The AMQP 1.0 specification restricts this list to symbol elements only. It is possible to use the special list subclass SymbolList as it will by default enforce this restriction on construction. In addition, if a string type is used, it will be silently converted into the required symbol.

Type:list containing symbol.
open()[source]

Opens the connection.

In more detail, this moves the local state of the connection to the ACTIVE state and triggers an open frame to be sent to the peer. A connection is fully active once both peers have opened it.

password

Set the authentication password for a client connection.

It is necessary to set the username and password before binding the connection to a transport and it isn’t allowed to change after the binding.

Note

Getting the password always returns None.

Type:str
properties

Connection properties as a dictionary of key/values. The AMQP 1.0 specification restricts this dictionary to have keys that are only symbol types. It is possible to use the special dict subclass PropertyDict which will by default enforce this restrictions on construction. In addition, if strings type are used, this will silently convert them into symbols.

Type:dict containing symbol` keys.
remote_condition

The remote condition associated with the connection endpoint. See Condition for more information.

Type:Condition
remote_container

The container identifier specified by the remote peer for this connection.

This will return None until the :const:’REMOTE_ACTIVE` state is reached. See Endpoint for more details on endpoint state.

Any (non None) name returned by this operation will be valid until the connection object is unbound from a transport or freed, whichever happens sooner.

Type:str
remote_desired_capabilities

The capabilities desired by the remote peer for this connection.

This operation will return a Data object that is valid until the connection object is freed. This Data object will be empty until the remote connection is opened as indicated by the REMOTE_ACTIVE flag.

Type:Data
remote_hostname

The hostname specified by the remote peer for this connection.

This will return None until the REMOTE_ACTIVE state is reached. See Endpoint for more details on endpoint state.

Any (non None) name returned by this operation will be valid until the connection object is unbound from a transport or freed, whichever happens sooner.

Type:str
remote_offered_capabilities

The capabilities offered by the remote peer for this connection.

This operation will return a Data object that is valid until the connection object is freed. This Data object will be empty until the remote connection is opened as indicated by the REMOTE_ACTIVE flag.

Type:Data
remote_properties

The properties specified by the remote peer for this connection.

This operation will return a Data object that is valid until the connection object is freed. This Data object will be empty until the remote connection is opened as indicated by the REMOTE_ACTIVE flag.

Type:Data
session()[source]

Returns a new session on this connection.

Returns:New session
Return type:Session
Raises:SessionException
session_head(mask)[source]

Retrieve the first session from a given connection that matches the specified state mask.

Examines the state of each session owned by the connection, and returns the first session that matches the given state mask. If state contains both local and remote flags, then an exact match against those flags is performed. If state contains only local or only remote flags, then a match occurs if any of the local or remote flags are set respectively.

Parameters:mask – State mask to match
Returns:The first session owned by the connection that matches the mask, else None if no sessions matches.
Return type:Session or None
state

The state of the connection as a bit field. The state has a local and a remote component. Each of these can be in one of three states: UNINIT, ACTIVE or CLOSED. These can be tested by masking against LOCAL_UNINIT, LOCAL_ACTIVE, LOCAL_CLOSED, REMOTE_UNINIT, REMOTE_ACTIVE and REMOTE_CLOSED.

transport

The transport bound to this connection. If the connection is unbound, then this operation will return None.

Type:Transport or None
user

The authentication username for a client connection.

It is necessary to set the username and password before binding the connection to a transport and it isn’t allowed to change after the binding.

If not set then no authentication will be negotiated unless the client sasl layer is explicitly created (this would be for something like Kerberos where the credentials are implicit in the environment, or to explicitly use the ANONYMOUS SASL mechanism)

Type:str
work_head

Extracts the first delivery on the connection that has pending operations.

Retrieves the first delivery on the Connection that has pending operations. A readable delivery indicates message data is waiting to be read. A writable delivery indicates that message data may be sent. An updated delivery indicates that the delivery’s disposition has changed. A delivery will never be both readable and writable, but it may be both readable and updated or both writable and updated.

Returns:The first delivery object that needs to be serviced, or None if none.
Return type:Delivery or None

class proton.ConnectionException[source]

Bases: proton._exceptions.ProtonException

An exception class raised when exceptions or errors related to a connection arise.

message

class proton.Data(capacity=16)[source]

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:

ARRAY = 23

An array value.

BINARY = 19

A binary string.

BOOL = 2

A boolean value.

BYTE = 4

A signed byte value.

CHAR = 9

A character value.

DECIMAL128 = 17

A DECIMAL128 value.

DECIMAL32 = 15

A DECIMAL32 value.

DECIMAL64 = 16

A DECIMAL64 value.

DESCRIBED = 22

A described value.

DOUBLE = 14

A double value.

FLOAT = 13

A float value.

INT = 8

A signed int value.

LIST = 24

A list value.

LONG = 11

A signed long value.

MAP = 25

A map value.

NULL = 1

A null value.

SHORT = 6

A short value.

STRING = 20

A unicode string.

SYMBOL = 21

A symbolic string.

TIMESTAMP = 12

A timestamp value.

UBYTE = 3

An unsigned byte value.

UINT = 7

An unsigned int value.

ULONG = 10

An unsigned long value.

USHORT = 5

An unsigned short value.

UUID = 18

A UUID value.

clear()[source]

Clears the data object.

copy(src)[source]

Copy the contents of another pn_data_t object. Any values in the data object will be lost.

Parameters:src (Data) – The source object from which to copy
Raise:DataException if there is a Proton error.
decode(encoded)[source]

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

Parameters:encoded (binary) – AMQP encoded binary data
Raise:DataException if there is a Proton error.
dump()[source]

Dumps a debug representation of the internal state of this Data object that includes its navigational state to cout (stdout) for debugging purposes.

encode()[source]

Returns a representation of the data encoded in AMQP format.

Returns:The size of the encoded data
Return type:int
Raise:DataException if there is a Proton error.
encoded_size()[source]

Returns the size in bytes needed to encode the data in AMQP format.

Returns:The size of the encoded data or an error code if data is invalid.
Return type:int
enter()[source]

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() to advance to the first child.

Returns:True iff the pointers to the current/parent nodes are changed, False otherwise.
Return type:bool
exit()[source]

Sets the current node to the parent node and the parent node to its own parent.

Returns:True iff the pointers to the current/parent nodes are changed, False otherwise.
Return type:bool
format()[source]

Formats the contents of this Data object in a human readable way.

Returns:A Formatted string containing contents of this Data object.
Return type:str
Raise:DataException if there is a Proton error.
get_array()[source]

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 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()
Returns:A tuple containing the number of array elements, the descriptor (or None if no descriptor) and the enumerated array element type.
Return type:tuple (int, str or None, int)
get_binary()[source]

Get the current node value as bytes.

Returns:If the current node is binary, its value, "" otherwise.
Return type:bytes
get_bool()[source]

Get the current node value as a bool.

Returns:If the current node is a boolean type, returns its value, False otherwise.
Return type:bool
get_byte()[source]

Get the current node value as a byte.

Returns:If the current node is a signed byte, its value, 0 otherwise.
Return type:byte
get_char()[source]

Get the current node value as a char.

Returns:If the current node is a char, its value, 0 otherwise.
Return type:char
get_decimal128()[source]

Get the current node value as a decimal128.

Returns:If the current node is a decimal128, its value, 0 otherwise.
Return type:decimal128
get_decimal32()[source]

Get the current node value as a decimal32.

Returns:If the current node is a decimal32, its value, 0 otherwise.
Return type:decimal32
get_decimal64()[source]

Get the current node value as a decimal64.

Returns:If the current node is a decimal64, its value, 0 otherwise.
Return type:decimal64
get_dict()[source]

A convenience method for decoding an AMQP map as a Python dict.

Returns:The decoded dictionary.
Return type:dict
get_double()[source]

Get the current node value as a double.

Returns:If the current node is a double, its value, 0 otherwise.
Return type:double
get_float()[source]

Get the current node value as a float32.

Returns:If the current node is a float, its value, 0 otherwise.
Return type:float32
get_int()[source]

Get the current node value as a int32.

Returns:If the current node is a signed int, its value, 0 otherwise.
Return type:int32
get_list()[source]

If the current node is a list, return the number of elements, otherwise return 0. 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()
Returns:the number of child elements of a list node
Return type:int
get_long()[source]

Get the current node value as a ulong.

Returns:If the current node is an signed long, its value, 0 otherwise.
Return type:long
get_map()[source]

If the current node is a map, return the number of child elements, otherwise return 0. 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()
Returns:the number of child elements of a map node
Return type:int
get_object()[source]
get_py_array()[source]

A convenience method for decoding an AMQP array into an Array object. This method encapsulates all the steps described in get_array() into a single function.

If the current node is an array, return an Array object representing the array and its contents. Otherwise return None.

Returns:The decoded AMQP array.
Return type:Array
get_py_described()[source]

A convenience method for decoding an AMQP described value.

Returns:The decoded AMQP descriptor.
Return type:Described
get_sequence()[source]

A convenience method for decoding an AMQP list as a Python list.

Returns:The decoded list.
Return type:list
get_short()[source]

Get the current node value as a short.

Returns:If the current node is a signed short, its value, 0 otherwise.
Return type:short
get_string()[source]

Get the current node value as str.

Returns:If the current node is a string, its value, "" otherwise.
Return type:str
get_symbol()[source]

Get the current node value as symbol.

Returns:If the current node is a symbol, its value, "" otherwise.
Return type:symbol
get_timestamp()[source]

Get the current node value as a timestamp.

Returns:If the current node is a timestamp, its value, 0 otherwise.
Return type:timestamp
get_ubyte()[source]

Get the current node value as a ubyte.

Returns:If the current node is an unsigned byte, its value, 0 otherwise.
Return type:ubyte
get_uint()[source]

Get the current node value as a uint.

Returns:If the current node is an unsigned int, its value, 0 otherwise.
Return type:uint
get_ulong()[source]

Get the current node value as a long.

Returns:If the current node is an unsigned long, its value, 0 otherwise.
Return type:ulong
get_ushort()[source]

Get the current node value as a ushort.

Returns:If the current node is an unsigned short, its value, 0 otherwise.
Return type:ushort
get_uuid()[source]

Get the current node value as a uuid.UUID.

Returns:If the current node is a UUID, its value, None otherwise.
Return type:uuid.UUID or None
is_described()[source]

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()
Returns:True if the current node is a described type, False otherwise.
Return type:bool
is_null()[source]

Checks if the current node is the AMQP null type.

Returns:True if the current node is the AMQP null type, False otherwise.
Return type:bool
narrow()[source]

Modify this Data object to behave as if the current node is the root node of the tree. This impacts the behavior of rewind(), next(), prev(), and anything else that depends on the navigational state of the Data object. Use widen() to reverse the effect of this operation.

next()[source]

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.

Returns:Node type or None
Return type:int or None
prev()[source]

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.

Returns:Node type or None
Return type:int or None
put_array(described, element_type)[source]

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

DataException if there is a Proton error.

put_binary(b)[source]

Puts a binary value.

Parameters:b (bytes) – a binary value
Raise:DataException if there is a Proton error.
put_bool(b)[source]

Puts a boolean value.

Parameters:b (bool or int) – a boolean value
Raise:DataException if there is a Proton error.
put_buffer(buff)[source]

Put a Python buffer object as an AMQP binary value.

Parameters:buff (Any object supporting the Python buffer interface.) – A Python buffer object (CHECK THIS)
Raise:DataException if there is a Proton error.
put_byte(b)[source]

Puts a signed byte value.

Parameters:

b (int, byte) – an integral value in the range \(-(2^7)\) to \(2^7 - 1\) inclusive.

Raise:
  • AssertionError if parameter is out of the range \(-(2^7)\) to \(2^7 - 1\) inclusive.
  • DataException if there is a Proton error.
put_char(c)[source]

Puts a char value.

Parameters:c (str, char) – a single character
Raise:DataException if there is a Proton error.
put_decimal128(d)[source]

Puts a decimal128 value.

Parameters:d (bytes, decimal128) – a decimal128 value encoded in a 16-byte binary value.
Raise:DataException if there is a Proton error.
put_decimal32(d)[source]

Puts a decimal32 value.

Parameters:d (int, decimal32) – a decimal32 number encoded in an 32-bit integral value.
Raise:DataException if there is a Proton error.
put_decimal64(d)[source]

Puts a decimal64 value.

Parameters:d (int, long, decimal64) – a decimal64 number encoded in an 32-bit integral value.
Raise:DataException if there is a Proton error.
put_described()[source]

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()
Raise:DataException if there is a Proton error.
put_dict(d)[source]

A convenience method for encoding the contents of a Python dict as an AMQP map.

Parameters:d (dict) – The dictionary to be encoded
Raise:DataException if there is a Proton error.
put_double(d)[source]

Puts a double value.

Parameters:d (double) – a floating point value.
Raise:DataException if there is a Proton error.
put_float(f)[source]

Puts a float value.

Parameters:f (float, float32) – a floating point value
Raise:DataException if there is a Proton error.
put_int(i)[source]

Puts a signed int value.

Parameters:

i (int, int32) – an integral value in the range \(-(2^{31})\) to \(2^{31} - 1\) inclusive.

Raise:
  • AssertionError if parameter is out of the range \(-(2^{31})\) to \(2^{31} - 1\) inclusive.
  • DataException if there is a Proton error.
put_list()[source]

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()
Raise:DataException if there is a Proton error.
put_long(l)[source]

Puts a signed long value.

Parameters:

l – an integral value in the range \(-(2^{63})\) to \(2^{63} - 1\) inclusive.

Raise:
  • AssertionError if parameter is out of the range \(-(2^{63})\) to \(2^{63} - 1\) inclusive.
  • DataException if there is a Proton error.
put_map()[source]

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()
Raise:DataException if there is a Proton error.
put_memoryview(mv)[source]

Put a Python memoryview object as an AMQP binary value.

Parameters:mv (memoryview) – A Python memoryview object
Raise:DataException if there is a Proton error.
put_null()[source]

Puts a null value.

Raise:DataException if there is a Proton error.
put_object(obj)[source]
put_py_array(a)[source]

A convenience method for encoding an Array object as an AMQP array. This method encapsulates the steps described in put_array() into a single function.

Parameters:a (Array) – The array object to be encoded
Raise:DataException if there is a Proton error.
put_py_described(d)[source]

A convenience method for encoding a Described object as an AMQP described value. This method encapsulates all the steps described in put_described() into a single method.

Parameters:d (Described) – The descriptor to be encoded
Raise:DataException if there is a Proton error.
put_sequence(s)[source]

A convenience method for encoding a Python list as an AMQP list.

Parameters:s (list) – The sequence to be encoded
Raise:DataException if there is a Proton error.
put_short(s)[source]

Puts a signed short value.

Parameters:

s (int, short) – an integral value in the range \(-(2^{15})\) to \(2^{15} - 1\) inclusive.

Raise:
  • AssertionError if parameter is out of the range \(-(2^{15})\) to \(2^{15} - 1\) inclusive.
  • DataException if there is a Proton error.
put_string(s)[source]

Puts a unicode value.

Parameters:s (str (Python 3.x) or unicode (Python 2.x)) – a unicode string
Raise:DataException if there is a Proton error.
put_symbol(s)[source]

Puts a symbolic value.

Parameters:s (string, symbol) – the symbol name
Raise:DataException if there is a Proton error.
put_timestamp(t)[source]

Puts a timestamp value.

Parameters:

t (int, timestamp) – a positive integral value

Raise:
  • AssertionError if parameter is negative.
  • DataException if there is a Proton error.
put_ubyte(ub)[source]

Puts an unsigned byte value.

Parameters:

ub (int, ubyte) – an integral value in the range \(0\) to \(2^8 - 1\) inclusive

Raise:
  • AssertionError if parameter is out of the range \(0\) to \(2^8 - 1\) inclusive.
  • DataException if there is a Proton error.
put_uint(ui)[source]

Puts an unsigned int value.

Parameters:

ui (int, uint) – an integral value in the range \(0\) to \(2^{32} - 1\) inclusive.

Raise:
  • AssertionError if parameter is out of the range \(0\) to \(2^{32} - 1\) inclusive.
  • DataException if there is a Proton error.
put_ulong(ul)[source]

Puts an unsigned long value.

Parameters:

ul (int, long, ulong) – an integral value in the range \(0\) to \(2^{64} - 1\) inclusive.

Raise:
  • AssertionError if parameter is out of the range \(0\) to \(2^{64} - 1\) inclusive.
  • DataException if there is a Proton error.
put_ushort(us)[source]

Puts an unsigned short value.

Parameters:

us (int, ushort) – an integral value in the range \(0\) to \(2^{16} - 1\) inclusive.

Raise:
  • AssertionError if parameter is out of the range \(0\) to \(2^{16} - 1\) inclusive.
  • DataException if there is a Proton error.
put_uuid(u)[source]

Puts a UUID value.

Parameters:u (uuid.UUID) – a uuid value.
Raise:DataException if there is a Proton error.
rewind()[source]

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.

type()[source]

Returns the type of the current node. Returns None if there is no current node.

Returns:The current node type enumeration.
Return type:int or None
classmethod type_name()[source]

Return a string name for an AMQP type.

Parameters:type (integer) – Numeric Proton AMQP type (enum pn_type_t)
Return type:String describing the AMQP type with numeric value amqptype
type_names = {1: 'null', 2: 'bool', 3: 'ubyte', 4: 'byte', 5: 'ushort', 6: 'short', 7: 'uint', 8: 'int', 9: 'char', 10: 'ulong', 11: 'long', 12: 'timestamp', 13: 'float', 14: 'double', 15: 'decimal32', 16: 'decimal64', 17: 'decimal128', 18: 'uuid', 19: 'binary', 20: 'string', 21: 'symbol', 22: 'described', 23: 'array', 24: 'list', 25: 'map'}

A map which uses the enumerated type as a key to get a text name for the type.

widen()[source]

Reverse the effect of narrow().


class proton.DataException[source]

Bases: proton._exceptions.ProtonException

The DataException class is the root of the Data exception hierarchy. All exceptions raised by the Data class extend this exception.

message

class proton.Delivery(impl)[source]

Bases: proton._wrapper.Wrapper

Tracks and/or records the delivery of a message over a link.

ACCEPTED = ACCEPTED

A terminal state indicating that the delivery was successfully processed. Once in this state there will be no further state changes prior to the delivery being settled.

MODIFIED = MODIFIED

A terminal state indicating that the delivery is being returned to the sender and should be annotated by the sender prior to further delivery attempts. Once in this state there will be no further state changes prior to the delivery being settled.

RECEIVED = RECEIVED

A non terminal state indicating how much (if any) message data has been received for a delivery.

REJECTED = REJECTED

A terminal state indicating that the delivery could not be processed due to some error condition. Once in this state there will be no further state changes prior to the delivery being settled.

RELEASED = RELEASED

A terminal state indicating that the delivery is being returned to the sender. Once in this state there will be no further state changes prior to the delivery being settled.

abort()[source]

Aborts the delivery. This indicates the application wishes to invalidate any data that may have already been sent on this delivery. The delivery cannot be aborted after it has been completely delivered.

aborted

True if the delivery has been aborted, False otherwise.

Type:bool
connection

The Connection over which the delivery was sent or received.

Type:Connection

The Link on which the delivery was sent or received.

Type:Link
local_state

A string representation of the local state of the delivery.

Type:str
partial

True for an incoming delivery if not all the data is yet available, False otherwise.

Type:bool
pending

The amount of pending message data for a delivery.

Type:int
readable

True for an incoming delivery that has data to read, False otherwise..

Type:bool
remote_state

A string representation of the state of the delivery as indicated by the remote peer.

Type:str
session

The Session over which the delivery was sent or received.

Type:Session
settle()[source]

Settles the delivery locally. This indicates the application considers the delivery complete and does not wish to receive any further events about it. Every delivery should be settled locally.

settled

True if the delivery has been settled by the remote peer, False otherwise.

Type:bool
tag

The identifier for the delivery.

Type:bytes
transport

The Transport bound to the Connection over which the delivery was sent or received.

Type:Transport
update(state)[source]

Set the local state of the delivery e.g. ACCEPTED, REJECTED, RELEASED.

Parameters:state (int) – State of delivery
updated

True if the state of the delivery has been updated (e.g. it has been settled and/or accepted, rejected etc), False otherwise.

Type:bool
work_next

The next Delivery on the connection that has pending operations.

Type:Delivery
writable

True for an outgoing delivery to which data can now be written, False otherwise..

Type:bool

class proton.Disposition(impl, local)[source]

Bases: object

A delivery state.

Dispositions record the current state or final outcome of a transfer. Every delivery contains both a local and remote disposition. The local disposition holds the local state of the delivery, and the remote disposition holds the last known remote state of the delivery.

ACCEPTED = ACCEPTED

A terminal state indicating that the delivery was successfully processed. Once in this state there will be no further state changes prior to the delivery being settled.

MODIFIED = MODIFIED

A terminal state indicating that the delivery is being returned to the sender and should be annotated by the sender prior to further delivery attempts. Once in this state there will be no further state changes prior to the delivery being settled.

RECEIVED = RECEIVED

A non terminal state indicating how much (if any) message data has been received for a delivery.

REJECTED = REJECTED

A terminal state indicating that the delivery could not be processed due to some error condition. Once in this state there will be no further state changes prior to the delivery being settled.

RELEASED = RELEASED

A terminal state indicating that the delivery is being returned to the sender. Once in this state there will be no further state changes prior to the delivery being settled.

annotations

The annotations associated with a disposition.

The Data object retrieved by this operation may be modified prior to updating a delivery. When a delivery is updated, the annotations described by the Data are reported to the peer if applicable to the current delivery state, e.g. states such as MODIFIED. The Data must be empty or contain a symbol keyed map.

The Data object returned by this operation is valid until the parent delivery is settled.

Type:Data
condition

The condition object associated with a disposition.

The Condition object retrieved by this operation may be modified prior to updating a delivery. When a delivery is updated, the condition described by the disposition is reported to the peer if applicable to the current delivery state, e.g. states such as REJECTED.

Type:Condition
data

Access the disposition as a Data object.

Dispositions are an extension point in the AMQP protocol. The disposition interface provides setters/getters for those dispositions that are predefined by the specification, however access to the raw disposition data is provided so that other dispositions can be used.

The Data object returned by this operation is valid until the parent delivery is settled.

Type:Data
failed

The failed flag for this disposition.

Type:bool
section_number

The section number associated with a disposition.

Type:int
section_offset

The section offset associated with a disposition.

Type:int
type

Get the type of this disposition object.

Defined values are:

Type:str
undeliverable

The undeliverable flag for this disposition.

Type:bool

class proton.Described(descriptor, value)[source]

Bases: object

A described AMQP type.

Variables:
  • descriptor (symbol) – A symbol describing the value.
  • value (Any AMQP value) – The described value

class proton.Endpoint[source]

Bases: object

Abstract class from which Connection, Session and Link are derived, and which defines the state of these classes.

The Endpoint state is an integral value with flags that encode both the local and remote state of an AMQP Endpoint (Connection, Link, or Session). The individual bits may be accessed using LOCAL_UNINIT, LOCAL_ACTIVE, LOCAL_CLOSED, and REMOTE_UNINIT, REMOTE_ACTIVE, REMOTE_CLOSED.

Every AMQP endpoint (Connection, Link, or Session) starts out in an uninitialized state and then proceeds linearly to an active and then closed state. This lifecycle occurs at both endpoints involved, and so the state model for an endpoint includes not only the known local state, but also the last known state of the remote endpoint.

LOCAL_ACTIVE = 2

The local endpoint state is closed.

LOCAL_CLOSED = 4

The remote endpoint state is active.

LOCAL_UNINIT = 1

The local endpoint state is uninitialized.

REMOTE_ACTIVE = 16

The remote endpoint state is uninitialized.

REMOTE_CLOSED = 32

The remote endpoint state is closed.

REMOTE_UNINIT = 8

The local endpoint state is active.

handler

Handler for events.

Getter:Get the event handler, or return None if no handler has been set.
Setter:Set the event handler.
Type:Handler or None
remote_condition

The remote condition associated with the connection endpoint. See Condition for more information.

Type:Condition

class proton.Event(impl, number, clsname, context)[source]

Bases: proton._events.EventBase

Notification of a state change in the protocol engine.

CONNECTION_BOUND = EventType(name=PN_CONNECTION_BOUND, number=6)

The connection has been bound to a transport. This event is issued when the Transport.bind() operation is invoked.

CONNECTION_FINAL = EventType(name=PN_CONNECTION_FINAL, number=12)

The connection has been freed and any outstanding processing has been completed. This is the final event that will ever be issued for a connection.

CONNECTION_INIT = EventType(name=PN_CONNECTION_INIT, number=5)

The connection has been created. This is the first event that will ever be issued for a connection. Events of this type point to the relevant connection.

CONNECTION_LOCAL_CLOSE = EventType(name=PN_CONNECTION_LOCAL_CLOSE, number=10)

The local connection endpoint has been closed. Events of this type point to the relevant connection.

CONNECTION_LOCAL_OPEN = EventType(name=PN_CONNECTION_LOCAL_OPEN, number=8)

The local connection endpoint has been closed. Events of this type point to the relevant connection.

CONNECTION_REMOTE_CLOSE = EventType(name=PN_CONNECTION_REMOTE_CLOSE, number=11)

The remote endpoint has closed the connection. Events of this type point to the relevant connection.

CONNECTION_REMOTE_OPEN = EventType(name=PN_CONNECTION_REMOTE_OPEN, number=9)

The remote endpoint has opened the connection. Events of this type point to the relevant connection.

CONNECTION_UNBOUND = EventType(name=PN_CONNECTION_UNBOUND, number=7)

The connection has been unbound from its transport. This event is issued when the Transport.unbind() operation is invoked.

DELIVERY = EventType(name=PN_DELIVERY, number=28)

A delivery has been created or updated. Events of this type point to the relevant delivery.

The link has been freed and any outstanding processing has been completed. This is the final event that will ever be issued for a link. Events of this type point to the relevant link.

The flow control state for a link has changed. Events of this type point to the relevant link.

The link has been created. This is the first event that will ever be issued for a link.

The local link endpoint has been closed. Events of this type point to the relevant link.

The local link endpoint has been detached. Events of this type point to the relevant link.

The local link endpoint has been opened. Events of this type point ot the relevant link.

The remote endpoint has closed the link. Events of this type point to the relevant link.

The remote endpoint has detached the link. Events of this type point to the relevant link.

The remote endpoint has opened the link. Events of this type point to the relevant link.

REACTOR_FINAL = EventType(name=reactor_final, number=10002)

A reactor has been stopped. Events of this type point to the reactor.

REACTOR_INIT = EventType(name=reactor_init, number=10000)

A reactor has been started. Events of this type point to the reactor.

REACTOR_QUIESCED = EventType(name=reactor_quiesced, number=10001)

A reactor has no more events to process. Events of this type point to the reactor.

SELECTABLE_ERROR = EventType(name=selectable_error, number=10008)
SELECTABLE_EXPIRED = EventType(name=selectable_expired, number=10007)
SELECTABLE_FINAL = EventType(name=selectable_final, number=10009)
SELECTABLE_INIT = EventType(name=selectable_init, number=10003)
SELECTABLE_READABLE = EventType(name=selectable_readable, number=10005)
SELECTABLE_UPDATED = EventType(name=selectable_updated, number=10004)
SELECTABLE_WRITABLE = EventType(name=selectable_writable, number=10006)
SESSION_FINAL = EventType(name=PN_SESSION_FINAL, number=18)

The session has been freed and any outstanding processing has been completed. This is the final event that will ever be issued for a session.

SESSION_INIT = EventType(name=PN_SESSION_INIT, number=13)

The session has been created. This is the first event that will ever be issued for a session.

SESSION_LOCAL_CLOSE = EventType(name=PN_SESSION_LOCAL_CLOSE, number=16)

The local session endpoint has been closed. Events of this type point ot the relevant session.

SESSION_LOCAL_OPEN = EventType(name=PN_SESSION_LOCAL_OPEN, number=14)

The local session endpoint has been opened. Events of this type point to the relevant session.

SESSION_REMOTE_CLOSE = EventType(name=PN_SESSION_REMOTE_CLOSE, number=17)

The remote endpoint has closed the session. Events of this type point to the relevant session.

SESSION_REMOTE_OPEN = EventType(name=PN_SESSION_REMOTE_OPEN, number=15)

The remote endpoint has opened the session. Events of this type point to the relevant session.

TIMER_TASK = EventType(name=PN_TIMER_TASK, number=4)

A timer event has occurred.

TRANSPORT = EventType(name=PN_TRANSPORT, number=29)

The transport has new data to read and/or write. Events of this type point to the relevant transport.

TRANSPORT_CLOSED = EventType(name=PN_TRANSPORT_CLOSED, number=34)

Indicates that the both the “head” and “tail” of the transport are closed. Events of this type point to the relevant transport.

TRANSPORT_ERROR = EventType(name=PN_TRANSPORT_ERROR, number=31)

Indicates that a transport error has occurred. Use Transport.condition to access the details of the error from the associated transport.

TRANSPORT_HEAD_CLOSED = EventType(name=PN_TRANSPORT_HEAD_CLOSED, number=32)

Indicates that the “head” or writing end of the transport has been closed. This means the transport will never produce more bytes for output to the network. Events of this type point to the relevant transport.

TRANSPORT_TAIL_CLOSED = EventType(name=PN_TRANSPORT_TAIL_CLOSED, number=33)

Indicates that the “tail” of the transport has been closed. This means the transport will never be able to process more bytes from the network. Events of this type point to the relevant transport.

clazz

The name of the class associated with the event context.

Type:str
connection

The connection associated with the event, or None if none is associated with it.

Type:Connection
container

The reactor.Container associated with the event.

context

The context object associated with the event.

Type:Depends on the type of event, and include the following: - Connection - Session - Link - Delivery - Transport
delivery

The delivery associated with the event, or None if none is associated with it.

Type:Delivery
dispatch(handler, type=None)

Process this event by sending it to all known handlers that are valid for this event type.

Parameters:
  • handler (Handler) – Parent handler to process this event
  • type (EventType) – Event type
handler

The handler for this event. The handler is determined by looking at the following in order:

  • The link
  • The session
  • The connection
  • The context object with an attribute “handler”

If none of these has a handler, then None is returned.

The link associated with the event, or None if none is associated with it.

Type:Link
reactor

Deprecated - The reactor.Container (was reactor) associated with the event.

receiver

The receiver link associated with the event, or None if none is associated with it. This is essentially an alias for link(), that does an additional check on the type of the link.

Type:Receiver (<– CHECK!)
sender

The sender link associated with the event, or None if none is associated with it. This is essentially an alias for link(), that does an additional check on the type of the link.

Type:Sender (<– CHECK!)
session

The session associated with the event, or None if none is associated with it.

Type:Session
transport

The transport associated with the event, or None if none is associated with it.

Type:Transport
type

The type name for this event

Type:str

class proton.EventType(name=None, number=None, method=None)[source]

Bases: object

Connects an event number to an event name, and is used internally by Event to represent all known event types. A global list of events is maintained. An EventType created with a name but no number is treated as an extended event, and is assigned an internal event number starting at 10000.

TYPES = {4: EventType(name=PN_TIMER_TASK, number=4), 5: EventType(name=PN_CONNECTION_INIT, number=5), 6: EventType(name=PN_CONNECTION_BOUND, number=6), 7: EventType(name=PN_CONNECTION_UNBOUND, number=7), 8: EventType(name=PN_CONNECTION_LOCAL_OPEN, number=8), 9: EventType(name=PN_CONNECTION_REMOTE_OPEN, number=9), 10: EventType(name=PN_CONNECTION_LOCAL_CLOSE, number=10), 11: EventType(name=PN_CONNECTION_REMOTE_CLOSE, number=11), 12: EventType(name=PN_CONNECTION_FINAL, number=12), 13: EventType(name=PN_SESSION_INIT, number=13), 14: EventType(name=PN_SESSION_LOCAL_OPEN, number=14), 15: EventType(name=PN_SESSION_REMOTE_OPEN, number=15), 16: EventType(name=PN_SESSION_LOCAL_CLOSE, number=16), 17: EventType(name=PN_SESSION_REMOTE_CLOSE, number=17), 18: EventType(name=PN_SESSION_FINAL, number=18), 19: EventType(name=PN_LINK_INIT, number=19), 20: EventType(name=PN_LINK_LOCAL_OPEN, number=20), 21: EventType(name=PN_LINK_REMOTE_OPEN, number=21), 22: EventType(name=PN_LINK_LOCAL_CLOSE, number=22), 23: EventType(name=PN_LINK_REMOTE_CLOSE, number=23), 24: EventType(name=PN_LINK_LOCAL_DETACH, number=24), 25: EventType(name=PN_LINK_REMOTE_DETACH, number=25), 26: EventType(name=PN_LINK_FLOW, number=26), 27: EventType(name=PN_LINK_FINAL, number=27), 28: EventType(name=PN_DELIVERY, number=28), 29: EventType(name=PN_TRANSPORT, number=29), 31: EventType(name=PN_TRANSPORT_ERROR, number=31), 32: EventType(name=PN_TRANSPORT_HEAD_CLOSED, number=32), 33: EventType(name=PN_TRANSPORT_TAIL_CLOSED, number=33), 34: EventType(name=PN_TRANSPORT_CLOSED, number=34), 10000: EventType(name=reactor_init, number=10000), 10001: EventType(name=reactor_quiesced, number=10001), 10002: EventType(name=reactor_final, number=10002), 10003: EventType(name=selectable_init, number=10003), 10004: EventType(name=selectable_updated, number=10004), 10005: EventType(name=selectable_readable, number=10005), 10006: EventType(name=selectable_writable, number=10006), 10007: EventType(name=selectable_expired, number=10007), 10008: EventType(name=selectable_error, number=10008), 10009: EventType(name=selectable_final, number=10009)}

Bases: proton._wrapper.Wrapper, proton._endpoints.Endpoint

A representation of an AMQP link (a unidirectional channel for transferring messages), of which there are two concrete implementations, Sender and Receiver.

LOCAL_ACTIVE = 2
LOCAL_CLOSED = 4
LOCAL_UNINIT = 1
RCV_FIRST = 0

The receiver will settle deliveries regardless of what the sender does.

RCV_SECOND = 1

The receiver will only settle deliveries after the sender settles.

REMOTE_ACTIVE = 16
REMOTE_CLOSED = 32
REMOTE_UNINIT = 8
SND_MIXED = 2

The sender may send a mixture of settled and unsettled deliveries.

SND_SETTLED = 1

The sender will send all deliveries settled to the receiver.

SND_UNSETTLED = 0

The sender will send all deliveries initially unsettled.

advance()[source]

Advance the current delivery of this link to the next delivery.

For sending links this operation is used to finish sending message data for the current outgoing delivery and move on to the next outgoing delivery (if any).

For receiving links, this operation is used to finish accessing message data from the current incoming delivery and move on to the next incoming delivery (if any).

Each link maintains a sequence of deliveries in the order they were created, along with a pointer to the current delivery. The advance() operation will modify the current delivery on the link to point to the next delivery in the sequence. If there is no next delivery in the sequence, the current delivery will be set to NULL.

Returns:True if the value of the current delivery changed (even if it was set to NULL, False otherwise.
Return type:bool
available

The available deliveries hint for this link.

The available count for a link provides a hint as to the number of deliveries that might be able to be sent if sufficient credit were issued by the receiving link endpoint. See Sender.offered() for more details.

Type:int
close()[source]

Closes the link.

In more detail, this moves the local state of the link to the LOCAL_CLOSED state and triggers an detach frame (with the closed flag set) to be sent to the peer. A link is fully closed once both peers have detached it.

This may be called without calling open(), in this case it is equivalent to calling open() followed by close().

connection

The connection on which this link was attached.

Type:Connection
credit

The amount of outstanding credit on this link.

Links use a credit based flow control scheme. Every receiver maintains a credit balance that corresponds to the number of deliveries that the receiver can accept at any given moment. As more capacity becomes available at the receiver (see Receiver.flow()), it adds credit to this balance and communicates the new balance to the sender. Whenever a delivery is sent/received, the credit balance maintained by the link is decremented by one. Once the credit balance at the sender reaches zero, the sender must pause sending until more credit is obtained from the receiver.

Note

A sending link may still be used to send deliveries even if credit reaches zero, however those deliveries will end up being buffered by the link until enough credit is obtained from the receiver to send them over the wire. In this case the balance reported by credit will go negative.

Type:int
current

The current delivery for this link.

Each link maintains a sequence of deliveries in the order they were created, along with a pointer to the current delivery. All send/recv operations on a link take place on the current delivery. If a link has no current delivery, the current delivery is automatically initialized to the next delivery created on the link. Once initialized, the current delivery remains the same until it is changed through use of advance() or until it is settled via Delivery.settle().

Return type:Delivery
delivery(tag)[source]

Create a delivery. Every delivery object within a link must be supplied with a unique tag. Links maintain a sequence of delivery object in the order that they are created.

Parameters:tag (bytes) – Delivery tag unique for this link.
Return type:Delivery
detach()[source]

Detach this link.

drain_mode

The drain mode on this link.

If a link is in drain mode (True), then the sending endpoint of a link must immediately use up all available credit on the link. If this is not possible, the excess credit must be returned by invoking drained(). Only the receiving endpoint can set the drain mode.

When False, this link is not in drain mode.

Type:bool
drained()[source]

Drain excess credit for this link.

When a link is in drain mode (see drain_mode), the sender must use all excess credit immediately, and release any excess credit back to the receiver if there are no deliveries available to send.

When invoked on a sending link that is in drain mode, this operation will release all excess credit back to the receiver and return the number of credits released back to the sender. If the link is not in drain mode, this operation is a noop.

When invoked on a receiving link, this operation will return and reset the number of credits the sender has released back to the receiver.

Returns:The number of credits drained.
Return type:int
free()[source]

Free this link object. When a link object is freed, all Delivery objects associated with the session (<– CHECK THIS) are also freed. Freeing a link will settle any unsettled deliveries on the link.

handler

Handler for events.

Getter:Get the event handler, or return None if no handler has been set.
Setter:Set the event handler.
Type:Handler or None
is_receiver

True if this link is a receiver, False otherwise.

Type:bool
is_sender

True if this link is a sender, False otherwise.

Type:bool
max_message_size

The maximum message size for this link. A zero value means the size is unlimited.

Warning

Unsettled API

Type:long
name

The name of the link.

Type:str
next(mask)[source]

Retrieve the next link that matches the given state mask.

When used with Connection.link_head(), the application can access all links on the connection that match the given state. See Connection.link_head() for a description of match behavior.

Parameters:mask (int) – State mask to match
Returns:The next link that matches the given state mask, or None if no link matches.
Return type:Link
open()[source]

Opens the link.

In more detail, this moves the local state of the link to the LOCAL_ACTIVE state and triggers an attach frame to be sent to the peer. A link is fully active once both peers have attached it.

queued

The number of queued deliveries for a link.

Links may queue deliveries for a number of reasons, for example there may be insufficient credit to send them to the receiver (see credit()), or they simply may not have yet had a chance to be written to the wire. This operation will return the number of queued deliveries on a link.

Type:int
rcv_settle_mode

The local receiver settle mode for this link. One of RCV_FIRST or RCV_SECOND.

Type:int
remote_condition

The remote condition associated with the connection endpoint. See Condition for more information.

Type:Condition
remote_max_message_size

Get the remote view of the maximum message size for this link.

Warning

Unsettled API

A zero value means the size is unlimited.

Type:long
remote_rcv_settle_mode

The remote receiver settle mode for this link. One of RCV_FIRST or RCV_SECOND.

Type:int
remote_snd_settle_mode

The remote sender settle mode for this link. One of SND_UNSETTLED, SND_SETTLED or SND_MIXED.

Type:int
remote_source

The source of the link as described by the remote peer. The returned object is valid until the link is freed. The remote Terminus object will be empty until the link is remotely opened as indicated by the REMOTE_ACTIVE flag.

Type:Terminus
remote_target

The target of the link as described by the remote peer. The returned object is valid until the link is freed. The remote Terminus object will be empty until the link is remotely opened as indicated by the REMOTE_ACTIVE flag.

Type:Terminus
session

The parent session for this link.

Type:Session
snd_settle_mode

The local sender settle mode for this link. One of SND_UNSETTLED, SND_SETTLED or SND_MIXED.

Type:int
source

The source of the link as described by the local peer. The returned object is valid until the link is freed.

Type:Terminus
state

The state of the link as a bit field. The state has a local and a remote component. Each of these can be in one of three states: UNINIT, ACTIVE or CLOSED. These can be tested by masking against LOCAL_UNINIT, LOCAL_ACTIVE, LOCAL_CLOSED, REMOTE_UNINIT, REMOTE_ACTIVE and REMOTE_CLOSED.

Type:int
target

The target of the link as described by the local peer. The returned object is valid until the link is freed.

Type:Terminus
transport

The transport bound to the connection on which this link was attached.

Type:Transport
unsettled

The number of unsettled deliveries for this link.

Type:int

class proton.LinkException[source]

Bases: proton._exceptions.ProtonException

An exception class raised when exceptions or errors related to a link arise.

message

class proton.Message(body=None, **kwargs)[source]

Bases: object

The Message class is a mutable holder of message content.

Variables:
  • instructions (dict) – delivery instructions for the message (“Delivery Annotations” in the AMQP 1.0 spec)
  • annotations (dict) – infrastructure defined message annotations (“Message Annotations” in the AMQP 1.0 spec)
  • properties (dict) – application defined message properties
  • body (bytes | unicode | dict | list | int | long | float | UUID) – message body
Parameters:

kwargs – Message property name/value pairs to initialize the Message

DEFAULT_PRIORITY = 4

Default AMQP message priority

address

The address of the message.

Type:str
Raise:MessageException if there is any Proton error when using the setter.
annotations

Message annotations as a dictionary of key/values. The AMQP 1.0 specification restricts this dictionary to have keys that are either symbol or ulong types. It is possible to use the special dict subclass AnnotationDict which will by default enforce these restrictions on construction. In addition, if a string types are used, this class will silently convert them into symbols.

Type:AnnotationDict. Any dict with ulong or symbol keys.
clear()[source]

Clears the contents of the Message. All fields will be reset to their default values.

content_encoding

The content-encoding of the message.

Type:symbol
Raise:MessageException if there is any Proton error when using the setter.
content_type

The RFC-2046 [RFC2046] MIME type for the message body.

Type:symbol
Raise:MessageException if there is any Proton error when using the setter.
correlation_id

The correlation-id for the message.

Type:

The valid AMQP types for a correlation-id are one of:

  • int (unsigned)
  • uuid.UUID
  • bytes
  • str
creation_time

The creation time of the message in seconds using the Unix time_t [IEEE1003] encoding.

Type:int
Raise:MessageException if there is any Proton error when using the setter.
delivery_count

The number of delivery attempts made for this message.

Type:int
Raise:MessageException if there is any Proton error when using the setter.
durable

The durable property indicates that the message should be held durably by any intermediaries taking responsibility for the message.

Type:bool
Raise:MessageException if there is any Proton error when using the setter.
expiry_time

The absolute expiry time of the message in seconds using the Unix time_t [IEEE1003] encoding.

Type:int
Raise:MessageException if there is any Proton error when using the setter.
first_acquirer

True iff the recipient is the first to acquire the message, False otherwise.

Type:bool
Raise:MessageException if there is any Proton error when using the setter.
group_id

The group id of the message.

Type:str
Raise:MessageException if there is any Proton error when using the setter.
group_sequence

The sequence of the message within its group.

Type:int
Raise:MessageException if there is any Proton error when using the setter.
id

The globally unique id of the message, and can be used to determine if a received message is a duplicate. The allowed types to set the id are:

Type:

The valid AMQP types for an id are one of:

  • int (unsigned)
  • uuid.UUID
  • bytes
  • str
inferred

The inferred flag for a message indicates how the message content is encoded into AMQP sections. If inferred is true then binary and list values in the body of the message will be encoded as AMQP DATA and AMQP SEQUENCE sections, respectively. If inferred is false, then all values in the body of the message will be encoded as AMQP VALUE sections regardless of their type.

Type:bool
Raise:MessageException if there is any Proton error when using the setter.
instructions

Delivery annotations as a dictionary of key/values. The AMQP 1.0 specification restricts this dictionary to have keys that are either symbol or ulong types. It is possible to use the special dict subclass AnnotationDict which will by default enforce these restrictions on construction. In addition, if string types are used, this class will be silently convert them into symbols.

Type:AnnotationDict. Any dict with ulong or symbol keys.
priority

The relative priority of the message, with higher numbers indicating higher priority. The number of available priorities depends on the implementation, but AMQP defines the default priority as the value 4. See the OASIS AMQP 1.0 standard for more details on message priority.

Type:int
Raise:MessageException if there is any Proton error when using the setter.
recv(link)[source]

Receives and decodes the message content for the current Delivery from the link. Upon success it will return the current delivery for the link. If there is no current delivery, or if the current delivery is incomplete, or if the link is not a receiver, it will return None.

Parameters:link (Link) – The link to receive a message from
Returns:the delivery associated with the decoded message (or None)
Return type:Delivery
reply_to

The reply-to address for the message.

Type:str
Raise:MessageException if there is any Proton error when using the setter.
reply_to_group_id

The group-id for any replies.

Type:str
Raise:MessageException if there is any Proton error when using the setter.
send(sender, tag=None)[source]

Encodes and sends the message content using the specified sender, and, if present, using the specified tag. Upon success, will return the Delivery object for the sent message.

Parameters:
  • sender (Sender) – The sender to send the message
  • tag (bytes) – The delivery tag for the sent message
Returns:

The delivery associated with the sent message

Return type:

Delivery

subject

The subject of the message.

Type:str
Raise:MessageException if there is any Proton error when using the setter.
ttl

The time to live of the message measured in seconds. Expired messages may be dropped.

Type:int
Raise:MessageException if there is any Proton error when using the setter.
user_id

The user id of the message creator.

Type:bytes
Raise:MessageException if there is any Proton error when using the setter.

class proton.MessageException[source]

Bases: proton._exceptions.ProtonException

The MessageException class is the root of the message exception hierarchy. All exceptions generated by the Message class derive from this exception.

message

class proton.ProtonException[source]

Bases: exceptions.Exception

The root of the proton exception hierarchy. All proton exception classes derive from this exception.

message

class proton.PropertyDict(e=None, raise_on_error=True, **kwargs)[source]

Bases: proton._data.RestrictedKeyDict

A dictionary that only takes symbol types as a key. However, if a string key is provided, it will be silently converted into a symbol key.

>>> from proton import symbol, ulong, PropertyDict
>>> a = PropertyDict(one=1, two=2)
>>> b = PropertyDict({'one':1, symbol('two'):2})
>>> c = PropertyDict(zip(['one', symbol('two')], [1, 2]))
>>> d = PropertyDict([(symbol('one'), 1), ('two', 2)])
>>> e = PropertyDict(a)
>>> a == b == c == d == e
True

By default, non-string and non-symbol keys cause a KeyError to be raised:

>>> PropertyDict({'one':1, 2:'two'})
  ...
KeyError: "invalid non-symbol key: <type 'int'>: 2"

but by setting raise_on_error=False, non-string and non-symbol keys will be ignored:

>>> PropertyDict({'one':1, 2:'two'}, raise_on_error=False)
PropertyDict({2: 'two', symbol(u'one'): 1})
Parameters:
  • e (dict or list of tuple or zip object) – Initialization for dict
  • raise_on_error (bool) – If True, will raise an KeyError if a non-string or non-symbol is encountered as a key in the initialization, or in a subsequent operation which adds such an key. If False, non-strings and non-symbols will be added as keys to the dictionary without an error.
  • kwargs – Keyword args for initializing a dict of the form key1=val1, key2=val2, …
clear() → None. Remove all items from D.
copy() → a shallow copy of D
fromkeys(S[, v]) → New dict with keys from S and values equal to v.

v defaults to None.

get(k[, d]) → D[k] if k in D, else d. d defaults to None.
has_key(k) → True if D has a key k, else False
items() → list of D's (key, value) pairs, as 2-tuples
iteritems() → an iterator over the (key, value) items of D
iterkeys() → an iterator over the keys of D
itervalues() → an iterator over the values of D
keys() → list of D's keys
pop(k[, d]) → v, remove specified key and return the corresponding value.

If key is not found, d is returned if given, otherwise KeyError is raised

popitem() → (k, v), remove and return some (key, value) pair as a

2-tuple; but raise KeyError if D is empty.

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D
update(e=None, **kwargs)

Equivalent to dict.update(), but it was needed to call __setitem__() instead of dict.__setitem__().

values() → list of D's values
viewitems() → a set-like object providing a view on D's items
viewkeys() → a set-like object providing a view on D's keys
viewvalues() → an object providing a view on D's values

class proton.Receiver(impl)[source]

Bases: proton._endpoints.Link

A link over which messages are received.

LOCAL_ACTIVE = 2
LOCAL_CLOSED = 4
LOCAL_UNINIT = 1
RCV_FIRST = 0
RCV_SECOND = 1
REMOTE_ACTIVE = 16
REMOTE_CLOSED = 32
REMOTE_UNINIT = 8
SND_MIXED = 2
SND_SETTLED = 1
SND_UNSETTLED = 0
advance()

Advance the current delivery of this link to the next delivery.

For sending links this operation is used to finish sending message data for the current outgoing delivery and move on to the next outgoing delivery (if any).

For receiving links, this operation is used to finish accessing message data from the current incoming delivery and move on to the next incoming delivery (if any).

Each link maintains a sequence of deliveries in the order they were created, along with a pointer to the current delivery. The advance() operation will modify the current delivery on the link to point to the next delivery in the sequence. If there is no next delivery in the sequence, the current delivery will be set to NULL.

Returns:True if the value of the current delivery changed (even if it was set to NULL, False otherwise.
Return type:bool
available

The available deliveries hint for this link.

The available count for a link provides a hint as to the number of deliveries that might be able to be sent if sufficient credit were issued by the receiving link endpoint. See Sender.offered() for more details.

Type:int
close()

Closes the link.

In more detail, this moves the local state of the link to the LOCAL_CLOSED state and triggers an detach frame (with the closed flag set) to be sent to the peer. A link is fully closed once both peers have detached it.

This may be called without calling open(), in this case it is equivalent to calling open() followed by close().

connection

The connection on which this link was attached.

Type:Connection
credit

The amount of outstanding credit on this link.

Links use a credit based flow control scheme. Every receiver maintains a credit balance that corresponds to the number of deliveries that the receiver can accept at any given moment. As more capacity becomes available at the receiver (see Receiver.flow()), it adds credit to this balance and communicates the new balance to the sender. Whenever a delivery is sent/received, the credit balance maintained by the link is decremented by one. Once the credit balance at the sender reaches zero, the sender must pause sending until more credit is obtained from the receiver.

Note

A sending link may still be used to send deliveries even if credit reaches zero, however those deliveries will end up being buffered by the link until enough credit is obtained from the receiver to send them over the wire. In this case the balance reported by credit will go negative.

Type:int
current

The current delivery for this link.

Each link maintains a sequence of deliveries in the order they were created, along with a pointer to the current delivery. All send/recv operations on a link take place on the current delivery. If a link has no current delivery, the current delivery is automatically initialized to the next delivery created on the link. Once initialized, the current delivery remains the same until it is changed through use of advance() or until it is settled via Delivery.settle().

Return type:Delivery
delivery(tag)

Create a delivery. Every delivery object within a link must be supplied with a unique tag. Links maintain a sequence of delivery object in the order that they are created.

Parameters:tag (bytes) – Delivery tag unique for this link.
Return type:Delivery
detach()

Detach this link.

drain(n)[source]

Grant credit for incoming deliveries on this receiver, and set drain mode to true.

Use drain_mode to set the drain mode explicitly.

Parameters:n (int) – The amount by which to increment the link credit
drain_mode

The drain mode on this link.

If a link is in drain mode (True), then the sending endpoint of a link must immediately use up all available credit on the link. If this is not possible, the excess credit must be returned by invoking drained(). Only the receiving endpoint can set the drain mode.

When False, this link is not in drain mode.

Type:bool
drained()

Drain excess credit for this link.

When a link is in drain mode (see drain_mode), the sender must use all excess credit immediately, and release any excess credit back to the receiver if there are no deliveries available to send.

When invoked on a sending link that is in drain mode, this operation will release all excess credit back to the receiver and return the number of credits released back to the sender. If the link is not in drain mode, this operation is a noop.

When invoked on a receiving link, this operation will return and reset the number of credits the sender has released back to the receiver.

Returns:The number of credits drained.
Return type:int
draining()[source]

Check if a link is currently draining. A link is defined to be draining when drain mode is set to True, and the sender still has excess credit.

Returns:True if the link is currently draining, False otherwise.
Return type:bool
flow(n)[source]

Increases the credit issued to the remote sender by the specified number of messages.

Parameters:n (int) – The credit to be issued to the remote sender.
free()

Free this link object. When a link object is freed, all Delivery objects associated with the session (<– CHECK THIS) are also freed. Freeing a link will settle any unsettled deliveries on the link.

handler

Handler for events.

Getter:Get the event handler, or return None if no handler has been set.
Setter:Set the event handler.
Type:Handler or None
is_receiver

True if this link is a receiver, False otherwise.

Type:bool
is_sender

True if this link is a sender, False otherwise.

Type:bool
max_message_size

The maximum message size for this link. A zero value means the size is unlimited.

Warning

Unsettled API

Type:long
name

The name of the link.

Type:str
next(mask)

Retrieve the next link that matches the given state mask.

When used with Connection.link_head(), the application can access all links on the connection that match the given state. See Connection.link_head() for a description of match behavior.

Parameters:mask (int) – State mask to match
Returns:The next link that matches the given state mask, or None if no link matches.
Return type:Link
open()

Opens the link.

In more detail, this moves the local state of the link to the LOCAL_ACTIVE state and triggers an attach frame to be sent to the peer. A link is fully active once both peers have attached it.

queued

The number of queued deliveries for a link.

Links may queue deliveries for a number of reasons, for example there may be insufficient credit to send them to the receiver (see credit()), or they simply may not have yet had a chance to be written to the wire. This operation will return the number of queued deliveries on a link.

Type:int
rcv_settle_mode

The local receiver settle mode for this link. One of RCV_FIRST or RCV_SECOND.

Type:int
recv(limit)[source]

Receive message data for the current delivery on this receiver.

Note

The link API can be used to stream large messages across the network, so just because there is no data to read does not imply the message is complete. To ensure the entirety of the message data has been read, either invoke recv() until None is returned.

Parameters:

limit (int) – the max data size to receive of this message

Returns:

The received message data, or None if the message has been completely received.

Return type:

binary or None

Raise:
remote_condition

The remote condition associated with the connection endpoint. See Condition for more information.

Type:Condition
remote_max_message_size

Get the remote view of the maximum message size for this link.

Warning

Unsettled API

A zero value means the size is unlimited.

Type:long
remote_rcv_settle_mode

The remote receiver settle mode for this link. One of RCV_FIRST or RCV_SECOND.

Type:int
remote_snd_settle_mode

The remote sender settle mode for this link. One of SND_UNSETTLED, SND_SETTLED or SND_MIXED.

Type:int
remote_source

The source of the link as described by the remote peer. The returned object is valid until the link is freed. The remote Terminus object will be empty until the link is remotely opened as indicated by the REMOTE_ACTIVE flag.

Type:Terminus
remote_target

The target of the link as described by the remote peer. The returned object is valid until the link is freed. The remote Terminus object will be empty until the link is remotely opened as indicated by the REMOTE_ACTIVE flag.

Type:Terminus
session

The parent session for this link.

Type:Session
snd_settle_mode

The local sender settle mode for this link. One of SND_UNSETTLED, SND_SETTLED or SND_MIXED.

Type:int
source

The source of the link as described by the local peer. The returned object is valid until the link is freed.

Type:Terminus
state

The state of the link as a bit field. The state has a local and a remote component. Each of these can be in one of three states: UNINIT, ACTIVE or CLOSED. These can be tested by masking against LOCAL_UNINIT, LOCAL_ACTIVE, LOCAL_CLOSED, REMOTE_UNINIT, REMOTE_ACTIVE and REMOTE_CLOSED.

Type:int
target

The target of the link as described by the local peer. The returned object is valid until the link is freed.

Type:Terminus
transport

The transport bound to the connection on which this link was attached.

Type:Transport
unsettled

The number of unsettled deliveries for this link.

Type:int

class proton.SASL(transport)[source]

Bases: proton._wrapper.Wrapper

The SASL layer is responsible for establishing an authenticated and/or encrypted tunnel over which AMQP frames are passed between peers. The peer acting as the SASL Client must provide authentication credentials. The peer acting as the SASL Server must provide authentication against the received credentials.

AUTH = 1
OK = 0
PERM = 3
SYS = 2
TEMP = 4
allow_insecure_mechs

Allow unencrypted cleartext passwords (PLAIN mech)

allowed_mechs(mechs)[source]

SASL mechanisms that are to be considered for authentication.

This can be used on either the client or the server to restrict the SASL mechanisms that may be used to the mechanisms on the list.

NOTE: By default the GSSAPI and GSS-SPNEGO mechanisms are not enabled for clients. This is because these mechanisms have the problematic behaviour of ‘capturing’ the client whenever they are installed so that they will be used by the client if offered by the server even if the client can’t successfully authenticate this way. This can lead to some very hard to debug failures.

NOTE: The GSSAPI or GSS-SPNEGO mechanisms need to be explicitly enabled if they are required (together with any other required mechanisms).

Parameters:mechs (string) – A list of mechanisms that are allowed for authentication, either a string containing a space-separated list of mechs "mech1 mech2 ...", or a Python list of strings ["mech1", "mech2", ...].
config_name(name)[source]

Set the SASL configuration name. This is used to construct the SASL configuration filename. In the current implementation ".conf" is added to the name and the file is looked for in the configuration directory.

If not set it will default to "proton-server" for a sasl server and "proton-client" for a client.

Parameters:name (string) – The configuration name.
config_path(path)[source]

Set the SASL configuration path. This is used to tell SASL where to look for the configuration file. In the current implementation it can be a colon separated list of directories.

The environment variable PN_SASL_CONFIG_PATH can also be used to set this path, but if both methods are used then this config_path() will take precedence.

If not set, the underlying implementation default will be used.

Parameters:path (string) – The configuration path, may contain colon-separated list if more than one path is specified.
done(outcome)[source]

Set the outcome of SASL negotiation. Used by the server to set the result of the negotiation process.

static extended()[source]

Check for support of extended SASL negotiation.

All implementations of Proton support ANONYMOUS and EXTERNAL on both client and server sides and PLAIN on the client side.

Extended SASL implementations use an external library (Cyrus SASL) to support other mechanisms beyond these basic ones.

Return type:True if we support extended SASL negotiation, False if we only support basic negotiation.
mech

Return the selected SASL mechanism.

The returned value is only reliable after the PN_TRANSPORT_AUTHENTICATED event has been received.

Return type:The authentication mechanism selected by the SASL layer.
outcome

Retrieve the outcome of SASL negotiation.

Return type:
  • None if no negotiation has taken place.
  • Otherwise the outcome of the negotiation.
user

Retrieve the authenticated user. This is usually used at the the server end to find the name of the authenticated user.

If outcome() returns a value other than OK, then there will be no user to return. The returned value is only reliable after the PN_TRANSPORT_AUTHENTICATED event has been received.

Return type:
  • If the SASL layer was not negotiated then 0 is returned.
  • If the ANONYMOUS mechanism is used then the user will be "anonymous".
  • Otherwise a string containing the user is returned.

class proton.Sender(impl)[source]

Bases: proton._endpoints.Link

A link over which messages are sent.

LOCAL_ACTIVE = 2
LOCAL_CLOSED = 4
LOCAL_UNINIT = 1
RCV_FIRST = 0
RCV_SECOND = 1
REMOTE_ACTIVE = 16
REMOTE_CLOSED = 32
REMOTE_UNINIT = 8
SND_MIXED = 2
SND_SETTLED = 1
SND_UNSETTLED = 0
advance()

Advance the current delivery of this link to the next delivery.

For sending links this operation is used to finish sending message data for the current outgoing delivery and move on to the next outgoing delivery (if any).

For receiving links, this operation is used to finish accessing message data from the current incoming delivery and move on to the next incoming delivery (if any).

Each link maintains a sequence of deliveries in the order they were created, along with a pointer to the current delivery. The advance() operation will modify the current delivery on the link to point to the next delivery in the sequence. If there is no next delivery in the sequence, the current delivery will be set to NULL.

Returns:True if the value of the current delivery changed (even if it was set to NULL, False otherwise.
Return type:bool
available

The available deliveries hint for this link.

The available count for a link provides a hint as to the number of deliveries that might be able to be sent if sufficient credit were issued by the receiving link endpoint. See Sender.offered() for more details.

Type:int
close()

Closes the link.

In more detail, this moves the local state of the link to the LOCAL_CLOSED state and triggers an detach frame (with the closed flag set) to be sent to the peer. A link is fully closed once both peers have detached it.

This may be called without calling open(), in this case it is equivalent to calling open() followed by close().

connection

The connection on which this link was attached.

Type:Connection
credit

The amount of outstanding credit on this link.

Links use a credit based flow control scheme. Every receiver maintains a credit balance that corresponds to the number of deliveries that the receiver can accept at any given moment. As more capacity becomes available at the receiver (see Receiver.flow()), it adds credit to this balance and communicates the new balance to the sender. Whenever a delivery is sent/received, the credit balance maintained by the link is decremented by one. Once the credit balance at the sender reaches zero, the sender must pause sending until more credit is obtained from the receiver.

Note

A sending link may still be used to send deliveries even if credit reaches zero, however those deliveries will end up being buffered by the link until enough credit is obtained from the receiver to send them over the wire. In this case the balance reported by credit will go negative.

Type:int
current

The current delivery for this link.

Each link maintains a sequence of deliveries in the order they were created, along with a pointer to the current delivery. All send/recv operations on a link take place on the current delivery. If a link has no current delivery, the current delivery is automatically initialized to the next delivery created on the link. Once initialized, the current delivery remains the same until it is changed through use of advance() or until it is settled via Delivery.settle().

Return type:Delivery
delivery(tag)

Create a delivery. Every delivery object within a link must be supplied with a unique tag. Links maintain a sequence of delivery object in the order that they are created.

Parameters:tag (bytes) – Delivery tag unique for this link.
Return type:Delivery
delivery_tag()[source]

HELP! I have no idea what is going on with this! Link.next() returns a Link, not a Delivery.

detach()

Detach this link.

drain_mode

The drain mode on this link.

If a link is in drain mode (True), then the sending endpoint of a link must immediately use up all available credit on the link. If this is not possible, the excess credit must be returned by invoking drained(). Only the receiving endpoint can set the drain mode.

When False, this link is not in drain mode.

Type:bool
drained()

Drain excess credit for this link.

When a link is in drain mode (see drain_mode), the sender must use all excess credit immediately, and release any excess credit back to the receiver if there are no deliveries available to send.

When invoked on a sending link that is in drain mode, this operation will release all excess credit back to the receiver and return the number of credits released back to the sender. If the link is not in drain mode, this operation is a noop.

When invoked on a receiving link, this operation will return and reset the number of credits the sender has released back to the receiver.

Returns:The number of credits drained.
Return type:int
free()

Free this link object. When a link object is freed, all Delivery objects associated with the session (<– CHECK THIS) are also freed. Freeing a link will settle any unsettled deliveries on the link.

handler

Handler for events.

Getter:Get the event handler, or return None if no handler has been set.
Setter:Set the event handler.
Type:Handler or None
is_receiver

True if this link is a receiver, False otherwise.

Type:bool
is_sender

True if this link is a sender, False otherwise.

Type:bool
max_message_size

The maximum message size for this link. A zero value means the size is unlimited.

Warning

Unsettled API

Type:long
name

The name of the link.

Type:str
next(mask)

Retrieve the next link that matches the given state mask.

When used with Connection.link_head(), the application can access all links on the connection that match the given state. See Connection.link_head() for a description of match behavior.

Parameters:mask (int) – State mask to match
Returns:The next link that matches the given state mask, or None if no link matches.
Return type:Link
offered(n)[source]

Signal the availability of deliveries for this Sender.

Parameters:n (int) – Credit the number of deliveries potentially available for transfer.
open()

Opens the link.

In more detail, this moves the local state of the link to the LOCAL_ACTIVE state and triggers an attach frame to be sent to the peer. A link is fully active once both peers have attached it.

queued

The number of queued deliveries for a link.

Links may queue deliveries for a number of reasons, for example there may be insufficient credit to send them to the receiver (see credit()), or they simply may not have yet had a chance to be written to the wire. This operation will return the number of queued deliveries on a link.

Type:int
rcv_settle_mode

The local receiver settle mode for this link. One of RCV_FIRST or RCV_SECOND.

Type:int
remote_condition

The remote condition associated with the connection endpoint. See Condition for more information.

Type:Condition
remote_max_message_size

Get the remote view of the maximum message size for this link.

Warning

Unsettled API

A zero value means the size is unlimited.

Type:long
remote_rcv_settle_mode

The remote receiver settle mode for this link. One of RCV_FIRST or RCV_SECOND.

Type:int
remote_snd_settle_mode

The remote sender settle mode for this link. One of SND_UNSETTLED, SND_SETTLED or SND_MIXED.

Type:int
remote_source

The source of the link as described by the remote peer. The returned object is valid until the link is freed. The remote Terminus object will be empty until the link is remotely opened as indicated by the REMOTE_ACTIVE flag.

Type:Terminus
remote_target

The target of the link as described by the remote peer. The returned object is valid until the link is freed. The remote Terminus object will be empty until the link is remotely opened as indicated by the REMOTE_ACTIVE flag.

Type:Terminus
send(obj, tag=None)[source]

A convenience method to send objects as message content.

Send specified object over this sender; the object is expected to have a send() method on it that takes the sender and an optional tag as arguments.

Where the object is a Message, this will send the message over this link, creating a new delivery for the purpose.

session

The parent session for this link.

Type:Session
snd_settle_mode

The local sender settle mode for this link. One of SND_UNSETTLED, SND_SETTLED or SND_MIXED.

Type:int
source

The source of the link as described by the local peer. The returned object is valid until the link is freed.

Type:Terminus
state

The state of the link as a bit field. The state has a local and a remote component. Each of these can be in one of three states: UNINIT, ACTIVE or CLOSED. These can be tested by masking against LOCAL_UNINIT, LOCAL_ACTIVE, LOCAL_CLOSED, REMOTE_UNINIT, REMOTE_ACTIVE and REMOTE_CLOSED.

Type:int
stream(data)[source]

Send specified data as part of the current delivery.

Parameters:data (binary) – Data to send
target

The target of the link as described by the local peer. The returned object is valid until the link is freed.

Type:Terminus
transport

The transport bound to the connection on which this link was attached.

Type:Transport
unsettled

The number of unsettled deliveries for this link.

Type:int

class proton.Session(impl)[source]

Bases: proton._wrapper.Wrapper, proton._endpoints.Endpoint

A container of links

LOCAL_ACTIVE = 2
LOCAL_CLOSED = 4
LOCAL_UNINIT = 1
REMOTE_ACTIVE = 16
REMOTE_CLOSED = 32
REMOTE_UNINIT = 8
close()[source]

Close a session.

Once this operation has completed, the LOCAL_CLOSED state flag will be set. This may be called without calling open(), in this case it is equivalent to calling open() followed by close().

connection

The parent connection for this session.

Type:Connection
free()[source]

Free this session. When a session is freed it will no longer be retained by the connection once any internal references to the session are no longer needed. Freeing a session will free all links on that session and settle any deliveries on those links.

handler

Handler for events.

Getter:Get the event handler, or return None if no handler has been set.
Setter:Set the event handler.
Type:Handler or None
incoming_bytes

The number of incoming bytes currently buffered.

Type:int (bytes)
incoming_capacity

The incoming capacity of this session in bytes. The incoming capacity of a session determines how much incoming message data the session can buffer.

Note

If set, this value must be greater than or equal to the negotiated frame size of the transport. The window is computed as a whole number of frames when dividing remaining capacity at a given time by the connection max frame size. As such, capacity and max frame size should be chosen so as to ensure the frame window isn’t unduly small and limiting performance.

Type:int (bytes)
next(mask)[source]

Retrieve the next session for this connection that matches the specified state mask.

When used with Connection.session_head(), application can access all sessions on the connection that match the given state. See Connection.session_head() for description of match behavior.

Parameters:mask – Mask to match.
Returns:The next session owned by this connection that matches the mask, else None if no sessions match.
Return type:Session or None
open()[source]

Open a session. Once this operation has completed, the LOCAL_ACTIVE state flag will be set.

outgoing_bytes

The number of outgoing bytes currently buffered.

Type:int (bytes)
outgoing_window

The outgoing window for this session.

Type:int
receiver(name)[source]

Create a new Receiver on this session.

Parameters:name (str) – Name of receiver
Returns:New Receiver object
Return type:Receiver
remote_condition

The remote condition associated with the connection endpoint. See Condition for more information.

Type:Condition
sender(name)[source]

Create a new Sender on this session.

Parameters:name (str) – Name of sender
Returns:New Sender object
Return type:Sender
state

The endpoint state flags for this session. See Endpoint for details of the flags.

Type:int
transport

The transport bound to the parent connection for this session.

Type:Transport

class proton.SessionException[source]

Bases: proton._exceptions.ProtonException

An exception class raised when exceptions or errors related to a session arise.

message

class proton.SSL[source]

Bases: object

An SSL session associated with a transport. A transport must have an SSL object in order to “speak” SSL over its connection.

CERT_CITY_OR_LOCALITY = 2

Certificate city or place name, not abbreviated

CERT_COMMON_NAME = 5

Certificate common name or URL

CERT_COUNTRY_NAME = 0

Certificate country name 2-char ISO code

CERT_ORGANIZATION_NAME = 3

Certificate organization name

CERT_ORGANIZATION_UNIT = 4

Certificate organization unit or division within organization

CERT_STATE_OR_PROVINCE = 1

Certificate state or province, not abbreviated

MD5 = 3

Produces hash that is 16 bytes long using MD5

RESUME_NEW = 1

Session renegotiated - not resumed.

RESUME_REUSED = 2

Session resumed from previous session.

RESUME_UNKNOWN = 0

Session resume state unknown/not supported.

SHA1 = 0

Produces hash that is 20 bytes long using SHA-1

SHA256 = 1

Produces hash that is 32 bytes long using SHA-256

SHA512 = 2

Produces hash that is 64 bytes long using SHA-512

cipher_name()[source]

Get the name of the Cipher that is currently in use.

Gets a text description of the cipher that is currently active, or returns None if SSL is not active (no cipher).

Note

The cipher in use may change over time due to renegotiation or other changes to the SSL state.

Returns:The cypher name, or None if no cipher in use.
Return type:str or None
get_cert_common_name()[source]

A convenience method to get a string that contains the CERT_COMMON_NAME sub field of the subject field in the ssl certificate.

Returns:A string containing the CERT_COMMON_NAME sub field.
Return type:str
get_cert_country()[source]

A convenience method to get a string that contains the CERT_COUNTRY_NAME sub field of the subject field in the ssl certificate.

Returns:A string containing the CERT_COUNTRY_NAME sub field.
Return type:str
get_cert_fingerprint(fingerprint_length, digest_name)[source]

Get the fingerprint of the certificate. The certificate fingerprint (as displayed in the Fingerprints section when looking at a certificate with say the Firefox browser) is the hexadecimal hash of the entire certificate. The fingerprint is not part of the certificate, rather it is computed from the certificate and can be used to uniquely identify a certificate.

Parameters:
  • fingerprint_length (int) – Must be \(>= 33\) for md5, \(>= 41\) for sha1, \(>= 65\) for sha256 and \(>= 129\) for sha512.
  • digest_name (str) – The hash algorithm to use. Must be one of SHA1, SHA256, SHA512, MD5.
Returns:

Hex fingerprint in a string, or None if an error occurred.

Return type:

str or None

get_cert_fingerprint_md5()[source]

A convenience method to get the MD5 fingerprint of the certificate.

Returns:Hex fingerprint in a string, or None if an error occurred.
Return type:str or None
get_cert_fingerprint_sha1()[source]

A convenience method to get the SHA1 fingerprint of the certificate.

Returns:Hex fingerprint in a string, or None if an error occurred.
Return type:str or None
get_cert_fingerprint_sha256()[source]

A convenience method to get the SHA256 fingerprint of the certificate.

Returns:Hex fingerprint in a string, or None if an error occurred.
Return type:str or None
get_cert_fingerprint_sha512()[source]

A convenience method to get the SHA512 fingerprint of the certificate.

Returns:Hex fingerprint in a string, or None if an error occurred.
Return type:str or None
get_cert_locality_or_city()[source]

A convenience method to get a string that contains the CERT_CITY_OR_LOCALITY sub field of the subject field in the ssl certificate.

Returns:A string containing the CERT_CITY_OR_LOCALITY sub field.
Return type:str
get_cert_organization()[source]

A convenience method to get a string that contains the CERT_ORGANIZATION_NAME sub field of the subject field in the ssl certificate.

Returns:A string containing the CERT_ORGANIZATION_NAME sub field.
Return type:str
get_cert_organization_unit()[source]

A convenience method to get a string that contains the CERT_ORGANIZATION_UNIT sub field of the subject field in the ssl certificate.

Returns:A string containing the CERT_ORGANIZATION_UNIT sub field.
Return type:str
get_cert_state_or_province()[source]

A convenience method to get a string that contains the CERT_STATE_OR_PROVINCE sub field of the subject field in the ssl certificate.

Returns:A string containing the CERT_STATE_OR_PROVINCE sub field.
Return type:str
get_cert_subject()[source]

Get the subject from the peer’s certificate.

Returns:A string containing the full subject.
Return type:str
get_cert_subject_subfield(subfield_name)[source]

Returns a string that contains the value of the sub field of the subject field in the ssl certificate. The subject field usually contains the following values:

Parameters:subfield_name (int) – The enumeration representing the required sub field listed above
Returns:A string which contains the requested sub field value which is valid until the ssl object is destroyed.
Return type:str
peer_hostname

Manage the expected name of the remote peer.

The hostname is used for two purposes:

  1. when set on an SSL client, it is sent to the server during the handshake (if Server Name Indication is supported)
  2. it is used to check against the identifying name provided in the peer’s certificate. If the supplied name does not exactly match a SubjectAltName (type DNS name), or the CommonName entry in the peer’s certificate, the peer is considered unauthenticated (potential imposter), and the SSL connection is aborted.

Note

Verification of the hostname is only done if SSLDomain.VERIFY_PEER_NAME is set using SSLDomain.set_peer_authentication().

Type:str
static present()[source]

Tests for an SSL implementation being present.

Returns:True if we support SSL, False if not.
Return type:bool
protocol_name()[source]

Get the name of the SSL protocol that is currently in use.

Gets a text description of the SSL protocol that is currently active, or returns None if SSL is not active.

Note

The protocol may change over time due to renegotiation.

Returns:The protocol name if SSL is active, or None if SSL connection is not ready or active.
Return type:str or None
remote_subject

The subject from the peers certificate.

Type:str
resume_status()[source]

Check whether the state has been resumed.

Used for client session resume. When called on an active session, indicates whether the state has been resumed from a previous session.

Note

This is a best-effort service - there is no guarantee that the remote server will accept the resumed parameters. The remote server may choose to ignore these parameters, and request a re-negotiation instead.

Returns:Status code indicating whether or not the session has been resumed. One of: * RESUME_UNKNOWN * RESUME_NEW * RESUME_REUSED
Return type:int

class proton.SSLDomain(mode)[source]

Bases: object

An SSL configuration domain, used to hold the SSL configuration for one or more SSL sessions.

ANONYMOUS_PEER = 2

Do not require a certificate nor cipher authorization.

MODE_CLIENT = 1

Local connection endpoint is an SSL client.

MODE_SERVER = 2

Local connection endpoint is an SSL server.

VERIFY_PEER = 1

Require peer to provide a valid identifying certificate.

VERIFY_PEER_NAME = 3

Require valid certificate and matching name.

allow_unsecured_client()[source]

Permit a server to accept connection requests from non-SSL clients.

This configures the server to “sniff” the incoming client data stream, and dynamically determine whether SSL/TLS is being used. This option is disabled by default: only clients using SSL/TLS are accepted.

Raise:SSLException if there is any Proton error
set_credentials(cert_file, key_file, password)[source]

Set the certificate that identifies the local node to the remote.

This certificate establishes the identity for the local node for all SSL sessions created from this domain. It will be sent to the remote if the remote needs to verify the identity of this node. This may be used for both SSL servers and SSL clients (if client authentication is required by the server).

Note

This setting effects only those SSL objects created after this call returns. SSL objects created before invoking this method will use the domain’s previous setting.

Parameters:
  • cert_file (str) – Specifier for the file/database containing the identifying certificate. For Openssl users, this is a PEM file. For Windows SChannel users, this is the PKCS#12 file or system store.
  • key_file (str) – An optional key to access the identifying certificate. For Openssl users, this is an optional PEM file containing the private key used to sign the certificate. For Windows SChannel users, this is the friendly name of the self-identifying certificate if there are multiple certificates in the store.
  • password (str) – The password used to sign the key, else None if key is not protected.
Returns:

0 on success

Return type:

int

Raise:

SSLException if there is any Proton error

set_peer_authentication(verify_mode, trusted_CAs=None)[source]

This method controls how the peer’s certificate is validated, if at all. By default, neither servers nor clients attempt to verify their peers (PN_SSL_ANONYMOUS_PEER). Once certificates and trusted CAs are configured, peer verification can be enabled.

Note

In order to verify a peer, a trusted CA must be configured. See set_trusted_ca_db().

Note

Servers must provide their own certificate when verifying a peer. See set_credentials().

Note

This setting effects only those SSL objects created after this call returns. SSL objects created before invoking this method will use the domain’s previous setting.

Parameters:
  • verify_mode (int) – The level of validation to apply to the peer, one of VERIFY_PEER, VERIFY_PEER_NAME, ANONYMOUS_PEER,
  • trusted_CAs (str) – Path to a database of trusted CAs that the server will advertise.
Returns:

0 on success

Return type:

int

Raise:

SSLException if there is any Proton error

set_trusted_ca_db(certificate_db)[source]

Configure the set of trusted CA certificates used by this domain to verify peers.

If the local SSL client/server needs to verify the identity of the remote, it must validate the signature of the remote’s certificate. This function sets the database of trusted CAs that will be used to verify the signature of the remote’s certificate.

Note

This setting effects only those SSL objects created after this call returns. SSL objects created before invoking this method will use the domain’s previous setting.

Note

By default the list of trusted CA certificates will be set to the system default. What this is is depends on the OS and the SSL implementation used: For OpenSSL the default will depend on how the OS is set up. When using the Windows SChannel implementation the default will be the users default trusted certificate store.

Parameters:certificate_db (str) – Database of trusted CAs, used to authenticate the peer.
Returns:0 on success
Return type:int
Raise:SSLException if there is any Proton error

class proton.SSLSessionDetails(session_id)[source]

Bases: object

Unique identifier for the SSL session. Used to resume previous session on a new SSL connection.

get_session_id()[source]

Get the unique identifier for this SSL session

Returns:Session identifier
Return type:str

class proton.SSLUnavailable[source]

Bases: proton._exceptions.SSLException

An exception class raised when exceptions or errors related to SSL availability arise. These typically include problems finding the SSL libraries.

message

class proton.SSLException[source]

Bases: proton._exceptions.TransportException

An exception class raised when exceptions or errors related to SSL usage arise. These typically include problems with initializing or configuring SSL.

message

class proton.SymbolList(t=None, raise_on_error=True)[source]

Bases: list

A list that can only hold symbol elements. However, if any string elements are present, they will be converted to symbols.

>>> a = SymbolList(['one', symbol('two'), 'three'])
>>> b = SymbolList([symbol('one'), 'two', symbol('three')])
>>> c = SymbolList(a)
>>> a == b == c
True

By default, using any key other than a symbol or string will result in a TypeError:

>>> SymbolList(['one', symbol('two'), 3])
  ...
TypeError: Non-symbol type <class 'int'>: 3

but by setting raise_on_error=False, non-symbol and non-string keys will be ignored:

>>> SymbolList(['one', symbol('two'), 3], raise_on_error=False)
SymbolList([symbol(u'one'), symbol(u'two'), 3])
Parameters:
  • t (list) – Initialization for list
  • raise_on_error (bool) – If True, will raise an TypeError if a non-string or non-symbol is encountered in the initialization list, or in a subsequent operation which adds such an element. If False, non-strings and non-symbols will be added to the list without an error.
append(v)[source]

Add a single value v to the end of the list

count(value) → integer -- return number of occurrences of value
extend(t)[source]

Add all elements of an iterable t to the end of the list

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

insert(i, v)[source]

Insert a value v at index i

pop([index]) → item -- remove and return item at index (default last).

Raises IndexError if list is empty or index is out of range.

remove()

L.remove(value) – remove first occurrence of value. Raises ValueError if the value is not present.

reverse()

L.reverse() – reverse IN PLACE

sort()

L.sort(cmp=None, key=None, reverse=False) – stable sort IN PLACE; cmp(x, y) -> -1, 0, 1


class proton.Terminus(impl)[source]

Bases: object

A source or target for messages.

CONFIGURATION = 1

A terminus with durably held configuration, but not delivery state.

COORDINATOR = 3

A special target identifying a transaction coordinator.

DELIVERIES = 2

A terminus with both durably held configuration and durably held delivery state.

DIST_MODE_COPY = 1

The receiver gets all messages.

DIST_MODE_MOVE = 2

The receiver competes for messages.

DIST_MODE_UNSPECIFIED = 0

The behavior is defined by the node.

EXPIRE_NEVER = 3

The terminus is never considered orphaned

EXPIRE_WITH_CONNECTION = 2

The terminus is orphaned when the parent connection is closed

The terminus is orphaned when the parent link is closed.

EXPIRE_WITH_SESSION = 1

The terminus is orphaned when the parent session is closed

NONDURABLE = 0

A non durable terminus.

SOURCE = 1

A source of messages.

TARGET = 2

A target for messages.

UNSPECIFIED = 0

A nonexistent terminus, may used as a source or target.

address

The terminus address.

Type:str
capabilities

Capabilities of the source or target.

Type:Data containing an array of symbol.
copy(src)[source]

Copy another terminus object.

Parameters:src (Terminus) – The terminus to be copied from
Raises:LinkException if there is an error
distribution_mode

The terminus distribution mode, must be one of DIST_MODE_UNSPECIFIED, DIST_MODE_COPY or DIST_MODE_MOVE.

Type:int
durability

The terminus durability mode, must be one of NONDURABLE, CONFIGURATION or DELIVERIES.

Type:int
dynamic

The dynamic flag for this terminus object. This indicates if this terminus was dynamically created.

Type:bool
expiry_policy

The terminus expiry policy, must be one of EXPIRE_WITH_LINK, EXPIRE_WITH_SESSION, EXPIRE_WITH_CONNECTION or EXPIRE_NEVER.

Type:int
filter

A filter on a source allows the set of messages transfered over the link to be restricted. The symbol-keyed map represents a’ filter set.

Type:Data containing a map with symbol keys.
outcomes

Outcomes of the source or target.

Type:Data containing an array of symbol.
properties

Properties of a dynamic source or target.

Type:Data containing a map with symbol keys.
timeout

The terminus timeout in seconds.

Type:int
type

The terminus type, must be one of UNSPECIFIED, SOURCE, TARGET or COORDINATOR

Type:int

class proton.Timeout[source]

Bases: proton._exceptions.ProtonException

A timeout exception indicates that a blocking operation has timed out.

message

class proton.Interrupt[source]

Bases: proton._exceptions.ProtonException

An interrupt exception indicates that a blocking operation was interrupted.

message

class proton.Transport(mode=None, _impl=<built-in function pn_transport>)[source]

Bases: proton._wrapper.Wrapper

A network channel supporting an AMQP connection.

CLIENT = 1

Transport mode is as a client.

SERVER = 2

Transport mode is as a server.

TRACE_DRV = 4

Log driver-related events.

TRACE_FRM = 2

Log protocol frames going in and out of the transport.

TRACE_OFF = 0

Turn logging off entirely.

TRACE_RAW = 1

Log raw binary data going in and out of the transport.

authenticated

Indicate whether the transport connection is authenticated.

Note

This property may not be stable until the Event.CONNECTION_REMOTE_OPEN event is received.

Type:bool
bind(connection)[source]

Assign a connection to the transport.

Parameters:connection (Connection) – Connection to which to bind.
Raise:TransportException if there is any Proton error.
bind_nothrow(connection)[source]

Assign a connection to the transport. Any failure is ignored rather than thrown.

Parameters:connection (Connection) – Connection to which to bind.
capacity()[source]

Get the amount of free space for input following the transport’s tail pointer.

Returns:Available space for input in bytes.
Return type:int
Raise:TransportException if there is any Proton error.
channel_max

The maximum channel number that may be used on this transport.

Note

This is the maximum channel number allowed, giving a valid channel number range of [0 .. channel_max]. Therefore the maximum number of simultaneously active channels will be channel_max plus 1.

You can set this more than once to raise and lower the limit your application imposes on max channels for this transport. However, smaller limits may be imposed by Proton, or by the remote peer.

After the OPEN frame has been sent to the remote peer, further calls to this function will have no effect.

Type:int
Raise:SessionException if the OPEN frame has already been sent.
close_head()[source]

Indicate that the output has closed.

This tells the transport that no more output will be popped.

Raise:TransportException if there is any Proton error.
close_tail()[source]

Indicate that the input has reached End Of Stream (EOS).

This tells the transport that no more input will be forthcoming.

Raise:TransportException if there is any Proton error.
closed

True iff both the transport head and transport tail are closed using close_head() and close_tail() respectively.

Type:bool
condition

Get additional information about the condition of the transport.

When a Event.TRANSPORT_ERROR event occurs, this operation can be used to access the details of the error condition.

See Condition for more information.

Type:Condition
connection

The connection bound to this transport.

Type:Connection
encrypted

Indicate whether the transport connection is encrypted.

Note

This property may not be stable until the Event.CONNECTION_REMOTE_OPEN event is received.

Type:bool
frames_input

Get the number of frames input by a transport.

Type:int
frames_output

Get the number of frames output by a transport.

Type:int
idle_timeout

The idle timeout of the connection in seconds. A zero idle timeout means heartbeats are disabled.

Type:float
log(message)[source]

Log a message using a transport’s logging mechanism.

This can be useful in a debugging context as the log message will be prefixed with the transport’s identifier.

Parameters:message (str) – The message to be logged.
max_frame_size

The maximum size for transport frames (in bytes).

Type:int
peek(size)[source]

Returns size bytes from the head of the transport.

It is an error to call this with a value of size that is greater than the value reported by pending().

Parameters:size (int) – Number of bytes to return.
Returns:size bytes from the head of the transport, or None if none are available.
Return type:bytes
Raise:TransportException if there is any Proton error.
pending()[source]

Get the number of pending output bytes following the transport’s head pointer.

Returns:The number of pending output bytes.
Return type:int
Raise:TransportException if there is any Proton error.
pop(size)[source]

Removes size bytes of output from the pending output queue following the transport’s head pointer.

Calls to this function may alter the transport’s head pointer as well as the number of pending bytes reported by pending().

Parameters:size (int) – Number of bytes to return.
push(binary)[source]

Pushes the supplied bytes into the tail of the transport. Only some of the bytes will be copied if there is insufficient capacity available. Use capacity() to determine how much capacity the transport has.

Parameters:

binary (bytes) – Data to be pushed onto the transport tail.

Raise:
  • TransportException if there is any Proton error.
  • OverflowError if the size of the data exceeds the transport capacity.
remote_channel_max

The maximum allowed channel number of a transport’s remote peer.

Type:int
remote_idle_timeout

Get the idle timeout for a transport’s remote peer in seconds. A zero idle timeout means heartbeats are disabled.

Type:float
remote_max_frame_size

The maximum frame size of a transport’s remote peer (in bytes).

Type:int
require_auth(bool)[source]

Set whether a non-authenticated transport connection is allowed.

There are several ways within the AMQP protocol suite to get unauthenticated connections:

  • Use no SASL layer (with either no TLS or TLS without client certificates)
  • Use a SASL layer but the ANONYMOUS mechanism

The default if this option is not set is to allow unauthenticated connections.

Parameters:bool (bool) – True when authenticated connections are required.
require_encryption(bool)[source]

Set whether a non encrypted transport connection is allowed

There are several ways within the AMQP protocol suite to get encrypted connections:

  • Use TLS
  • Use a SASL with a mechanism that supports security layers

The default if this option is not set is to allow unencrypted connections.

Parameters:bool (bool) – True if encryption is required on this transport, False otherwise.
sasl()[source]

Get the SASL object associated with this transport.

Returns:SASL object associated with this transport.
Return type:SASL
ssl(domain=None, session_details=None)[source]

Get the SSL session associated with this transport. If not set, then a new session will be created using domain and session_details.

Parameters:
  • domain (SSLDomain) – An SSL domain configuration object
  • session_details (SSLSessionDetails) – A unique identifier for the SSL session.
Returns:

SSL session associated with this transport.

Return type:

SSL

tick(now)[source]

Process any pending transport timer events (like heartbeat generation).

This method should be called after all pending input has been processed by the transport and before generating output. It returns the deadline for the next pending timer event, if any are present.

Note

This function does nothing until the first data is read from or written to the transport.

Parameters:now (float) – seconds since epoch.
Returns:If non-zero, then the monotonic expiration time of the next pending timer event for the transport. The caller must invoke tick() again at least once at or before this deadline occurs. If 0.0, then there are no pending events.
Return type:float
trace(n)[source]

Update a transports trace flags.

The trace flags for a transport control what sort of information is logged. The value may be TRACE_OFF or any combination of TRACE_DRV, TRACE_FRM, TRACE_RAW using a bitwise or operation.

Parameters:n (int) – Trace flags
tracer

A callback for trace logging. The callback is passed the transport and log message. For no tracer callback, value is None.

Type:Tracer callback function
unbind()[source]

Unbinds a transport from its AMQP connection.

Raise:TransportException if there is any Proton error.
user

The authenticated user.

On the client it will return whatever user was passed in to the Connection.user attribute of the bound connection.

The returned value is only reliable after the PN_TRANSPORT_AUTHENTICATED event has been received.

Type:str

class proton.TransportException[source]

Bases: proton._exceptions.ProtonException

An exception class raised when exceptions or errors related to the AMQP transport arise.

message

class proton.Url(url=None, defaults=True, **kwargs)[source]

Bases: object

DEPRECATED Simple URL parser/constructor.

Deprecated since version 0.27: Use a str containing the URL instead.

Handles URLs of the form:

<scheme>://<user>:<password>@<host>:<port>/<path>

All components can be None if not specified in the URL string.

The port can be specified as a service name, e.g. ‘amqp’ in the URL string but Url.Port always gives the integer value.

Warning

The placement of user and password in URLs is not recommended. It can result in credentials leaking out in program logs. Use connection configuration attributes instead.

Variables:
  • scheme – Url scheme e.g. ‘amqp’ or ‘amqps’
  • username – Username
  • password – Password
  • host – Host name, ipv6 literal or ipv4 dotted quad.
  • port – Integer port.
  • host_port – Returns host:port
Parameters:
  • url (str) – URL string to parse.
  • defaults (bool) – If True, fill in missing default values in the URL. If False, you can fill them in later by calling self.defaults()
  • kwargs – scheme, user, password, host, port, path. If specified, replaces corresponding part in url string.
AMQP = 'amqp'

URL scheme for the AMQP protocol.

AMQPS = 'amqps'

URL scheme for the AMQP protocol secured with SSL.

class Port[source]

Bases: int

An integer port number that can be constructed from a service name string

defaults()[source]

Fill in missing values (scheme, host or port) with defaults :return: self

host

The host segment of a URL

Type:str
path

The path segment of a URL

Type:str
port

The port number segment of a URL.

Type:Url.Port

class proton.Array(descriptor, type, *elements)[source]

Bases: object

An AMQP array, a sequence of AMQP values of a single type.

This class provides a convenient way to handle AMQP arrays when used with convenience methods Data.get_py_array() and Data.put_py_array().

Variables:
  • descriptor – Optional descriptor if the array is to be described, otherwise None
  • type – Array element type, as an integer. The Data class has constants defined for all the valid AMQP types. For example, for an array of double values, use Data.DOUBLE, which has integer value 14.
  • elements – A Python list of elements of the appropriate type.

class proton.byte[source]

Bases: int

The byte AMQP type.

An 8 bit signed integer in the range \(-(2^7)\) to \(2^7 - 1\) inclusive.


class proton.char[source]

Bases: unicode

The char AMQP type.

A 32 bit UTF-32BE encoded Unicode character.


class proton.decimal32[source]

Bases: int

The decimal32 AMQP type.

A 32 bit decimal floating point number (IEEE 754-2008 decimal32).


class proton.decimal64[source]

Bases: long

The decimal64 AMQP type.

A 64 bit decimal floating point number (IEEE 754-2008 decimal64).


class proton.decimal128[source]

Bases: str

The decimal128 AMQP type.

A 128-bit decimal floating-point number (IEEE 754-2008 decimal128).


class proton.float32[source]

Bases: float

The float AMQP type.

A 32 bit floating point number (IEEE 754-2008 binary32).


class proton.int32[source]

Bases: int

The signed int AMQP type.

A 32 bit signed integer in the range \(-(2^{31})\) to \(2^{31} - 1\) inclusive.


class proton.short[source]

Bases: int

The short AMQP type.

A 16 bit signed integer in the range \(-(2^{15})\) to \(2^{15} - 1\) inclusive.


class proton.symbol[source]

Bases: unicode

The symbol AMQP type.

Symbolic values from a constrained domain, represented by a sequence of ASCII characters.


class proton.timestamp[source]

Bases: long

The timestamp AMQP type.

An absolute point in time, represented by a signed 64 bit value measuring milliseconds since the epoch. This value is encoded using the Unix time_t [IEEE1003] encoding of UTC, but with a precision of milliseconds. For example, 1311704463521 represents the moment 2011-07-26T18:21:03.521Z.


class proton.ubyte(i)[source]

Bases: int

The unsigned byte AMQP type.

An 8 bit unsigned integer in the range \(0\) to \(2^8 - 1\) inclusive.


class proton.uint(l)[source]

Bases: long

The unsigned int AMQP type.

A 32 bit unsigned integer in the range \(0\) to \(2^{32} - 1\) inclusive.


class proton.ulong(l)[source]

Bases: long

The ulong AMQP type.

An unsigned 64 bit integer in the range \(0\) to \(2^{64} - 1\) inclusive.


class proton.ushort(i)[source]

Bases: int

The unsigned short AMQP type.

A 16 bit unsigned integer in the range \(0\) to \(2^{16} - 1\) inclusive.