You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by gs...@apache.org on 2014/11/26 22:03:10 UTC
qpid-proton git commit: Some initial pydoc for library code
supporting examples
Repository: qpid-proton
Updated Branches:
refs/heads/examples d4b154cbd -> afc52a00f
Some initial pydoc for library code supporting examples
Project: http://git-wip-us.apache.org/repos/asf/qpid-proton/repo
Commit: http://git-wip-us.apache.org/repos/asf/qpid-proton/commit/afc52a00
Tree: http://git-wip-us.apache.org/repos/asf/qpid-proton/tree/afc52a00
Diff: http://git-wip-us.apache.org/repos/asf/qpid-proton/diff/afc52a00
Branch: refs/heads/examples
Commit: afc52a00f08cbb9121b07c9b345ba24085fb83cc
Parents: d4b154c
Author: Gordon Sim <gs...@redhat.com>
Authored: Wed Nov 26 21:03:54 2014 +0000
Committer: Gordon Sim <gs...@redhat.com>
Committed: Wed Nov 26 21:03:54 2014 +0000
----------------------------------------------------------------------
proton-c/bindings/python/proton/handlers.py | 38 ++++++++++++-
proton-c/bindings/python/proton/reactors.py | 71 ++++++++++++++++++++++--
proton-c/bindings/python/proton/utils.py | 3 +
3 files changed, 104 insertions(+), 8 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/afc52a00/proton-c/bindings/python/proton/handlers.py
----------------------------------------------------------------------
diff --git a/proton-c/bindings/python/proton/handlers.py b/proton-c/bindings/python/proton/handlers.py
index c0d9685..7837d64 100644
--- a/proton-c/bindings/python/proton/handlers.py
+++ b/proton-c/bindings/python/proton/handlers.py
@@ -23,7 +23,10 @@ from proton import Message, Handler, ProtonException, Transport, TransportExcept
from select import select
class FlowController(Handler):
-
+ """
+ A handler that controls a configured credit window for associated
+ receivers.
+ """
def __init__(self, window=1):
self.window = window
@@ -63,7 +66,12 @@ def add_nested_handler(handler, nested):
handler.handlers = [nested]
class ScopedHandler(Handler):
-
+ """
+ An internal handler that checks for handlers scoped to the engine
+ objects an event relates to. E.g it allows delivery, link, session
+ or connection scoped handlers that will only be called with events
+ for the object to which they are scoped.
+ """
scopes = {
"pn_connection": ["connection"],
"pn_session": ["session", "connection"],
@@ -82,6 +90,10 @@ class ScopedHandler(Handler):
h(event)
class OutgoingMessageHandler(Handler):
+ """
+ A utility for simpler and more intuitive handling of delivery
+ events related to outgoing i.e. sent messages.
+ """
def __init__(self, auto_settle=True, delegate=None):
self.auto_settle = auto_settle
self.delegate = delegate
@@ -162,6 +174,11 @@ class Acking(object):
delivery.settle()
class IncomingMessageHandler(Handler, Acking):
+ """
+ A utility for simpler and more intuitive handling of delivery
+ events related to incoming i.e. received messages.
+ """
+
def __init__(self, auto_accept=True, delegate=None):
self.delegate = delegate
self.auto_accept = auto_accept
@@ -191,6 +208,18 @@ class IncomingMessageHandler(Handler, Acking):
dispatch(self.delegate, 'on_settled', event)
class EndpointStateHandler(Handler):
+ """
+ A utility that exposes 'endpoint' events i.e. the open/close for
+ links, sessions and connections in a more intuitive manner. A
+ XXX_opened method will be called when both local and remote peers
+ have opened the link, session or connection. This can be used to
+ confirm a locally initiated action for example. A XXX_opening
+ method will be called when the remote peer has requested an open
+ that was not initiated locally. By default this will simply open
+ locally, which then triggers the XXX_opened call. The same applies
+ to close.
+ """
+
def __init__(self, peer_close_is_error=False, delegate=None):
self.delegate = delegate
self.peer_close_is_error = peer_close_is_error
@@ -351,6 +380,11 @@ class EndpointStateHandler(Handler):
self.on_link_error(event)
class MessagingHandler(Handler, Acking):
+ """
+ A general purpose handler that makes the proton-c events somewhat
+ simpler to deal with and.or avoids repetitive tasks for common use
+ cases.
+ """
def __init__(self, prefetch=10, auto_accept=True, auto_settle=True, peer_close_is_error=False):
self.handlers = []
# FlowController if used needs to see event before
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/afc52a00/proton-c/bindings/python/proton/reactors.py
----------------------------------------------------------------------
diff --git a/proton-c/bindings/python/proton/reactors.py b/proton-c/bindings/python/proton/reactors.py
index 3e96a56..fc10860 100644
--- a/proton-c/bindings/python/proton/reactors.py
+++ b/proton-c/bindings/python/proton/reactors.py
@@ -23,8 +23,11 @@ from proton import Message, Handler, ProtonException, Transport, TransportExcept
from select import select
from proton.handlers import nested_handlers, ScopedHandler
-
class AmqpSocket(object):
+ """
+ Associates a transport with a connection and a socket and can be
+ used in an io loop to track the io for an AMQP 1.0 connection.
+ """
def __init__(self, conn, sock, events, heartbeat=None):
self.events = events
@@ -152,7 +155,12 @@ class AmqpSocket(object):
if t: return t - time.time()
else: return None
-class Acceptor:
+class AmqpAcceptor:
+ """
+ Listens for incoming sockets, creates an AmqpSocket for them and
+ adds that to the list of tracked 'selectables'. The acceptor can
+ itself be added to an io loop.
+ """
def __init__(self, events, loop, host, port):
self.events = events
@@ -192,7 +200,13 @@ class Acceptor:
def removed(self): pass
def tick(self): return None
+
class EventInjector(object):
+ """
+ Can be added to an io loop to allow events to be triggered by an
+ external thread but handled on the event thread associated with
+ the loop.
+ """
def __init__(self, events):
self.events = events
self.queue = Queue.Queue()
@@ -258,11 +272,19 @@ class Events(object):
return self.collector.peek() == None
class ExtendedEventType(object):
+ """
+ Event type identifier for events defined outside the proton-c
+ library
+ """
def __init__(self, name):
self.name = name
self.method = "on_%s" % name
class ApplicationEvent(Event):
+ """
+ Application defined event, which can optionally be associated with
+ an engine object and or an arbitrary subject
+ """
def __init__(self, typename, connection=None, session=None, link=None, delivery=None, subject=None):
self.type = ExtendedEventType(typename)
self.subject = subject
@@ -293,6 +315,9 @@ class StartEvent(ApplicationEvent):
self.reactor = reactor
class ScheduledEvents(Events):
+ """
+ Support for timed events
+ """
def __init__(self, *handlers):
super(ScheduledEvents, self).__init__(*handlers)
self._events = []
@@ -324,7 +349,9 @@ def _min(a, b):
else: return b
class SelectLoop(object):
-
+ """
+ An io loop based on select()
+ """
def __init__(self, events):
self.events = events
self.selectables = []
@@ -417,6 +444,9 @@ def _send_msg(self, msg, tag=None, handler=None, transaction=None):
class Transaction(object):
+ """
+ Class to track state of an AMQP 1.0 transaction.
+ """
def __init__(self, txn_ctrl, handler, settle_before_discharge=False):
self.txn_ctrl = txn_ctrl
self.handler = handler
@@ -491,8 +521,21 @@ class Transaction(object):
self._clear_pending()
class LinkOption(object):
- def apply(self, link): pass
- def test(self, link): return True
+ """
+ Abstract interface for link configuration options
+ """
+ def apply(self, link):
+ """
+ Subclasses will implement any configuration logic in this
+ method
+ """
+ pass
+ def test(self, link):
+ """
+ Subclasses can override this to selectively apply an option
+ e.g. based on some link criteria
+ """
+ return True
class AtMostOnce(LinkOption):
def apply(self, link):
@@ -519,6 +562,9 @@ class Filter(ReceiverOption):
receiver.source.filter.put_dict(self.filter_set)
class Selector(Filter):
+ """
+ Configures a link with a message selector filter
+ """
def __init__(self, value, name='selector'):
super(Selector, self).__init__({symbol(name): Described(symbol('apache.org:selector-filter:string'), value)})
@@ -532,6 +578,11 @@ def _apply_link_options(options, link):
class MessagingContext(object):
+ """
+ A context for creating links. This allows the user to ignore
+ sessions unless they explicitly want to control them. Additionally
+ provides support for transactional messaging.
+ """
def __init__(self, conn, handler=None, ssn=None):
self.conn = conn
if handler:
@@ -614,6 +665,10 @@ class MessagingContext(object):
self.conn.close()
class Connector(Handler):
+ """
+ Internal handler that triggers the necessary socket connect for an
+ opened connection.
+ """
def attach_to(self, loop):
self.loop = loop
@@ -648,6 +703,10 @@ class Connector(Handler):
self._connect(event.connection)
class Backoff(object):
+ """
+ A reconnect strategy involving an increasing delay between
+ retries, up to a maximum or 10 seconds.
+ """
def __init__(self):
self.delay = 0
@@ -708,7 +767,7 @@ class EventLoop(object):
def listen(self, url):
host, port = Urls([url]).next()
- return Acceptor(self.events, self, host, port)
+ return AmqpAcceptor(self.events, self, host, port)
def schedule(self, deadline, connection=None, session=None, link=None, delivery=None, subject=None):
self.events.schedule(deadline, ApplicationEvent("timer", connection, session, link, delivery, subject))
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/afc52a00/proton-c/bindings/python/proton/utils.py
----------------------------------------------------------------------
diff --git a/proton-c/bindings/python/proton/utils.py b/proton-c/bindings/python/proton/utils.py
index db23e55..845c3ab 100644
--- a/proton-c/bindings/python/proton/utils.py
+++ b/proton-c/bindings/python/proton/utils.py
@@ -49,6 +49,9 @@ class BlockingReceiver(BlockingLink):
if credit: receiver.flow(credit)
class BlockingConnection(Handler):
+ """
+ A synchronous style connection wrapper.
+ """
def __init__(self, url, timeout=None):
self.timeout = timeout
self.events = Events(ScopedHandler())
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org