content/releases/qpid-proton-0.32.0/proton/python/docs/index.html - qpid-site - Git at Google


 <!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 &#8212; 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> &#187;</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> &#187;</li>
         <li class="nav-item nav-item-this"><a href="">Qpid Proton Python API Documentation</a></li>
       </ul>
     </div>
     <div class="footer" role="contentinfo">
         &#169; Copyright 2019, Apache Qpid Contributors.
       Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.2.1.
     </div>
   </body>
 </html>

	<!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>