amps-python-client 5.3.4.1__zip → 5.3.4.2__zip

amps-python-client-5.3.4.2/docs/python/html/_sources/chapters/subscriptions.rst.txt

@@ -0,0 +1,374 @@
+
+4. Subscriptions
+================
+
+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.
+
+Subscribing to a Topic
+----------------------
+
+The AMPS client makes it simple to subscribe to a topic. You call
+``client.subscribe()`` with the topic to subscribe to and the parameters
+for the subscription. The client submits the subscription to AMPS and
+returns a ``MessageStream`` that you can iterate over to receive the
+messages from the subscription. Below is a short example:
+
+.. code:: python
+
+    from AMPS import Client
+
+    # Here, we create a Client object and connect to an AMPS server.
+    client = Client("test")
+    client.connect("tcp://127.0.0.1:9007/amps/json")
+    client.logon()
+
+    # Here we subscribe to the topic messages. We do not provide a filter, so AMPS
+    # does not content-filter the topic. Although we don't use the object explicitly
+    # here, the subscribe method returns a MessageStream object that we iterate over.
+    # If, at any time, we no longer need to subscribe, we can break out of the loop.
+    # When there are no more active references to the MessageStream, the client sends
+    # an unsubscribe command to AMPS and stops receiving messages.
+    for message in client.subscribe("messages"):
+
+        # Within the loop, we process the message. In this case, we simply print the
+        # contents of the message.
+        print(message.get_data())
+
+**Example 4.1:** *Basic AMPS subscription*
+
+AMPS creates a background thread that receives messages and copies them
+into the ``MessageStream`` that you iterate over. This means that the
+client application as a whole can continue to receive messages while you
+are doing processing work.
+
+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:
+
+.. code:: python
+
+    from AMPS import Client
+    from AMPS import Command
+
+    # Here, we create a Client object and connect to an AMPS server.
+    client = Client("test")
+    client.connect("tcp://127.0.0.1:9007/amps/json")
+    client.logon()
+
+    # Here, we create a Command object for the subscribe command, specifying the topic
+    # messages. We do not provide a filter, so AMPS does not content-filter the
+    # subscription. Although we don't use the object explicitly here, the execute
+    # method returns a MessageStream object that we iterate over. If, at any time, we
+    # no longer need to subscribe, we can break out of the loop. When we break out of
+    # the loop, there are no more references to the MessageStream and the AMPS client
+    # sends an unsubscribe message to AMPS.
+    for message in client.execute(Command("subscribe").set_topic("messages")):
+        # Within the body of the loop, we can process the message as we need to. In this
+        # case, we simply print the contents of the message.
+        print(message.get_data())
+
+**Example 4.2:** *Subscribing to a topic using a command*
+
+The ``Command`` interface allows you to precisely customize the commands
+you send to AMPS. For flexibility and ease of maintenance, 60East
+recommends using the ``Command`` 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.
+
+Asynchronous Message Processing Interface
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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 
+:ref:`Understanding Threading and Message Handlers <#understanding-threading-section>` 
+for a discussion of threading considerations, including considerations for
+message handlers.
+
+Below is a short example (error handling and connection details are
+omitted for brevity):
+
+.. code:: python
+
+    from AMPS import Client
+    from AMPS import Command
+
+    ...
+
+    # Here, we create a Client object and connect to an AMPS server.
+    client = Client("exampleSubscriber")
+    client.connect("tcp://127.0.0.1:9007/amps/json")
+    client.logon()
+
+    def on_message_printer(message):
+        print(message.get_data())
+
+    # Here, we create a subscription with the following parameters:
+    subscriptionid = client.execute_async( 
+        Command("subscribe").set_topic("messages"),
+        on_message_printer
+    ) 
+    # on_message_printer is a function that acts as our message handler. When a
+    # message is received, this function is invoked, and in this case, the get_data()
+    # method from message is printed to the screen. Message is of type AMPS.Message.
+
+**Example 4.3:** *Subscribing to a topic with asynchronous processing*
+
+Using an Instance Method as a Message Handler
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+One of the more common ways of providing a message handler is as an
+instance method on an object that maintains message state. It's simple
+to provide a handler with this capability, as shown below:
+
+.. code:: python
+
+    # Define a class that saves state and
+    # handles messages.
+    class StatefulHandler:
+        # Initialize self with state to save
+        def __init__(self, name):
+            self.name_ = name
+
+        # Use state from this instance while handling
+        # the message.
+        def __call__(self, message):
+            print ("%s got %s" % (self.name_, message.get_data()))
+
+**Example 4.4:** *Providing a message handler*
+
+You can then provide an instance of the handler directly wherever a
+message handler is required, as shown below:
+
+.. code:: python
+
+    client.subscribe(StatefulHandler("An instance"), "topic")
+
+.. _#understanding-threading-section:
+
+.. include:: ./understanding-threading-section.inc
+Understanding Messages
+----------------------
+
+So far, we have seen that subscribing to a topic involves working with
+objects of ``AMPS.Message`` type. A ``Message`` represents a single
+message to or from an AMPS server. Messages are received or sent for
+every client/server operation in AMPS.
+
+Header Properties
+^^^^^^^^^^^^^^^^^^
+
+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 ``Message`` class
+contains a distinct property that allows for retrieval and setting of
+that field. For example, the ``Message.get_command_id()`` function
+corresponds to the ``commandId`` header field, the
+``Message.get_batch_size()`` function corresponds to the ``BatchSize``
+header field, and so on. For more information on these header fields,
+consult the *AMPS User Guide* and *AMPS Command Reference*.
+
+To work with header fields, a ``Message`` contains
+``get_xxx()``/``set_xxx()`` methods corresponding to the header fields,
+as well as a number of ``getXXX()``/``setXXX()`` 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.
+
+get_data() Method
+^^^^^^^^^^^^^^^^^
+
+Access to the data section of a message is provided via the
+``get_data()`` method. The ``data`` property will contain the unparsed
+data of the message. Your application code parses and works with the
+data.
+
+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.
+
+Unsubscribing
+-------------
+
+The AMPS server continues a subscription until the client explicitly
+ends the subscription (that is, *unsubscribes*) or until the connection
+to the client is closed.
+
+With a ``MessageStream``, AMPS automatically unsubscribes to the topic
+when there are no more references to the ``MessageStream``. You can also
+call the ``close()`` method on the ``MessageStream`` object to remove
+the subscription.
+
+With asynchronous message processing, when a subscription is
+successfully made, messages will begin flowing to the message handler
+function and the ``subscribe()`` or ``execute_async()`` call returns a
+string that serves as the identifier for this subscription. A ``Client`` 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 ``unsubscribe`` with the subscription identifier, as shown
+below:
+
+.. code:: python
+
+    client = Client("exampleClient") 
+
+    # Register an asynchronous subscription
+    subId = client.execute_async(
+        Command("subscribe").set_topic("messages"), 
+        on_message_printer
+    )
+        
+    ...
+
+    # when the program is done with the subscription, unsubscribe
+    client.unsubscribe(subId)
+
+**Example 4.5:** *Unsubscribing from a topic*
+
+In this example, we use the ``execute_async()`` method to create a subscription
+to the ``messages`` 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 ``subscribe`` command. After the subscription
+is removed, no more messages will flow into our ``on_message_printer``
+function.
+
+When an application calls ``unsubscribe()``, the client sends an
+explicit ``unsubscribe`` 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 ``MessageStream`` or
+message handler for that subscription will no longer receive
+messages for that subscription.
+
+Notice that calling ``unsubscribe`` 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 ``last_chance_message_handler`` is registered,
+the handler will receive the messages. Otherwise, they will be
+discarded since no message handler matches the subscription ID on
+the message.
+
+Advanced Messaging Support
+----------------------------
+
+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.
+
+Regex Subscriptions
+^^^^^^^^^^^^^^^^^^^
+
+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.
+
+To use a regular expression, simply supply the regular expression in
+place of the topic name in the ``subscribe()`` call. For example:
+
+.. code:: python
+
+    def message_handler(msg):
+        topic = msg.get_topic()
+
+    subscription_id = client.subscribe(
+        message_handler,
+        "orders.*"
+    )
+
+**Example 4.6:** *Regex topic subscription*
+
+In this example, messages on topics ``orders-north-america`` and
+``orders-europe`` would match the regular expression, and those messages
+would all be sent to our ``message_handler`` function. As in the
+example, you can use the ``get_topic()`` method to determine the actual
+topic of the message sent to the function.
+
+Content Filtering
+^^^^^^^^^^^^^^^^^
+
+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.
+
+To apply a content filter to a subscription, simply pass it into the
+``client.subscribe()`` call or use the ``set_filter`` method to add a
+filter to the ``Command``:
+
+.. code:: python
+
+    for message in client.subscribe( 
+        "letters", 
+        "/sender='mom'",
+        timeout=5000
+    ):
+      print("Mom says: %s" % message.get_data())
+
+**Example 4.7:** *Using content filtering*
+
+.. include:: ./content-filtering-info.inc
+.. include:: ./filter-replace.inc
+.. code-block:: python
+
+  sub_cmd = AMPS.Command("sow_and_subscribe") \
+             .set_topic("orders-sow")      \
+             .set_sub_id("A42")            \
+             .set_filter("/details/items/description LIKE 'puppy'")
+
+
+  client.execute_async(sub_cmd, MyHandler)
+
+
+  # Elsewhere in the program...
+
+  replace_cmd = AMPS.Command("sow_and_subscribe") \
+                 .set_topic("orders-sow")      \
+                 .set_sub_id("A42")            \
+                 .set_filter("/details/items/description LIKE 'kitten'") \
+                 .set_options("replace")
+
+  client.execute_async(replace_cmd, MyHandler)
+
+
+
+Next Steps
+----------
+
+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.

