| |
| <!DOCTYPE html> |
| |
| <html> |
| <head> |
| <meta charset="utf-8" /> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0" /> |
| <title>Qpid Proton Python API Documentation — Qpid Proton Python API 0.32.0 documentation</title> |
| <link rel="stylesheet" href="_static/sphinxdoc.css" type="text/css" /> |
| <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> |
| <script id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script> |
| <script src="_static/jquery.js"></script> |
| <script src="_static/underscore.js"></script> |
| <script src="_static/doctools.js"></script> |
| <script src="_static/language_data.js"></script> |
| <script async="async" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/latest.js?config=TeX-AMS-MML_HTMLorMML"></script> |
| <link rel="index" title="Index" href="genindex.html" /> |
| <link rel="search" title="Search" href="search.html" /> |
| <link rel="next" title="Module proton" href="proton.html" /> |
| </head><body> |
| <div class="related" role="navigation" aria-label="related navigation"> |
| <h3>Navigation</h3> |
| <ul> |
| <li class="right" style="margin-right: 10px"> |
| <a href="genindex.html" title="General Index" |
| accesskey="I">index</a></li> |
| <li class="right" > |
| <a href="proton.html" title="Module proton" |
| accesskey="N">next</a> |</li> |
| <li class="nav-item nav-item-0"><a href="#">Qpid Proton Python API 0.32.0 documentation</a> »</li> |
| <li class="nav-item nav-item-this"><a href="">Qpid Proton Python API Documentation</a></li> |
| </ul> |
| </div> |
| |
| <div class="document"> |
| <div class="documentwrapper"> |
| <div class="bodywrapper"> |
| <div class="body" role="main"> |
| |
| <div class="section" id="qpid-proton-python-api-documentation"> |
| <h1>Qpid Proton Python API Documentation<a class="headerlink" href="#qpid-proton-python-api-documentation" title="Permalink to this headline">¶</a></h1> |
| <p>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.</p> |
| <div class="section" id="modules"> |
| <h2>Modules<a class="headerlink" href="#modules" title="Permalink to this headline">¶</a></h2> |
| <div class="toctree-wrapper compound"> |
| <ul> |
| <li class="toctree-l1"><a class="reference internal" href="proton.html">Module <code class="docutils literal notranslate"><span class="pre">proton</span></code></a><ul> |
| <li class="toctree-l2"><a class="reference internal" href="proton.html#module-summary">Module Summary</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="proton.html#module-detail">Module Detail</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l1"><a class="reference internal" href="proton.handlers.html">Module <code class="docutils literal notranslate"><span class="pre">proton.handlers</span></code></a><ul> |
| <li class="toctree-l2"><a class="reference internal" href="proton.handlers.html#module-summary">Module Summary</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="proton.handlers.html#module-detail">Module Detail</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l1"><a class="reference internal" href="proton.reactor.html">Module <code class="docutils literal notranslate"><span class="pre">proton.reactor</span></code></a><ul> |
| <li class="toctree-l2"><a class="reference internal" href="proton.reactor.html#module-summary">Module Summary</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="proton.reactor.html#module-detail">Module Detail</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l1"><a class="reference internal" href="proton.utils.html">Module <code class="docutils literal notranslate"><span class="pre">proton.utils</span></code></a><ul> |
| <li class="toctree-l2"><a class="reference internal" href="proton.utils.html#module-summary">Module Summary</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="proton.utils.html#module-detail">Module Detail</a></li> |
| </ul> |
| </li> |
| </ul> |
| </div> |
| </div> |
| <div class="section" id="about-amqp-and-the-qpid-proton-python-api"> |
| <h2>About AMQP and the Qpid Proton Python API<a class="headerlink" href="#about-amqp-and-the-qpid-proton-python-api" title="Permalink to this headline">¶</a></h2> |
| <div class="toctree-wrapper compound"> |
| <ul> |
| <li class="toctree-l1"><a class="reference internal" href="overview.html">API Overview</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="types.html">AMQP Types</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="tutorial.html">Tutorial</a></li> |
| </ul> |
| </div> |
| <div class="section" id="key-api-features"> |
| <h3>Key API Features<a class="headerlink" href="#key-api-features" title="Permalink to this headline">¶</a></h3> |
| <blockquote> |
| <div><ul class="simple"> |
| <li><p>Event-driven API</p></li> |
| <li><p>SSL/TLS secured communication</p></li> |
| <li><p>SASL authentication</p></li> |
| <li><p>Automatic reconnect and failover</p></li> |
| <li><p>Seamless conversion between AMQP and Python data types</p></li> |
| <li><p>AMQP 1.0</p></li> |
| </ul> |
| </div></blockquote> |
| </div> |
| <div class="section" id="basic-api-concepts"> |
| <h3>Basic API Concepts<a class="headerlink" href="#basic-api-concepts" title="Permalink to this headline">¶</a></h3> |
| <p>The Qpid Python client API and library allows applications to send and receive AMQP messages. See <a class="reference internal" href="overview.html#overview"><span class="std std-ref">API Overview</span></a> |
| for a more detailed explanation.</p> |
| <div class="section" id="containers"> |
| <h4>Containers<a class="headerlink" href="#containers" title="Permalink to this headline">¶</a></h4> |
| <p>Messages are transferred between connected peers (or nodes) using <strong>senders</strong> and <strong>receivers</strong>. Each sender |
| or receiver is established over a <strong>connection</strong>. Each connection is established between two unique <strong>containers</strong>, |
| the entry point for the API. The container class <a class="reference internal" href="proton.reactor.html#proton.reactor.Container" title="proton.reactor.Container"><code class="xref py py-class docutils literal notranslate"><span class="pre">proton.reactor.Container</span></code></a> is found in the <code class="docutils literal notranslate"><span class="pre">proton.reactor</span></code> |
| module.</p> |
| </div> |
| <div class="section" id="connections"> |
| <h4>Connections<a class="headerlink" href="#connections" title="Permalink to this headline">¶</a></h4> |
| <p>A <strong>connection</strong> object tracks the status of an AMQP connection. For applications which <em>don’t</em> require either |
| authorization or encryption, these may be automatically created by convenience methods |
| <a class="reference internal" href="proton.reactor.html#proton.reactor.Container.create_sender" title="proton.reactor.Container.create_sender"><code class="xref py py-meth docutils literal notranslate"><span class="pre">proton.reactor.Container.create_sender()</span></code></a> and/or <a class="reference internal" href="proton.reactor.html#proton.reactor.Container.create_receiver" title="proton.reactor.Container.create_receiver"><code class="xref py py-meth docutils literal notranslate"><span class="pre">proton.reactor.Container.create_receiver()</span></code></a>. |
| However, for applications which <em>do</em> require either of these services, a connection object should be created |
| using the convenience method <a class="reference internal" href="proton.reactor.html#proton.reactor.Container.connect" title="proton.reactor.Container.connect"><code class="xref py py-meth docutils literal notranslate"><span class="pre">proton.reactor.Container.connect()</span></code></a>, providing the required parameters. |
| This object should then be passed to the convenience methods <a class="reference internal" href="proton.reactor.html#proton.reactor.Container.create_sender" title="proton.reactor.Container.create_sender"><code class="xref py py-meth docutils literal notranslate"><span class="pre">proton.reactor.Container.create_sender()</span></code></a> |
| and/or <a class="reference internal" href="proton.reactor.html#proton.reactor.Container.create_receiver" title="proton.reactor.Container.create_receiver"><code class="xref py py-meth docutils literal notranslate"><span class="pre">proton.reactor.Container.create_receiver()</span></code></a> as needed. The connection class may be found at |
| <a class="reference internal" href="proton.html#proton.Connection" title="proton.Connection"><code class="xref py py-class docutils literal notranslate"><span class="pre">proton.Connection</span></code></a>.</p> |
| </div> |
| <div class="section" id="senders"> |
| <h4>Senders<a class="headerlink" href="#senders" title="Permalink to this headline">¶</a></h4> |
| <p>The peer that sends messages uses a <strong>sender</strong> to send messages, which includes the target queue or topic which is |
| to receive the messages. The sender may be found at <a class="reference internal" href="proton.html#proton.Sender" title="proton.Sender"><code class="xref py py-class docutils literal notranslate"><span class="pre">proton.Sender</span></code></a>. Note that senders are most commonly |
| obtained by using the convenience method <a class="reference internal" href="proton.reactor.html#proton.reactor.Container.create_sender" title="proton.reactor.Container.create_sender"><code class="xref py py-meth docutils literal notranslate"><span class="pre">proton.reactor.Container.create_sender()</span></code></a>.</p> |
| </div> |
| <div class="section" id="receivers"> |
| <h4>Receivers<a class="headerlink" href="#receivers" title="Permalink to this headline">¶</a></h4> |
| <p>The peer that receives messages uses a <strong>receiver</strong> to receive messages, and includes a source queue or topic from |
| which to receive messages. The receiver may be found at <a class="reference internal" href="proton.html#proton.Receiver" title="proton.Receiver"><code class="xref py py-class docutils literal notranslate"><span class="pre">proton.Receiver</span></code></a>. Note that senders are most commonly |
| obtained by using the convenience method <a class="reference internal" href="proton.reactor.html#proton.reactor.Container.create_receiver" title="proton.reactor.Container.create_receiver"><code class="xref py py-meth docutils literal notranslate"><span class="pre">proton.reactor.Container.create_receiver()</span></code></a>.</p> |
| </div> |
| <div class="section" id="message-delivery"> |
| <h4>Message Delivery<a class="headerlink" href="#message-delivery" title="Permalink to this headline">¶</a></h4> |
| <p>The process of sending a message is known as <strong>delivery</strong>. 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 (ie causing the delivery status to be forgotten when it is no longer needed). The delivery class may be found |
| at <a class="reference internal" href="proton.html#proton.Delivery" title="proton.Delivery"><code class="xref py py-class docutils literal notranslate"><span class="pre">proton.Delivery</span></code></a>. The delivery object is most commonly obtained |
| when a message-related event occurs through the event object. See <a class="reference internal" href="#event-handlers">Event Handlers</a> below.</p> |
| </div> |
| <div class="section" id="event-handlers"> |
| <h4>Event Handlers<a class="headerlink" href="#event-handlers" title="Permalink to this headline">¶</a></h4> |
| <p>A <strong>handler</strong> 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 an object associated with the event. For example, |
| when a message is received, the event object will have the property <code class="docutils literal notranslate"><span class="pre">event.message</span></code> by which the message itself may |
| be obtained. See <a class="reference internal" href="proton.html#proton.Event" title="proton.Event"><code class="xref py py-class docutils literal notranslate"><span class="pre">proton.Event</span></code></a> for more details.</p> |
| <p>The following are some of the important event callbacks that may be implemented by a developer:</p> |
| <ul class="simple"> |
| <li><dl class="simple"> |
| <dt><strong>on_start()</strong>: This indicates that the event loop in the container has started, and that a new sender and/or</dt><dd><p>receiver may now be created.</p> |
| </dd> |
| </dl> |
| </li> |
| </ul> |
| <p>To send a message, the following events may need to be handled:</p> |
| <ul class="simple"> |
| <li><dl class="simple"> |
| <dt><strong>on_sendable()</strong>: This callback indicates that send credit has now been set by the receiver, and that a message may</dt><dd><p>now be sent.</p> |
| </dd> |
| </dl> |
| </li> |
| <li><p><strong>on_accepted()</strong>: This callback indicates that a message has been received and accepted by the receiving peer.</p></li> |
| </ul> |
| <p>To receive a message, the following event may need to be handled:</p> |
| <ul class="simple"> |
| <li><dl class="simple"> |
| <dt><strong>on_message()</strong>: This callback indicates that a message has been received. The message and its delivery object may</dt><dd><p>be retreived, and if needed, the message can be either accepted or rejected.</p> |
| </dd> |
| </dl> |
| </li> |
| </ul> |
| <p>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 <a class="reference internal" href="tutorial.html#tutorial"><span class="std std-ref">Tutorial</span></a> for examples of handling |
| some other events.</p> |
| <p>Several event handlers are provided which provide default behavior for most events. These may be found in the |
| <code class="docutils literal notranslate"><span class="pre">proton.handlers</span></code> module. The <a class="reference internal" href="proton.handlers.html#proton.handlers.MessagingHandler" title="proton.handlers.MessagingHandler"><code class="xref py py-class docutils literal notranslate"><span class="pre">proton.handlers.MessagingHandler</span></code></a> is the most commonly used handler for |
| 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.</p> |
| </div> |
| <div class="section" id="amqp-types"> |
| <h4>AMQP types<a class="headerlink" href="#amqp-types" title="Permalink to this headline">¶</a></h4> |
| <p>The types defined by the AMQP specification are mapped to either native Python types or to special proton classes |
| which represent the AMQP type. See <a class="reference internal" href="types.html#types"><span class="std std-ref">AMQP Types</span></a> for a summary.</p> |
| </div> |
| <div class="section" id="examples"> |
| <h4>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h4> |
| <p>Several examples may be found in the |
| <a class="reference external" href="https://qpid.apache.org/releases/qpid-proton-0.28.0/proton/python/examples/index.html">Apache Qpid Proton Examples</a> |
| 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.</p> |
| </div> |
| <div class="section" id="tutorial"> |
| <h4>Tutorial<a class="headerlink" href="#tutorial" title="Permalink to this headline">¶</a></h4> |
| <p>See this <a class="reference internal" href="tutorial.html#tutorial"><span class="std std-ref">Tutorial</span></a> on using the API.</p> |
| </div> |
| </div> |
| <div class="section" id="indices-and-tables"> |
| <h3>Indices and tables<a class="headerlink" href="#indices-and-tables" title="Permalink to this headline">¶</a></h3> |
| <ul class="simple"> |
| <li><p><a class="reference internal" href="genindex.html"><span class="std std-ref">Index</span></a></p></li> |
| <li><p><a class="reference internal" href="search.html"><span class="std std-ref">Search Page</span></a></p></li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| |
| |
| <div class="clearer"></div> |
| </div> |
| </div> |
| </div> |
| <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> |
| <div class="sphinxsidebarwrapper"> |
| <h3><a href="#">Table of Contents</a></h3> |
| <ul> |
| <li><a class="reference internal" href="#">Qpid Proton Python API Documentation</a><ul> |
| <li><a class="reference internal" href="#modules">Modules</a></li> |
| <li><a class="reference internal" href="#about-amqp-and-the-qpid-proton-python-api">About AMQP and the Qpid Proton Python API</a><ul> |
| <li><a class="reference internal" href="#key-api-features">Key API Features</a></li> |
| <li><a class="reference internal" href="#basic-api-concepts">Basic API Concepts</a><ul> |
| <li><a class="reference internal" href="#containers">Containers</a></li> |
| <li><a class="reference internal" href="#connections">Connections</a></li> |
| <li><a class="reference internal" href="#senders">Senders</a></li> |
| <li><a class="reference internal" href="#receivers">Receivers</a></li> |
| <li><a class="reference internal" href="#message-delivery">Message Delivery</a></li> |
| <li><a class="reference internal" href="#event-handlers">Event Handlers</a></li> |
| <li><a class="reference internal" href="#amqp-types">AMQP types</a></li> |
| <li><a class="reference internal" href="#examples">Examples</a></li> |
| <li><a class="reference internal" href="#tutorial">Tutorial</a></li> |
| </ul> |
| </li> |
| <li><a class="reference internal" href="#indices-and-tables">Indices and tables</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| |
| <h4>Next topic</h4> |
| <p class="topless"><a href="proton.html" |
| title="next chapter">Module <code class="docutils literal notranslate"><span class="pre">proton</span></code></a></p> |
| <div role="note" aria-label="source link"> |
| <h3>This Page</h3> |
| <ul class="this-page-menu"> |
| <li><a href="_sources/index.rst.txt" |
| rel="nofollow">Show Source</a></li> |
| </ul> |
| </div> |
| <div id="searchbox" style="display: none" role="search"> |
| <h3 id="searchlabel">Quick search</h3> |
| <div class="searchformwrapper"> |
| <form class="search" action="search.html" method="get"> |
| <input type="text" name="q" aria-labelledby="searchlabel" /> |
| <input type="submit" value="Go" /> |
| </form> |
| </div> |
| </div> |
| <script>$('#searchbox').show(0);</script> |
| </div> |
| </div> |
| <div class="clearer"></div> |
| </div> |
| <div class="related" role="navigation" aria-label="related navigation"> |
| <h3>Navigation</h3> |
| <ul> |
| <li class="right" style="margin-right: 10px"> |
| <a href="genindex.html" title="General Index" |
| >index</a></li> |
| <li class="right" > |
| <a href="proton.html" title="Module proton" |
| >next</a> |</li> |
| <li class="nav-item nav-item-0"><a href="#">Qpid Proton Python API 0.32.0 documentation</a> »</li> |
| <li class="nav-item nav-item-this"><a href="">Qpid Proton Python API Documentation</a></li> |
| </ul> |
| </div> |
| <div class="footer" role="contentinfo"> |
| © Copyright 2019, Apache Qpid Contributors. |
| Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.2.1. |
| </div> |
| </body> |
| </html> |