PROTON-2402: Clarify proton docs for on_sendable, prefetch for Messag…

python/docs/proton.reactor.rst

@@ -11,7 +11,9 @@ Module Summary
 
 +---------------------------+----------------------------------------------------------------------------------------------------+
 | :class:`Container`        | A representation of the AMQP concept of a ‘container’, which loosely speaking is something that    |
-|                           | establishes links to or from another container, over which messages are transfered.                |
+|                           | establishes links to or from another container, over which messages are transferred. This class    |
+|                           | is NOT threadsafe. The :class:`EventInjector` class may be used for communication with external    |
+|                           | threads.                                                                                           |
 +---------------------------+----------------------------------------------------------------------------------------------------+
 | :class:`ApplicationEvent` | Application defined event, which can optionally be associated with an engine object and or an      |
 |                           | arbitrary subject.                                                                                 |

python/proton/_endpoints.py

@@ -1297,8 +1297,21 @@ def send(self, obj, tag=None):
         have a ``send()`` method on it that takes the sender and an optional
         tag as arguments.
 
+        The available credit count :attr:`Sender.credit` is decremented
+        immediately by 1 when the invocation has finished.
+
+        Message is registered for delivery but will be send eventually over the
+        wire when credit is available and the link is active. Will be buffered
+        until then.
+
         Where the object is a :class:`Message`, this will send the message over
         this link, creating a new delivery for the purpose.
+
+        :param tag: Use specified delivery tag is available. May be used in case
+            the message is retried and send again.
+        :type tag: ``bytes``
+        :param obj: The object to send.
+        :type obj: :class:`Message` or ``binary``
         """
         if hasattr(obj, 'send'):
             return obj.send(self, tag=tag)

python/proton/_handlers.py

@@ -705,6 +705,8 @@ class MessagingHandler(Handler, Acking):
     cases.
 
     :param prefetch: Initial flow credit for receiving messages, defaults to 10.
+        Whenever a message is settled, available credit will be increased to this
+        number through a flow frame.
     :type prefetch: ``int``
     :param auto_accept: If ``True``, accept all messages (default). Otherwise
         messages must be individually accepted or rejected.
@@ -876,7 +878,10 @@ def on_disconnected(self, event):
     def on_sendable(self, event):
         """
         Called when the sender link has credit and messages can
-        therefore be transferred.
+        therefore be transferred. This callback is called when:
+
+        1) A flow frame is received from remote peer.
+        2) When locally a message is send but more credit is still available.
 
         :param event: The underlying event object. Use this to obtain further
             information on the event.

python/proton/_reactor.py

@@ -1155,9 +1155,12 @@ class Container(Reactor):
     """
     A representation of the AMQP concept of a 'container', which
     loosely speaking is something that establishes links to or from
-    another container, over which messages are transfered. This is
+    another container, over which messages are transferred. This is
     an extension to the Reactor class that adds convenience methods
     for creating connections and sender- or receiver- links.
+
+    This class is NOT threadsafe. The :class:`EventInjector` class
+    may be used for communication with external threads.
     """
 
     def __init__(self, *handlers, **kwargs):