Module `proton`¶

Module Summary¶

`AnnotationDict`	A dictionary that only takes `symbol` or `ulong` types as a key.
`Condition`	An AMQP Condition object.
`Connection`	A representation of an AMQP connection.
`Data`	Provides an interface for decoding, extracting, creating, and encoding arbitrary AMQP data.
`Delivery`	Tracks and/or records the delivery of a message over a link.
`Disposition`	A delivery state.
`Endpoint`	Abstract class from which `Connection`, `Session` and `Link` are derived, and which defines the state of these classes.
`Event`	Notification of a state change in the protocol engine.
`EventType`	Connects an event number to an event name, and is used internally by `Event` to represent all known event types.
`Link`	A representation of an AMQP link (a unidirectional channel for transferring messages), of which there are two concrete implementations, `Sender` and `Receiver`.
`Message`	A mutable holder of message content.
`PropertyDict`	A dictionary that only takes `symbol` types as a key.
`Receiver`	A link over which messages are received.
`SASL`	The SASL layer is responsible for establishing an authenticated and/or encrypted tunnel over which AMQP frames are passed between peers.
`Sender`	A link over which messages are sent.
`Session`	A container of links.
`SSL`	An SSL session associated with a transport.
`SSLDomain`	An SSL configuration domain, used to hold the SSL configuration for one or more SSL sessions.
`SSLSessionDetails`	Unique identifier for the SSL session.
`SymbolList`	A list that can only hold `symbol` elements.
`Terminus`	A source or target for messages.
`Transport`	A network channel supporting an AMQP connection.
`Url`	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¶

NOTE: Some AMQP types are represented by native Python types. This table contains only classes for non-native Python types defined in this module. See AMQP Types for a full list of 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: Dict | List | Tuple | Iterable | None = None, raise_on_error: bool = True, **kwargs)[source]¶

Bases: 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 – Initializer for dict: a dict or list of tuple or zip object
raise_on_error – 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(value=None, /)¶: Create a new dictionary with keys from iterable and values set to value.

get(key, default=None, /)¶: Return the value for key if key is in the dictionary, else default.

items() → a set-like object providing a view on D's items¶

keys() → a set-like object providing a view on D's keys¶

pop(k[, d]) → v, remove specified key and return the corresponding value.¶: If the key is not found, return the default if given; otherwise, raise a KeyError.

popitem()¶

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

setdefault(key, default=None, /)¶

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

update(e: Any | None = None, **kwargs) → None¶: Equivalent to dict.update(), but it was needed to call __setitem__() instead of dict.__setitem__().

values() → an object providing a view on D's values¶

class proton.Condition(name: str, description: str | None = None, info: PythonAMQPData | None = None)[source]¶

Bases: object

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 – The name of the condition.
~.description – A description of the condition.
~.info – 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: Any = None)[source]¶

Bases: Wrapper, Endpoint

A representation of an AMQP connection.

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.

property authorization: str¶

The authorization username for a client connection.

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

If not set then implicitly the requested authorization is the same as the authentication user.

