[
https://issues.apache.org/jira/browse/PROTON-2086?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16914616#comment-16914616
]
ASF GitHub Bot commented on PROTON-2086:
----------------------------------------
astitcher commented on pull request #186: PROTON-2086: Changed API
documentation from epydoc to Sphinx
URL: https://github.com/apache/qpid-proton/pull/186#discussion_r317293384
##########
File path: python/docs/index.rst
##########
@@ -1,11 +1,134 @@
-Apache Qpid Proton: python documentation
-========================================
+####################################
+Qpid Proton Python API Documentation
+####################################
-Contents:
+The Proton module provides a Python 2.7 and 3.x API for Qpid Proton. It
enables a developer to write Python applications
+that send and receive AMQP messages.
+*******
+Modules
+*******
.. toctree::
:maxdepth: 2
- tutorial
+ proton
+ proton.handlers
+ proton.reactor
+ proton.utils
+
+*****************************************
+About AMQP and the Qpid Proton Python API
+*****************************************
+
+.. toctree::
+ :maxdepth: 1
+
overview
+ tutorial
+
+Key API Features
+================
+
+ * Event-driven API
+ * SSL/TLS secured communication
+ * SASL authentication
+ * Automatic reconnect and failover
+ * Seamless conversion between AMQP and Python data types
+ * AMQP 1.0
+
+Basic API Concepts
+==================
+
+The Qpid Python client API and library allows applications to send and receive
AMQP messages. See :ref:`overview`
+for a more detailed explanation.
+
+Containers
+----------
+
+Messages are transferred between connected peers (or nodes) using **senders**
and **receivers**. Each sender
+or receiver is established over a **connection**. Each connection is
established between two unique **containers**,
+the entry point for the API. The container class
:class:`proton.reactor.Container` is found in the ``proton.reactor``
+module.
+
+Senders
+-------
+
+The peer that sends messages uses a **sender** to send messages, which
includes the target queue or topic which is
+to receive the messages. The sender may be found at :class:`proton.Sender`.
Note that senders are most commonly
+obtained by using the convenience method
:meth:`proton.reactor.Container.create_sender`.
+
+Receivers
+---------
+
+The peer that receives messages uses a **receiver** to receive messages, and
includes a source queue or topic from
+which to receive messages. The receiver may be found at
:class:`proton.Receiver`. Note that senders are most commonly
+obtained by using the convenience method
:meth:`proton.reactor.Container.create_receiver`.
+
+Message Delivery
+----------------
+
+The process of sending a message is known as **delevery**. Each sent message
has a delivry 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
+when a message-related event occurs through the event object. See `Event
Handlers`_ below.
+
+Event Handlers
+--------------
+
+A **handler** is a class that handles events associated with the sending and
receiving of messages. This includes
+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,
+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:
+
+* **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:
+
+* **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:
+
+* **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.
+
+Many other events exist for the handling of transactions and other message
events and errors, and if present in
+your handler will be called as the corresponding events arise. See the
:ref:`tutorial` for examples of handling
+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
Review comment:
I think that the API we provide is actually MessagingHandler - your
application needs to inherit from that - the other handlers aren't intended for
user use (at least not any more) - so specifically we should not be suggesting
that anyone uses handlers inherited directly from proton.Handler.
Also my opinion is that none of the other predefined handlers are for the
user to use currently (they are actually aggregated inside MessagingHandler
anyway) except perhaps the transaction related handlers (which I know little
about). This is partly because I want to view then as implementation detail and
get rid of them as separate entities in the future (although this may need a
major release revision)
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
> Move Python API docs to use Sphinx
> ----------------------------------
>
> Key: PROTON-2086
> URL: https://issues.apache.org/jira/browse/PROTON-2086
> Project: Qpid Proton
> Issue Type: Task
> Components: python-binding
> Reporter: Kim van der Riet
> Assignee: Kim van der Riet
> Priority: Major
>
> Currently the Python API docs are generated using ePyDoc. These should be
> switched to using Sphinx.
--
This message was sent by Atlassian Jira
(v8.3.2#803003)
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@qpid.apache.org
For additional commands, e-mail: dev-h...@qpid.apache.org
