AMPS Module Reference¶

The BadRegexTopicException is raised when a topic query containing a regular expression is unable to be compiled by the AMPS regular expression compiler.

exception AMPS.BadSowKeyException¶

Bases: AMPS.CommandException

The BadSowKeyException is raised when command uses an invalid sow key

class AMPS.CMessageHandler¶

Bases: object

Wraps a C/C++ message handler function for use as a higher-performance AMPS message handler. To use, create a shared library or DLL with an exported function of type AMPS::MessageHandlerFunc.

For example:

extern "C" void my_message_handler(const AMPS::Message& message, void* userdata) { ... }

and then use the python ctypes module to load and supply it:

import ctypes
client = AMPS.Client(...)

my_dll = ctypes.CDLL("./mymessagehandler.so") # load my DLL
client.subscribe( AMPS.CMessageHandler( my_dll.my_message_handler, "user data"), "my_amps_topic" )

As messages arrive they are sent directly to my_message_handler, without passing through the python interpreter or taking the python global interpreter lock, resulting in potentially higher performance.

Note

No checking is performed to make sure your C/C++ function is of the appropriate signature. Supplying a function of a different signature than that shown, results in undefined behavior.

class AMPS.Client(name)¶

Bases: object

The base AMPS Client object used in AMPS applications. Each Client object manages a single connection to AMPS. Each AMPS connection has a name, a specific transport (such as tcp), a protocol (used for framing messages to AMPS), and a message type (such as FIX or JSON).

The Client object creates and manages a background thread, and sends and receives messages on that thread. The object provides both a synchronous interface for processing messages on the calling thread, and an asynchronous interface suitable for populating a queue to be processed by worker threads.

Each Client has a name. The AMPS server uses this name for duplicate message detection, so the name of each instance of the client application should be unique.

An example of a Python client publishing a JSON message is listed below:

client = AMPS.Client("test_client")

try:
  client.connect("tcp://127.0.0.1:9004/amps/json")
  client.logon()
  client.publish("topic_name",'{"a":1,"b":"2"}')
finally:
  client.close()

Constructor Arguments:

Parameters:	name – The unique name for this client. AMPS does not enforce specific restrictions on the character set used, however some protocols (for example, XML) may not allow specific characters. 60East recommends that the client name be meaningful, short, human readable, and avoid using control characters, newline characters, or square brackets.

class Bookmarks¶

Bases: object

This class provides special values for bookmark subscriptions:

EPOCH - Begin the subscription at the beginning of the journal.

MOST_RECENT - Begin the subscription at the first undiscarded message in the bookmark store, or at the end of the bookmark store if all messages have been discarded.

NOW - Begin the subscription at the time that AMPS processes the subscription.

For example, to begin a bookmark subscription at the beginning of the journal, provide AMPS.Client.Bookmarks.EPOCH as the bookmark in the call to AMPS.Client.bookmark_subscribe().

class Client.ConnectionStateListener¶

Bases: object

AMPS ConnectionStateListener type used to determine the new connection state.

Client.ack(message, options=None) OR ack(topic, bookmark, options=None)¶

Acknowledges a message queue message.

Parameters:	message – An `AMPS.Message` object to ack, OR topic – The topic of the message to ack. bookmark – The bookmark of the message to ack. options – An optional string to include in the ack such as ‘cancel’.

Client.add_connection_state_listener(listener_callable)¶

Sets a function to be called when this client connects or disconnects from AMPS.

Parameters: listener_callable (A python function or other callable that takes a single value.) – The function or callable to be called. This function will be passed True if a connection is established, False if a disconnect occurs. Notice that when a connection is established, the client has not yet logged in or completed any recovery steps. The application should not issue commands on the client until recovery is completed.

Client.add_message_handler(command_id, message_handler, acks, is_subscribe)¶

Add a message handler to the Client to handle messages and the requested acknowledgments sent in response to the given command_id.

Parameters:	command_id (str) – The command, query, or sub ID for messages and acks. message_handler (`MessageHandler`) – The message handler that will receive messages for the `command_id`. acks (str) – The acknowledgments requested to go to the `message_handler`. is_subscribe (int) – If the `message_handler` is for a subscribe command.

Client.allocateMessage()¶: A legacy method name for allocate_message().

Client.allocate_message()¶

Creates a new Message appropriate for this client.

This function should be called rarely, since it does allocate a handful of small objects.

Returns:	A new Message instance.

Client.bookmark_subscribe()¶

Signatures:

Client.bookmark_subscribe(on_message, topic, bookmark, filter=None, sub_id=None, options=None, timeout=0)
Client.bookmark_subscribe(topic, bookmark, filter=None, sub_id=None, options=None, timeout=0)

Places a bookmark subscription with AMPS. Starts replay at the most recent message reported by the bookmark parameter.

There are two ways to use this method:
1. When a message handler is provided, this method submits the bookmark_subscribe command on a background thread and calls the message handler with individual messages from the transaction log replay (if any) and then cuts over to live messages that match the subscription.
2. When no message handler is provided, this method returns a message stream that can be iterated on to process messages received from the transaction log replay (if any) and then cuts over to live messages that match the subscription.

Parameters:	on_message (`MessageHandler`) – The message handler to invoke with matching messages (specified only in the case where async processing is used). topic (str) – The topic to subscribe to. bookmark (str) – A bookmark identifier or one of the constants from `Bookmarks`. filter (str) – The filter. sub_id (str) – The subscription ID. You may optionally provide a subscription ID to ease recovery scenarios, instead of having the system automatically generate one for you. When used with the ‘replace’ option, this is the subscription to be replaced. With a bookmark store, this is the subscription ID used for recovery. So, when using a persistent bookmark store, provide an explicit subscription ID that is consistent across application restarts. options (str) – A comma separated string of options. Default is None. timeout (int) – The maximum time to wait for the client to receive and and consume a processed ack for this subscription (in milliseconds). `0` indicates to wait indefinitely.
Returns:	The command identifier assigned to this command if a message handler was provided. If no message handler was provided, returns a `MessageStream` containing the results of the command.
Raises:	`SubscriptionAlreadyExistsException`, `BadFilterException`, `BadRegexTopicException`, `TimedOutException`, `DisconnectedException`.

Client.close()¶: Disconnect from the AMPS server.

Client.connect(uri)¶

Connects to the AMPS instance through the provided URI.

The URI is a string with the format:

transport://userId:password@host:port/protocol

The components of the URI are as follows:

transport – The network transport used for the connection.

userId – If authentication is enabled, this is the unique user ID used to authenticate the connection.

password – If authentication is enabled, this is the password used to authenticate the connection.

host – The hostname or IP address of the host where AMPS is installed.

port – The port to connect to the AMPS instance.

protocol – The protocol used by this connection.

Note

Authentication is optional. If the system is using the default authentication with AMPS, which allows all users in without regard for their userId or password, then the userId:password@ string can be omitted from the connect URI.

Parameters:	uri (str) – The `URI` used to connect to AMPS.
Raises:	`ConnectionException`

Client.convert_version_to_number(version)¶

Converts the provided version string to a number using 2 digits for each dot. A value such as 4.0.0.0 will become 4000000 while 3.8.1.7 will return 3080107.

Parameters:	version (str) – The version string to convert.
Returns:	The numeric value for the version string.

Client.deltaPublish(topic, data)¶: This is a legacy method name for delta_publish().

Deprecated since version 3.2.0.0: Use delta_publish() instead.

Client.deltaSubscribe(on_message, topic, filter=None, options=0, timeout=0)¶: A legacy method name for delta_subscribe().

Deprecated since version 3.2.0.0: Use delta_subscribe() instead.

Client.delta_publish(topic, data, expiration=None)¶

Delta publish a message to an AMPS topic. This method does not wait for a response from the AMPS server. To detect failure, install a failed write handler. If the client was created with a persistent store on construction, then the client will store before forwarding the message to AMPS.

Parameters:	topic (str) – The topic to publish the data to. data (str) – The data to publish to the topic. expiration (int) – Number of seconds until published messages should expire.
Returns:	The sequence number assigned to this message by the publish store or 0 if there is no publish store and the server is assigning sequence numbers.
Raises:	`DisconnectedException`

Client.delta_subscribe()¶

Signatures:

Client.delta_subscribe(on_message, topic, filter=None, options=None, timeout=0, sub_id=None)
Client.delta_subscribe(topic, filter=None, options=None, timeout=0, sub_id=None)

Places a delta subscription with AMPS.

There are two ways to use this method:
1. When a message handler is provided, this method submits the delta_subscribe command on a background thread and calls the message handler with individual messages that match the subscription and that contain the updated fields.
2. When no message handler is provided, this method returns a message stream that can be iterated on to process messages received that match the subscription and that contain the updated fields.

Parameters:	on_message (str) – The message handler to invoke with matching messages (specified only in the case where async processing is used). topic (str) – The topic to subscribe to. filter (str) – The filter. options (str) – A comma separated list of values indicating additional processing options. timeout (int) – The maximum time to wait for the client to receive and consume the processed ack for this subscription (in milliseconds). `0` indicates to wait indefinitely. sub_id (str) – The subscription ID. You may optionally provide a subscription ID to ease recovery scenarios, instead of having the system automatically generate one for you. When used with the `replace` option, this is the subscription to be replaced.
Returns:	The command identifier assigned to this command if a message handler was provided. If no message handler was provided, returns a `MessageStream` containing the results of the command.
Raises:	`SubscriptionAlreadyExistsException`, `BadFilterException`, `BadRegexTopicException`, `TimedOutException`, `DisconnectedException`

Client.disconnect()¶: Disconnects and closes any active connections.

Client.execute(command)¶

Execute the provided command and process responses using a MessageStream. This method creates a Message based on the provided Command, sends the Message to AMPS, and returns a MessageStream that can be iterated on to process messages returned in response to the command.

Parameters:	command (AMPS.Command) – The command to execute.
Returns:	A `MessageStream` to iterate over.

Client.execute_async(command, on_message)¶

Execute the provided command and process responses on the client receive thread using the provided handler. This method creates a Message based on the provided Command, sends the Message to AMPS, and invokes the provided handler to process messages returned in response to the command. Rather than providing messages on the calling thread, the AMPS Python client runs the handler directly on the client receive thread.

When the provided handler is not None, this function blocks until AMPS acknowledges that the command has been processed. The results of the command after that acknowledgment are provided to the handler.

Parameters:	command (AMPS.Command) – The command to execute. on_message (A function or other callable object.) – A handler for messages returned by this command execution.
Returns:	The command ID assigned to the executed command.

Client.flush(timeout=0)¶

Another name for publish_flush().

Parameters:	timeout (int) – The maximum time to wait for the messages to be acknowledged as persisted, or for the flush command to be acknowledged by AMPS (in milliseconds). `0` indicates to wait indefinitely.

Client.getName()¶: A legacy method name for get_name().

Client.get_ack_batch_size()¶

Gets the current batch size used for batching message queue acknowledgment messages.

Returns:	The current batch size used for batching message queue ack messages.

Client.get_ack_timeout()¶

Gets the current time (milliseconds) before queued acknowledgment messages are sent.

Returns:	The current time (milliseconds) before queued ack messages are sent.

Client.get_auto_ack()¶

Called to check if auto-acknowledgment of message queue messages is enabled.

Returns:	True, if auto-acknowledgment of message queue messages is enabled.

Client.get_default_max_depth()¶

Gets the maximum depth for any new MessageStream.

Returns:	The current maximum depth for any new `MessageStream`. `0` is no maximum.

Client.get_duplicate_message_handler()¶

Gets the message handler object set with set_duplicate_message_handler().

Returns:	The message handler object set with `set_duplicate_message_handler()`.

Client.get_error_on_publish_gap()¶

Called to check if the Store will throw PublishStoreGapException.

Returns:	If true, `PublishStoreGapException` can be thrown by the client publish store if the client logs onto a server that appears to be missing messages no longer held in the store.

Client.get_exception_listener()¶

Gets the exception listener callable set on self.

Returns:	The exception listener callable set on self, or None.

Client.get_logon_correlation_data()¶

Gets the data used to correlate the logon of this Client to the server.

Returns:	The logon correlation data.

Client.get_name()¶

Gets the name of the Client object.

Returns:	The `Client` name.

Client.get_name_hash()¶

Gets the string name hash of the Client object.

Returns:	The name hash string.

Client.get_name_hash_value()¶

Gets the numeric name hash of the Client object.

Returns:	The name hash int.

Client.get_retry_on_disconnect()¶

Called to check if automatic retry of a command to AMPS after a reconnect is enabled.

