PyPI - amps-python-client - Versions diffs - 5.3.4.1__zip → 5.3.4.3__zip - Mend

amps-python-client 5.3.4.1zip → 5.3.4.3zip

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (918) hide show

amps-python-client-5.3.4.3/docs/python/html/chapters/subscriptions.html ADDED Viewed

@@ -0,0 +1,535 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    <title>4. Subscriptions &#8212; Python Developer Guide 5.3.4.0
+ documentation</title>
+    <link rel="stylesheet" href="../_static/alabaster.css" type="text/css" />
+    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+    <script type="text/javascript">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    '../',
+        VERSION:     '5.3.4.0',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true,
+        SOURCELINK_SUFFIX: '.txt'
+      };
+    </script>
+    <script type="text/javascript" src="../_static/jquery.js"></script>
+    <script type="text/javascript" src="../_static/underscore.js"></script>
+    <script type="text/javascript" src="../_static/doctools.js"></script>
+    <link rel="index" title="Index" href="../genindex.html" />
+    <link rel="search" title="Search" href="../search.html" />
+    <link rel="next" title="5. Error Handling" href="error-handling.html" />
+    <link rel="prev" title="3. Your First AMPS Program" href="first-program.html" />
+  <link rel="stylesheet" href="../_static/custom.css" type="text/css" />
+  <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
+  </head>
+  <body role="document">
+  <div class="document">
+      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
+        <div class="sphinxsidebarwrapper">
+            <p class="logo"><a href="../index.html">
+              <img class="logo" src="../_static/flag_logo.png" alt="Logo"/>
+            </a></p>
+  <h3><a href="../index.html">Table Of Contents</a></h3>
+  <ul>
+<li><a class="reference internal" href="#">4. Subscriptions</a><ul>
+<li><a class="reference internal" href="#subscribing-to-a-topic">Subscribing to a Topic</a><ul>
+<li><a class="reference internal" href="#asynchronous-message-processing-interface">Asynchronous Message Processing Interface</a></li>
+<li><a class="reference internal" href="#using-an-instance-method-as-a-message-handler">Using an Instance Method as a Message Handler</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#understanding-threading-and-message-handlers">Understanding Threading and Message Handlers</a></li>
+<li><a class="reference internal" href="#understanding-messages">Understanding Messages</a><ul>
+<li><a class="reference internal" href="#header-properties">Header Properties</a></li>
+<li><a class="reference internal" href="#get-data-method">get_data() Method</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#unsubscribing">Unsubscribing</a></li>
+<li><a class="reference internal" href="#advanced-messaging-support">Advanced Messaging Support</a><ul>
+<li><a class="reference internal" href="#regex-subscriptions">Regex Subscriptions</a></li>
+<li><a class="reference internal" href="#content-filtering">Content Filtering</a></li>
+<li><a class="reference internal" href="#updating-the-filter-on-a-subscribe">Updating the Filter on a Subscribe</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#next-steps">Next Steps</a></li>
+</ul>
+</li>
+</ul>
+<div class="relations">
+<h3>Related Topics</h3>
+<ul>
+  <li><a href="../index.html">Documentation overview</a><ul>
+      <li>Previous: <a href="first-program.html" title="previous chapter">3. Your First AMPS Program</a></li>
+      <li>Next: <a href="error-handling.html" title="next chapter">5. Error Handling</a></li>
+  </ul></li>
+</ul>
+</div>
+<div id="searchbox" style="display: none" role="search">
+  <h3>Quick search</h3>
+    <form class="search" action="../search.html" method="get">
+      <div><input type="text" name="q" /></div>
+      <div><input type="submit" value="Go" /></div>
+      <input type="hidden" name="check_keywords" value="yes" />
+      <input type="hidden" name="area" value="default" />
+    </form>
+</div>
+<script type="text/javascript">$('#searchbox').show(0);</script>
+        </div>
+      </div>
+      <div class="documentwrapper">
+        <div class="bodywrapper">
+          <div class="body" role="main">
+  <div class="section" id="subscriptions">
+<h1>4. Subscriptions<a class="headerlink" href="#subscriptions" title="Permalink to this headline">¶</a></h1>
+<p>Messages published to a topic on an AMPS server are available to other
+clients via a subscription. Before messages can be received, a client
+must subscribe to one or more topics on the AMPS server so that the
+server will begin sending messages to the client. The server will
+continue sending messages to the client until the client unsubscribes,
+or the client disconnects. With content filtering, the AMPS server will
+limit the messages sent to only those messages that match a
+client-supplied filter. In this chapter, you will learn how to
+subscribe, unsubscribe, and supply filters for messages using the AMPS
+Python client.</p>
+<div class="section" id="subscribing-to-a-topic">
+<h2>Subscribing to a Topic<a class="headerlink" href="#subscribing-to-a-topic" title="Permalink to this headline">¶</a></h2>
+<p>The AMPS client makes it simple to subscribe to a topic. You call
+<code class="docutils literal"><span class="pre">client.subscribe()</span></code> with the topic to subscribe to and the parameters
+for the subscription. The client submits the subscription to AMPS and
+returns a <code class="docutils literal"><span class="pre">MessageStream</span></code> that you can iterate over to receive the
+messages from the subscription. Below is a short example:</p>
+<div class="code python highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">AMPS</span> <span class="kn">import</span> <span class="n">Client</span>
+<span class="c1"># Here, we create a Client object and connect to an AMPS server.</span>
+<span class="n">client</span> <span class="o">=</span> <span class="n">Client</span><span class="p">(</span><span class="s2">&quot;test&quot;</span><span class="p">)</span>
+<span class="n">client</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="s2">&quot;tcp://127.0.0.1:9007/amps/json&quot;</span><span class="p">)</span>
+<span class="n">client</span><span class="o">.</span><span class="n">logon</span><span class="p">()</span>
+<span class="c1"># Here we subscribe to the topic messages. We do not provide a filter, so AMPS</span>
+<span class="c1"># does not content-filter the topic. Although we don&#39;t use the object explicitly</span>
+<span class="c1"># here, the subscribe method returns a MessageStream object that we iterate over.</span>
+<span class="c1"># If, at any time, we no longer need to subscribe, we can break out of the loop.</span>
+<span class="c1"># When there are no more active references to the MessageStream, the client sends</span>
+<span class="c1"># an unsubscribe command to AMPS and stops receiving messages.</span>
+<span class="k">for</span> <span class="n">message</span> <span class="ow">in</span> <span class="n">client</span><span class="o">.</span><span class="n">subscribe</span><span class="p">(</span><span class="s2">&quot;messages&quot;</span><span class="p">):</span>
+    <span class="c1"># Within the loop, we process the message. In this case, we simply print the</span>
+    <span class="c1"># contents of the message.</span>
+    <span class="nb">print</span><span class="p">(</span><span class="n">message</span><span class="o">.</span><span class="n">get_data</span><span class="p">())</span>
+</pre></div>
+</div>
+<p><strong>Example 4.1:</strong> <em>Basic AMPS subscription</em></p>
+<p>AMPS creates a background thread that receives messages and copies them
+into the <code class="docutils literal"><span class="pre">MessageStream</span></code> that you iterate over. This means that the
+client application as a whole can continue to receive messages while you
+are doing processing work.</p>
+<p>The simple method described above is provided for convenience. The AMPS
+Python client provides convenience methods for the most common form of
+AMPS commands. The client also provides an interface that allows you to
+have precise control over the command. Using that interface, the example
+above becomes:</p>
+<div class="code python highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">AMPS</span> <span class="kn">import</span> <span class="n">Client</span>
+<span class="kn">from</span> <span class="nn">AMPS</span> <span class="kn">import</span> <span class="n">Command</span>
+<span class="c1"># Here, we create a Client object and connect to an AMPS server.</span>
+<span class="n">client</span> <span class="o">=</span> <span class="n">Client</span><span class="p">(</span><span class="s2">&quot;test&quot;</span><span class="p">)</span>
+<span class="n">client</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="s2">&quot;tcp://127.0.0.1:9007/amps/json&quot;</span><span class="p">)</span>
+<span class="n">client</span><span class="o">.</span><span class="n">logon</span><span class="p">()</span>
+<span class="c1"># Here, we create a Command object for the subscribe command, specifying the topic</span>
+<span class="c1"># messages. We do not provide a filter, so AMPS does not content-filter the</span>
+<span class="c1"># subscription. Although we don&#39;t use the object explicitly here, the execute</span>
+<span class="c1"># method returns a MessageStream object that we iterate over. If, at any time, we</span>
+<span class="c1"># no longer need to subscribe, we can break out of the loop. When we break out of</span>
+<span class="c1"># the loop, there are no more references to the MessageStream and the AMPS client</span>
+<span class="c1"># sends an unsubscribe message to AMPS.</span>
+<span class="k">for</span> <span class="n">message</span> <span class="ow">in</span> <span class="n">client</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="n">Command</span><span class="p">(</span><span class="s2">&quot;subscribe&quot;</span><span class="p">)</span><span class="o">.</span><span class="n">set_topic</span><span class="p">(</span><span class="s2">&quot;messages&quot;</span><span class="p">)):</span>
+    <span class="c1"># Within the body of the loop, we can process the message as we need to. In this</span>
+    <span class="c1"># case, we simply print the contents of the message.</span>
+    <span class="nb">print</span><span class="p">(</span><span class="n">message</span><span class="o">.</span><span class="n">get_data</span><span class="p">())</span>
+</pre></div>
+</div>
+<p><strong>Example 4.2:</strong> <em>Subscribing to a topic using a command</em></p>
+<p>The <code class="docutils literal"><span class="pre">Command</span></code> interface allows you to precisely customize the commands
+you send to AMPS. For flexibility and ease of maintenance, 60East
+recommends using the <code class="docutils literal"><span class="pre">Command</span></code> interface (rather than a named method)
+for any command that will receive messages from AMPS. For publishing
+messages, there can be a slight performance advantage to using the named
+commands where possible.</p>
+<div class="section" id="asynchronous-message-processing-interface">
+<h3>Asynchronous Message Processing Interface<a class="headerlink" href="#asynchronous-message-processing-interface" title="Permalink to this headline">¶</a></h3>
+<p>The AMPS Python client also supports an interface that allows you to
+process messages asynchronously. In this case, you add a message handler
+to the method call. The client returns the command ID of the subscribe
+command once the server has acknowledged that the command has been
+processed. As messages arrive, the client calls your message handler
+directly on the background thread. This can be an advantage for some
+applications. For example, if your application is highly multithreaded
+and copies message data to a work queue processed by multiple threads,
+there may be a performance benefit to enqueuing work directly
+from the background thread. See
+<a class="reference internal" href="#understanding-threading-section"><span class="std std-ref">Understanding Threading and Message Handlers</span></a>
+for a discussion of threading considerations, including considerations for
+message handlers.</p>
+<p>Below is a short example (error handling and connection details are
+omitted for brevity):</p>
+<div class="code python highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">AMPS</span> <span class="kn">import</span> <span class="n">Client</span>
+<span class="kn">from</span> <span class="nn">AMPS</span> <span class="kn">import</span> <span class="n">Command</span>
+<span class="o">...</span>
+<span class="c1"># Here, we create a Client object and connect to an AMPS server.</span>
+<span class="n">client</span> <span class="o">=</span> <span class="n">Client</span><span class="p">(</span><span class="s2">&quot;exampleSubscriber&quot;</span><span class="p">)</span>
+<span class="n">client</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="s2">&quot;tcp://127.0.0.1:9007/amps/json&quot;</span><span class="p">)</span>
+<span class="n">client</span><span class="o">.</span><span class="n">logon</span><span class="p">()</span>
+<span class="k">def</span> <span class="nf">on_message_printer</span><span class="p">(</span><span class="n">message</span><span class="p">):</span>
+    <span class="nb">print</span><span class="p">(</span><span class="n">message</span><span class="o">.</span><span class="n">get_data</span><span class="p">())</span>
+<span class="c1"># Here, we create a subscription with the following parameters:</span>
+<span class="n">subscriptionid</span> <span class="o">=</span> <span class="n">client</span><span class="o">.</span><span class="n">execute_async</span><span class="p">(</span>
+    <span class="n">Command</span><span class="p">(</span><span class="s2">&quot;subscribe&quot;</span><span class="p">)</span><span class="o">.</span><span class="n">set_topic</span><span class="p">(</span><span class="s2">&quot;messages&quot;</span><span class="p">),</span>
+    <span class="n">on_message_printer</span>
+<span class="p">)</span>
+<span class="c1"># on_message_printer is a function that acts as our message handler. When a</span>
+<span class="c1"># message is received, this function is invoked, and in this case, the get_data()</span>
+<span class="c1"># method from message is printed to the screen. Message is of type AMPS.Message.</span>
+</pre></div>
+</div>
+<p><strong>Example 4.3:</strong> <em>Subscribing to a topic with asynchronous processing</em></p>
+</div>
+<div class="section" id="using-an-instance-method-as-a-message-handler">
+<h3>Using an Instance Method as a Message Handler<a class="headerlink" href="#using-an-instance-method-as-a-message-handler" title="Permalink to this headline">¶</a></h3>
+<p>One of the more common ways of providing a message handler is as an
+instance method on an object that maintains message state. It&#8217;s simple
+to provide a handler with this capability, as shown below:</p>
+<div class="code python highlight-default"><div class="highlight"><pre><span></span><span class="c1"># Define a class that saves state and</span>
+<span class="c1"># handles messages.</span>
+<span class="k">class</span> <span class="nc">StatefulHandler</span><span class="p">:</span>
+    <span class="c1"># Initialize self with state to save</span>
+    <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">name_</span> <span class="o">=</span> <span class="n">name</span>
+    <span class="c1"># Use state from this instance while handling</span>
+    <span class="c1"># the message.</span>
+    <span class="k">def</span> <span class="fm">__call__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">message</span><span class="p">):</span>
+        <span class="nb">print</span> <span class="p">(</span><span class="s2">&quot;</span><span class="si">%s</span><span class="s2"> got </span><span class="si">%s</span><span class="s2">&quot;</span> <span class="o">%</span> <span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">name_</span><span class="p">,</span> <span class="n">message</span><span class="o">.</span><span class="n">get_data</span><span class="p">()))</span>
+</pre></div>
+</div>
+<p><strong>Example 4.4:</strong> <em>Providing a message handler</em></p>
+<p>You can then provide an instance of the handler directly wherever a
+message handler is required, as shown below:</p>
+<div class="code python highlight-default"><div class="highlight"><pre><span></span><span class="n">client</span><span class="o">.</span><span class="n">subscribe</span><span class="p">(</span><span class="n">StatefulHandler</span><span class="p">(</span><span class="s2">&quot;An instance&quot;</span><span class="p">),</span> <span class="s2">&quot;topic&quot;</span><span class="p">)</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="understanding-threading-and-message-handlers">
+<span id="client-threading"></span><span id="understanding-threading-section"></span><h2>Understanding Threading and Message Handlers<a class="headerlink" href="#understanding-threading-and-message-handlers" title="Permalink to this headline">¶</a></h2>
+<p>The first time a command causes an instance of the <code class="docutils literal"><span class="pre">Client</span></code> or <code class="docutils literal"><span class="pre">HAClient</span></code> to
+connect to AMPS (typically, the <cite>logon()</cite> command), the client creates a thread
+that runs in the background. This background thread is responsible for
+processing incoming messages from AMPS, which includes both messages that
+contain data and acknowledgments from the server.</p>
+<p>When you call a command on the AMPS client, the command typically waits for
+an acknowledgment from the server and then returns. (The exception to this
+is <cite>publish</cite>. For performance, the <cite>publish</cite> command does not wait for
+an acknowledgment from the server before returning.)</p>
+<p>In the simple case, using synchronous message processing, the
+client provides an internal handler function that populates the
+<code class="docutils literal"><span class="pre">MessageStream</span></code>. The client receive thread calls the internal
+handler function, which makes a deep copy of the incoming message
+and adds it to the <code class="docutils literal"><span class="pre">MessageStream</span></code>. The <code class="docutils literal"><span class="pre">MessageStream</span></code> is used
+on the calling thread, so operations on the <code class="docutils literal"><span class="pre">MessageStream</span></code> do not
+block the client receive thread.</p>
+<p>When using asynchronous message processing, AMPS calls the handler
+function from the client receive thread. Message handlers provided for
+<em>asynchronous</em> message processing must be aware of the following
+considerations:</p>
+<ul class="simple">
+<li>The client creates one client receive thread at a time, and the lifetime
+of the thread lasts for the lifetime of the connection to the AMPS server.
+A message handler that is only provided to a single client will
+only be called from a single thread at a time. If your message handler will
+be used by multiple clients, then multiple threads will call your message
+handler. In this case, you should take care to protect any state that will
+be shared between threads. Notice that if the client connection fails (or
+is closed), and the client reconnects, the client will create a different
+thread for the new connection.</li>
+<li>For maximum performance, do as little work in the message handler as
+possible. For example, if you use the contents of the message to update
+an external database, a message handler that adds the relevant data to
+an update queue, that is processed by a different thread, will typically
+perform better than a message handler that does this update during the
+message handling.</li>
+<li>While your message handler is running, the thread that calls your
+message handler is no longer receiving messages. This makes it easier to
+write a message handler because you know that no other messages are
+arriving from the same subscription. However, this also means that you
+cannot use the same client that called the message handler to send
+commands to AMPS. Acknowledgments from AMPS cannot be processed and
+your application will deadlock waiting for the acknowledgment. Instead,
+enqueue the command in a work queue to be processed by a separate
+thread or use a different client object to submit the commands.</li>
+<li>The AMPS client resets and reuses the <code class="docutils literal"><span class="pre">Message</span></code> provided to this
+function between calls. This improves performance in the client, but
+means that if your handler function needs to preserve information
+contained within the message, you must copy the information (either
+by making a copy of the entire message or copying the required
+fields) rather than just saving the message object. Otherwise, the
+AMPS client cannot guarantee the state of the object or the contents
+of the object when your program goes to use it. Likewise, a
+message handler should not modify the <code class="docutils literal"><span class="pre">Message</span></code> &#8211; this will
+result in modifying the message provided to other handlers (including
+handlers internal to the AMPS client).</li>
+</ul>
+</div>
+<div class="section" id="understanding-messages">
+<h2>Understanding Messages<a class="headerlink" href="#understanding-messages" title="Permalink to this headline">¶</a></h2>
+<p>So far, we have seen that subscribing to a topic involves working with
+objects of <code class="docutils literal"><span class="pre">AMPS.Message</span></code> type. A <code class="docutils literal"><span class="pre">Message</span></code> represents a single
+message to or from an AMPS server. Messages are received or sent for
+every client/server operation in AMPS.</p>
+<div class="section" id="header-properties">
+<h3>Header Properties<a class="headerlink" href="#header-properties" title="Permalink to this headline">¶</a></h3>
+<p>There are two parts of each message in AMPS: a set of headers that
+provide metadata for the message, and the data that the message
+contains. Every AMPS message has one or more header fields defined. The
+precise headers present depend on the type and context of the message.
+There are many possible fields in any given message, but only a few are
+used for any given message. For each header field, the <code class="docutils literal"><span class="pre">Message</span></code> class
+contains a distinct property that allows for retrieval and setting of
+that field. For example, the <code class="docutils literal"><span class="pre">Message.get_command_id()</span></code> function
+corresponds to the <code class="docutils literal"><span class="pre">commandId</span></code> header field, the
+<code class="docutils literal"><span class="pre">Message.get_batch_size()</span></code> function corresponds to the <code class="docutils literal"><span class="pre">BatchSize</span></code>
+header field, and so on. For more information on these header fields,
+consult the <em>AMPS User Guide</em> and <em>AMPS Command Reference</em>.</p>
+<p>To work with header fields, a <code class="docutils literal"><span class="pre">Message</span></code> contains
+<code class="docutils literal"><span class="pre">get_xxx()</span></code>/<code class="docutils literal"><span class="pre">set_xxx()</span></code> methods corresponding to the header fields,
+as well as a number of <code class="docutils literal"><span class="pre">getXXX()</span></code>/<code class="docutils literal"><span class="pre">setXXX()</span></code> methods for
+compatibility with previous implementations of the AMPS Python client.
+60East does not recommend attempting to parse header fields from the raw
+data of the message.</p>
+</div>
+<div class="section" id="get-data-method">
+<h3>get_data() Method<a class="headerlink" href="#get-data-method" title="Permalink to this headline">¶</a></h3>
+<p>Access to the data section of a message is provided via the
+<code class="docutils literal"><span class="pre">get_data()</span></code> method. The <code class="docutils literal"><span class="pre">data</span></code> property will contain the unparsed
+data of the message. Your application code parses and works with the
+data.</p>
+<p>The AMPS Python client contains a collection of helper classes for
+working with message types that are specific to AMPS (for example, FIX,
+NVFIX, and AMPS composite message types). For message types that are
+widely used, such as JSON or XML, you can use the standard Python
+facilities or the library you typically use in your environment.</p>
+</div>
+</div>
+<div class="section" id="unsubscribing">
+<h2>Unsubscribing<a class="headerlink" href="#unsubscribing" title="Permalink to this headline">¶</a></h2>
+<p>The AMPS server continues a subscription until the client explicitly
+ends the subscription (that is, <em>unsubscribes</em>) or until the connection
+to the client is closed.</p>
+<p>With a <code class="docutils literal"><span class="pre">MessageStream</span></code>, AMPS automatically unsubscribes to the topic
+when there are no more references to the <code class="docutils literal"><span class="pre">MessageStream</span></code>. You can also
+call the <code class="docutils literal"><span class="pre">close()</span></code> method on the <code class="docutils literal"><span class="pre">MessageStream</span></code> object to remove
+the subscription.</p>
+<p>With asynchronous message processing, when a subscription is
+successfully made, messages will begin flowing to the message handler
+function and the <code class="docutils literal"><span class="pre">subscribe()</span></code> or <code class="docutils literal"><span class="pre">execute_async()</span></code> call returns a
+string that serves as the identifier for this subscription. A <code class="docutils literal"><span class="pre">Client</span></code> can
+have any number of active subscriptions, and this subscription ID is how
+AMPS designates messages intended for this subscription. To unsubscribe,
+we simply call <code class="docutils literal"><span class="pre">unsubscribe</span></code> with the subscription identifier, as shown
+below:</p>
+<div class="code python highlight-default"><div class="highlight"><pre><span></span><span class="n">client</span> <span class="o">=</span> <span class="n">Client</span><span class="p">(</span><span class="s2">&quot;exampleClient&quot;</span><span class="p">)</span>
+<span class="c1"># Register an asynchronous subscription</span>
+<span class="n">subId</span> <span class="o">=</span> <span class="n">client</span><span class="o">.</span><span class="n">execute_async</span><span class="p">(</span>
+    <span class="n">Command</span><span class="p">(</span><span class="s2">&quot;subscribe&quot;</span><span class="p">)</span><span class="o">.</span><span class="n">set_topic</span><span class="p">(</span><span class="s2">&quot;messages&quot;</span><span class="p">),</span>
+    <span class="n">on_message_printer</span>
+<span class="p">)</span>
+<span class="o">...</span>
+<span class="c1"># when the program is done with the subscription, unsubscribe</span>
+<span class="n">client</span><span class="o">.</span><span class="n">unsubscribe</span><span class="p">(</span><span class="n">subId</span><span class="p">)</span>
+</pre></div>
+</div>
+<p><strong>Example 4.5:</strong> <em>Unsubscribing from a topic</em></p>
+<p>In this example, we use the <code class="docutils literal"><span class="pre">execute_async()</span></code> method to create a subscription
+to the <code class="docutils literal"><span class="pre">messages</span></code> topic. When our application is done listening to this
+topic, it unsubscribes (on the last line) by passing in the subscription
+identifier returned by the <code class="docutils literal"><span class="pre">subscribe</span></code> command. After the subscription
+is removed, no more messages will flow into our <code class="docutils literal"><span class="pre">on_message_printer</span></code>
+function.</p>
+<p>When an application calls <code class="docutils literal"><span class="pre">unsubscribe()</span></code>, the client sends an
+explicit <code class="docutils literal"><span class="pre">unsubscribe</span></code> command to AMPS. The AMPS server removes that
+subscription from the set of subscriptions for the client, and stops
+sending messages for that subscription. On the client side, the client
+unregisters the subscription so that the <code class="docutils literal"><span class="pre">MessageStream</span></code> or
+message handler for that subscription will no longer receive
+messages for that subscription.</p>
+<p>Notice that calling <code class="docutils literal"><span class="pre">unsubscribe</span></code> does not destroy messages that
+the server has already sent to the client. If there are messages on
+the way to the client for this subscription, the AMPS client must
+consume those messages. If a <code class="docutils literal"><span class="pre">last_chance_message_handler</span></code> is registered,
+the handler will receive the messages. Otherwise, they will be
+discarded since no message handler matches the subscription ID on
+the message.</p>
+</div>
+<div class="section" id="advanced-messaging-support">
+<h2>Advanced Messaging Support<a class="headerlink" href="#advanced-messaging-support" title="Permalink to this headline">¶</a></h2>
+<p>AMPS has two powerful features: it allows selective subscription to
+topics using pattern matching, and message content using content filtering.
+Pattern matching provides the ability to receive messages from multiple
+topics using a single pattern, while using a filter ensures that you only
+receive messages where the content of the message matches your filter,
+reducing traffic on the network.</p>
+<div class="section" id="regex-subscriptions">
+<h3>Regex Subscriptions<a class="headerlink" href="#regex-subscriptions" title="Permalink to this headline">¶</a></h3>
+<p>Regular Expression (Regex) subscriptions allow a regular expression to
+be supplied in the place of a topic name. When you supply a regular
+expression, it is as if a subscription is made to every topic that
+matches your expression, including topics that do not yet exist at the
+time of creating the subscription.</p>
+<p>To use a regular expression, simply supply the regular expression in
+place of the topic name in the <code class="docutils literal"><span class="pre">subscribe()</span></code> call. For example:</p>
+<div class="code python highlight-default"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">message_handler</span><span class="p">(</span><span class="n">msg</span><span class="p">):</span>
+    <span class="n">topic</span> <span class="o">=</span> <span class="n">msg</span><span class="o">.</span><span class="n">get_topic</span><span class="p">()</span>
+<span class="n">subscription_id</span> <span class="o">=</span> <span class="n">client</span><span class="o">.</span><span class="n">subscribe</span><span class="p">(</span>
+    <span class="n">message_handler</span><span class="p">,</span>
+    <span class="s2">&quot;orders.*&quot;</span>
+<span class="p">)</span>
+</pre></div>
+</div>
+<p><strong>Example 4.6:</strong> <em>Regex topic subscription</em></p>
+<p>In this example, messages on topics <code class="docutils literal"><span class="pre">orders-north-america</span></code> and
+<code class="docutils literal"><span class="pre">orders-europe</span></code> would match the regular expression, and those messages
+would all be sent to our <code class="docutils literal"><span class="pre">message_handler</span></code> function. As in the
+example, you can use the <code class="docutils literal"><span class="pre">get_topic()</span></code> method to determine the actual
+topic of the message sent to the function.</p>
+</div>
+<div class="section" id="content-filtering">
+<h3>Content Filtering<a class="headerlink" href="#content-filtering" title="Permalink to this headline">¶</a></h3>
+<p>One of the most powerful features of AMPS is content filtering. With
+content filtering, filters based on message content are applied at the
+server so that your application and the network are not utilized by
+messages that are not relevent to your application. For example, if
+your application is only displaying messages from a particular user, you
+can send a content filter to the server so that only messages from that
+particular user are sent to the client.</p>
+<p>To apply a content filter to a subscription, simply pass it into the
+<code class="docutils literal"><span class="pre">client.subscribe()</span></code> call or use the <code class="docutils literal"><span class="pre">set_filter</span></code> method to add a
+filter to the <code class="docutils literal"><span class="pre">Command</span></code>:</p>
+<div class="code python highlight-default"><div class="highlight"><pre><span></span><span class="k">for</span> <span class="n">message</span> <span class="ow">in</span> <span class="n">client</span><span class="o">.</span><span class="n">subscribe</span><span class="p">(</span>
+    <span class="s2">&quot;letters&quot;</span><span class="p">,</span>
+    <span class="s2">&quot;/sender=&#39;mom&#39;&quot;</span><span class="p">,</span>
+    <span class="n">timeout</span><span class="o">=</span><span class="mi">5000</span>
+<span class="p">):</span>
+  <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Mom says: </span><span class="si">%s</span><span class="s2">&quot;</span> <span class="o">%</span> <span class="n">message</span><span class="o">.</span><span class="n">get_data</span><span class="p">())</span>
+</pre></div>
+</div>
+<p><strong>Example 4.7:</strong> <em>Using content filtering</em></p>
+<p>In this example, we have passed in a content filter <code class="docutils literal"><span class="pre">/sender</span> <span class="pre">=</span> <span class="pre">'mom'</span></code>. This will
+result in the server only sending us messages, from the <code class="docutils literal"><span class="pre">messages</span></code> topic, that have
+the sender field equal to <code class="docutils literal"><span class="pre">mom</span></code> in the message.</p>
+<p>For example, the AMPS server will send the following message, where <code class="docutils literal"><span class="pre">/sender</span></code>
+is <code class="docutils literal"><span class="pre">mom</span></code>:</p>
+<div class="highlight-javascript"><div class="highlight"><pre><span></span><span class="p">{</span>
+    <span class="s2">&quot;sender&quot;</span> <span class="o">:</span> <span class="s2">&quot;mom&quot;</span><span class="p">,</span>
+    <span class="s2">&quot;text&quot;</span> <span class="o">:</span> <span class="s2">&quot;Happy Birthday!&quot;</span><span class="p">,</span>
+    <span class="s2">&quot;reminder&quot;</span> <span class="o">:</span> <span class="s2">&quot;Call me Thursday!&quot;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The AMPS server will not send a message with a different <code class="docutils literal"><span class="pre">/sender</span></code> value:</p>
+<div class="highlight-javascript"><div class="highlight"><pre><span></span><span class="p">{</span>
+    <span class="s2">&quot;sender&quot;</span> <span class="o">:</span> <span class="s2">&quot;henry dave&quot;</span><span class="p">,</span>
+    <span class="s2">&quot;text&quot;</span> <span class="o">:</span> <span class="s2">&quot;Things do not change; we change.&quot;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="updating-the-filter-on-a-subscribe">
+<h3>Updating the Filter on a Subscribe<a class="headerlink" href="#updating-the-filter-on-a-subscribe" title="Permalink to this headline">¶</a></h3>
+<p>AMPS allows you to update the filter on a subscription. When you replace
+a filter on the subscription, AMPS immediately begins sending only
+messages that match the updated filter. Notice that if the subscription
+was entered with a command that includes a SOW query, using the
+<code class="docutils literal"><span class="pre">replace</span></code> option can re-issue the SOW query (as described in the <em>AMPS
+User Guide</em>).</p>
+<p>To update the filter on a subscription, you create a <code class="docutils literal"><span class="pre">subscribe</span></code>
+command. You set the <code class="docutils literal"><span class="pre">SubscriptionId</span></code> provided on the <code class="docutils literal"><span class="pre">Command</span></code> to
+the identifier of the existing subscription and include the <code class="docutils literal"><span class="pre">replace</span></code>
+option on the <code class="docutils literal"><span class="pre">Command</span></code>. When you send the <code class="docutils literal"><span class="pre">Command</span></code>, AMPS
+atomically replaces the filter and sends messages that match the updated
+filter from that point forward.</p>
+<div class="highlight-python"><div class="highlight"><pre><span></span><span class="n">sub_cmd</span> <span class="o">=</span> <span class="n">AMPS</span><span class="o">.</span><span class="n">Command</span><span class="p">(</span><span class="s2">&quot;sow_and_subscribe&quot;</span><span class="p">)</span> \
+           <span class="o">.</span><span class="n">set_topic</span><span class="p">(</span><span class="s2">&quot;orders-sow&quot;</span><span class="p">)</span>      \
+           <span class="o">.</span><span class="n">set_sub_id</span><span class="p">(</span><span class="s2">&quot;A42&quot;</span><span class="p">)</span>            \
+           <span class="o">.</span><span class="n">set_filter</span><span class="p">(</span><span class="s2">&quot;/details/items/description LIKE &#39;puppy&#39;&quot;</span><span class="p">)</span>
+<span class="n">client</span><span class="o">.</span><span class="n">execute_async</span><span class="p">(</span><span class="n">sub_cmd</span><span class="p">,</span> <span class="n">MyHandler</span><span class="p">)</span>
+<span class="c1"># Elsewhere in the program...</span>
+<span class="n">replace_cmd</span> <span class="o">=</span> <span class="n">AMPS</span><span class="o">.</span><span class="n">Command</span><span class="p">(</span><span class="s2">&quot;sow_and_subscribe&quot;</span><span class="p">)</span> \
+               <span class="o">.</span><span class="n">set_topic</span><span class="p">(</span><span class="s2">&quot;orders-sow&quot;</span><span class="p">)</span>      \
+               <span class="o">.</span><span class="n">set_sub_id</span><span class="p">(</span><span class="s2">&quot;A42&quot;</span><span class="p">)</span>            \
+               <span class="o">.</span><span class="n">set_filter</span><span class="p">(</span><span class="s2">&quot;/details/items/description LIKE &#39;kitten&#39;&quot;</span><span class="p">)</span> \
+               <span class="o">.</span><span class="n">set_options</span><span class="p">(</span><span class="s2">&quot;replace&quot;</span><span class="p">)</span>
+<span class="n">client</span><span class="o">.</span><span class="n">execute_async</span><span class="p">(</span><span class="n">replace_cmd</span><span class="p">,</span> <span class="n">MyHandler</span><span class="p">)</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="next-steps">
+<h2>Next Steps<a class="headerlink" href="#next-steps" title="Permalink to this headline">¶</a></h2>
+<p>At this point, you are able to build AMPS programs in Python that
+publish and subscribe to AMPS topics. For an AMPS application to be
+truly robust, it needs to be able to handle the errors and
+disconnections that occur in any distributed system. In the next
+chapter, we will take a closer look at error handling and recovery and
+how you can use it to make your application ready for the real world.</p>
+</div>
+</div>
+          </div>
+        </div>
+      </div>
+    <div class="clearer"></div>
+  </div>
+    <div class="footer">
+      &copy;2022, 60East Technologies, Inc..
+      |
+      Powered by <a href="http://sphinx-doc.org/">Sphinx 1.5.3</a>
+      &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.10</a>
+    </div>
+  </body>
+</html>

amps-python-client 5.3.4.1__zip → 5.3.4.3__zip

amps-python-client 5.3.4.1zip → 5.3.4.3zip