amps-python-client-5.3.4.2/docs/python/html/_sources/chapters/utilities.rst.txt

@@ -0,0 +1,214 @@
+
+11. Utilities
+=============
+
+The AMPS Python client includes a set of utilities and helper classes to
+make working with AMPS easier.
+
+Composite Message Types
+------------------------
+
+The client provides a pair of classes for creating and parsing composite
+message types:
+
+-  ``CompositeMessageBuilder`` allows you to assemble the parts of a
+   composite message and then serialize them in a format suitable for
+   AMPS.
+
+-  ``CompositeMessageParser`` extracts the individual parts of a
+   composite message type.
+
+For more information regarding composite message types, refer to the 
+*Message Types* chapter in the *AMPS User Guide*.
+
+Building Composite Messages
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To build a composite message, create an instance of
+``CompositeMessageBuilder``, and populate the parts. The
+``CompositeMessageBuilder`` copies the parts provided, in order, to the
+underlying message. The builder simply writes to an internal buffer with
+the appropriate formatting, and does not allow you to update or change
+the individual parts of a message once they've been added to the
+builder.
+
+The snippet below shows how to build a composite message that includes a
+JSON part, constructed as a string, and a binary part consisting of the
+bytes from an ``array.array`` that contains doubles.
+
+.. code:: python
+
+    json = '{"data":"sample"}'
+
+
+    data = array.array('d')
+    # populate data
+    ...
+
+
+    # Create the payload for the composite message
+    builder = AMPS.CompositeMessageBuilder()
+
+    # Construct the composite
+    builder.append(json)
+    builder.append(data.tostring())
+
+    # Send the message
+    client.publish("messages", builder.get_data())
+
+Parsing Composite Messages
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To parse a composite message, create an instance of
+``CompositeMessageParser``, then use the ``parse()`` method to parse the
+message provided by the AMPS client. The ``CompositeMessageParser``
+gives you access to each part of the message as a sequence of bytes.
+
+For example, the following snippet parses and prints messages that
+contain a JSON part and a binary part that contains an array of doubles.
+
+.. code:: python
+
+    parts = parser.parse(message)  
+
+    json = parser.get_part(0)
+    data = array.array('d')
+    data.fromstring(parser.get_part(1))
+
+    print("Received message with %d parts." % parts)
+    print(json)
+    datastring = ""
+    for d in data:
+        datastring += "%f " % d
+    print(datastring)
+
+Notice that the receiving application is written with explicit knowledge
+of the structure and content of the composite message type.
+
+NVFIX Messages
+--------------
+
+The client provides a pair of classes for creating and parsing NVFIX
+messages:
+
+-  ``NVFIXBuilder`` allows you to assemble an NVFIX message and then
+   serialize it in a format suitable for AMPS.
+
+-  ``NVFIXShredder`` extracts the individual fields of an NVFIX message
+   type.
+
+Building NVFIX Messages
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+To build an NVFIX message, create an instance of ``NVFIXBuilder``, then
+add the fields of the message using ``append()``. ``NVFIXBuilder``
+copies the fields provided, in order, to the underlying message. The
+builder simply writes to an internal buffer with the appropriate
+formatting, and does not allow you to update or change the individual
+fields of a message once they've been added to the builder.
+
+The snippet below shows how to build an NVFIX message and publish it to the
+AMPS client.
+
+.. code:: python
+
+    # create the payload for the NVFIX Message
+    builder = AMPS.NVFIXBuilder()
+        
+    # construct the NVFIX message
+    builder.append("sample","data")
+    builder.append("even", "more data")
+    ...
+
+    # display the data
+    print(builder.get_string())
+
+    # publish the message
+    client.publish("messages-sow", builder.get_string())
+
+Parsing NVFIX Messages
+^^^^^^^^^^^^^^^^^^^^^^
+
+To parse an NVFIX message, create an instance of ``NVFIXShredder``, then
+use the ``to_map()`` method to parse the message provided by the AMPS
+client. The ``NVFIXShredder`` gives you access to each field of the
+message in a map.
+
+The snippet below shows how to parse and print an NVFIX message.
+
+.. code:: python
+
+    # create the shredder for the message and subscribe to the topic
+    shredder = AMPS.NVFIXShredder()
+    message = client.subscribe(topic="messages-sow", timeout=5000)
+
+    # shred the message to a map
+    message_map = shredder.to_map(message.next().get_data())
+
+    # display the values of the message
+    for key in message_map: 
+        print(key + " " + message_map[key])
+
+FIX Messages
+------------
+
+The client provides a pair of classes for creating and parsing FIX
+messages:
+
+-  ``FIXBuilder`` allows you to assemble a FIX message and then
+   serialize it in a format suitable for AMPS.
+
+-  ``FIXShredder`` extracts the individual fields of a FIX message.
+
+Building FIX Messages
+^^^^^^^^^^^^^^^^^^^^^^
+
+To build a FIX message, create an instance of ``FIXBuilder``, then add
+the fields of the message using ``append()``. ``FIXBuilder`` copies the
+fields provided, in order, to the underlying message. The builder simply
+writes to an internal buffer with the appropriate formatting, and does
+not allow you to update or change the individual fields of a message
+once they've been added to the builder.
+
+The snippet below shows how to build a FIX message and publish it to the
+AMPS client.
+
+.. code:: python
+
+    # create the payload for the FIX Message
+    builder = AMPS.FIXBuilder()
+        
+    # construct the FIX message
+    builder.append(0,"data")
+    builder.append(1, "more data")
+    ...
+
+    # display the data
+    print(builder.get_string())
+
+    # publish the message
+    client.publish("messages-sow", builder.get_string())
+
+Parsing FIX Messages
+^^^^^^^^^^^^^^^^^^^^^
+
+To parse a FIX message, create an instance of ``FIXShredder``, then use
+the ``to_map()`` method to parse the message provided by the AMPS
+client. The ``FIXShredder`` gives you access to each field of the
+message in a map.
+
+The snippet below shows how to parse and print a FIX message.
+
+.. code:: python
+
+    # create the shredder for the message and subscribe to the topic
+    shredder = AMPS.FIXShredder()
+    message = client.subscribe(topic="messages-sow", timeout=5000)
+
+    # shred the message to a map
+    message_map = shredder.to_map(message.next().get_data())
+
+    # display the values of the message
+    for key in message_map: 
+        print(str(key) + " " + message_map[key])
+