Returns:	True, if automatic retry of a command to AMPS after a reconnect is enabled.

Client.get_server_version()¶

Gets the connected server’s version as a numeric value.

Returns:	The version converted to a number. For example, server version 3.8.1.7 would be 3080107.

Client.get_server_version_info()¶

Gets the connected server’s version as a VersionInfo.

Returns:	The version in a VersionInfo.

Client.get_ssl()¶: For a tcps client, returns the PySSLSocket of the connection

Client.get_unpersisted_count()¶

Gets the count of unpersisted publishes.

Returns:	The count of unpersisted publishes.

Client.get_uri()¶

Gets the URI string passed into the Client during the connect() invocation.

Returns:	The URI string.

Client.logon(timeout=0, authenticator=AMPS.DefaultAuthenticator, options=None)¶

Logs into AMPS with the parameters provided in the connect() method.

Parameters:	timeout (int) – The maximum time to wait for the command to receive a processed ack from AMPS for the logon command (in milliseconds). `0` indicates to wait indefinitely. authenticator (Authenticator) – An Authenticator object used to negotiate logon. options (string) – An options string to be passed to the server during logon, such as `ack_conflation=100ms`.
Returns:	The command identifier.
Raises:	`ConnectionException`

Client.name()¶

The name of the Client object.

Returns:	The `Client` name.

Client.publish(topic, data, expiration=None)¶

Publish a message to an AMPS topic. This method does not wait for a response from the AMPS server. To detect failure, install a failed write handler. If the client was created with a persistent store on construction, then the client will store before forwarding the message to AMPS. If a DisconnectException occurs, the message is still stored in the publish store.

Parameters:	topic (str) – The topic to publish to. data (str) – The data to publish. expiration (int) – Number of seconds until published message should expire.
Returns:	The sequence number assigned to this message by the publish store or 0 if there is no publish store and the server is assigning sequence numbers.
Raises:	`DisconnectedException`

Client.publish_flush(timeout=0, ack_type=Message.AckType.ProcessedEnum)¶

Ensures that pending AMPS messages are sent and have been processed by the AMPS server. When the client has a publish store configured, waits until all messages that are in the store at the time the command is called have been acknowledged by AMPS. Otherwise, issues a flush command and waits for the server to acknowledge that command.

This method blocks until messages have been processed or until the timeout expires, and is most useful when the application reaches a point at which it is acceptable to block to ensure that messages are delivered to the AMPS server. For example, an application might call publish_flush before exiting.

One thing to note is that if AMPS is unavailable (HA Client), publish_flush needs to wait for a connection to come back up, which may look like it’s hanging.

Parameters:	timeout (int) – The maximum time to wait for the messages to be acknowledged as persisted, or for the flush command to be acknowledged by AMPS (in milliseconds). `0` indicates to wait indefinitely. ack_type (int) – Whether the command should wait for a Processed or a Persisted ack when sending the `flush` command.

Client.remove_connection_state_listener(listener_callable)¶

Removes a listener function previously supplied to add_connection_state_listener().

Parameters:	listener_callable (A python function or other callable that takes a single value.) – The function or callable to be removed.

Client.remove_message_handler(command_id)¶

Remove a message handler from the Client.

Parameters:	command_id (str) – The command ID for the handler to remove.

Client.send(message, message_handler=None, timeout=None)¶

Send a Message to AMPS via the Transport used in the Client.

Parameters:	message (`Message`) – The message to send. message_handler (`MessageHandler`) – The message handler that will receive messages for this command. timeout (int) – The maximum time to wait for the client to receive and consume a processed ack for this command (in milliseconds). `0` indicates to wait indefinitely.
Returns:	The command identifier assigned to this command, or None if one is not assigned.

Client.setDisconnectHandler(client_disconnect_handler)¶: A legacy method name for set_disconnect_handler().

Deprecated since version 3.2.0.0: Use set_disconnect_handler() instead.

Client.setExceptionListener(exception_listener)¶: A legacy method name for set_exception_listener().

Deprecated since version 3.2.0.0: Use set_exception_listener() instead.

Client.setName(name)¶: A legacy method name for set_name().

Deprecated since version 3.2.0.0: Use set_name() instead.

Client.setOnDisconnectHandler(client_disconnect_handler)¶: A legacy method name for set_disconnect_handler().

Deprecated since version 3.2.0.0: Use set_disconnect_handler() instead.

Client.setUnhandledMessageHandler(message_handler)¶: A legacy method name for set_last_chance_message_handler().

Deprecated since version 3.2.0.0: Use set_last_chance_message_handler() instead.

Client.set_ack_batch_size(batch_size)¶

Sets the batch size used for batching message queue ack messages.

Parameters:	batch_size – The number of ack messages to batch before sending.

Client.set_ack_timeout(timeout)¶

Sets the time before queued ack messages are sent.

Parameters:	timeout – The maximum amount of time to wait after adding the first message to an acknowledgment batch before sending the batch, in milliseconds. 0 indicates that the client will wait until the batch is full. A value of 0 is not recommended unless the batch size is set to 1.

Client.set_auto_ack(enabled)¶

Enables or disables auto-acknowledgment of message queue messages.

Parameters:	enabled (Boolean) – True to enable auto-acknowledgment of message queue messages.

Client.set_bookmark_store(bookmark_store)¶

Sets a bookmark store on self.

Parameters:	bookmark_store – A `MMapBookmarkStore` or `MemoryBookmarkStore` instance, or a custom object that implements the required bookmark store methods.

Client.set_default_max_depth(depth)¶

Sets a default maximum depth for all new MessageStream objects that are returned from synchronous API calls such as execute().

Parameters:	depth (int) – The new depth to use. A depth of `0` means no max and is the default.

Client.set_disconnect_handler(client_disconnect_handler)¶

Sets the DisconnectHandler used by the Client. In the event that the Client is unintentionally disconnected from AMPS, the invoke method from the ClientDisconnectHandler will be invoked.

Parameters:	client_disconnect_handler (`DisconnectHandler`) – The disconnect handler.

Client.set_duplicate_message_handler(message_handler)¶

Sets the MessageHandler instance used for messages that arrive from AMPS that are deemed to be duplicates of previous messages, according to the local bookmark store.

Parameters:	message_handler (`MessageHandler`) – The message handler to invoke for duplicate messages.

Client.set_error_on_publish_gap(error_on_publish_gap)¶

Called to enable or disable throwing PublishStoreGapException.

Parameters:	error_on_publish_gap (Boolean) – If true, `PublishStoreGapException` can be thrown by the client publish store if the client logs onto a server that appears to be missing messages no longer held in the store.

Client.set_exception_listener(exception_listener)¶

Sets the exception listener instance used for communicating absorbed exceptions.

Parameters:	exception_listener (`Exception`) – The exception listener instance to invoke for exceptions.

Client.set_failed_write_handler(failedWriteHandler)¶

Sets a failed write handler on self.

For example, you might implement a function like:

def PrintFailedWrites(message, reason):
    output = "Uh-oh, something went wrong writing to AMPS. (%s) " % reason
    if (message != None):
          output += "Topic: %s, Data snippet: %s..." % 
                  (message.get_topic(), message.get_data()[0:20])
    print output

Parameters: failedWriteHandler – A callable object to be invoked when AMPS indicates that a published message is not written. This could be because a duplicate message already exists in the transaction log, this client is not entitled to publish to the topic, the message failed to parse, or other similar reasons. Parameters to this callable are an AMPS message when the client has a message saved in the publish store, and a string that contains the reason the publish failed.

Client.set_global_command_type_message_handler(command, message_handler)¶

Add a message handler to the Client to handle messages from the server with the specified command.

Parameters:	command (str) – The command to send to the handler. Valid values are `ack` and `heartbeat`. message_handler (`MessageHandler`) – The message handler that will receive messages of the command specified.

Client.set_heartbeat(interval_seconds, timeout_seconds=None)¶

Used to enable heartbeating between the client and the AMPS Server. When a Client sends a heartbeat message to an AMPS instance, the AMPS instance will send back an acknowledgment message. From this point forward the Client and AMPS instance will each monitor that the other is still active. AMPS sends heartbeat messages to the client at the specified interval. If the Client does not receive a heartbeat message within the time interval specified in timeout_seconds, then the Client will assume that the connection has ended, close the connection and invoke the DisconnectHandler. Likewise, if the server sends a heartbeat and does not receive a response within the timeout, the server will consider the client to be nonresponsive and close the connection.

Heartbeats are processed in the client receive thread. If you use asynchronous message processing, your message handler must process messages within the timeout interval, or risk being disconnected by the server.

Parameters:	interval_seconds (int) – The time between heartbeat messages being sent to AMPS. timeout_seconds (int) – The maximum time to wait for AMPS to acknowledge the start of heartbeating (in seconds).

Client.set_last_chance_message_handler(message_handler)¶

Sets the MessageHandler instance called when no other incoming message handler matches.

Parameters:	message_handler (`MessageHandler`) – The message handler to invoke when no other incoming message handler matches.

Client.set_logon_correlation_data(logon_correlation_data)¶

Sets the data used to correlate the logon of this Client in the server.

Parameters:	logon_correlation_data – The base64 data string to send with the logon.

Client.set_name(name)¶

Sets the Client name.

Parameters:	name – The `Client` name.

Client.set_publish_store(publish_store)¶

Sets a publish store on self.

Parameters:	publish_store – a `PublishStore` or `MemoryPublishStore` instance.

Client.set_retry_on_disconnect(enabled)¶

Enables or disables automatic retry of a command to AMPS after a reconnect. This behavior is enabled by default.

Note

Clients using a publish store will have all publish messages sent, regardless of this setting. Also, Clients with a subscription manager, including all HAClients, will have all subscribe calls placed.

Parameters:	enabled (Boolean) – False to disable automatic retry of commands to AMPS.

Client.set_thread_created_callback(thread_created_callable)¶

Sets a function to be called when this client creates a thread used to receive data from the server.

Parameters:	thread_created_callable (A python function or other callable that takes no parameters.) – The function or callable to be called. This function is called by the newly created thread.

Client.set_transport_filter(transport_filter_callable)¶

Sets a function to be called when this client sends or receives data.

Parameters:	transport_filter_callable (A python function or other callable that takes two parameters: data and direction.) – The function or callable to be called. This function is passed a string (‘data’) containing the raw bytes sent or received. The ‘direction’ parameter is False if the data is being sent to the server, or True if data is received from the server.

Client.set_unhandled_message_handler(message_handler)¶: A legacy method name for set_last_chance_message_handler().

Deprecated since version 4.0.0.0: Use set_last_chance_message_handler() instead.

Client.sow()¶

Signatures:

Client.sow(on_message, topic, filter=None, batch_size=10, timeout=0, top_n=None, order_by=None, bookmark=None, options=0)
Client.sow(topic, filter=None, batch_size=10, timeout=0, top_n=None, order_by=None, bookmark=None, options=0)

Executes a SOW query.

There are two ways to use this method:
1. When a message handler is provided, this method submits the SOW query on a background thread and calls the message handler with individual messages, including the group_begin and group_end messages, that indicate the beginning and end of the SOW results.
2. When no message handler is provided, this method returns a message stream that can be iterated on to process messages received including the group_begin and group_end messages, that indicate the beginning and end of the SOW results.

For example:

client = AMPS.Client("test_client")

try:
    client.connect("tcp://127.0.0.1:9004/amps/fix")
    client.logon()
    for message in client.sow("MySowTopic"):
        print(message.get_data())
finally:
    client.close()

Parameters:	on_message (`MessageHandler`) – The message handler to invoke with matching messages. If this parameter is not present, AMPS creates a `MessageStream` and returns that message stream from the call to sow (specified only in the case where async processing is used). topic (str) – The topic to execute the SOW query against. filter (str) – The filter. batch_size (int) – The batching parameter to use for the results. timeout (int) – The maximum time to wait for the client to receive and consume a processed ack for this command (in milliseconds). `0` indicates to wait indefinitely. top_n (int) – The maximum number of records to return from the SOW. order_by (str) – To have the records ordered by the server. bookmark (int) – The bookmark for historical query of the SOW. options (str) – A comma separated list of values indicating additional processing options.
Returns:	The command identifier assigned to this command if a message handler was provided. If no message handler was provided, returns a `MessageStream` containing the results of the command.
Raises:	`BadFilterException`, `BadRegexTopicException`, `TimedOutException`, `DisconnectedException`

Client.sowAndDeltaSubscribe(on_message, topic, filter=None, batch_size=1, oof_enabled=False, send_empties=False, options=0, timeout=0, top_n=None)¶: A legacy method name for sow_and_delta_subscribe().

