qpid-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From g...@apache.org
Subject qpid-proton git commit: Small improvements to documentation based on feedback received
Date Tue, 07 Apr 2015 11:27:31 GMT
Repository: qpid-proton
Updated Branches:
  refs/heads/master 5bf533c2e -> 450b8ba5d


Small improvements to documentation based on feedback received


Project: http://git-wip-us.apache.org/repos/asf/qpid-proton/repo
Commit: http://git-wip-us.apache.org/repos/asf/qpid-proton/commit/450b8ba5
Tree: http://git-wip-us.apache.org/repos/asf/qpid-proton/tree/450b8ba5
Diff: http://git-wip-us.apache.org/repos/asf/qpid-proton/diff/450b8ba5

Branch: refs/heads/master
Commit: 450b8ba5d061014de879c5fdd3c507a65003aca4
Parents: 5bf533c
Author: Gordon Sim <gsim@redhat.com>
Authored: Tue Apr 7 12:28:45 2015 +0100
Committer: Gordon Sim <gsim@redhat.com>
Committed: Tue Apr 7 12:28:45 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/450b8ba5/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/450b8ba5/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 68a499e..eeb7768 100644
--- a/proton-c/bindings/python/proton/__init__.py
+++ b/proton-c/bindings/python/proton/__init__.py
@@ -2689,6 +2689,7 @@ class Link(Wrapper, Endpoint):
 
   @property
   def name(self):
+    """Returns the name of the link"""
     return utf82unicode(pn_link_name(self._impl))
 
   @property
@@ -2770,6 +2771,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)))
@@ -2794,6 +2796,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))
@@ -2807,10 +2811,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
@@ -2819,6 +2825,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/450b8ba5/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: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org


Mime
View raw message