close() → None[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.

property connected_address: str¶: The address for this connection.

property connection: Connection¶: Get this connection.

property container: str¶: The container name for this connection object.

property desired_capabilities: Array | SymbolList | None¶: 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.

property 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() → None[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.

property handler: Handler | None¶

Handler for events.

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

property hostname: str | None¶: 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.

link_head(mask: int) → Sender | Receiver | None[source]¶

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 – State mask to match
Returns:: The first link owned by the connection that matches the mask, else None if no link matches.

property offered_capabilities: Array | SymbolList | None¶: 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.

open() → None[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.

property password: None¶

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.

property properties: PropertyDict | None¶: 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.

property remote_condition: Condition | None¶: The remote condition associated with the connection endpoint. See Condition for more information.

property remote_container: str | None¶

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.

property 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

property remote_hostname: str | None¶

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.

property 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

property 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() → Session[source]¶

Returns a new session on this connection.

Returns:: New session
Raises:: SessionException

session_head(mask: int) → Session | None[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.

property state: int¶: 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.

property transport: Transport | None¶: The transport bound to this connection. If the connection is unbound, then this operation will return None.

property user: str | None¶

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)

class proton.ConnectionException[source]¶

Bases: ProtonException

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

add_note()¶: Exception.add_note(note) – add a note to the exception

with_traceback()¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

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

Bases: object

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

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

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

The following types of scalar values are supported:

NULL

BOOL

UBYTE

USHORT

SHORT

UINT

INT

ULONG

LONG

FLOAT

DOUBLE

BINARY

STRING

SYMBOL

The following types of compound values are supported:

DESCRIBED

ARRAY

LIST

MAP

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() → None[source]¶: Clears the data object.

copy(src: Data) → None[source]¶

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

Parameters:: src – The source object from which to copy
Raise:: DataException if there is a Proton error.

decode(encoded: bytes) → int[source]¶

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

Parameters:: encoded – AMQP encoded binary data
Raise:: DataException if there is a Proton error.

dump() → None[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() → bytes[source]¶

Returns a binary representation of the data encoded in AMQP format.

Returns:: The encoded data
Raise:: DataException if there is a Proton error.

encoded_size() → int[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.

enter() → bool[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.

exit() → bool[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.

format() → str[source]¶

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

Returns:: A Formatted string containing contents of this Data object.
Raise:: DataException if there is a Proton error.

get_array() → Tuple[int, bool, int | None][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, a bool indicating whether the array is described, and the enumerated array element type.

get_binary() → bytes[source]¶

Get the current node value as bytes.

Returns:: If the current node is binary, its value, b"" otherwise.

get_bool() → bool[source]¶

Get the current node value as a bool.

Returns:: If the current node is a boolean type, returns its value, False otherwise.

get_byte() → byte[source]¶

Get the current node value as a byte.

Returns:: If the current node is a signed byte, its value, 0 otherwise.

get_char() → char[source]¶

Get the current node value as a char.

Returns:: If the current node is a char, its value, 0 otherwise.

get_decimal128() → decimal128[source]¶

Get the current node value as a decimal128.

Returns:: If the current node is a decimal128, its value, 0 otherwise.

get_decimal32() → decimal32[source]¶

Get the current node value as a decimal32.

Returns:: If the current node is a decimal32, its value, 0 otherwise.

get_decimal64() → decimal64[source]¶

Get the current node value as a decimal64.

Returns:: If the current node is a decimal64, its value, 0 otherwise.

get_dict() → Dict[Any, Any][source]¶

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

Returns:: The decoded dictionary.

get_double() → float[source]¶

Get the current node value as a double.

Returns:: If the current node is a double, its value, 0 otherwise.

get_float() → float32[source]¶

Get the current node value as a float32.

Returns:: If the current node is a float, its value, 0 otherwise.

get_int() → int32[source]¶

Get the current node value as a int32.

Returns:: If the current node is a signed int, its value, 0 otherwise.

get_list() → int[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

get_long() → int[source]¶

Get the current node value as a long.

Returns:: If the current node is an signed long, its value, 0 otherwise.

get_map() → int[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

get_object() → Any | None[source]¶

get_py_array() → Array | None[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.

get_py_described() → Described[source]¶

A convenience method for decoding an AMQP described value.

Returns:: The decoded AMQP descriptor.

get_sequence() → List[Any][source]¶

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

Returns:: The decoded list.

get_short() → short[source]¶

Get the current node value as a short.

Returns:: If the current node is a signed short, its value, 0 otherwise.

get_string() → str[source]¶

Get the current node value as str.

Returns:: If the current node is a string, its value, "" otherwise.

get_symbol() → symbol[source]¶

Get the current node value as symbol.

Returns:: If the current node is a symbol, its value, "" otherwise.

get_timestamp() → timestamp[source]¶

Get the current node value as a timestamp.

Returns:: If the current node is a timestamp, its value, 0 otherwise.

get_ubyte() → ubyte[source]¶

Get the current node value as a ubyte.

Returns:: If the current node is an unsigned byte, its value, 0 otherwise.

get_uint() → uint[source]¶

Get the current node value as a uint.

Returns:: If the current node is an unsigned int, its value, 0 otherwise.

get_ulong() → ulong[source]¶

Get the current node value as a ulong.

Returns:: If the current node is an unsigned long, its value, 0 otherwise.

get_ushort() → ushort[source]¶

Get the current node value as a ushort.

Returns:: If the current node is an unsigned short, its value, 0 otherwise.

get_uuid() → UUID | None[source]¶

Get the current node value as a uuid.UUID.

Returns:: If the current node is a UUID, its value, None otherwise.

is_described() → bool[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.

is_null() → bool[source]¶

Checks if the current node is the AMQP null type.

Returns:: True if the current node is the AMQP null type, False otherwise.

narrow() → None[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() → int | None[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

prev() → int | None[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

put_array(described: bool, element_type: int) → None[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 – specifies whether the array is described
element_type – the type of the array elements

Raise:

DataException if there is a Proton error.

put_binary(b: bytes) → None[source]¶

Puts a binary value.

Parameters:: b – a binary value
Raise:: DataException if there is a Proton error.

put_bool(b: bool | int) → None[source]¶

Puts a boolean value.

Parameters:: b – a boolean value
Raise:: DataException if there is a Proton error.

put_byte(b: byte | int) → None[source]¶

Puts a signed byte value.

Parameters:

b – 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: char | str) → None[source]¶

Puts a char value.

Parameters:: c – a single character
Raise:: DataException if there is a Proton error.

put_decimal128(d: decimal128 | bytes) → None[source]¶

Puts a decimal128 value.

Parameters:: d – a decimal128 value encoded in a 16-byte binary value.
Raise:: DataException if there is a Proton error.

put_decimal32(d: decimal32 | int) → None[source]¶

Puts a decimal32 value.

Parameters:: d – a decimal32 number encoded in an 32-bit integral value.
Raise:: DataException if there is a Proton error.

put_decimal64(d: decimal64 | int) → None[source]¶

Puts a decimal64 value.

Parameters:: d – a decimal64 number encoded in an 32-bit integral value.
Raise:: DataException if there is a Proton error.

put_described() → None[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: Dict[Any, Any]) → None[source]¶

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

Parameters:: d – The dictionary to be encoded
Raise:: DataException if there is a Proton error.

put_double(d: float | int) → None[source]¶

Puts a double value.

Parameters:: d – a floating point value.
Raise:: DataException if there is a Proton error.

put_float(f: float32 | float | int) → None[source]¶

Puts a float value.

Parameters:: f – a floating point value
Raise:: DataException if there is a Proton error.

put_int(i: int32 | int) → None[source]¶

Puts a signed int value.

Parameters:

i – 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() → None[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(i64: int) → None[source]¶

Puts a signed long value.

Parameters:

i64 – 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() → None[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: memoryview) → None[source]¶

Put a Python memoryview object as an AMQP binary value.

Parameters:: mv – A Python memoryview object
Raise:: DataException if there is a Proton error.

put_null() → None[source]¶

Puts a null value.

Raise:: DataException if there is a Proton error.

put_object(obj: Any) → None[source]¶

put_py_array(a: Array) → None[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 – The array object to be encoded
Raise:: DataException if there is a Proton error.

put_py_described(d: Described) → None[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: List[Any]) → None[source]¶

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

Parameters:: s – The sequence to be encoded
Raise:: DataException if there is a Proton error.

put_short(s: short | int) → None[source]¶

Puts a signed short value.

Parameters:

s – 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: str) → None[source]¶

Puts a unicode value.

Parameters:: s – a unicode string
Raise:: DataException if there is a Proton error.

put_symbol(s: str | symbol) → None[source]¶

Puts a symbolic value.

Parameters:: s – the symbol name
Raise:: DataException if there is a Proton error.

put_timestamp(t: timestamp | int) → None[source]¶

Puts a timestamp value.

Parameters:

t – a positive integral value

Raise:

AssertionError if parameter is negative.
DataException if there is a Proton error.

put_ubyte(ub: ubyte | int) → None[source]¶

Puts an unsigned byte value.

Parameters:

ub – 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: uint | int) → None[source]¶

Puts an unsigned int value.

Parameters:

ui – 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: ulong | int) → None[source]¶

Puts an unsigned long value.

Parameters:

ul – 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: ushort | int) → None[source]¶

Puts an unsigned short value.

Parameters:

us – 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: UUID) → None[source]¶

Puts a UUID value.

Parameters:: u – a uuid value.
Raise:: DataException if there is a Proton error.

rewind() → None[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() → int | None[source]¶

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

Returns:: The current node type enumeration.

classmethod type_name(amqptype: int) → str[source]¶

Return a string name for an AMQP type.

Parameters:: amqptype – Numeric Proton AMQP type (enum pn_type_t)
Returns:: 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() → None[source]¶: Reverse the effect of narrow().

class proton.DataException[source]¶

Bases: ProtonException

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

add_note()¶: Exception.add_note(note) – add a note to the exception

with_traceback()¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class proton.Delivery(impl)[source]¶

Bases: Wrapper

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

ACCEPTED = 36¶: 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 = 39¶: 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 = 35¶: A non terminal state indicating how much (if any) message data has been received for a delivery.

REJECTED = 37¶: 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 = 38¶: 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() → None[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.

property aborted: bool¶: True if the delivery has been aborted, False otherwise.

property connection: Connection¶: The Connection over which the delivery was sent or received.

property link: Receiver | Sender¶: The Link on which the delivery was sent or received.

property local_state: int | DispositionType¶: A local state of the delivery.

property partial: bool¶: True for an incoming delivery if not all the data is yet available, False otherwise.

property pending: int¶: The amount of pending message data for a delivery.

property readable: bool¶: True for an incoming delivery that has data to read, False otherwise..

property remote_state: int | DispositionType¶: A remote state of the delivery as indicated by the remote peer.

property session: Session¶: The Session over which the delivery was sent or received.

settle() → None[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.

property settled: bool¶: True if the delivery has been settled by the remote peer, False otherwise.

property tag: str¶: The identifier for the delivery.

property transport: Transport¶: The Transport bound to the Connection over which the delivery was sent or received.

update(state: int | DispositionType) → None[source]¶

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

Parameters:: state – State of delivery

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

property writable: bool¶: True for an outgoing delivery to which data can now be written, False otherwise..

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 = 36¶

MODIFIED = 39¶

RECEIVED = 35¶

REJECTED = 37¶

RELEASED = 38¶

property annotations: Dict[symbol, PythonAMQPData] | None¶

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.

property condition: Condition | None¶

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.

property data: List[int] | None¶

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.

property failed: bool¶: The failed flag for this disposition.

property section_number: int¶: The section number associated with a disposition.

property section_offset: int¶: The section offset associated with a disposition.

property type: int | DispositionType¶

Get the type of this disposition object.

Defined values are:

RECEIVED
ACCEPTED
REJECTED
RELEASED
MODIFIED

property undeliverable: bool¶: The undeliverable flag for this disposition.

Bases: object

A described AMQP type.

Variables:

descriptor – Any AMQP value can be a descriptor
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.

property handler: Handler | None¶

Handler for events.

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

property remote_condition: Condition | None¶: The remote condition associated with the connection endpoint. See Condition for more information.

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

Bases: 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.

LINK_FINAL = EventType(name=PN_LINK_FINAL, number=27)¶: 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.

LINK_FLOW = EventType(name=PN_LINK_FLOW, number=26)¶: The flow control state for a link has changed. Events of this type point to the relevant link.

LINK_INIT = EventType(name=PN_LINK_INIT, number=19)¶: The link has been created. This is the first event that will ever be issued for a link.

LINK_LOCAL_CLOSE = EventType(name=PN_LINK_LOCAL_CLOSE, number=22)¶: The local link endpoint has been closed. Events of this type point to the relevant link.

LINK_LOCAL_DETACH = EventType(name=PN_LINK_LOCAL_DETACH, number=24)¶: The local link endpoint has been detached. Events of this type point to the relevant link.

LINK_LOCAL_OPEN = EventType(name=PN_LINK_LOCAL_OPEN, number=20)¶: The local link endpoint has been opened. Events of this type point ot the relevant link.

LINK_REMOTE_CLOSE = EventType(name=PN_LINK_REMOTE_CLOSE, number=23)¶: The remote endpoint has closed the link. Events of this type point to the relevant link.

LINK_REMOTE_DETACH = EventType(name=PN_LINK_REMOTE_DETACH, number=25)¶: The remote endpoint has detached the link. Events of this type point to the relevant link.

LINK_REMOTE_OPEN = EventType(name=PN_LINK_REMOTE_OPEN, number=21)¶: 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.

property clazz: str¶: The name of the class associated with the event context.

property connection: Connection | None¶: The connection associated with the event, or None if none is associated with it.

property container: Container¶: The reactor.Container associated with the event.

The context object associated with the event.

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

property delivery: Delivery | None¶: The delivery associated with the event, or None if none is associated with it.

dispatch(handler: Handler, type: EventType | None = None) → None¶

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

Parameters:

handler – Parent handler to process this event
type – Event type

property handler: Handler | None¶

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.

property link: Sender | Receiver | None¶: The link associated with the event, or None if none is associated with it.

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

property receiver: Receiver | None¶: The receiver link associated with the event, or None if none is associated with it. This is essentially an alias for link property, that does an additional check on the type of the link.

property sender: Sender | None¶: The sender link associated with the event, or None if none is associated with it. This is essentially an alias for link property, that does an additional check on the type of the link.

property session: Session | None¶: The session associated with the event, or None if none is associated with it.

property transport: Transport | None¶: The transport associated with the event, or None if none is associated with it.

property type: EventType¶: The type of this event.

class proton.EventType(name: str | None = None, number: int | None = None, method: str | None = 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)}¶

class proton.Link(impl)[source]¶

Bases: Wrapper, 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¶: The local endpoint state is closed.

LOCAL_CLOSED = 4¶: The remote endpoint state is active.

LOCAL_UNINIT = 1¶: The local endpoint state is uninitialized.

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¶: The remote endpoint state is uninitialized.

REMOTE_CLOSED = 32¶: The remote endpoint state is closed.

REMOTE_UNINIT = 8¶: The local endpoint state is active.

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() → bool[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.

property available: int¶

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.

close() → None[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().

property connection: Connection¶: The connection on which this link was attached.

property credit: int¶

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.

property current: Delivery | None¶

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

delivery(tag: str) → Delivery[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 – Delivery tag unique for this link.

detach() → None[source]¶: Detach this link.

property drain_mode: bool¶

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.

drained() → int[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.

free() → None[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.

property handler: Handler | None¶

Handler for events.

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

property is_receiver: bool¶: True if this link is a receiver, False otherwise.

property is_sender: bool¶: True if this link is a sender, False otherwise.

property max_message_size: int¶: The maximum message size for this link. A zero value means the size is unlimited.

Warning

Unsettled API

property name: str¶: The name of the link.

next(mask: int) → Sender | Receiver | None[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 – State mask to match
Returns:: The next link that matches the given state mask, or None if no link matches.

open() → None[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.

property properties: PropertyDict | None¶: Link 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.

property queued: int¶

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.

property rcv_settle_mode: int¶: The local receiver settle mode for this link. One of RCV_FIRST or RCV_SECOND.

property remote_condition: Condition | None¶: The remote condition associated with the connection endpoint. See Condition for more information.

property remote_max_message_size: int¶

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

Warning

Unsettled API

A zero value means the size is unlimited.

property remote_properties¶

The properties specified by the remote peer for this link.

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

Type:: Data

property remote_rcv_settle_mode: int¶: The remote receiver settle mode for this link. One of RCV_FIRST or RCV_SECOND.

property remote_snd_settle_mode: int¶: The remote sender settle mode for this link. One of SND_UNSETTLED, SND_SETTLED or SND_MIXED.

property remote_source: Terminus¶: 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.

property remote_target: Terminus¶: 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.

property session: Session¶: The parent session for this link.

property snd_settle_mode: int¶: The local sender settle mode for this link. One of SND_UNSETTLED, SND_SETTLED or SND_MIXED.

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

property state: int¶: 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.

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

property transport: Transport¶: The transport bound to the connection on which this link was attached.

property unsettled: int¶: The number of unsettled deliveries for this link.

class proton.LinkException[source]¶

Bases: ProtonException

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

add_note()¶: Exception.add_note(note) – add a note to the exception

with_traceback()¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

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 – message body

Parameters:

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

DEFAULT_PRIORITY = 4¶: Default AMQP message priority

property address: str | None¶

The address of the message.

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

property annotations: AnnotationDict | None¶

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() → None[source]¶: Clears the contents of the Message. All fields will be reset to their default values.

property content_encoding: symbol¶

The content-encoding of the message.

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

property content_type: symbol¶

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

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

property correlation_id: str | bytes | UUID | ulong | None¶

The correlation-id for the message.

Type:

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

int (unsigned)
uuid.UUID
bytes
str

property creation_time: float¶

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

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

property delivery_count: int¶

The number of delivery attempts made for this message.

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

property durable: bool¶

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

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

property expiry_time: float¶

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

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

property first_acquirer: bool¶

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

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

property group_id: str | None¶

The group id of the message.

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

property group_sequence: int¶

The sequence of the message within its group.

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

property id: str | bytes | UUID | ulong | None¶

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

property inferred: bool¶

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.

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

property instructions: AnnotationDict | None¶

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.

property priority: int¶

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.

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

recv(link: Sender) → None[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 – The link to receive a message from
Returns:: the delivery associated with the decoded message (or None)

property reply_to: str | None¶

The reply-to address for the message.

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

property reply_to_group_id: str | None¶

The group-id for any replies.

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

send(sender: Sender, tag: str | None = None) → Delivery[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 – The sender to send the message
tag – The delivery tag for the sent message

Returns:

The delivery associated with the sent message

property subject: str | None¶

The subject of the message.

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

property ttl: float¶

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

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

property user_id: bytes¶

The user id of the message creator.

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

class proton.MessageException[source]¶

Bases: ProtonException

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

add_note()¶: Exception.add_note(note) – add a note to the exception

with_traceback()¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class proton.ProtonException[source]¶

Bases: Exception

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

add_note()¶: Exception.add_note(note) – add a note to the exception

with_traceback()¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class proton.PropertyDict(e: Any | None = None, raise_on_error: bool = True, **kwargs)[source]¶

Bases: 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 – 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(value=None, /)¶: Create a new dictionary with keys from iterable and values set to value.

get(key, default=None, /)¶: Return the value for key if key is in the dictionary, else default.

items() → a set-like object providing a view on D's items¶

keys() → a set-like object providing a view on D's keys¶

pop(k[, d]) → v, remove specified key and return the corresponding value.¶: If the key is not found, return the default if given; otherwise, raise a KeyError.

popitem()¶

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

setdefault(key, default=None, /)¶

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

update(e: Any | None = None, **kwargs) → None¶: Equivalent to dict.update(), but it was needed to call __setitem__() instead of dict.__setitem__().

values() → an object providing a view on D's values¶

class proton.Receiver(impl)[source]¶

Bases: Link

A link over which messages are received.

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.

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¶: The remote endpoint state is uninitialized.

REMOTE_CLOSED = 32¶: The remote endpoint state is closed.

REMOTE_UNINIT = 8¶: The local endpoint state is active.

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() → bool¶

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.

property available: int¶

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.

close() → None¶

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

property connection: Connection¶: The connection on which this link was attached.

property credit: int¶

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.

property current: Delivery | None¶

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

delivery(tag: str) → Delivery¶

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 – Delivery tag unique for this link.

detach() → None¶: Detach this link.

drain(n: int) → None[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 – The amount by which to increment the link credit

property drain_mode: bool¶

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.

drained() → int¶

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.

draining() → bool[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.

flow(n: int) → None[source]¶

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

Parameters:: n – The credit to be issued to the remote sender.

free() → None¶: 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.

property handler: Handler | None¶

Handler for events.

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

property is_receiver: bool¶: True if this link is a receiver, False otherwise.

property is_sender: bool¶: True if this link is a sender, False otherwise.

property max_message_size: int¶: The maximum message size for this link. A zero value means the size is unlimited.

Warning

Unsettled API

property name: str¶: The name of the link.

next(mask: int) → Sender | Receiver | None¶

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 – State mask to match
Returns:: The next link that matches the given state mask, or None if no link matches.

open() → None¶

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.

property properties: PropertyDict | None¶: Link 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.

property queued: int¶

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.

property rcv_settle_mode: int¶: The local receiver settle mode for this link. One of RCV_FIRST or RCV_SECOND.

recv(limit: int) → bytes | None[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 – the max data size to receive of this message

Returns:

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

Raise:

Timeout if timed out
Interrupt if interrupted
LinkException for all other exceptions

property remote_condition: Condition | None¶: The remote condition associated with the connection endpoint. See Condition for more information.

property remote_max_message_size: int¶

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

Warning

Unsettled API

A zero value means the size is unlimited.

property remote_properties¶

The properties specified by the remote peer for this link.

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

Type:: Data

property remote_rcv_settle_mode: int¶: The remote receiver settle mode for this link. One of RCV_FIRST or RCV_SECOND.

property remote_snd_settle_mode: int¶: The remote sender settle mode for this link. One of SND_UNSETTLED, SND_SETTLED or SND_MIXED.

property remote_source: Terminus¶: 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.

property remote_target: Terminus¶: 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.

property session: Session¶: The parent session for this link.

property snd_settle_mode: int¶: The local sender settle mode for this link. One of SND_UNSETTLED, SND_SETTLED or SND_MIXED.

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

property state: int¶: 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.

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

property transport: Transport¶: The transport bound to the connection on which this link was attached.

property unsettled: int¶: The number of unsettled deliveries for this link.

class proton.SASL(transport: Transport)[source]¶

Bases: 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¶

property allow_insecure_mechs: bool¶: Allow unencrypted cleartext passwords (PLAIN mech)

allowed_mechs(mechs: str | List[str]) → None[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 – 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", ...].

property authorization: str | None¶

Retrieve the requested authorization user. This is usually used at the the server end to find the name of any requested authorization user.

If the peer has not requested an authorization user or the SASL mechanism has no capability to transport an authorization id this will be the same as the authenticated user.

Note that it is the role of the server to ensure that the authenticated user is actually allowed to act as the requested authorization 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 None is returned.
If the ANONYMOUS mechanism is used then the user will be "anonymous".
Otherwise a string containing the user is returned.

config_name(name: str)[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 – The configuration name.

config_path(path: str)[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 – 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() → bool[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.

property mech: str¶

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.

property outcome: int | None¶

Retrieve the outcome of SASL negotiation.

Return type:

None if no negotiation has taken place.
Otherwise the outcome of the negotiation.

property user: str | None¶

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 None 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: Link

A link over which messages are sent.

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.

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¶: The remote endpoint state is uninitialized.

REMOTE_CLOSED = 32¶: The remote endpoint state is closed.

REMOTE_UNINIT = 8¶: The local endpoint state is active.

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() → bool¶

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.

property available: int¶

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.

close() → None¶

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

property connection: Connection¶: The connection on which this link was attached.

property credit: int¶

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.

property current: Delivery | None¶

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

delivery(tag: str) → Delivery¶

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 – Delivery tag unique for this link.

delivery_tag() → str[source]¶: Increments and returns a counter to be used as the next message tag.

detach() → None¶: Detach this link.

property drain_mode: bool¶

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.

drained() → int¶

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.

free() → None¶: 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.

property handler: Handler | None¶

Handler for events.

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

property is_receiver: bool¶: True if this link is a receiver, False otherwise.

property is_sender: bool¶: True if this link is a sender, False otherwise.

property max_message_size: int¶: The maximum message size for this link. A zero value means the size is unlimited.

Warning

Unsettled API

property name: str¶: The name of the link.

next(mask: int) → Sender | Receiver | None¶

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 – State mask to match
Returns:: The next link that matches the given state mask, or None if no link matches.

offered(n: int) → None[source]¶

Signal the availability of deliveries for this Sender.

Parameters:: n – Credit the number of deliveries potentially available for transfer.

open() → None¶

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.

property properties: PropertyDict | None¶: Link 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.

property queued: int¶

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.

property rcv_settle_mode: int¶: The local receiver settle mode for this link. One of RCV_FIRST or RCV_SECOND.

property remote_condition: Condition | None¶: The remote condition associated with the connection endpoint. See Condition for more information.

property remote_max_message_size: int¶

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

Warning

Unsettled API

A zero value means the size is unlimited.

property remote_properties¶

The properties specified by the remote peer for this link.

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

Type:: Data

property remote_rcv_settle_mode: int¶: The remote receiver settle mode for this link. One of RCV_FIRST or RCV_SECOND.

property remote_snd_settle_mode: int¶: The remote sender settle mode for this link. One of SND_UNSETTLED, SND_SETTLED or SND_MIXED.

property remote_source: Terminus¶: 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.

property remote_target: Terminus¶: 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.

send(obj: bytes | Message, tag: str | None = None) → int | Delivery[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.

property session: Session¶: The parent session for this link.

property snd_settle_mode: int¶: The local sender settle mode for this link. One of SND_UNSETTLED, SND_SETTLED or SND_MIXED.

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

property state: int¶: 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.

stream(data: bytes) → int[source]¶

Send specified data as part of the current delivery.

Parameters:: data – Data to send

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

property transport: Transport¶: The transport bound to the connection on which this link was attached.

property unsettled: int¶: The number of unsettled deliveries for this link.

class proton.Session(impl)[source]¶

Bases: Wrapper, Endpoint

A container of links

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.

close() → None[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().

property connection: Connection¶: The parent connection for this session.

free() → None[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.

property handler: Handler | None¶

Handler for events.

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

property incoming_bytes: int¶: The number of incoming bytes currently buffered.

property incoming_capacity: int¶: 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.

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() → None[source]¶: Open a session. Once this operation has completed, the LOCAL_ACTIVE state flag will be set.

property outgoing_bytes: int¶: The number of outgoing bytes currently buffered.

property outgoing_window: int¶: The outgoing window for this session.

receiver(name: str) → Receiver[source]¶

Create a new Receiver on this session.

Parameters:: name – Name of receiver

property remote_condition: Condition | None¶: The remote condition associated with the connection endpoint. See Condition for more information.

sender(name: str) → Sender[source]¶

Create a new Sender on this session.

Parameters:: name – Name of sender

property state: int¶: The endpoint state flags for this session. See Endpoint for details of the flags.

property transport: Transport¶: The transport bound to the parent connection for this session.

class proton.SessionException[source]¶

Bases: ProtonException

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

add_note()¶: Exception.add_note(note) – add a note to the exception

with_traceback()¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class proton.SSL(transport: Transport, domain: SSLDomain, session_details: SSLSessionDetails | None = None)[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() → str | None[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.

get_cert_common_name() → str[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.

get_cert_country() → str[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.

get_cert_fingerprint(fingerprint_length: int, digest_name: int) → str | None[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 – Must be \(>= 33\) for md5, \(>= 41\) for sha1, \(>= 65\) for sha256 and \(>= 129\) for sha512.
digest_name – 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.

get_cert_fingerprint_md5() → str | None[source]¶

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

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

get_cert_fingerprint_sha1() → str | None[source]¶

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

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

get_cert_fingerprint_sha256() → str | None[source]¶

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

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

get_cert_fingerprint_sha512() → str | None[source]¶

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

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

get_cert_locality_or_city() → str[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.

get_cert_organization() → str[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.

get_cert_organization_unit() → str[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.

get_cert_state_or_province() → str[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.

get_cert_subject() → str[source]¶

Get the subject from the peer’s certificate.

Returns:: A string containing the full subject.

get_cert_subject_subfield(subfield_name: int) → str | None[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:

CERT_COUNTRY_NAME

CERT_STATE_OR_PROVINCE

CERT_CITY_OR_LOCALITY

CERT_ORGANIZATION_NAME

CERT_ORGANIZATION_UNIT

CERT_COMMON_NAME

Parameters:: subfield_name – 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.

property peer_hostname: str¶

Manage the expected name of the remote peer.

The hostname is used for two purposes:

when set on an SSL client, it is sent to the server during the handshake (if Server Name Indication is supported)

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

static present() → bool[source]¶

Tests for an SSL implementation being present.

Returns:: True if we support SSL, False if not.

protocol_name() → str | None[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.

property remote_subject: str¶: The subject from the peers certificate.

resume_status() → int[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

class proton.SSLDomain(mode: int)[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() → int[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: str, key_file: str, password: str | None) → int[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 – 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 – 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 – The password used to sign the key, else None if key is not protected.

Returns:

0 on success

Raise:

SSLException if there is any Proton error

set_peer_authentication(verify_mode: int, trusted_CAs: str | None = None) → int[source]¶

This method controls how the peer’s certificate is validated, if at all. By default, servers do not attempt to verify their peers (PN_SSL_ANONYMOUS_PEER) but clients attempt to verify both the certificate and peer name (PN_SSL_VERIFY_PEER_NAME). 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 – The level of validation to apply to the peer, one of VERIFY_PEER, VERIFY_PEER_NAME, ANONYMOUS_PEER,
trusted_CAs – Path to a database of trusted CAs that the server will advertise.

Returns:

0 on success

Raise:

SSLException if there is any Proton error

set_trusted_ca_db(certificate_db: str) → int[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 – Database of trusted CAs, used to authenticate the peer.
Returns:: 0 on success
Raise:: SSLException if there is any Proton error

class proton.SSLSessionDetails(session_id: str)[source]¶

Bases: object

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

get_session_id() → str[source]¶

Get the unique identifier for this SSL session

Returns:: Session identifier

class proton.SSLUnavailable[source]¶

Bases: SSLException

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

add_note()¶: Exception.add_note(note) – add a note to the exception

with_traceback()¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class proton.SSLException[source]¶

Bases: TransportException

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

add_note()¶: Exception.add_note(note) – add a note to the exception

with_traceback()¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class proton.SymbolList(t: List[Any] | None = None, raise_on_error: bool = 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 – Initializer for list
raise_on_error – 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: str) → None[source]¶: Add a single value v to the end of the list

clear()¶: Remove all items from list.

copy()¶: Return a shallow copy of the list.

count(value, /)¶: Return number of occurrences of value.

extend(t: Iterable[str]) → None[source]¶: Add all elements of an iterable t to the end of the list

index(value, start=0, stop=9223372036854775807, /)¶

Return first index of value.

Raises ValueError if the value is not present.

insert(i: int, v: str) → None[source]¶: Insert a value v at index i

pop(index=-1, /)¶

Remove and return item at index (default last).

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

remove(value, /)¶

Remove first occurrence of value.

Raises ValueError if the value is not present.

reverse()¶: Reverse IN PLACE.

sort(*, key=None, reverse=False)¶

Sort the list in ascending order and return None.

The sort is in-place (i.e. the list itself is modified) and stable (i.e. the order of two equal elements is maintained).

If a key function is given, apply it once to each list item and sort them, ascending or descending, according to their function values.

The reverse flag can be set to sort in descending order.

to_array()[source]¶

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

EXPIRE_WITH_LINK = 0¶: 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.

property address: str | None¶: The address that identifies the source or target node

property capabilities¶

Capabilities of the source or target.

Type:: Data containing an array of symbol.

copy(src: Terminus) → None[source]¶

Copy another terminus object.

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

property distribution_mode: int¶: The terminus distribution mode, must be one of DIST_MODE_UNSPECIFIED, DIST_MODE_COPY or DIST_MODE_MOVE.

property durability: int¶: The terminus durability mode, must be one of NONDURABLE, CONFIGURATION or DELIVERIES.

property dynamic: bool¶: Indicates whether the source or target node was dynamically created

property expiry_policy: int¶: The terminus expiry policy, must be one of EXPIRE_WITH_LINK, EXPIRE_WITH_SESSION, EXPIRE_WITH_CONNECTION or EXPIRE_NEVER.

property filter¶

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

Type:: Data containing a map with symbol keys.

property outcomes¶

Outcomes of the source or target.

Type:: Data containing an array of symbol.

property properties¶

Properties of a dynamic source or target.

Type:: Data containing a map with symbol keys.

property timeout: int¶: The terminus timeout in seconds.

property type: int¶: The terminus type, must be one of UNSPECIFIED, SOURCE, TARGET or COORDINATOR.

class proton.Timeout[source]¶

Bases: ProtonException

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

add_note()¶: Exception.add_note(note) – add a note to the exception

with_traceback()¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class proton.Interrupt[source]¶

Bases: ProtonException

An interrupt exception indicates that a blocking operation was interrupted.

add_note()¶: Exception.add_note(note) – add a note to the exception

with_traceback()¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class proton.Transport(mode: int | None = None, impl: Callable = None)[source]¶

Bases: 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.

property authenticated: bool¶

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: Connection) → None[source]¶

Assign a connection to the transport.

Parameters:: connection – Connection to which to bind.
Raise:: TransportException if there is any Proton error.

bind_nothrow(connection: Connection) → None[source]¶

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

Parameters:: connection – Connection to which to bind.

capacity() → int[source]¶

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

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

property channel_max: int¶

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.

Raise:: SessionException if the OPEN frame has already been sent.

close_head() → None[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() → None[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.

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

property condition: Condition | None¶

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.

property connection: Connection¶: The connection bound to this transport.

property encrypted: bool¶: Indicate whether the transport connection is encrypted.

Note

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

property frames_input: int¶: Get the number of frames input by a transport.

property frames_output: int¶: Get the number of frames output by a transport.

property idle_timeout: float¶: The idle timeout of the connection in seconds. A zero idle timeout means heartbeats are disabled.

log(message: str) → None[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.

property max_frame_size: int¶: The maximum size for transport frames (in bytes).

peek(size: int) → bytes | None[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 – Number of bytes to return.
Returns:: size bytes from the head of the transport, or None if none are available.
Raise:: TransportException if there is any Proton error.

pending() → int[source]¶

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

Returns:: The number of pending output bytes.
Raise:: TransportException if there is any Proton error.

pop(size: int) → None[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 – Number of bytes to remove.

push(binary: bytes) → None[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 – 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.

property remote_channel_max: int¶: The maximum allowed channel number of a transport’s remote peer.

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

property remote_max_frame_size: int¶: The maximum frame size of a transport’s remote peer (in bytes).

require_auth(bool: bool) → None[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 – 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() → SASL[source]¶

Get the SASL object associated with this transport.

Returns:: SASL object associated with this transport.

ssl(domain: SSLDomain | None = None, session_details: SSLSessionDetails | None = None) → SSL[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 – An SSL domain configuration object
session_details – A unique identifier for the SSL session.

Returns:

SSL session associated with this transport.

tick(now: float) → float[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 – 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.

trace(n: int) → None[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 – Trace flags

property tracer: Callable[[Transport, str], None] | None¶: A callback for trace logging. The callback is passed the transport and log message. For no tracer callback, value is None.

unbind() → None[source]¶

Unbinds a transport from its AMQP connection.

Raise:: TransportException if there is any Proton error.

property user: str | None¶

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.

class proton.TransportException[source]¶

Bases: ProtonException

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

add_note()¶: Exception.add_note(note) – add a note to the exception

with_traceback()¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

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(value)[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

property host¶

The host segment of a URL

Type:: str

property path¶

The path segment of a URL

Type:: str

property port¶

The port number segment of a URL.

Type:: Url.Port

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

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

The decimal64 AMQP type.

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

class proton.decimal128[source]¶

Bases: bytes

The decimal128 AMQP type.

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

class proton.float32(x=0, /)[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: str

The symbol AMQP type.

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

class proton.timestamp[source]¶

Bases: int

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: int)[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(u32: int)[source]¶

Bases: int

The unsigned int AMQP type.

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

class proton.ulong(u64: int)[source]¶

Bases: int

The ulong AMQP type.

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

class proton.ushort(i: int)[source]¶

Bases: int

The unsigned short AMQP type.

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

Module `proton`¶

Module Summary¶

Exceptions¶

AMQP Types¶

Module Detail¶

Table of Contents

Previous topic

Next topic

This Page

Module proton¶

Module Summary¶

Exceptions¶

AMQP Types¶

Module Detail¶

Module `proton`¶