Deprecated since version 3.2.0.0: Use sow_and_delta_subscribe() instead.

Client.sowAndSubscribe(on_message, topic, filter, batch_size=1, oof_enabled=False, options=0, timeout=0, top_n=None)¶: A legacy method name for sow_and_subscribe().

Deprecated since version 3.2.0.0: Use sow_and_subscribe() instead.

Client.sowDelete(on_message, topic, filter=None, timeout=0)¶: A legacy method name for sow_delete().

Deprecated since version 3.2.0.0: Use sow_delete() instead.

Client.sow_and_delta_subscribe()¶

Signatures:

Client.sow_and_delta_subscribe(on_message, topic, filter=None, batch_size=1, oof_enabled=False, send_empties=False, timeout=0, top_n=None, order_by=None, options=None)
Client.sow_and_delta_subscribe(topic, filter=None, batch_size=1, oof_enabled=False, send_empties=False, timeout=0, top_n=None, order_by=None, options=None)

Executes a SOW query and places a delta subscription.

There are two ways to use this method:
1. When a message handler is provided, this method submits the sow_and_delta_subscribe command on a background thread and calls the message handler with individual messages received from the SOW query, including the group_begin and group_end messages, that indicate the beginning and end of the SOW results and then with messages received that match the subscription and that contain the updated fields.
2. When no message handler is provided, this method returns a message stream that can be iterated on to process messages received from the SOW query, including the group_begin and group_end messages, that indicate the beginning and end of the SOW results and then processes messages received that match the subscription and that contain the updated fields.

Parameters:	on_message (`MessageHandler`) – The message handler to invoke with matching messages (specified only in the case where async processing is used). topic (str) – The topic to execute the SOW query against. filter (str) – The filter. batch_size (int) – The batch sizing parameter to use for the results. oof_enabled (boolean) – Specifies whether or not Out-of-Focus processing is enabled. send_empties (boolean) – Specifies whether or not unchanged records are received on the delta subscription. timeout (int) – The maximum time to wait for the client to receive and consume the processed ack for this command (in milliseconds). `0` indicates to wait indefinitely. top_n (int) – The maximum number of records to return from the SOW. order_by (str) – To have the records ordered by the server. options (str) – A comma separated list of values indicating additional processing options.
Returns:	The command identifier assigned to this command if a message handler was provided. If no message handler was provided, returns a `MessageStream` containing the results of the command.
Raises:	`SubscriptionAlreadyExistsException`, `BadFilterException`, `BadRegexTopicException`, `TimedOutException`, `DisconnectedException`

Client.sow_and_subscribe()¶

Signatures:

Client.sow_and_subscribe(on_message, topic, filter=None, batch_size=1, oof_enabled=False, timeout=0, top_n=None, order_by=None, bookmark=None, options=None)
Client.sow_and_subscribe(topic, filter=None, batch_size=1, oof_enabled=False, timeout=0, top_n=None, order_by=None, bookmark=None, options=None)

Executes a SOW query and places a subscription.

There are two ways to use this method:
1. When a message handler is provided, this method submits the sow_and_subscribe command on a background thread and calls the message handler with individual messages received from the SOW query, including the group_begin and group_end messages, that indicate the beginning and end of the SOW results and then with messages received that match the subscription.
2. When no message handler is provided, this method returns a message stream that can be iterated on to process messages received from the SOW query, including the group_begin and group_end messages, that indicate the beginning and end of the SOW results and then processes messages received that match the subscription.

Parameters:	on_message (`MessageHandler`) – The message handler to invoke with matching messages (specified only in the case where async processing is used). topic (str) – The topic to execute the SOW query against. filter (str) – The filter. batch_size (int) – The batching parameter to use for the results. oof_enabled (boolean) – Specifies whether or not Out-of-Focus processing is enabled. timeout (int) – The maximum time to wait for the client to receive and consume the processed ack for this command (in milliseconds). `0` indicates to wait indefinitely. top_n (int) – The maximum number of records to return from the SOW. order_by (str) – To have the records ordered by the server. bookmark (str) – The bookmark for historical query of the SOW. options (str) – A comma separated list of values indicating additional processing options.
Returns:	The command identifier assigned to this command if a message handler was provided. If no message handler was provided, returns a `MessageStream` containing the results of the command.
Raises:	`SubscriptionAlreadyExistsException`, `BadFilterException`, `BadRegexTopicException`, `TimedOutException`, `DisconnectedException`

Client.sow_delete()¶

Signatures:

Client.sow_delete(on_message, topic, filter=None, timeout=0)
Client.sow_delete(topic, filter=None, timeout=0)

Executes a SOW delete with a filter.

There are two ways to use this method:
1. When a message handler is provided, this method submits the sow_delete command on a background thread and calls the message handler with the results of the delete.
2. When no message handler is provided, this method returns an acknowledgment message with the result of the delete command.

For example, to delete all messages that match a filter:

...
ackMessage = client.sow_delete("sow_topic","/status = 'obsolete'")
print("%s: %s" % (ackMessage.get_ack_type(), ackMessage.get_status()))
...

Parameters:	on_message (`MessageHandler`) – The message handler to invoke with stats and completed acknowledgments (specified only in the case where async processing is used). topic (str) – The topic to execute the SOW delete against. filter (str) – The filter. To delete all records, set a filter that is always true (‘1=1’). timeout (int) – The maximum time to wait for the client to receive and consume the processed ack for this command (in milliseconds). `0` indicates to wait indefinitely.
Returns:	The command identifier assigned to this command if a message handler was provided. If no message handler was provided, returns an acknowledgment.
Raises:	`BadFilterException`, `BadRegexTopicException`, `TimedOutException`, `DisconnectedException`

Client.sow_delete_by_data()¶

Signatures:

Client.sow_delete_by_data(on_message, topic, data, timeout=0)
Client.sow_delete_by_data(topic, data, timeout=0)

Executes a SOW delete using the provided message data to determine the SOW key of the record to delete.

There are two ways to use this method:
1. When a message handler is provided, this method submits the sow_delete_by_data on a background thread, and calls the message handler with the results of the delete.
2. When no message handler is provided, this method provides an acknowledgment message with the result of the delete command.

For example, to efficiently delete a message that your program has received from AMPS:

...
topic= aMessage.get_topic()
data = aMessage.get_data()
ackMessage = client.sow_delete_by_data(topic,data)
print("%s: %s" % (ackMessage.get_ack_type(), ackMessage.get_status()))
...

In addition to deleting a message from AMPS, this method allows deletion of a message whose keys match one that is already stored, for example:

data = orders[orderId]
ackMessage = client.sow_delete_by_data('orders', data)
del orders[orderId]

Parameters:

on_message (MessageHandler) – The message handler to invoke with stats and completed acknowledgments (specified only in the case where async processing is used).
topic (str) – The topic to execute the SOW delete against.
data (str) – A message whose keys match the message to be deleted in the server’s SOW.
timeout (int) – The maximum time to wait for the client to receive and consume the processed ack for this command (in milliseconds). 0 indicates to wait indefinitely.

Returns:

The command identifier assigned to this command if a message handler was provided. If no message handler was provided, returns an acknowledgment.

Client.sow_delete_by_keys()¶

Signatures:

Client.sow_delete_by_keys(on_message, topic, keys, timeout=0)
Client.sow_delete_by_keys(topic, keys, timeout=0)

Executes a SOW delete using the provided SOW key(s) to determine the record(s) to delete.

There are two ways to use this method:
1. When a message handler is provided, this method submits the sow_delete_by_keys command on a background thread and calls the message handler with the results of the delete.
2. When no message handler is provided, this method provides an acknowledgment message with the result of the delete command.

Parameters:

on_message (MessageHandler) – The message handler to invoke with stats and completed acknowledgments (specified only in the case where async processing is used).
topic (str) – The topic to execute the SOW delete against.
keys (str) – A comma separated list of SOW keys to be deleted.
timeout (int) – The maximum time to wait for the client to receive and consume the processed ack for this command (in millseconds). 0 indicates to wait indefinitely.

Returns:

The command identifier assigned to this command if a message handler was provided. If no message handler was provided, returns an acknowledgment.

Client.start_timer()¶: Used to start a timer on an AMPS Server for the client.

Deprecated since version 5.3.2.0.

Client.stop_timer(handler)¶

Used to stop a timer on an AMPS Server previously started for the client.

Deprecated since version 5.3.2.0.

Parameters:	handler – The handler to be invoked with the timer response.

Client.subscribe()¶

Signatures:

Client.subscribe(on_message, topic, filter=None, options=None, timeout=0, sub_id=None)
Client.subscribe(topic, filter=None, options=None, timeout=0, sub_id=None)

Places a subscription with AMPS.

There are two ways to use this method:
1. When a message handler is provided, this method submits the subscribe command on a background thread and calls the message handler with individual messages that match the subscription.
2. When no message handler is provided, this method returns a message stream that can be iterated on to process messages received that match the subscription.

Parameters:	on_message (str) – The message handler to invoke with matching messages (specified only in the case where async processing is used). topic (str) – The topic to subscribe to. filter (str) – The filter. options (str) – A comma separated list of values indicating additional processing options. timeout (int) – The maximum time to wait for the client to receive and consume the processed ack for this command (in milliseconds). `0` indicates to wait indefinitely. sub_id (str) – The subscription ID. You may optionally provide a subscription ID to ease recovery scenarios, instead of having the system automatically generate one for you. When used with the ‘replace’ option, this is the subscription to be replaced.
Returns:	The command identifier assigned to this command if a message handler was provided. If no message handler was provided, returns a `MessageStream` containing the results of the command.
Raises:	`SubscriptionAlreadyExistsException`, `BadFilterException`, `BadRegexTopicException`, `TimedOutException`, `DisconnectedException`

Client.unsubscribe(sub_id=None)¶

Remove a subscription from AMPS.

Note

Using the keyword all with sub_id will remove all subscriptions to AMPS.

Parameters:	sub_id (str) – The subscription ID to remove.

exception AMPS.ClientNameInUse¶

Bases: AMPS.ConnectionException

deprecated - use NameInUseException

class AMPS.Command(command_name)¶

Bases: object

AMPS.Command represents a single message (or command) sent to the AMPS server. The class provides methods for headers that are used for commands to the server. Applications typically use this class to create outgoing requests to AMPS. The responses to requests, whether acknowledgments or messages that contain data, are returned as instances of the AMPS.Message class.

The AMPS.Client provides named convenience methods that support a subset of the options available via a Command. For most applications, the recommended approach is to use the publish() methods for sending data to AMPS (unless the application needs to set options not available through that method) and use the Command class for queries, subscriptions, and to remove data.

To use the Command class to run a command on the server, you create the Command, set options as described in the Command Cookbook in the Python Developer Guide or the AMPS Command Reference, and then use AMPS.Client.execute_async() to process messages asynchronously, or AMPS.Client.execute() to process messages synchronously.

Constructor Arguments:

Parameters:	command_name – The name of the command to send to the server. For example, `sow`, `sow_and_subscribe` or `publish`.

add_ack_type(value)¶

Adds an ack type to this command, in addition to any other ack types that have been previously set or that will be set by the Client.

Parameters:	value – The ack type to add.
Returns:	This command.

get_ack_type()¶

Gets the ack type for this command.

Returns:	The ack type as a string.

get_ack_type_enum()¶

Gets the ack type enum for this command.

Returns:	The ack type as an enum.

get_sequence()¶

Gets the sequence of self for publish, delta_publish, or sow_delete commands. This can be checked after calling execute or executeAsync to query the sequence number that was used, if any.

Returns:	The sequence number used in the last `publish`, `delta_publish`, or `sow_delete` command.

reset(command)¶

Resets this command with a new Command type and re-initializes all other fields.

Parameters:	command – A string indicating the AMPS command.

set_ack_type(value)¶

Sets the ack type for this command, replacing any other ack types that have been previously set or that will be set by the Client.

Parameters:	value – The ack type to set.
Returns:	This command.

set_ack_type_enum(value)¶

Sets the ack type enum for this command, replacing any other ack types that have been previously set or that will be set by the Client.

Parameters:	value – The ack type enum to set.
Returns:	This command.

set_batch_size(value)¶

Sets the batch size header, which is used to control the number of records that AMPS will send in each batch when returning the results of a SOW query. See the AMPS User Guide for details on SOW query batches.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value to set for the header.
Returns:	This command.

set_bookmark(value)¶

Sets the value of the bookmark header. For a subscription, this identifies the point in the transaction log at which to begin the replay. For a sow_delete (queue acknowledgment), this indicates the message or messages to acknowledge. For a query on a SOW topic with History configured, this indicates the point at which to query the topic.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value to set for the header.
Returns:	This command.

