You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by kp...@apache.org on 2019/08/28 19:24:34 UTC
[qpid-proton] branch shinx-docs updated: PROTON-2086: Final
modifications to docs as part of a PR. Incorporated feedback from PR.
This is an automated email from the ASF dual-hosted git repository.
kpvdr pushed a commit to branch shinx-docs
in repository https://gitbox.apache.org/repos/asf/qpid-proton.git
The following commit(s) were added to refs/heads/shinx-docs by this push:
new 26c4394 PROTON-2086: Final modifications to docs as part of a PR. Incorporated feedback from PR.
26c4394 is described below
commit 26c43942d5297c317123e567fed6b7b69f4ba561
Author: Kim van der Riet <kv...@localhost.localdomain>
AuthorDate: Wed Aug 28 15:24:21 2019 -0400
PROTON-2086: Final modifications to docs as part of a PR. Incorporated feedback from PR.
---
python/docs/conf.py | 17 +++++++++++++++--
python/docs/index.rst | 32 ++++++++++++++++++++++----------
python/docs/proton.handlers.rst | 30 ------------------------------
3 files changed, 37 insertions(+), 42 deletions(-)
diff --git a/python/docs/conf.py b/python/docs/conf.py
index bc073bf..edd613e 100644
--- a/python/docs/conf.py
+++ b/python/docs/conf.py
@@ -23,9 +23,22 @@ copyright = '2019, Apache Qpid Contributors'
author = 'Apache Qpid Contributors'
# The short X.Y version
-version = '0.27'
+version = '0.0'
# The full version, including alpha/beta/rc tags
-release = '0.27'
+release = '0.0'
+# Read version from VERSION.txt file in Proton top level directory
+try:
+ ver_file_path = os.path.abspath('../../VERSION.txt')
+ with open(ver_file_path, 'r') as ver_file:
+ ver_str = ver_file.read().replace('\n', '')
+ if '-' in ver_str:
+ version = ver_str.split("-")[0] # Strip '-SNAPSHOT' from end of string
+ else:
+ version = ver_str;
+ release = version
+ print('Proton version: %s' % version)
+except IOError:
+ print('WARNING: Proton version file %s not found.' % ver_file_path)
# -- General configuration ---------------------------------------------------
diff --git a/python/docs/index.rst b/python/docs/index.rst
index e19164e..ad9fa48 100644
--- a/python/docs/index.rst
+++ b/python/docs/index.rst
@@ -50,6 +50,18 @@ or receiver is established over a **connection**. Each connection is established
the entry point for the API. The container class :class:`proton.reactor.Container` is found in the ``proton.reactor``
module.
+Connections
+-----------
+
+A **connection** object tracks the status of an AMQP connection. For applications which *don't* require either
+authorization or encryption, these may be automatically created by convenience methods
+:meth:`proton.reactor.Container.create_sender` and/or :meth:`proton.reactor.Container.create_receiver`.
+However, for applications which *do* require either of these services, a connection object should be created
+using the convenience method :meth:`proton.reactor.Container.connect`, providing the required parameters.
+This object should then be passed to the convenience methods :meth:`proton.reactor.Container.create_sender`
+and/or :meth:`proton.reactor.Container.create_receiver` as needed. The connection class may be found at
+:class:`proton.Connection`.
+
Senders
-------
@@ -67,10 +79,10 @@ obtained by using the convenience method :meth:`proton.reactor.Container.create_
Message Delivery
----------------
-The process of sending a message is known as **delevery**. Each sent message has a delivry object which tracks the
+The process of sending a message is known as **delivery**. Each sent message has a delivery object which tracks the
status of the message as it is sent from the sender to the receiver. This also includes actions such as settling the
-delivery, a mechanism by which each peer can verify that the message has been properly received and is either accepted
-or rejected. The delivery class may be found at :class:`proton.Delivery`. The delivery object is most commonly obtained
+delivery (ie causing the delivery status to be forgotten when it is no longer needed). The delivery class may be found
+at :class:`proton.Delivery`. The delivery object is most commonly obtained
when a message-related event occurs through the event object. See `Event Handlers`_ below.
Event Handlers
@@ -80,22 +92,22 @@ A **handler** is a class that handles events associated with the sending and rec
callbacks for events such as the arrival of a new message, error conditions that might arise, and the closing
of the connection over which messages are sent. An application developer must handle some key events to
successfully send and receive messages. When an event handler callback is called by the library, an Event object is
-passed to it which contains details of the event, and in some cases, objects associated with the event. For example,
+passed to it which contains an object associated with the event. For example,
when a message is received, the event object will have the property ``event.message`` by which the message itself may
be obtained. See :class:`proton.Event` for more details.
-The following are some of the important event callbacks that should be implemented by a developer:
+The following are some of the important event callbacks that may be implemented by a developer:
* **on_start()**: This indicates that the event loop in the container has started, and that a new sender and/or
receiver may now be created.
-To send a message, the following events need to be handled:
+To send a message, the following events may need to be handled:
* **on_sendable()**: This callback indicates that send credit has now been set by the receiver, and that a message may
now be sent.
* **on_accepted()**: This callback indicates that a message has been received and accepted by the receiving peer.
-To receive a message, the following event need to be handled:
+To receive a message, the following event may need to be handled:
* **on_message()**: This callback indicates that a message has been received. The message and its delivery object may
be retreived, and if needed, the message can be either accepted or rejected.
@@ -106,7 +118,8 @@ some other events.
Several event handlers are provided which provide default behavior for most events. These may be found in the
``proton.handlers`` module. The :class:`proton.handlers.MessagingHandler` is the most commonly used handler for
-non-transactional applications.
+non-transactional applications. Developers would typically directly inherit from this handler to provide the
+application's event behavior, and override callbacks as needed to provide additional behavior they may require.
Examples
--------
@@ -115,8 +128,7 @@ Several examples may be found in the
`Apache Qpid Proton Examples <https://qpid.apache.org/releases/qpid-proton-0.28.0/proton/python/examples/index.html>`_
whcih illustrate the techniques and concepts of sending messages. They are also present in the source. These make
an excellent starting point for developers new to this API. Make sure to read the README file, which gives
-instructions on how to run them and a brief explanation of each example and how to configure SASL for examples which
-use it.
+instructions on how to run them and a brief explanation of each example.
Tutorial
--------
diff --git a/python/docs/proton.handlers.rst b/python/docs/proton.handlers.rst
index 941027a..662eb23 100644
--- a/python/docs/proton.handlers.rst
+++ b/python/docs/proton.handlers.rst
@@ -12,9 +12,6 @@ Module Summary
.. autosummary::
MessagingHandler
- EndpointStateHandler
- IncomingMessageHandler
- OutgoingMessageHandler
TransactionHandler
TransactionalClientHandler
@@ -46,33 +43,6 @@ Module Detail
------------
-.. autoclass:: proton.handlers.EndpointStateHandler
- :members:
- :show-inheritance:
- :inherited-members:
- :undoc-members:
- :exclude-members: handlers, add, on_link_remote_close, on_session_remote_close, on_connection_remote_close, on_connection_local_open, on_connection_remote_open, on_session_local_open, on_session_remote_open, on_link_local_open, on_link_remote_open
-
-------------
-
-.. autoclass:: proton.handlers.IncomingMessageHandler
- :members:
- :show-inheritance:
- :inherited-members:
- :undoc-members:
- :exclude-members: handlers, add, on_delivery
-
-------------
-
-.. autoclass:: proton.handlers.OutgoingMessageHandler
- :members:
- :show-inheritance:
- :inherited-members:
- :undoc-members:
- :exclude-members: handlers, add, on_link_flow, on_delivery
-
-------------
-
.. autoclass:: proton.handlers.TransactionHandler
:members:
:show-inheritance:
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org