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 2015/04/07 13:27:31 UTC
qpid-proton git commit: Small improvements to documentation based on
feedback received
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 <gs...@redhat.com>
Authored: Tue Apr 7 12:28:45 2015 +0100
Committer: Gordon Sim <gs...@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