set_command_id(value)¶

Sets the value of the command ID header. This header is used to identify responses to the command. The AMPS FAQ has details on the relationship between command ID, subscription ID, and query ID.

If not set, the AMPS Client will automatically fill in a command_id when the client needs one to be present (for example, when the client needs a processed acknowledgment to be able to tell if a subscribe command succeeded or failed).

Parameters:	value – The new value for this header.
Returns:	This command.

set_correlation_id(value)¶

Sets the value of the correlation ID header. The AMPS server does not process or interpret this value; however, the value must contain only characters that are valid in Base64 encoding for the server to be guaranteed to process the Command.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value to set for the header.
Returns:	This command.

set_data(value)¶

Sets the data for this command. This is used for publish commands and for sow_delete commands.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value to set for the header.
Returns:	This command.

set_expiration(value)¶

Sets the expiration of self. For a publish to a SOW topic or queue, this sets the number of seconds the message will be active before expiring.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value to set for the header.
Returns:	This command.

set_filter(value)¶

Sets the value of the filter header.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value to set for the header.
Returns:	This command.

set_options(value)¶

Sets the value of the options header. The options available, and how AMPS interprets the options, depend on the command being sent. The AMPS.Message.Options class contains constants and helper methods for building an options string. See the AMPS Command Reference for details on the options available for a given command.

Parameters:	value – The value to set.
Returns:	This command.

set_order_by(value)¶

Sets the value of the order by header. This header is only used for SOW query results, and must contain one or more XPath identifiers and an optional ASC or DESC order specifier (for example, /orderTimestamp DESC).

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value to set for the header.
Returns:	This command.

set_query_id(value)¶

Sets the query ID of self.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value to set for the header.
Returns:	This command.

set_sequence(value)¶

Sets the sequence of self for publish, delta_publish, or sow_delete commands. A publish store on the client may replace this value.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value to set for the header.
Returns:	This command.

set_sow_key(value)¶

Sets the SOW key for this command. This is useful for publish commands.

For a publish command, sets the SOW key for a message when the SOW is configured so that the publisher is responsible for determining and providing the SOW key. This option is ignored on a publish when the topic is configured with a Key field in the SOW file.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value to set for the header.
Returns:	This command.

set_sow_keys(value)¶

The SOW keys for a command are a comma-separated list of the keys that AMPS assigns to SOW messages. The SOW key for a message is available through the Message.get_sow_key() method on a message.

For a sow_delete command, this list indicates the set of messages to be deleted.

For a query or subscription, this list indicates the set of messages to include in the query or subscription.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value to set for the header.
Returns:	This command.

set_sub_id(value)¶

Sets the subscription ID of self.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value to set for the header.
Returns:	This command.

set_timeout(value)¶

Sets the amount of time that the Client will wait for a processed acknowledgment from the server to be received and consumed before abandoning the request; this option is only used by the Client and is not sent to the server. The acknowledgment is processed on the client receive thread. This option is expressed in milliseconds, where a value of 0 means to wait indefinitely.

Parameters:	value – The value to set.
Returns:	This command.

set_top_n(value)¶

Sets the top N header of this command. Although AMPS accepts a top N value in the header of a command, most AMPS applications pass the value in the top_n option for clarity.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value to set for the header.
Returns:	This command.

set_topic(value)¶

Sets the value of the topic header, which specifies the topic that the command applies to. For a publish command, this field is interpreted as the literal topic to publish to. For commands such as sow or subscribe, the topic is interpreted as a literal topic unless there are regular expression characters present in the topic name. For those commands, if regular expression characters are present, the command will be interpreted as applying to all topics with names that match the regular expression.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value to set for the header.
Returns:	This command.

exception AMPS.CommandError¶

Bases: AMPS.AMPSException

deprecated - use CommandException

exception AMPS.CommandException¶

Bases: AMPS.CommandError

The CommandException is raised when a Command is used in an improper or unrecognized manner.

exception AMPS.CommandTimedOut¶

Bases: AMPS.CommandException

deprecated - legacy exception

exception AMPS.CommandTypeError¶

Bases: AMPS.CommandException

deprecated - use CommandException

class AMPS.CompositeMessageBuilder¶

Bases: object

AMPS CompositeMessageBuilder Object

append(value)¶: Appends a message part to this object.

clear()¶: Clears this object. Does not resize or free internal buffer.

get_data()¶: Returns the composite message’s data.

class AMPS.CompositeMessageParser¶

Bases: object

AMPS CompositeMessageParser Object

get_part(index)¶: Returns the index’th composite message part, or None if index is invalid.

get_part_raw(index)¶: Returns the index’th composite message part as a python bytes object, or None if index is invalid.

parse(str_or_Message)¶: Parse a composite message body or composite AMPS.Message. Returns the number of valid parts parsed.

size()¶: Returns the number of message parts last parsed.

class AMPS.ConflatingRecoveryPointAdapter¶

Bases: object

This class can be used as an adapter on an AMPS.MemoryBookmarkStore. It is a pass-through to another adapter type that provides conflation of updates to help reduce the load on the underlying adapter. Conflation can be on an interval, a set number of updates or both.

close(subid, bookmark)¶: Close the delegate.

next()¶

Returns the next RecoveryPoint from the delegate or an empty one if: recovery has completed.

prune()¶: Tell the delegate to prune.

purge(sub_id)¶: If sub_id is provided, remove all records related to sub_id. If no sub_id is provided, remove all records for this client. :param sub_id: The optional sub_id to remove or all if none

update(recoveryPoint)¶: Conflate the new information in recoveryPoint. :param recovery_point: The new recovery information to save. :type recovery_point: :ampspy:recoveryPoint

exception AMPS.ConnectionError¶

Bases: AMPS.AMPSException

deprecated - use ConnectionException

exception AMPS.ConnectionException¶

Bases: AMPS.ConnectionError

The ConnectionException is raised when the client is unable to connect to AMPS.

exception AMPS.ConnectionRefused¶

Bases: AMPS.ConnectionException

deprecated - use ConnectionRefusedException

exception AMPS.ConnectionRefusedException¶

Bases: AMPS.ConnectionRefused

The ConnectionRefusedException is raised when the connection to AMPS is refused due to a socket error.

exception AMPS.CorruptedRecord¶

Bases: AMPS.LocalStorageError

deprecated - legacy exception

class AMPS.DefaultAuthenticator¶

Bases: object

AMPS Authenticator Object

authenticate(username, password)¶

Authenticates self to an external system.

Parameters:	username (str) – The current username supplied in a URI. password (str) – The current password supplied in a URI.
Returns:	The new password to be sent to the server in the logon request.

completed(username, password, reason)¶

Called when authentication is completed, with the username and password returned by the server in the final acknowledgement for the logon sequence.

Parameters:	username (str) – The username returned by the server password (str) – The password or authentication token returned by the server in the last logon request. reason (str) – The reason the server provided for finishing the logon sequence. (For example, the logon might have succeeded, authentication might be disabled, and so on.)

retry(username, password)¶

Called when the server indicates a retry is necessary to complete authentication.

Parameters:	username (str) – The username supplied to the server. password (str) – The password or authentication token returned by the server in the last logon request.
Returns:	The new password or authentication token to be sent to the server.

class AMPS.DefaultServerChooser¶

Bases: object

A simple server chooser that keeps a list of AMPS instances and Authenticators, and advances to the next one when failure occurs.

To use the DefaultServerChooser, you add the URIs for the server to choose from, then set the server for the HAClient as shown below:

client = AMPS.HAClient("showchooser")
chooser = AMPS.DefaultServerChooser()
chooser.add("tcp://server:9005/nvfix")
chooser.add("tcp://server-two:9005/nvfix")
client.set_server_chooser(chooser)
client.connect_and_logon()

You can add any number of URIs to the DefaultServerChooser.

add(uri)¶

Adds a URI to this server chooser.

Parameters:	uri (str) – The URI of an AMPS instance that may be chosen.

add_all(uris)¶

Adds a list of URIs to this server chooser.

Parameters:	uris – The list of URIs of AMPS instances that may be chosen.

get_current_authenticator()¶

Called by HAClient to retrieve an Authenticator to use for authentication with the current server.

Returns:	The current `Authenticator`.

get_current_uri()¶

Called by the HAClient to retrieve the current URI to connect to.

Returns:	A URI to connect to, or None if no server should be connected to.

get_error()¶

Provides additional detail to be included in an exception thrown by when the AMPS instance(s) are not available. Called by the HAClient when creating an exception.

Returns:	A string with information about the connection that failed and the reason for the failure. When no further information is available, returns an empty string.

next()¶: Invoked to advance to the next server.

report_failure(exception, connectionInfo)¶

Invoked by HAClient to indicate a connection failure occurred.

Parameters:	exception (`Exception`) – An exception object containing an error message. connectionInfo (dict(str, str)) – A dictionary of properties associated with the failed connection.

report_success(connectionInfo)¶

Invoked by HAClient to indicate a connection attempt was successful.

Parameters:	connectionInfo (dict(str, str)) – A dictionary of properties associated with the successful connection.

exception AMPS.Disconnected¶

Bases: AMPS.ConnectionException

deprecated - use DisconnectedException

exception AMPS.DisconnectedException¶

Bases: AMPS.Disconnected

The DisconnectedException is raised when an operation is requested by the client, but either a connection has yet to be established or the client was disconnected.

exception AMPS.DuplicateLogonException¶

Bases: AMPS.CommandException

The DuplicateLogonException is raised when a client is trying to logon after already logging on.

class AMPS.ExponentialDelayStrategy(initial_delay=200, maximum_delay=20000, backoff_exponent=2.0, maximum_retry_time=0, jitter=1.0)¶

Bases: object

ExponentialDelayStrategy is an implementation that exponentially backs off when reconnecting to the same server, with a maximum time to retry before it gives up entirely.

By default, an ExponentialDelayStrategy has an initial delay of 200 ms, a maximum delay of 20 seconds, a backoff exponent of 2.0, and has no limit to the amount of time to retry the connection.

Constructor Arguments:

Parameters:

initial_delay – The time (in milliseconds) to wait before reconnecting to a server for the first time after a failed connection.
maximum_delay – The maximum time to wait for any reconnect attempt (milliseconds). Exponential backoff will not exceed this maximum.
backoff_exponent – The exponent to use for calculating the next delay time. For example, if the initial time is 200ms and the exponent is 2.0, the next delay will be 400ms, then 800ms, etc.
maximum_retry_time – The maximum time (milliseconds) to allow reconnect attempts to continue without a successful connection, before ‘giving up’ and abandoning the connection attempt.
jitter – The amount of ‘jitter’ to apply when calculating a delay time, measured in multiples of the initial delay. Jitter is used to reduce the number of simultaneous reconnects that may be issued from multiple clients.

get_connect_wait_duration()¶: Returns the time that the client should delay before connecting to the given server URI.

reset()¶: Reset the state of this reconnect delay. AMPS calls this method when a connection is established.

class AMPS.FIXBuilder¶

Bases: object

AMPS FIXBuilder Object

append(tag, value, (optional)offset, (optional)length)¶: Appends tag=value to self. :param tag: The numeric tag to use. :type tag: int :param value: The value for the given tag. :type value: str :param offset: Optional. The offset into value at which the value actually starts. :type offset: int :param length: Optional. The length of the actual value within value. Only valid and required if offset is also provided :type tag: int

get_string()¶

Called to get the string FIX message.

Returns:	The FIX message as a string.

reset()¶: Called to clear the state of the FIXBuilder to create a new FIX message

class AMPS.FIXShredder¶

Bases: object

Convenience class for easily processing FIX strings. Constructor arguments:

Parameters:	separator – The delimiter to expect between FIX fields. Defaults to chr(1) if no delimiter is provided.

to_map(message)¶

Parse the provided FIX message and return a map that contains the fields in the message.

Parameters:	message – The FIX message to parse.

class AMPS.FixedDelayStrategy(initial_delay, maximum)¶

Bases: object

FixedDelayStrategy is a reconnect delay strategy implementation that waits a fixed amount of time before retrying a connection.

By default, a FixedDelayStrategy waits for 200ms between connection attempts and does not have a maximum timeout.

Constructor Arguments:

Parameters:	initial_delay – The time (in milliseconds) to wait before reconnecting to a server for the first time after a failed connection. maximum – The maximum time (in milliseconds) to keep retrying before giving up.

get_connect_wait_duration()¶: Returns the time that the client should delay before connecting to the given server URI.

