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 <[email protected]> Authored: Wed Nov 26 21:03:54 2014 +0000 Committer: Gordon Sim <[email protected]> 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: [email protected] For additional commands, e-mail: [email protected]
