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

Class Messenger

source code

object --+
         |
        Messenger

The Messenger class defines a high level interface for sending and receiving Messages. Every Messenger contains a single logical queue of incoming messages and a single logical queue of outgoing messages. These messages in these queues may be destined for, or originate from, a variety of addresses.

Address Syntax

An address has the following form:

 [ amqp[s]:// ] [user[:password]@] domain [/[name]]

Where domain can be one of:

 host | host:port | ip | ip:port | name

The following are valid examples of addresses:

Sending & Receiving Messages

The Messenger class works in conjuction with the Message class. The Message class is a mutable holder of message content. The put method will encode the content in a given Message object into the outgoing message queue leaving that Message object free to be modified or discarded without having any impact on the content in the outgoing queue.

>>> message = Message()
>>> for i in range(3):
...   message.address = "amqp://host/queue"
...   message.subject = "Hello World %i" % i
...   messenger.put(message)
>>> messenger.send()

Similarly, the get method will decode the content in the incoming message queue into the supplied Message object.

>>> message = Message()
>>> messenger.recv(10):
>>> while messenger.incoming > 0:
...   messenger.get(message)
...   print message.subject
Hello World 0
Hello World 1
Hello World 2
Instance Methods
 
__init__(self, name=None)
Construct a new Messenger with the given name.
source code
 
__del__(self) source code
 
name(self)
The name of the Messenger.
source code
 
start(self)
Transitions the Messenger to an active state.
source code
 
stop(self)
Transitions the Messenger to an inactive state.
source code
 
stopped(self) source code
 
subscribe(self, source)
Subscribes the Messenger to messages originating from the specified source.
source code
 
put(self, message)
Places the content contained in the message onto the outgoing queue of the Messenger.
source code
 
status(self, tracker)
Gets the last known remote state of the delivery associated with the given tracker.
source code
 
settle(self, tracker=None) source code
 
send(self, n=-1)
Blocks until the outgoing queue is empty or the operation times out.
source code
 
recv(self, n=None)
Receives up to n messages into the incoming queue of the Messenger.
source code
 
work(self, timeout=None) source code
 
interrupt(self) source code
 
get(self, message=None)
Moves the message from the head of the incoming message queue into the supplied message object.
source code
 
accept(self, tracker=None)
Accepts messages retreived from the incoming message queue.
source code
 
reject(self, tracker=None)
Rejects messages retreived from the incoming message queue.
source code
 
outgoing(self)
The outgoing queue depth.
source code
 
incoming(self)
The incoming queue depth.
source code
 
route(self, pattern, address) source code
 
rewrite(self, pattern, address) source code

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __repr__, __setattr__, __sizeof__, __str__, __subclasshook__

Class Variables
  certificate = property(_get_certificate, _set_certificate, doc...
  private_key = property(_get_private_key, _set_private_key, doc...
  password = property(_get_password, _set_password, doc= ...
  trusted_certificates = property(_get_trusted_certificates, _se...
  timeout = property(_get_timeout, _set_timeout, doc= ...
  blocking = property(_is_blocking, _set_blocking)
  incoming_window = property(_get_incoming_window, _set_incoming...
  outgoing_window = property(_get_outgoing_window, _set_outgoing...
Properties

Inherited from object: __class__

Method Details

__init__(self, name=None)
(Constructor)

source code 

Construct a new Messenger with the given name. The name has global scope. If a NULL name is supplied, a uuid.UUID based name will be chosen.

Parameters:
  • name (string) - the name of the messenger or None
Overrides: object.__init__

name(self)

source code 

The name of the Messenger.

Decorators:
  • @property

start(self)

source code 

Transitions the Messenger to an active state. A Messenger is initially created in an inactive state. When inactive a Messenger will not send or receive messages from its internal queues. A Messenger must be started before calling send or recv.

stop(self)

source code 

Transitions the Messenger to an inactive state. An inactive Messenger will not send or receive messages from its internal queues. A Messenger should be stopped before being discarded to ensure a clean shutdown handshake occurs on any internally managed connections.

stopped(self)

source code 
Decorators:
  • @property

subscribe(self, source)

source code 

Subscribes the Messenger to messages originating from the specified source. The source is an address as specified in the Messenger introduction with the following addition. If the domain portion of the address begins with the '~' character, the Messenger will interpret the domain as host/port, bind to it, and listen for incoming messages. For example "~0.0.0.0", "amqp://~0.0.0.0", and "amqps://~0.0.0.0" will all bind to any local interface and listen for incoming messages with the last variant only permitting incoming SSL connections.

Parameters:
  • source (string) - the source of messages to subscribe to

put(self, message)

source code 

Places the content contained in the message onto the outgoing queue of the Messenger. This method will never block, however it will send any unblocked Messages in the outgoing queue immediately and leave any blocked Messages remaining in the outgoing queue. The send call may be used to block until the outgoing queue is empty. The outgoing property may be used to check the depth of the outgoing queue.

Parameters:
  • message (Message) - the message to place in the outgoing queue
Returns:
a tracker

status(self, tracker)

source code 

Gets the last known remote state of the delivery associated with the given tracker.

Parameters:
  • tracker (tracker) - the tracker whose status is to be retrieved
Returns:
one of None, PENDING, REJECTED, or ACCEPTED

send(self, n=-1)

source code 

Blocks until the outgoing queue is empty or the operation times out. The timeout property controls how long a Messenger will block before timing out.

recv(self, n=None)

source code 

Receives up to n messages into the incoming queue of the Messenger. If n is not specified, Messenger will receive as many messages as it can buffer internally. This method will block until at least one message is available or the operation times out.

get(self, message=None)

source code 

Moves the message from the head of the incoming message queue into the supplied message object. Any content in the message will be overwritten.

Parameters:
  • message (Message) - the destination message object
Returns:
a tracker

accept(self, tracker=None)

source code 

Accepts messages retreived from the incoming message queue.

Parameters:
  • tracker (tracker) - a tracker as returned by get

reject(self, tracker=None)

source code 

Rejects messages retreived from the incoming message queue.

Parameters:
  • tracker (tracker) - a tracker as returned by get

outgoing(self)

source code 

The outgoing queue depth.

Decorators:
  • @property

incoming(self)

source code 

The incoming queue depth.

Decorators:
  • @property

Class Variable Details

certificate

Value:
property(_get_certificate, _set_certificate, doc= """
Path to a certificate file for the L{Messenger}. This certificate is
used when the L{Messenger} accepts or establishes SSL/TLS connections.
This property must be specified for the L{Messenger} to accept
incoming SSL/TLS connections and to establish client authenticated
outgoing SSL/TLS connection. Non client authenticated outgoing SSL/TLS
connections do not require this property.
""")

private_key

Value:
property(_get_private_key, _set_private_key, doc= """
Path to a private key file for the L{Messenger's<Messenger>}
certificate. This property must be specified for the L{Messenger} to
accept incoming SSL/TLS connections and to establish client
authenticated outgoing SSL/TLS connection. Non client authenticated
SSL/TLS connections do not require this property.
""")

password

Value:
property(_get_password, _set_password, doc= """
This property contains the password for the L{Messenger.private_key}
file, or None if the file is not encrypted.
""")

trusted_certificates

Value:
property(_get_trusted_certificates, _set_trusted_certificates, doc= ""\
"
A path do a database of trusted certificates for use in verifying the
peer on an SSL/TLS connection. If this property is None, then the peer
will not be verified.
""")

timeout

Value:
property(_get_timeout, _set_timeout, doc= """
The timeout property contains the default timeout for blocking
operations performed by the L{Messenger}.
""")

incoming_window

Value:
property(_get_incoming_window, _set_incoming_window, doc= """
The incoming tracking window for the messenger. The messenger will
track the remote status of this many incoming deliveries after they
have been accepted or rejected. Defaults to zero.
""")

outgoing_window

Value:
property(_get_outgoing_window, _set_outgoing_window, doc= """
The outgoing tracking window for the messenger. The messenger will
track the remote status of this many outgoing deliveries after calling
send. Defaults to zero.
""")