reset()¶: Reset the state of this reconnect delay. AMPS calls this method when a connection is established.

class AMPS.HAClient(name, publish_store=None, bookmark_store=None, no_store=False)¶

Bases: AMPS.Client

AMPS HAClient Object used for highly-available client connections. Derives from Client.

An example of a Python client publishing a JSON message using the HAClient is listed below:

client = AMPS.HAClient("test_client")

chooser = AMPS.DefaultServerChooser()
chooser.add("tcp://127.0.0.1:9004/amps/json")
client.set_server_chooser(chooser)

try:
  client.connect_and_logon()
  client.publish("topic_name",'{"a":1,"b":"2"}')
finally:
  client.close()

Constructor Arguments:

Parameters:

name – The unique name for this client. AMPS does not enforce specific restrictions on the character set used, however some protocols (for example, XML) may not allow specific characters. 60East recommends that the client name be meaningful, short, human readable, and avoid using control characters, newline characters, or square brackets.
publish_store – An optional file name for the client’s local publish store. If not supplied, a memory-backed publish store is used.
bookmark_store – An optional file name for the client’s local bookmark store. If not supplied, a memory-backed bookmark store is used.
no_store – Pass no_store=True to indicate that a memory bookmark and/or publish store should not be used.

connect()¶: Connects and logs on using the ServerChooser you’ve supplied via set_server_chooser(). Will continue attempting to connect and logon to each URI returned by the ServerChooser until the connection succeeds or the ServerChooser returns an empty URI.

connect_and_logon()¶: Connects and logs on using the ServerChooser you’ve supplied via set_server_chooser(). Will continue attempting to connect and logon to each URI returned by the ServerChooser until the connection succeeds or the ServerChooser returns an empty URI.

discard(message)¶

Discards a message from the local bookmark store.

Parameters:	message (AMPS.Message) – An `AMPS.Message` instance that was received from a bookmark subscription.

get_default_resubscription_timeout()¶: Gets the default timeout, in milliseconds, used when attempting to resubscribe each subscription after a re-connect.

get_logon_options()¶: Gets self’s logon options string and returns it.

get_most_recent(sub_id)¶

Gets the most recent bookmark from the local bookmark store for the given subscription ID.

Parameters:	sub_id (string) – The subscription ID for which to retrieve the most recent bookmark.

get_reconnect_delay_strategy()¶

Returns the reconnect delay strategy object used to control delay behavior when connecting and reconnecting to servers.

Returns:	The reconnect delay strategy object.

get_resubscription_timeout()¶: Gets the timeout, in milliseconds, used when attempting to resubscribe each subscription after a re-connect.

get_server_chooser()¶: Gets self’s server chooser and returns it.

logon()¶: Not used in the HAClient; call connect_and_logon() to connect and log on to AMPS once a server chooser is set.

prune_store(tmp_file_name)¶

Prunes the local bookmark store. If it’s file-based, it will remove unnecessary entries from the file.

Parameters:	tmp_file_name (string) – Optional file name to use for temporary storage during prune operation.

set_default_resubscription_timeout(timeout)¶

Sets the default timeout, in milliseconds, used when attempting to resubscribe each subscription after a re-connect. Default value is 0 (no timeout).

Parameters:	timeout – The number of milliseconds to wait for a server response. `0` indicates no timeout.

set_failed_resubscribe_handler(handler)¶

Sets the handler that is called if a resubscribe after failover, fails to complete successfully. The subscribe Message, requested ack types, and exception are passed to the handler. The handler should return False to force a new attempt at connect_and_logon or True to ignore the failure and remove the subscription from the subscription manager.

Parameters:	handler – The callable handler to invoke.

set_logon_options(options)¶

Sets a logon options on self.

Parameters:	options (string) – An options string to be passed to the server during logon, such as `ack_conflation=100ms`.

set_reconnect_delay(reconnect_delay)¶

Sets the delay in milliseconds used when reconnecting, after a disconnect occurs. Calling this method creates and installs a new FixedDelayStrategy in this client. Default value is 200 (0.2 seconds).

Parameters:	reconnect_delay – The number of milliseconds to wait before reconnecting, after a disconnect occurs.

set_reconnect_delay_strategy(reconnect_delay_strategy)¶

Sets the reconnect delay strategy object used to control delay behavior when connecting and reconnecting to servers.

Parameters:

reconnect_delay_strategy –

The reconnect delay strategy object to use when connecting and reconnecting to AMPS instances. The object must have the following two methods defined:

get_connect_wait_duration(uri):

uri - A string containing the next URI AMPS will connect with. Returns an integer representing the time in milliseconds to wait before connecting to that URI.

reset():

Resets the state of self after a successful connection.

set_resubscription_timeout(timeout)¶

Sets the timeout, in milliseconds, used when attempting to resubscribe each subscription after a re-connect.

Default value is 0 (no timeout), but can be changed using set_default_resubscription_timeout().

Parameters:	timeout – The number of milliseconds to wait for a server response. `0` indicates no timeout.

set_server_chooser(serverChooser)¶

Sets a server chooser on self.

Parameters:	serverChooser (ServerChooser) – A ServerChooser instance, such as a `DefaultServerChooser`.

set_timeout(timeout)¶

Sets the timeout, in milliseconds, used when sending a logon command to the server. Default value is 10000 (10 seconds).

Parameters:	timeout – The number of milliseconds to wait for a server response to logon. `0` indicates no timeout.

class AMPS.HybridPublishStore¶

Bases: object

A publish store that keeps messages on disk as well as in memory. When used with an HAClient, the HAClient manages storing messages in the publish store, replaying messages to the server after failover, and removing messages from the store. With this publish store, an application can recover messages from disk after exiting and restarting.

discard_up_to()¶

Discard all messages in the publish store with a sequence number less than or equal to the provided argument.

Parameters:	sequence – The highest sequence number to discard.

get_last_persisted()¶: Returns the sequence number of last message ACK’ed by the server.

get_lowest_unpersisted()¶: Returns the sequence number of the oldest message in the publish store.

get_unpersisted_count()¶: Returns the number of messages published which have not been ACK’ed by the server.

replay()¶: Replays all messages currently in the publish store via the provided message handler. :param handler: The message handler to call with each message.

replay_single()¶: Replays the message with the given sequence number if it is currently in the publish store via the provided message handler. :param handler: The message handler to call with each message. :param sequence: The sequence number of the message to replay.

set_resize_handler()¶: Sets the object to call when the store needs to resize.

store()¶

Store the provided message into the publish store. Returns the sequence number that should be assigned to the message.

Parameters:	message – The message to put into the store.

exception AMPS.InvalidBookmarkException¶

Bases: AMPS.CommandException

The InvalidBookmarkException is raised when a client uses an invalid bookmark.

exception AMPS.InvalidMessageTypeOptions¶

Bases: AMPS.MessageTypeException

deprecated - use MessageTypeException

exception AMPS.InvalidOptionsException¶

Bases: AMPS.CommandException

The InvalidOptionsException is raised when a client uses an invalid options.

exception AMPS.InvalidOrderByException¶

Bases: AMPS.CommandException

The InvalidOrderByException is raised when a client uses an invalid orderby clause.

exception AMPS.InvalidSubIdException¶

Bases: AMPS.CommandException

The InvalidSubIdException is raised when a client uses an invalid subid.

exception AMPS.InvalidTopicError¶

Bases: AMPS.CommandException

deprecated - use InvalidTopicException

exception AMPS.InvalidTopicException¶

Bases: AMPS.InvalidTopicError

The InvalidTopicException is raised when a query is performed against a topic that does not exist.

exception AMPS.InvalidTransportOptions¶

Bases: AMPS.TransportException

deprecated - use InvalidTransportOptionsException

exception AMPS.InvalidTransportOptionsException¶

Bases: AMPS.InvalidTransportOptions

InvalidTransportOptionsException is raised when a URI string contains invalid options for a given transport.

exception AMPS.InvalidUriException¶

Bases: AMPS.InvalidUriFormat

InvalidUriException is raised when the format of the URI is invalid.

exception AMPS.InvalidUriFormat¶

Bases: AMPS.ConnectionException

deprecated - use InvalidUriException

exception AMPS.LocalStorageError¶

Bases: AMPS.AMPSException

deprecated - legacy exception

exception AMPS.LogonRequiredException¶

Bases: AMPS.CommandException

The LogonRequiredException is raised when a client attempts to execute a command before calling logon.

class AMPS.MMapBookmarkStore¶

Bases: object

AMPS MMapBookmarkStore Object

Stores bookmarks in a local file. Construct with the filename to use or recover from. Optional second bool argument to request that the last modified timestamp of the file is included in the initial most recent bookmark. Optional third argument of a RecoveryPointAdapter.

discard(subid, sequence)¶: Log a discard-bookmark entry to the persisted log.

discard_message(message)¶: Log a message as discarded from the store.

get_most_recent(subid)¶: Returns the most recent bookmark from the log that ought to be used for (re-)subscriptions.

get_oldest_bookmark_seq(subid)¶: Called to find the oldest bookmark sequence in the store.

is_discarded(message)¶: Called for each arriving message to determine if the application has already seen this bookmark and should not be reprocessed. Returns True if the bookmark is in the log and should not be re-processed, False otherwise.

log(message)¶: Log a bookmark to the log and return the corresponding sequence number.

persisted(subid, bookmark)¶: Mark all bookmarks up to the provided one as replicated to all replication destinations for the given subscription.

persisted_index()¶

persisted(subid, bookmark_index)

Mark all bookmarks up to the provided index as replicated to all replication destinations for the given subscription.

prune([temp_file_name])¶: Used to trim the size of a store’s storage. Implemented for file based stores to remove items no longer necessary to create the current state.

purge()¶: Called to purge the contents of this store. Removes any tracking history associated with publishers and received messages, and may delete or truncate on-disk representations as well.

purge_sub_id()¶: Called to purge the contents of this store for a given subscription id. Removes any tracking history associated with publishers and received messages, and may delete or truncate on-disk representations as well.

set_resize_handler()¶: Sets the object to call when the store needs to resize.

set_server_version(version)¶: Internally used to set the server version so the store knows how to deal with persisted acks and calls to get_most_recent().

class AMPS.MemoryBookmarkStore¶

Bases: object

A bookmark store that maintains information about the recovery point for bookmark subscriptions in memory.

When the bookmark store is set on a Client or HAClient, the AMPS client library manages adding subscriptions to the store and tracking bookmarks as they arrive. The AMPS HAClient uses the bookmark store on failover to recover bookmark subscriptions at the appropriate point.

For a bookmark subscription, an application must discard() messages when they have been processed. The other methods on this class are not typically called by the application during normal use.

A RecoveryPointAdapter may optionally be specified when created to add something such as storage in a SOW using SOWRecoveryPointAdapter to prevent any message loss if the client application dies.

discard(subid, sequence)¶: Log a discard-bookmark entry to the persisted log.

discard_message(message)¶: Log a message as discarded from the store.

get_most_recent(subid)¶: Returns the most recent bookmark from the log that ought to be used for (re-)subscriptions.

get_oldest_bookmark_seq(subid)¶: Called to find the oldest bookmark sequence in the store.

is_discarded(message)¶: Called for each arriving message to determine if the application has already seen this bookmark and should not be reprocessed. Returns True if the bookmark is in the log and should not be re-processed, False otherwise.

log(message)¶: Log a bookmark to the log and return the corresponding sequence number.

persisted(subid, bookmark)¶: Mark all bookmarks up to the provided one as replicated to all replication destinations for the given subscription.

persisted_index()¶

persisted(subid, bookmark_index)

Mark all bookmarks up to the provided index as replicated to all replication destinations for the given subscription.

purge()¶: Called to purge the contents of this store. Removes any tracking history associated with publishers and received messages, and may delete or truncate on-disk representations as well.

purge_sub_id()¶: Called to purge the contents of this store for a given subscription id. Removes any tracking history associated with publishers and received messages, and may delete or truncate on-disk representations as well.

set_resize_handler()¶: Sets the object to call when the store needs to resize.

set_server_version(version)¶: Internally used to set the server version so the store knows how to deal with persisted acks and calls to get_most_recent().

class AMPS.MemoryPublishStore¶

Bases: object

A publish store that keeps messages in memory. This class is the default publish store for a python HAClient. The HAClient manages storing messages in the publish store, replaying messages to the server after failover, and removing messages from the store. With this publish store, an application typically checks to be sure that the publish store is empty (that is, all messages have been persisted in the AMPS server) before exiting.

discard_up_to()¶

Discard all messages in the publish store with a sequence number less than or equal to the provided argument.

