Small improvements to documentation based on feedback received (cherry picked from commit 450b8ba5d061014de879c5fdd3c507a65003aca4)
Project: http://git-wip-us.apache.org/repos/asf/qpid-proton/repo Commit: http://git-wip-us.apache.org/repos/asf/qpid-proton/commit/cf122858 Tree: http://git-wip-us.apache.org/repos/asf/qpid-proton/tree/cf122858 Diff: http://git-wip-us.apache.org/repos/asf/qpid-proton/diff/cf122858 Branch: refs/heads/0.9.x Commit: cf12285841934790940c0e3fba7575f1f569ff43 Parents: 62a97b6 Author: Gordon Sim <[email protected]> Authored: Tue Apr 7 12:28:45 2015 +0100 Committer: Robert Gemmell <[email protected]> Committed: Mon Apr 27 15:12:49 2015 +0100 ---------------------------------------------------------------------- .../bindings/python/docs/source/overview.rst | 100 ++++++++++++++----- proton-c/bindings/python/proton/__init__.py | 8 ++ proton-c/bindings/python/proton/reactor.py | 44 +++++++- 3 files changed, 124 insertions(+), 28 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/cf122858/proton-c/bindings/python/docs/source/overview.rst ---------------------------------------------------------------------- diff --git a/proton-c/bindings/python/docs/source/overview.rst b/proton-c/bindings/python/docs/source/overview.rst index 077c3de..d589c0b 100644 --- a/proton-c/bindings/python/docs/source/overview.rst +++ b/proton-c/bindings/python/docs/source/overview.rst @@ -8,7 +8,10 @@ An overview of the model Messages are transferred between connected peers over 'links'. At the sending peer the link is called a sender. At the receiving peer it is -a receiver. Messages are sent by senders and received by receivers. +called a receiver. Messages are sent by senders and received by +receivers. Links may have named 'source' and 'target' addresses (for +example to identify the queue from which message were to be received +or to which they were to be sent). Links are established over sessions. Sessions are established over connections. Connections are (generally) established between two @@ -24,35 +27,32 @@ transfer of that content. To indicate that a delivery is complete, either the sender or the receiver 'settles' it. When the other side learns that it has been settled, they will no longer communicate about that delivery. The -receiver can also indicate whether they accept or reject the message. +receiver can also indicate whether they accept or reject the +message. -Three different delivery levels or 'guarantees' can be achieved. - -For at-most-once, the sender settles the message as soon as it sends -it. If the connection is lost before the message is received by the -receiver, the message will not be delivered. - -For at-least-once, the receiver accepts and settles the message on -receipt. If the connection is lost before the sender is informed of -the settlement, then the delivery is considered in-doubt and should be -retried. This will ensure it eventually gets delivered (provided of -course the connection and link can be reestablished). It may mean that -it is delivered multiple times though. - -Finally, for exactly-once, the receiver accepts the message but -doesn't settle it. The sender settles once it is aware that the -receiver accepted it. In this way the receiver retains knowledge of an -accepted message until it is sure the sender knows it has been -accepted. If the connection is lost before settlement, the receiver -informs the sender of all the unsettled deliveries it knows about, and -from this the sender can deduce which need to be redelivered. The -sender likewise informs the receiver which deliveries it knows about, -from which the receiver can deduce which have already been settled. +Three different delivery levels or 'guarantees' can be achieved: +at-most-once, at-least-once or exactly-once. See +:ref:`delivery-guarantees` for more detail. ======================================================= A summary of the most commonly used classes and members ======================================================= +A brief summary of some of the key classes follows. A more complete +reference is available in :doc:`reference`. + +The :py:class:`~proton.reactor.Container` class is a convenient entry +point into the API, allowing connections and links to be +established. Applications are structured as one or more event +handlers. Handlers can be set at Container, Connection, or Link +scope. Messages are sent by establishing an approprate sender and +invoking its :py:meth:`~proton.Sender.send()` method. This is +typically done when the sender is sendable, a condition indicated by +the :py:meth:`~proton.handlers.MessagingHandler.on_sendable()` event, to +avoid execessive build up of messages. Messages can be received by +establishing an appropriate receiver and handling the +:py:meth:`~proton.handlers.MessagingHandler.on_message()` event. + .. autoclass:: proton.reactor.Container :show-inheritance: proton.reactor.Reactor :members: connect, create_receiver, create_sender, run, schedule @@ -64,6 +64,13 @@ A summary of the most commonly used classes and members connections it establishes. Container names should be unique. By default a UUID will be used. + The :py:meth:`~proton.reactor.Container.connect()` method returns + an instance of :py:class:`~proton.Connection`, the + :py:meth:`~proton.reactor.Container.create_receiver()` method + returns an instance of :py:class:`~proton.Receiver` and the + :py:meth:`~proton.reactor.Container.create_sender()` method + returns an instance of :py:class:`~proton.Sender`. + .. autoclass:: proton.Connection :members: open, close, state, session, hostname, container, remote_container, remote_desired_capabilities, remote_hostname, remote_offered_capabilities , remote_properties @@ -80,11 +87,18 @@ A summary of the most commonly used classes and members :undoc-members: .. autoclass:: proton.Link - :members: state, is_sender, is_receiver, + :members: name, state, is_sender, is_receiver, credit, queued, session, connection, source, target, remote_source, remote_target :undoc-members: + The :py:meth:`~proton.Link.source()`, + :py:meth:`~proton.Link.target()`, + :py:meth:`~proton.Link.remote_source()` and + :py:meth:`~proton.Link.remote_target()` methods all return an + instance of :py:class:`~proton.Terminus`. + + .. autoclass:: proton.Delivery :members: update, settle, settled, remote_state, local_state, partial, readable, writable, link, session, connection @@ -92,6 +106,11 @@ A summary of the most commonly used classes and members .. autoclass:: proton.handlers.MessagingHandler :members: on_start, on_reactor_init, + on_message, + on_accepted, + on_rejected, + on_settled, + on_sendable, on_connection_error, on_link_error, on_session_error, @@ -109,3 +128,34 @@ A summary of the most commonly used classes and members group_id, group_sequence, reply_to_group_id, send, recv, encode, decode :undoc-members: + +.. autoclass:: proton.Terminus + :members: address, dynamic, properties, capabilities, filter + :undoc-members: + +.. _delivery-guarantees: + +=================== +Delivery guarantees +=================== + +For at-most-once, the sender settles the message as soon as it sends +it. If the connection is lost before the message is received by the +receiver, the message will not be delivered. + +For at-least-once, the receiver accepts and settles the message on +receipt. If the connection is lost before the sender is informed of +the settlement, then the delivery is considered in-doubt and should be +retried. This will ensure it eventually gets delivered (provided of +course the connection and link can be reestablished). It may mean that +it is delivered multiple times though. + +Finally, for exactly-once, the receiver accepts the message but +doesn't settle it. The sender settles once it is aware that the +receiver accepted it. In this way the receiver retains knowledge of an +accepted message until it is sure the sender knows it has been +accepted. If the connection is lost before settlement, the receiver +informs the sender of all the unsettled deliveries it knows about, and +from this the sender can deduce which need to be redelivered. The +sender likewise informs the receiver which deliveries it knows about, +from which the receiver can deduce which have already been settled. http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/cf122858/proton-c/bindings/python/proton/__init__.py ---------------------------------------------------------------------- diff --git a/proton-c/bindings/python/proton/__init__.py b/proton-c/bindings/python/proton/__init__.py index d69d3dc..ed2a431 100644 --- a/proton-c/bindings/python/proton/__init__.py +++ b/proton-c/bindings/python/proton/__init__.py @@ -2683,6 +2683,7 @@ class Link(Wrapper, Endpoint): @property def name(self): + """Returns the name of the link""" return utf82unicode(pn_link_name(self._impl)) @property @@ -2764,6 +2765,7 @@ class Terminus(object): type = property(_get_type, _set_type) def _get_address(self): + """The address that identifies the source or target node""" return utf82unicode(pn_terminus_get_address(self._impl)) def _set_address(self, address): self._check(pn_terminus_set_address(self._impl, unicode2utf8(address))) @@ -2788,6 +2790,8 @@ class Terminus(object): timeout = property(_get_timeout, _set_timeout) def _is_dynamic(self): + """Indicates whether the source or target node was dynamically + created""" return pn_terminus_is_dynamic(self._impl) def _set_dynamic(self, dynamic): self._check(pn_terminus_set_dynamic(self._impl, dynamic)) @@ -2801,10 +2805,12 @@ class Terminus(object): @property def properties(self): + """Properties of a dynamic source or target.""" return Data(pn_terminus_properties(self._impl)) @property def capabilities(self): + """Capabilities of the source or target.""" return Data(pn_terminus_capabilities(self._impl)) @property @@ -2813,6 +2819,8 @@ class Terminus(object): @property def filter(self): + """A filter on a source allows the set of messages transfered over + the link to be restricted""" return Data(pn_terminus_filter(self._impl)) def copy(self, src): http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/cf122858/proton-c/bindings/python/proton/reactor.py ---------------------------------------------------------------------- diff --git a/proton-c/bindings/python/proton/reactor.py b/proton-c/bindings/python/proton/reactor.py index dcd2507..467bb76 100644 --- a/proton-c/bindings/python/proton/reactor.py +++ b/proton-c/bindings/python/proton/reactor.py @@ -600,7 +600,8 @@ class Container(Reactor): def connect(self, url=None, urls=None, address=None, handler=None, reconnect=None, heartbeat=None, ssl_domain=None): """ - Initiates the establishment of an AMQP connection. + Initiates the establishment of an AMQP connection. Returns an + instance of proton.Connection. """ conn = self.connection(handler) conn.container = self.container_id or str(generate_uuid()) @@ -643,7 +644,25 @@ class Container(Reactor): def create_sender(self, context, target=None, source=None, name=None, handler=None, tags=None, options=None): """ - Initiates the establishment of a link over which messages can be sent. + Initiates the establishment of a link over which messages can + be sent. Returns an instance of proton.Sender. + + There are two patterns of use. (1) A connection can be passed + as the first argument, in which case the link is established + on that connection. In this case the target address can be + specified as the second argument (or as a keyword + argument). The source address can also be specified if + desired. (2) Alternatively a URL can be passed as the first + argument. In this case a new connection will be establised on + which the link will be attached. If a path is specified and + the target is not, then the path of the URL is used as the + target address. + + The name of the link may be specified if desired, otherwise a + unique name will be generated. + + Various LinkOptions can be specified to further control the + attachment. """ if isinstance(context, basestring): context = Url(context) @@ -665,7 +684,26 @@ class Container(Reactor): def create_receiver(self, context, source=None, target=None, name=None, dynamic=False, handler=None, options=None): """ - Initiates the establishment of a link over which messages can be received (aka a subscription). + Initiates the establishment of a link over which messages can + be received (aka a subscription). Returns an instance of + proton.Receiver. + + There are two patterns of use. (1) A connection can be passed + as the first argument, in which case the link is established + on that connection. In this case the source address can be + specified as the second argument (or as a keyword + argument). The target address can also be specified if + desired. (2) Alternatively a URL can be passed as the first + argument. In this case a new connection will be establised on + which the link will be attached. If a path is specified and + the source is not, then the path of the URL is used as the + target address. + + The name of the link may be specified if desired, otherwise a + unique name will be generated. + + Various LinkOptions can be specified to further control the + attachment. """ if isinstance(context, basestring): context = Url(context) --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