Parameters:	sequence – The highest sequence number to discard.

get_error_on_publish_gap()¶

Returns If true, PublishStoreGapException can be thrown: by the client publish store if the client logs onto a server that appears to be missing messages no longer held in the store.

get_last_persisted()¶: Returns the sequence number of last message ACK’ed by the server.

get_lowest_unpersisted()¶: Returns the sequence number of the oldest message in the publish store.

get_unpersisted_count()¶: Returns the number of messages published which have not been ACK’ed by the server.

replay()¶: Replays all messages currently in the publish store via the provided message handler. :param handler: The message handler to call with each message.

replay_single()¶: Replays the message with the given sequence number if it is currently in the publish store via the provided message handler. :param handler: The message handler to call with each message. :param sequence: The sequence number of the message to replay.

set_error_on_publish_gap()¶

Called to enable or disable throwing PublishStoreGapException.

Parameters:	error_on_publish_gap (Boolean) – If true, PublishStoreGapException can be thrown by the client publish store if the client logs onto a server that appears to be missing messages no longer held in the store.

set_resize_handler()¶: Sets the object to call when the store needs to resize.

store()¶

Store the provided message into the publish store. Returns the sequence number that should be assigned to the message.

Parameters:	message – The message to put into the store.

class AMPS.Message¶

Bases: object

AMPS.Message represents a single message sent to or received from the AMPS server. The class provides methods for every header that can be present, whether or not that header will be populated or used in a particular context.

Applications typically use an AMPS.Command to create outgoing requests to AMPS, and receive instances of AMPS.Message in response.

The AMPS Command Reference provides details on which headers are used by AMPS and which will be populated on messages received from AMPS, depending on the command the AMPS.Message responds to, the optionsand headers set on that command, and the type of the response message.

AMPS.Message has been designed to minimize unnecessary memory allocation. Copying a Message does not copy the underlying content of the message. When the AMPS client provides a Message to a message handler function, the data in that Message is a region in the buffer that the AMPS client uses to read from the socket. If your application will use the Message after the message handler returns, you should use the __deepcopy__() function to copy the underlying data as well as the Message, since in this case the AMPS client will reuse the underlying buffer once the MessageHandler returns. See the AMPS Python Developer Guide section on asynchronous message processing for more details.

If your application has the need to bypass most of the AMPS.Client infrastructure for some reason when sending commands to AMPS, the AMPS.Message / AMPS.Client.send() interface provides the flexibility to do so. In return, your application must provide functionality that is normally provided automatically by the AMPS.Client (for example, tracking subscriptions for failover, recording the message in the publish store and managing success or failure of the publish, and so on). Although this functionality is available for flexibility, it is rarely needed in practice. 60East recommends using AMPS.Command objects with AMPS.Client.execute() and AMPS.Client.execute_async() for sending commands to AMPS.

class Options¶

Bases: object

AMPS.Message.Options is a class that provides convenience methods for constructing an options string for use in a command to AMPS. This class is intended to help in formatting the options. It does not validate the values provided, that the options apply to any particular command,or that the options have a particular result. The AMPS Python client (and the AMPS server itself) accept options as a string, so there is no requirement to use this class to format options.

cmd = AMPS.Command("sow_and_subscribe").set_topic("my_cool_topic") \ 
          .set_options(str(AMPS.Message.Options().set_OOF().set_conflation("5s") ))

Note

Not every option applies to every command. See the AMPS User Guide and AMPS Command Reference for details on what options are available on a given command, and what effect the option has.

set_OOF()¶: Adds the oof option to the current set of options. See the AMPS Command Reference and AMPS User Guide for details.

set_cancel()¶: Adds the cancel option to the current set of options. See the AMPS Command Reference and AMPS User Guide for details.

set_conflation()¶

Sets the conflation option as a time interval such as 250ms or 1m. See the AMPS Command Reference and AMPS User Guide for details.

Parameters:	value – the conflation interval to set

set_conflation_key()¶

Sets the conflation_key for a subscription, as one or more XPath identifiers to use to determine which messages are identical and should be conflated. See the AMPS Command Reference and AMPS User Guide for details.

Parameters:	value – the key or keys for the command to conflate on

set_fully_durable()¶: Adds the fully_durable option to the current set of options. See the AMPS Command Reference and AMPS User Guide for details.

set_grouping()¶

Sets the grouping option, which defines how to group messages from the original topic into result messages in an aggregated subscription or aggregated query. See the AMPS Command Reference and AMPS User Guide for details.

Parameters:	value – the grouping definition for the command

set_live()¶: Adds the live option to the current set of options. See the AMPS Command Reference and AMPS User Guide for details.

set_max_backlog()¶

Sets the max_backlog option, the maximum number of unacknowledged queue messages that a subscription is willing to accept at a given time. (The actual number of messages allowed will be either this setting, or the per subscription maximum set for the queue, whichever is smaller). See the AMPS Command Reference and AMPS User Guide for details.

Parameters:	value – the maximum backlog for the subscription

set_no_empties()¶: Adds the no_empties option to the current set of options. See the AMPS Command Reference and AMPS User Guide for details.

set_no_sowkey()¶: Adds the no_sowkey option to the current set of options. See the AMPS Command Reference and AMPS User Guide for details.

set_none()¶: Clears options set on self.

set_pause()¶: Adds the pause option to the current set of options. See the AMPS Command Reference and AMPS User Guide for details.

set_projection()¶

Sets the projection option, which defines the fields produced by an aggregated subscription or aggregated query. See the AMPS Command Reference and AMPS User Guide for details.

Parameters:	value – the projection definition for the command

set_rate()¶

Sets the rate option, which optionally controls the maximum rate at which a transaction log replay will produce messages. See the AMPS Command Reference and AMPS User Guide for details.

Parameters:	value – the rate value as a message number, number of data bytes, or multiplier of the original message rate

set_rate_max_gap()¶

Sets the rate_max_gap option, which controls the amount of time AMPS will go without producing a message from a transaction log replay when the rate option is specified. See the AMPS Command Reference and AMPS User Guide for details.

Parameters:	value – the maximum gap as an interval (such as `30s`)

set_replace()¶: Adds the replace option to the current set of options. See the AMPS Command Reference and AMPS User Guide for details.

set_resume()¶: Adds the resume option to the current set of options. See the AMPS Command Reference and AMPS User Guide for details.

set_send_keys()¶: Adds the send_keys option to the current set of options. See the AMPS Command Reference and AMPS User Guide for details.

set_skip_n()¶

Sets the skip_n value for a command. See the AMPS Command Reference and AMPS User Guide for details.

Parameters:	value – the skip_n value as an integer

set_timestamp()¶: Adds the timestamp option to the current set of options. See the AMPS Command Reference and AMPS User Guide for details.

set_top_n()¶

Sets the top_n value for a command. See the AMPS Command Reference and AMPS User Guide for details.

Parameters:	value – the top_n value, as an integer

Message.ack()¶: Acknowledges the current message queue message.

Message.getAckType()¶

Gets the value of ack_type for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of ack_type on this message.

Message.getBatchSize()¶

Gets the value of the BatchSize header.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of batch_size on this message.

Message.getBookmark()¶

Gets the value of the Bookmark header. For messages returned from AMPS, this is an opaque identifier that AMPS can use to locate the message in the transaction log, and is returned on messages that are produced from the transaction log (for example, messages delivered from queues or returned in response to a bookmark subscribe command).

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of bookmark on this message.

Message.getClientName()¶

Gets the value of client_name for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of client_name on this message.

Message.getCommand()¶

Gets the value of the command header, which specifies what type of message this is. Every message from AMPS has the Command header set, and should interpret the message based on the Command. See the AMPS Command reference for details on what Command values will be returned in response to a given command to AMPS, what header fields are provided on Messages with a given Command value, and how an application should interpret those header fields.

Returns:	The value of the Command set on this message.

Message.getCommandId()¶

Gets the value of command_id for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of command_id on this message.

Message.getCorrelationId()¶

Gets the value of the correlation_id header. The correlation ID is set when a command is provided to AMPS. The AMPS server does not process or interpret this value: the correlation ID is returned verbatim, as it was submitted with the command.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of correlation_id on this message.

Message.getData()¶

Gets the value of data for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of data on this message.

Message.getExpiration()¶

Gets the value of expiration for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of expiration on this message.

Message.getFilter()¶

Gets the value of filter for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of filter on this message.

Message.getGroupSequenceNumber()¶

Gets the value of group_seq_no for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of group_seq_no on this message.

Message.getHeartbeat()¶

Gets the value of heartbeat for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of heartbeat on this message.

Message.getLeasePeriod()¶

Gets the value of lease_period for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of lease_period on this message.

Message.getMatches()¶

Gets the value of matches for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of matches on this message.

Message.getMessageLength()¶

Gets the value of message_size for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of message_size on this message.

Message.getMessageType()¶

Gets the value of message_type for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of message_type on this message.

Message.getOptions()¶

Gets the value of options for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of options on this message.

Message.getOrderBy()¶

Gets the value of order_by for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of order_by on this message.

Message.getPassword()¶

Gets the value of password for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of password on this message.

Message.getQueryID()¶

Gets the value of query_id for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of query_id on this message.

Message.getReason()¶

Gets the value of reason for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of reason on this message.

Message.getRecordsInserted()¶

Gets the value of records_inserted for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of records_inserted on this message.

Message.getRecordsReturned()¶

Gets the value of records_returned for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of records_returned on this message.

Message.getRecordsUpdated()¶

Gets the value of records_updated for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of records_updated on this message.

Message.getSequence()¶

Gets the value of sequence for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of sequence on this message.

Message.getSowDelete()¶

Gets the value of sow_deleted for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of sow_deleted on this message.

Message.getSowKey()¶

Gets the value of the sow_key header. When a message is returned from a Topic in the State of the World, this header provides the key that the AMPS server uses to identify the message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of sow_key on this message.

Message.getSowKeys()¶

Gets the value of sow_keys for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of sow_keys on this message.

Message.getStatus()¶

Gets the value of status for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of status on this message.

Message.getSubscriptionId()¶

Gets the value of sub_id for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of sub_id on this message.

Message.getSubscriptionIds()¶

Gets the value of sub_ids for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of sub_ids on this message.

Message.getTimeoutInterval()¶

Gets the value of timeout_interval for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of timeout_interval on this message.

Message.getTimestamp()¶

Gets the value of the timestamp header. When the timestamp option is specified on a command, publish and sow messages returned will have the time at which the AMPS server processed the message returned in this field.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of timestamp on this message.

Message.getTopNRecordsReturned()¶

Gets the value of top_n for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of top_n on this message.

Message.getTopic()¶

Gets the value of topic for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of topic on this message.

Message.getTopicMatches()¶

Gets the value of topic_matches for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of topic_matches on this message.

Message.getUserId()¶

Gets the value of user_id for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of user_id on this message.

Message.getVersion()¶

Gets the value of version for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of version on this message.

Message.get_ack_type()¶

Gets the value of ack_type for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of ack_type on this message.

Message.get_batch_size()¶

Gets the value of the BatchSize header.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of batch_size on this message.

Message.get_bookmark()¶

Gets the value of the Bookmark header. For messages returned from AMPS, this is an opaque identifier that AMPS can use to locate the message in the transaction log, and is returned on messages that are produced from the transaction log (for example, messages delivered from queues or returned in response to a bookmark subscribe command).

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of bookmark on this message.

Message.get_bookmark_seq_no()¶: Gets the bookmark sequence number of this message.

Message.get_client_name()¶

Gets the value of client_name for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of client_name on this message.

Message.get_command()¶

Gets the value of the command header, which specifies what type of message this is. Every message from AMPS has the Command header set, and should interpret the message based on the Command. See the AMPS Command reference for details on what Command values will be returned in response to a given command to AMPS, what header fields are provided on Messages with a given Command value, and how an application should interpret those header fields.

Returns:	The value of the Command set on this message.

Message.get_command_id()¶

Gets the value of command_id for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of command_id on this message.

Message.get_correlation_id()¶

Gets the value of the correlation_id header. The correlation ID is set when a command is provided to AMPS. The AMPS server does not process or interpret this value: the correlation ID is returned verbatim, as it was submitted with the command.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of correlation_id on this message.

Message.get_data()¶

Gets the value of data for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of data on this message.

Message.get_data_raw()¶

Returns:	the data of this message as a python bytes object

Message.get_expiration()¶

Gets the value of expiration for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of expiration on this message.

Message.get_filter()¶

Gets the value of filter for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of filter on this message.

Message.get_group_seq_no()¶

Gets the value of group_seq_no for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of group_seq_no on this message.

Message.get_heartbeat()¶

Gets the value of heartbeat for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of heartbeat on this message.

Message.get_lease_period()¶

Gets the value of lease_period for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of lease_period on this message.

Message.get_matches()¶

Gets the value of matches for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of matches on this message.

Message.get_message_size()¶

Gets the value of message_size for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of message_size on this message.

Message.get_message_type()¶

Gets the value of message_type for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of message_type on this message.

Message.get_options()¶

Gets the value of options for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of options on this message.

Message.get_order_by()¶

Gets the value of order_by for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of order_by on this message.

Message.get_password()¶

Gets the value of password for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of password on this message.

Message.get_query_id()¶

Gets the value of query_id for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of query_id on this message.

Message.get_reason()¶

Gets the value of reason for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of reason on this message.

Message.get_records_inserted()¶

Gets the value of records_inserted for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of records_inserted on this message.

Message.get_records_returned()¶

Gets the value of records_returned for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of records_returned on this message.

Message.get_records_updated()¶

Gets the value of records_updated for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of records_updated on this message.

Message.get_sequence()¶

Gets the value of sequence for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of sequence on this message.

Message.get_sow_deleted()¶

Gets the value of sow_deleted for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of sow_deleted on this message.

Message.get_sow_key()¶

Gets the value of the sow_key header. When a message is returned from a Topic in the State of the World, this header provides the key that the AMPS server uses to identify the message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of sow_key on this message.

Message.get_sow_keys()¶

Gets the value of sow_keys for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of sow_keys on this message.

Message.get_status()¶

Gets the value of status for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of status on this message.

Message.get_sub_id()¶

Gets the value of sub_id for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of sub_id on this message.

Message.get_sub_ids()¶

Gets the value of sub_ids for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of sub_ids on this message.

Message.get_timeout_interval()¶

Gets the value of timeout_interval for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of timeout_interval on this message.

Message.get_timestamp()¶

Gets the value of the timestamp header. When the timestamp option is specified on a command, publish and sow messages returned will have the time at which the AMPS server processed the message returned in this field.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of timestamp on this message.

Message.get_top_n()¶

Gets the value of top_n for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of top_n on this message.

Message.get_topic()¶

Gets the value of topic for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of topic on this message.

Message.get_topic_matches()¶

Gets the value of topic_matches for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of topic_matches on this message.

Message.get_user_id()¶

Gets the value of user_id for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of user_id on this message.

Message.get_version()¶

Gets the value of version for this message.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of version on this message.

Message.reset()¶: Resets the contents of this message.

Message.setAckType()¶

Sets the value of ack_type for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for ack_type.
Returns:	this message

Message.setBatchSize()¶

Sets the value of the BatchSize header, which is used to control the number of records that AMPS will send in a batch when returning the results of a SOW query. See the AMPS User Guide for details on SOW query batches.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for batch_size.
Returns:	this message

Message.setBookmark()¶

Sets the value of the Bookmark header. For a subscription, this identifies the point at which to begin the replay. For a sow_delete (queue acknowledgement), this indicates the message or messages to acknowledge. For a query on a SOW topic with History configured, this indicates the point at which to query the topic.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for bookmark.
Returns:	this message

Message.setClientName()¶

Sets the value of the ClientName header. In a logon command, this header sets the client name for the connection.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for client_name.
Returns:	this message

Message.setCommand()¶

Sets the value of the command header. Every message sent to AMPS is required to have a command header set, which specifies how the message is to be intrepreted. It is an error to send a message to AMPS without setting this field.

See the AMPS Command Reference for details on the values that AMPS accepts for this header, how those commands are interpreted, and what headers and options can be set for a given command.

Note

If you are building a command to be sent to AMPS, using the AMPS.Command class rather than Message is recommended for most purposes.

Param:	The new value for the Command.

Message.setCommandId()¶

Sets the value of the command_id header. This header is used to identify responses to the command. The AMPS FAQ has details on the relationship between command ID, subscription ID, and query ID.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of command_id on this message.

Message.setCorrelationId()¶

Sets the value of the correlation_id header. The AMPS server does not process or interpret this value; however, the value set must contain only characters that are valid in Base64 encoding for the server to be guaranteed to process the Message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for correlation_id.
Returns:	this message

Message.setData()¶

Sets the value of data for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for data.
Returns:	this message

Message.setExpiration()¶

Sets the value of the expiration header. For a publish to a SOW topic or queue, this sets the number of seconds the message will be active before expiring.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for expiration.
Returns:	this message

Message.setFilter()¶

Sets the value of filter for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for filter.
Returns:	this message

Message.setGroupSequenceNumber()¶

Sets the value of group_seq_no for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for group_seq_no.
Returns:	this message

Message.setHeartbeat()¶

Sets the value of heartbeat for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for heartbeat.
Returns:	this message

Message.setLeasePeriod()¶

Sets the value of lease_period for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for lease_period.
Returns:	this message

Message.setMatches()¶

Sets the value of matches for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for matches.
Returns:	this message

Message.setMessageLength()¶

Sets the value of message_size for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for message_size.
Returns:	this message

Message.setMessageType()¶

Sets the value of the message_type header. This header is used during logon to set the message type for the connection, and is ignored on other commands.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for message_type.
Returns:	this message

Message.setOptions()¶

Sets the value of options for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for options.
Returns:	this message

Message.setOrderBy()¶

Sets the value of order_by for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for order_by.
Returns:	this message

Message.setPassword()¶

Sets the value of password for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for password.
Returns:	this message

Message.setQueryID()¶

Sets the value of query_id for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for query_id.
Returns:	this message

Message.setReason()¶

Sets the value of reason for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for reason.
Returns:	this message

Message.setRecordsInserted()¶

Sets the value of records_inserted for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for records_inserted.
Returns:	this message

Message.setRecordsReturned()¶

Sets the value of records_returned for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for records_returned.
Returns:	this message

Message.setRecordsUpdated()¶

Sets the value of records_updated for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for records_updated.
Returns:	this message

Message.setSequence()¶

Sets the value of sequence for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for sequence.
Returns:	this message

Message.setSowDelete()¶

Sets the value of sow_deleted for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for sow_deleted.
Returns:	this message

Message.setSowKey()¶

Sets the value of the sow_key header. When publishing a message to a topic in the State of the World that is configured to require the publisher to set an explicit key (rather than having AMPS calculate the key based on the message contents), the publisher uses this header to set the key to be used.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for sow_key.
Returns:	this message

Message.setSowKeys()¶

Sets the value of the sow_keys header. When sending a command to AMPS that should only apply to specific items in a State of the World topic, the sow_keys header can restrict the effects of the command to just the items that have a SowKey that appears in this header.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for sow_key.
Returns:	this message

Message.setStatus()¶

Sets the value of status for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for status.
Returns:	this message

Message.setSubscriptionId()¶

Sets the value of sub_id for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for sub_id.
Returns:	this message

Message.setSubscriptionIds()¶

Sets the value of sub_ids for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for sub_ids.
Returns:	this message

Message.setTimeoutInterval()¶

Sets the value of timeout_interval for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for timeout_interval.
Returns:	this message

Message.setTimestamp()¶

Sets the value of the timestamp header. This option is provided for use by the AMPS Client when constructing a message. No commands to the AMPS server use this header.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for timestamp.
Returns:	this message

Message.setTopNRecordsReturned()¶

Sets the value of top_n for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for top_n.
Returns:	this message

Message.setTopic()¶

Sets the value of topic for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for topic.
Returns:	this message

Message.setTopicMatches()¶

Sets the value of topic_matches for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for topic_matches.
Returns:	this message

Message.setUserId()¶

Sets the value of user_id for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for user_id.
Returns:	this message

Message.setVersion()¶

Sets the value of version for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for version.
Returns:	this message

Message.set_ack_type()¶

Sets the value of ack_type for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for ack_type.
Returns:	this message

Message.set_batch_size()¶

Sets the value of the BatchSize header, which is used to control the number of records that AMPS will send in a batch when returning the results of a SOW query. See the AMPS User Guide for details on SOW query batches.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for batch_size.
Returns:	this message

Message.set_bookmark()¶

Sets the value of the Bookmark header. For a subscription, this identifies the point at which to begin the replay. For a sow_delete (queue acknowledgement), this indicates the message or messages to acknowledge. For a query on a SOW topic with History configured, this indicates the point at which to query the topic.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for bookmark.
Returns:	this message

Message.set_client_name()¶

Sets the value of the ClientName header. In a logon command, this header sets the client name for the connection.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for client_name.
Returns:	this message

Message.set_command()¶

Sets the value of the command header. Every message sent to AMPS is required to have a command header set, which specifies how the message is to be intrepreted. It is an error to send a message to AMPS without setting this field.

See the AMPS Command Reference for details on the values that AMPS accepts for this header, how those commands are interpreted, and what headers and options can be set for a given command.

Note

If you are building a command to be sent to AMPS, using the AMPS.Command class rather than Message is recommended for most purposes.

Param:	The new value for the Command.

Message.set_command_id()¶

Sets the value of the command_id header. This header is used to identify responses to the command. The AMPS FAQ has details on the relationship between command ID, subscription ID, and query ID.

Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

Returns:	The value of command_id on this message.

Message.set_correlation_id()¶

Sets the value of the correlation_id header. The AMPS server does not process or interpret this value; however, the value set must contain only characters that are valid in Base64 encoding for the server to be guaranteed to process the Message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for correlation_id.
Returns:	this message

Message.set_data()¶

Sets the value of data for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for data.
Returns:	this message

Message.set_expiration()¶

Sets the value of the expiration header. For a publish to a SOW topic or queue, this sets the number of seconds the message will be active before expiring.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for expiration.
Returns:	this message

Message.set_filter()¶

Sets the value of filter for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for filter.
Returns:	this message

Message.set_group_seq_no()¶

Sets the value of group_seq_no for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for group_seq_no.
Returns:	this message

Message.set_heartbeat()¶

Sets the value of heartbeat for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for heartbeat.
Returns:	this message

Message.set_lease_period()¶

Sets the value of lease_period for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for lease_period.
Returns:	this message

Message.set_matches()¶

Sets the value of matches for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for matches.
Returns:	this message

Message.set_message_size()¶

Sets the value of message_size for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for message_size.
Returns:	this message

Message.set_message_type()¶

Sets the value of the message_type header. This header is used during logon to set the message type for the connection, and is ignored on other commands.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for message_type.
Returns:	this message

Message.set_options()¶

Sets the value of options for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for options.
Returns:	this message

Message.set_order_by()¶

Sets the value of order_by for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for order_by.
Returns:	this message

Message.set_password()¶

Sets the value of password for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for password.
Returns:	this message

Message.set_query_id()¶

Sets the value of query_id for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for query_id.
Returns:	this message

Message.set_reason()¶

Sets the value of reason for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for reason.
Returns:	this message

Message.set_records_inserted()¶

Sets the value of records_inserted for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for records_inserted.
Returns:	this message

Message.set_records_returned()¶

Sets the value of records_returned for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for records_returned.
Returns:	this message

Message.set_records_updated()¶

Sets the value of records_updated for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for records_updated.
Returns:	this message

Message.set_sequence()¶

Sets the value of sequence for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for sequence.
Returns:	this message

Message.set_sow_deleted()¶

Sets the value of sow_deleted for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for sow_deleted.
Returns:	this message

Message.set_sow_key()¶

Sets the value of the sow_key header. When publishing a message to a topic in the State of the World that is configured to require the publisher to set an explicit key (rather than having AMPS calculate the key based on the message contents), the publisher uses this header to set the key to be used.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for sow_key.
Returns:	this message

Message.set_sow_keys()¶

Sets the value of the sow_keys header. When sending a command to AMPS that should only apply to specific items in a State of the World topic, the sow_keys header can restrict the effects of the command to just the items that have a SowKey that appears in this header.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for sow_key.
Returns:	this message

Message.set_status()¶

Sets the value of status for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for status.
Returns:	this message

Message.set_sub_id()¶

Sets the value of sub_id for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for sub_id.
Returns:	this message

Message.set_sub_ids()¶

Sets the value of sub_ids for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for sub_ids.
Returns:	this message

Message.set_timeout_interval()¶

Sets the value of timeout_interval for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for timeout_interval.
Returns:	this message

Message.set_timestamp()¶

Sets the value of the timestamp header. This option is provided for use by the AMPS Client when constructing a message. No commands to the AMPS server use this header.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for timestamp.
Returns:	this message

Message.set_top_n()¶

Sets the value of top_n for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for top_n.
Returns:	this message

Message.set_topic()¶

Sets the value of topic for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for topic.
Returns:	this message

Message.set_topic_matches()¶

Sets the value of topic_matches for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for topic_matches.
Returns:	this message

Message.set_user_id()¶

Sets the value of user_id for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for user_id.
Returns:	this message

Message.set_version()¶

Sets the value of version for this message.

Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

Parameters:	value – The new value for version.
Returns:	this message

class AMPS.MessageStream¶

Bases: object

A message handler used to create an in-thread iterator interface over the Messages that are returned from a command.

close()¶: Closes this message stream.

conflate()¶: Enables message conflation by SOW key.

get_depth()¶: Gets the current depth of this message stream.

get_max_depth()¶: Gets the maximum depth allowed for this message stream.

max_depth(maxDepth)¶

Sets the maximum depth allowed for this message stream (that is, the maximum number of messages stored in this object at a given time). When this limit is exceeded, the Client will stop receiving messages from the socket until messages are removed from the MessageStream.

Parameters:	maxDepth – The maximum number of messages that are buffered in this stream before pushback on the network connection.

timeout(millis)¶: Sets the timeout on this message stream.

If no message is received in this timeout, None is returned to the caller of next(), and the stream remains open.

exception AMPS.MessageTypeError¶

Bases: AMPS.ConnectionException

deprecated - use MessageTypeException

exception AMPS.MessageTypeException¶

Bases: AMPS.MessageTypeError

MessageTypeException is raised when the message type requested by the client is unsupported.

exception AMPS.MessageTypeNotFound¶

Bases: AMPS.MessageTypeException

deprecated - use MessageTypeException

exception AMPS.MissingFieldsException¶

Bases: AMPS.CommandException

The MissingFieldsException is raised when a client attempts to execute a command and required fields are missing.

class AMPS.NVFIXBuilder(delimiter)¶

Bases: object

Convenience class for easily creating NVFIX strings.

Constructor Arguments:

Parameters:	delimiter – The delimiter to use between NVFIX fields. Defaults to \x01 if no delimiter is provided.

append(tag, value, offset(optional), length(optional))¶

Appends tag=value to self.

Parameters:	tag (str) – The tag to use. value (str) – The value for the given tag. offset (int) – The offset into value at which the value actually starts. Optional. length (int) – The length of the actual value within value. Optional. Only valid and required if offset is also provided.

get_string()¶

Called to get the string NVFIX message.

Returns:	The NVFIX message as a string.

reset()¶: Called to clear the state of the NVFIXBuilder to create a new NVFIX message.

class AMPS.NVFIXShredder(delimiter)¶

Bases: object

Convenience class for easily processing NVFIX strings.

Constructor Arguments:

Parameters:	delimiter – The delimiter to expect between NVFIX fields. Defaults to \x01 if no delimiter is provided.

to_map(message)¶

Parse the provided NVFIX message and return a map that contains the fields in the message.

Parameters:	message – The NVFIX message to parse.

exception AMPS.NameInUseException¶

Bases: AMPS.ClientNameInUse

NameInUseException is raised when a client attempts to connect and uses the same client name as a currently connected client.

exception AMPS.NotEntitledError¶

Bases: AMPS.ConnectionException

deprecated - use NotEntitledException

exception AMPS.NotEntitledException¶

Bases: AMPS.NotEntitledError

NotEntitledException is raised when an authenticated client attempts to access a resource to which the user has not been granted proper entitlements.

exception AMPS.PublishException¶

Bases: AMPS.CommandException

The PublishException is raised when a client attempts to publish an invalid message or some other error occurs with the message.

class AMPS.PublishStore¶

Bases: object

AMPS PublishStore Object

Stores published records in a file while awaiting an ACK from the server. Construct with the name of the file to use for record storage and optionally, a Boolean to specify if the store should throw an exception if logging onto a server that might be missing messages not in the store.

discard_up_to()¶

Discard all messages in the publish store with a sequence number less than or equal to the provided argument.

Parameters:	sequence – The highest sequence number to discard.

get_error_on_publish_gap()¶

Returns If true, PublishStoreGapException can be thrown: by the client publish store if the client logs onto a server that appears to be missing messages no longer held in the store.

get_last_persisted()¶: Returns the sequence number of last message ACK’ed by the server.

get_lowest_unpersisted()¶: Returns the sequence number of the oldest message in the publish store.

get_unpersisted_count()¶: Returns the number of messages published which have not been ACK’ed by the server.

replay()¶: Replays all messages currently in the publish store via the provided message handler. :param handler: The message handler to call with each message.

replay_single()¶: Replays the message with the given sequence number if it is currently in the publish store via the provided message handler. :param handler: The message handler to call with each message. :param sequence: The sequence number of the message to replay.

set_error_on_publish_gap()¶

Called to enable or disable throwing PublishStoreGapException.

Parameters:	error_on_publish_gap (Boolean) – If true, PublishStoreGapException can be thrown by the client publish store if the client logs onto a server that appears to be missing messages no longer held in the store.

set_resize_handler()¶: Sets the object to call when the store needs to resize.

store()¶

Store the provided message into the publish store. Returns the sequence number that should be assigned to the message.

Parameters:	message – The message to put into the store.

truncate_on_close()¶: Sets if the PublishStore should truncate the file to initial capacity when it closes if it is empty.

exception AMPS.PublishStoreGapException¶

Bases: AMPS.StoreException

An exception was thrown by the underlying publish store because the client is attempting to logon to a server that appears to be missing messages from this client that are no longer in the publish store.

class AMPS.Reason¶

Bases: object

AMPS Reason Object

class AMPS.RecoveryPoint¶

Bases: object

This class represents a subscription’s recovery point. It consists of a sub_id and a bookmark, which is opaque.

get_bookmark()¶: returns the bookmark for this RecoveryPoint

get_sub_id()¶: returns the subId of this RecoveryPoint

exception AMPS.RetryOperation¶

Bases: AMPS.ConnectionException

deprecated - use RetryOperationException

exception AMPS.RetryOperationException¶

Bases: AMPS.RetryOperation

RetryOperationException is raised when sending of a message has failed two consecutive attempts. Any send which receives this can assume that the message was not delivered to AMPS.

class AMPS.RingBookmarkStore¶

Bases: object

AMPS RingBookmarkStore Object

discard(subid, sequence)¶: Log a discard-bookmark entry to the persisted log.

discard_message(message)¶: Log a message as discarded from the store.

get_most_recent(subid)¶: Returns the most recent bookmark from the log that ought to be used for (re-)subscriptions.

get_oldest_bookmark_seq(subid)¶: Called to find the oldest bookmark sequence in the store.

is_discarded(message)¶: Called for each arriving message to determine if the application has already seen this bookmark and should not be reprocessed. Returns True if the bookmark is in the log and should not be re-processed, False otherwise.

log(message)¶: Log a bookmark to the log and return the corresponding sequence number.

persisted(subid, bookmark)¶: Mark all bookmarks up to the provided one as replicated to all replication destinations for the given subscription.

persisted_index()¶

persisted(subid, bookmark_index)

Mark all bookmarks up to the provided index as replicated to all replication destinations for the given subscription.

purge()¶: Called to purge the contents of this store. Removes any tracking history associated with publishers and received messages, and may delete or truncate on-disk representations as well.

purge_sub_id()¶: Called to purge the contents of this store for a given subscription id. Removes any tracking history associated with publishers and received messages, and may delete or truncate on-disk representations as well.

set_resize_handler()¶: Sets the object to call when the store needs to resize.

set_server_version(version)¶: Internally used to set the server version so the store knows how to deal with persisted acks and calls to get_most_recent().

class AMPS.SOWRecoveryPointAdapter¶

Bases: object

This class can be used as an adapter on an AMPS.MemoryBookmarkStore to save enough recovery state information to guarantee no missed messages. It must be constructed with a client using json message type, connected and logged on to a server on which the chosen topic is defined as a SOW topic with key fields equivalent to the chosen client name field and sub id field. It also must not be the same client that is being tracked, whose name is provided as the tracked client name.

close(subid, bookmark)¶: Close the store so it can no longer be used. May close the store client if that option was true when constructed.

get_exception_listener()¶: Returns the exception listener callable set on self, or None.

next()¶

Returns the next RecoveryPoint from the SOW or an empty one if: recovery has completed.

prune()¶: This has no affect on a SOWRecoveryPointAdapter.

purge(sub_id)¶: If sub_id is provided, remove all records related to sub_id. If no sub_id is provided, remove all records for this client. :param sub_id: The optional sub_id to remove or all if none

set_exception_listener(listener)¶

set_exception_listener(exception_listener)

Sets the exception listener instance used for communicating

absorbed exceptions.

Parameters:	exception_listener (`Exception`) – The exception listener instance to invoke for exceptions.

update(recoveryPoint)¶: Updates the SOW with the new information in recoveryPoint. :param recovery_point: The new recovery information to save. :type recovery_point: :ampspy:recoveryPoint

class AMPS.Store¶

Bases: object

AMPS Store Object

exception AMPS.StoreException¶

Bases: AMPS.StoreError

An exception was thrown by the underlying publish store.

exception AMPS.StreamError¶

Bases: AMPS.ConnectionException

deprecated - use StreamException

exception AMPS.StreamException¶

Bases: AMPS.StreamError

StreamException is raised when an incoming message is improperly formatted.

exception AMPS.SubidInUseException¶

Bases: AMPS.CommandException

The SubidInUseException is raised when a subscription is place with the same subscription id.

exception AMPS.SubscriptionAlreadyExists¶

Bases: AMPS.CommandException

deprecated - use SubscriptionAlreadyExistsException

exception AMPS.SubscriptionAlreadyExistsException¶

Bases: AMPS.SubscriptionAlreadyExists

The SubscriptionAlreadyExistsException is raised when a subscription is place which matches a subscription that already exists.

exception AMPS.TimedOut¶

Bases: AMPS.ConnectionException

deprecated - use TimedOutException

exception AMPS.TimedOutException¶

Bases: AMPS.TimedOut

The TimedOutException is raised when an operation times out.

exception AMPS.TransportError¶

Bases: AMPS.ConnectionException

deprecated - use TransportException

exception AMPS.TransportException¶

Bases: AMPS.TransportError

TransportException is raised when an AMPS Client transport has an error.

exception AMPS.TransportNotFound¶

Bases: AMPS.TransportException

deprecated - use TransportException

exception AMPS.TransportTypeException¶

Bases: AMPS.ConnectionException

TransportTypeException is raised when an unknown or invalid transport is attempted.

exception AMPS.UnknownError¶

Bases: AMPS.CommandException

deprecated - use UnknownException

exception AMPS.UnknownException¶

Bases: AMPS.UnknownError

The UnknownException is raised when the AMPS Python Client is in an unrecoverable state.

exception AMPS.UsageException¶

Bases: AMPS.AMPSException

The UsageException is raised when an attempt is made to incorrectly use an object or function, such setting ack timeout to 0 when the ack batch size is > 1.

class AMPS.VersionInfo¶

Bases: object

AMPS VersionInfo Object

get_old_style_version()¶: Returns the version as number with 2 digits for major version, 2 digits for minor version, 2 digits for maintenance version and 2 digits for patch version. Any values greater than 99 are represented as 99.

get_version_number()¶: Returns the version as number with 4 digits for major version, 4 digits for minor version, 5 digits for maintenance version and 5 digits for patch version.

get_version_string()¶: Returns the version string.

set_version(version)¶: Sets the string version to represent.

AMPS.ssl_get_context()¶: Returns the SSLContext used for SSL connections. Call ssl_init first.

AMPS.ssl_init()¶

Initializes SSL support in the AMPS module.

Parameters:

dllpath – The path to the OpenSSL DLL or shared library to use for SSL functionality.
ssl_context – An ssl.SSLContext preconfigured with desired settings for tcps connections to the AMPS server.
strict_ciphers_only – If True, use only the stricter ciphers allowed by default in Python version 3.10 and above. The default is False, which enables all default OpenSSL ciphers for compatibility with some AMPS versions using older OpenSSL libraries.

AMPS.ssl_load_verify_locations()¶

Override default CA certificate locations for AMPS SSL connections.

Parameters:	ca_file – Path to a PEM file containing CA certificates. ca_path – Path to a directory containing multiple CA certificates as PEM files. See OpenSSL’s SSL_CTX_load_verify_locations for more information.

AMPS.ssl_set_verify()¶

Enables or disables peer certificate validation for SSL connections.

Parameters:	enabled – True to enable, False to disable. Default: False (disabled).

AMPS Module Reference¶

Previous topic

This Page