AMPS Module Reference¶
-
exception
AMPS.
AMPSException
¶ Bases:
exceptions.Exception
The base exception class for all exceptions in the AMPS Python Client.
-
exception
AMPS.
AlreadyConnected
¶ Bases:
AMPS.ConnectionException
deprecated - use
AlreadyConnectedException
-
exception
AMPS.
AlreadyConnectedException
¶ Bases:
AMPS.AlreadyConnected
The AlreadyConnectedExcpetion is raised when a client attemptsmultiple connections to an AMPS instance after being successfullyconnected.
-
exception
AMPS.
AuthenticationError
¶ Bases:
AMPS.ConnectionException
deprecated - use
AuthenticationException
-
exception
AMPS.
AuthenticationException
¶ Bases:
AMPS.AuthenticationError
The AuthenticationException is raised when the credentials provided to the client fail in AMPS authentication.
-
exception
AMPS.
BadFilter
¶ Bases:
AMPS.CommandException
deprecated - use
BadFilterException
-
exception
AMPS.
BadFilterException
¶ Bases:
AMPS.BadFilter
The BadFilterException is raised when a query contains invalid content or is not used against a valid topic or field.
-
exception
AMPS.
BadRegexTopic
¶ Bases:
AMPS.CommandException
deprecated - use
BadRegexTopicException
-
exception
AMPS.
BadRegexTopicException
¶ Bases:
AMPS.BadRegexTopic
The BadRegexTopicException is raised when a topic query containing a regular expression is unable to be compiled by the AMPS regular expression compiler.
-
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
¶ 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 simple Python client publishing a JSON message is listed below:
c = Client("test_client") try: c.connect("tcp://127.0.0.1:9004/json") cid = c.logon() c.publish("topic_name",'{"a":1,"b":"2"}') finally: c.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 journalMOST_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 discardedNOW
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 toAMPS.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)¶ ACKs a message queue message.
:param message an AMPS.Message object to ack, OR :param topic The topic of the message to ACK :param bookmark The bookmark of the message to ACK. :param 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 acks sent in response to the given command_id.Parameters: - command_id (str) – The command_id for messages and acks.
- message_handler (
MessageHandler
) – The message handler that will receive messages for the command_id. - acks (int) – The acks 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
(on_message, 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.
Parameters: - on_message (
MessageHandler
) – The message handler to invoke with matching messages. - 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 subscription to be placed (milliseconds). 0 indicates no timeout.
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
where:
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
orpassword
, then theuserId:password@
string can be omitted from the connect URI.Parameters: uri (str) – The :class`URI` used to connect to AMPS. Raises: ConnectionException
- The
-
Client.
convert_version_to_number
()¶ 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 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. If the client was created with a persistent store on construction, then the client will store before forwarding the message to AMPS. This method does not wait for a response from the AMPS server. To detect failure, install a failed write handler.
Parameters: - topic (str) – Topic to publish the data to.
- data (int) – Data to publish to the topic.
- expiration – Number of seconds until published message should expire.
Raises:
-
Client.
delta_subscribe
(on_message, topic, filter=None, options=0, timeout=0, sub_id=None)¶ Places a delta subscription with AMPS.
Parameters: - on_message (str) – The message handler to invoke with matching messages.
- 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 subscription to be placed (milliseconds). 0 indicates no timeout.
- 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.
Raises: SubscriptionAlreadyExistsException
,BadFilterException
,BadRegexTopicException
,TimedOutException
,DisconnectedException
-
Client.
disconnect
()¶ Disconnects and closes any active connections.
-
Client.
execute
()¶ Executes a Command on self.
Param: An AMPS.Command to execute. Returns: A MessageStream to iterate over.
-
Client.
execute_async
()¶ Execute the provided command and process responses on the client receive thread using the provided handler.
This method creates a
Message
based on the providedCommand
, sends theMessage
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 acknowledgement 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()
.
-
Client.
getName
()¶ A legacy method name for
get_name()
.
-
Client.
get_ack_batch_size
()¶ Returns the current batch size used for batching message queue ACK messages.
-
Client.
get_ack_timeout
()¶ Returns the current time (milliseconds) before queued ack messages are sent.
-
Client.
get_auto_ack
()¶ Returns True if auto-acknowledgement of message queue messages is enabled.
-
Client.
get_default_max_depth
()¶ Returns the current maximum depth for new MessageStreams, 0 is no maximum.
-
Client.
get_duplicate_message_handler
()¶ Returns the message handler object set with set_duplicate_message_handler.
-
Client.
get_exception_listener
()¶ Returns the exception listener callable set on self, or None.
-
Client.
get_logon_correlation_data
()¶ Returns the data used to correlate the logon of this Client to the server.
Returns: logon correlation data
-
Client.
get_name
()¶ Returns the name of the Client object.
Returns: name
-
Client.
get_retry_on_disconnect
()¶ Returns True if automatc retry of a command to AMPS after a reconnect is enabled.
-
Client.
get_server_version
()¶ Returns the connected server’s version as a numeric value.
Returns: The version converted to a number: server version 3.8.1.7 would be 3080107
-
Client.
get_server_version_info
()¶ Returns the connected server’s version as a VersionInfo.
Returns: The version in a VersionInfo
-
Client.
get_unpersisted_count
()¶ Returns the count of unpersisted publishes.
Returns: count of unpersisted publishes.
-
Client.
get_uri
()¶ Returns the
URI
string passed into theClient
during theconnect()
invocation.Returns: uri
-
Client.
logon
(timeout=0, authenticator=AMPS.DefaultAuthenticator, options='')¶ Logs into AMPS with the parameters provided in the
connect()
method.Parameters: - timeout (int) – The maximum time to wait for the command to execute (milliseconds). 0 indicates no timeout
- authenticator (Authenticator) – An Authenticator object used to negotiate logon.
- options (string) – An options string to pass to the server such as ack_conflation=10ms execute (milliseconds). 0 indicates no timeout
Returns: The command identifier.
Raises:
-
Client.
name
()¶ Returns the name of the Client object.
Returns: name
-
Client.
publish
(topic, data, expiration=None)¶ Publish a mesage to an AMPS topic. If the client was created with a persistent store on construction, then the client will store before forwarding the message to AMPS. This method does not wait for a response from the AMPS server. To detect failure, install a failed write handler. If a DisconnectException occurs, the message is still stored in the publish store.
Parameters: - topic (str) – The topic to publish to.
- data (int) – The data to publish.
- expiration – Number of seconds until published message should expire.
Raises: DisconnectedException
The client is not connected; the program needs to call connect()
-
Client.
publish_flush
(timeout = 0)¶ - Ensures that pending AMPS messages are sent and have been processed by the AMPS server. When the client is connected to a server that implements the flush command, the client issues that command and waits for an acknowledgement. For older versions of AMPS, the client sends a publish to a dummy topic. 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), publishFlush 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 flush to be acknowledged in milliseconds, or 0 for no maximum.
-
Client.
remove_connection_state_listener
(listener_callable)¶ Removes a listener function previously supplied to add_connection_state_listener.
-
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)¶ 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 subscription to be placed (milliseconds). 0 indicates no timeout.
Returns: The command identifier assigned to this command, or None if one is not assigned.
- message (
-
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.
- A legacy method name for
-
Client.
setExceptionListener
(exception_listener)¶ - A legacy method name for
set_exception_listener()
. Deprecated since version 3.2.0.0: Use
set_exception_listener()
instead.
- A legacy method name for
-
Client.
setName
(name)¶ - A legacy method name for
set_name()
. Deprecated since version 3.2.0.0: Use
set_name()
instead.
- A legacy method name for
-
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.
- A legacy method name for
-
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.
- A legacy method name for
-
Client.
set_ack_batch_size
(batch_size)¶ Sets the batch size used for batching message queue ACK messages.
:param 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.
:param timeout The ack message send timeout, in milliseconds. 0 indicates no timeout.
-
Client.
set_auto_ack
(enabled)¶ Enables or disables auto-acknowledgement of message queue messages.
:param enabled True to enable auto-acknowledgement of message queue messages.
-
Client.
set_bookmark_store
(bookmarkStore)¶ Sets a bookmark store on self.
Parameters: bookmarkStore – an MMapBookmarkStore
orMemoryBookmarkStore
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().
:param depth The new depth to use. A depth of 0 means no max and is the default. :type depth: int.
-
Client.
set_disconnect_handler
(client_disconnect_handler)¶ - Sets the
DisconnectHandler
used by theClient
. In - the event that the Client is unintentionally disconnected from AMPS, the invoke
method from the
ClientDisconnectHandler
will be invoked.
Parameters: client_disconnect_handler – The disconnect handler. - Sets the
-
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 duplicates messages.- Sets the
-
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.
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. 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
-
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 theClient
and AMPS instance will each monitor that the other is still active. AMPS sends heartbeat messages to the client at the specified interval. If theClient
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 theDisconnectHandler
. 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 – 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
()¶ Sets the data used to correlate the logon of this Client in the server.
Parameters: logonCorrelationData – The base64 data string to send with the logon.
-
Client.
set_name
(name)¶ A legacy method name for
set_name()
.
-
Client.
set_publish_store
(publishStore)¶ Sets a publish store on self.
Parameters: publishStore – an PublishStore
orMemoryPublishStore
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.
:param enabled False to disable automatic retry of commands to AMPS. :type enabled: Boolean.
-
Client.
set_transport_filter
(transport_filter_callable)¶ Sets a function to be called when this client sends or receives data.
-
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.
- A legacy method name for
-
Client.
sow
(on_message, topic, filter=None, batch_size=10, timeout=0, top_n=None, order_by=None, bookmark=None, options=None)¶ Executes a SOW query. There are two ways to use this method. First, you can provide a topic, filter, and options for the subscription. In this case, the method returns a message stream that you can iterate over. For example:
c = Client("test_client") try: c.connect("tcp://127.0.0.1:9004/fix") cid = c.logon(timeout=0) for aMessage in c.sow("MySowTopic"): print aMessage.get_data() finally: c.close()
Second, you can provide a message handler. In this case, the method creates a background thread and calls the message handler with each message received from AMPS, including the group_begin and group_end messages that indicate the beginning and end of the SOW query.
Parameters: - on_message (
MessageHandler
) – The message handler to invoke with matching messages. If this parameter is not present, AMPS creates a :class: MessageStream and returns that message stream from the call to sow. - 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 subscription to be placed (milliseconds). 0 indicates no timeout.
- 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: If a message handler is provided, returns the command identifier assigned to this command. If no message handler is present, returns a MessageStream containing the results of the command.
Raises: BadFilterException
,BadRegexTopicException
,TimedOutException
,DisconnectedException
- on_message (
-
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.
- A legacy method name for
-
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.
- A legacy method name for
-
Client.
sowDelete
(on_message, topic, filter=None, options=0, timeout=0)¶ - A legacy method name for
sow_delete()
. Deprecated since version 3.2.0.0: Use
sow_delete()
instead.
- A legacy method name for
-
Client.
sow_and_delta_subscribe
(on_message, topic, filter=None, batch_size=1, oof_enabled=False, send_empties=False, options=0, timeout=0, top_n=None)¶ Executes a SOW query and places a delta subscription.
Parameters: - on_message (
MessageHandler
) – The message handler to invoke with matching messages. - 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 subscription to be placed (milliseconds). 0 indicates no timeout.
- 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.
Raises: SubscriptionAlreadyExistsException
,BadFilterException
,BadRegexTopicException
,TimedOutException
,DisconnectedException
- on_message (
-
Client.
sow_and_subscribe
(on_message, topic, filter, batch_size=1, oof_enabled=False, timeout=0, top_n=None, order_by=, bookmark=, options=)¶ Executes a SOW query and places a subscription.
Parameters: - on_message (
MessageHandler
) – The message handler to invoke with matching messages. - 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 subscription to be placed (milliseconds). 0 indicates no timeout.
- 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.
Raises: SubscriptionAlreadyExistsException
,BadFilterException
,BadRegexTopicException
,TimedOutException
,DisconnectedException
- on_message (
-
Client.
sow_delete
(on_message, topic, filter=None, options=0, timeout=0)¶ Executes a SOW delete with a filter.
There are two ways to use this method. When no message handler is provided, the method returns a
Message
that will receive the results of the delete command.When a message handler is provided, this method submits the SOW delete on a background thread and calls the message handler with the results of the delete.
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 - 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’)
- options (str) – A comma separated list of values indicating additional processing options.
- timeout (int) – The maximum time to wait for the subscription to be placed (milliseconds). 0 indicates no timeout.
Returns: The command identifier assigned to this command.
Raises: BadFilterException
,BadRegexTopicException
,TimedOutException
,DisconnectedException
- on_message (
-
Client.
sow_delete_by_data
(on_message, topic, data, timeout=0)¶ Delete a message from a SOW, using data supplied to locate a SOW entry with matching keys.
There are two ways to use this method. When no message handler is provided, the method returns a
Message
that will receive the results of the delete command.When a message handler is provided, this method submits the SOW delete on a background thread and calls the message handler with the results of the delete.
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 - 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 subscription to be placed (milliseconds). 0 indicates no timeout.
Returns: The command identifier assigned to this command.
- on_message (
-
Client.
sow_delete_by_keys
(on_message, topic, keys, timeout=0)¶ Executes a SOW delete with sow keys.
There are two ways to use this method. When no message handler is provided, the method returns a
Message
that will receive the results of the delete command.When a message handler is provided, this method submits the SOW delete on a background thread and calls the message handler with the results of the delete.
Parameters: - on_message (
MessageHandler
) – The message handler to invoke with stats and completed acknowledgments - 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 subscription to be placed (milliseconds). 0 indicates no timeout.
Returns: The command identifier assigned to this command.
- on_message (
-
Client.
start_timer
()¶ Used to start a timer on an AMPS Server for the client.
-
Client.
stop_timer
(handler)¶ Used to stop a timer on an AMPS Server previously started for the client. :param handler: The handler to be invoked with the timer response.
-
Client.
subscribe
(on_message, topic, filter=None, options=None, timeout=0, sub_id=None)¶ Places a subscription with AMPS.
Parameters: - on_message (str) – The message handler to invoke with matching messages.
- 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 subscription to be placed (milliseconds). 0 indicates no timeout.
- 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.
Raises: SubscriptionAlreadyExistsException
,BadFilterException
,BadRegexTopicException
,TimedOutException
,DisconnectedException
-
Client.
unsubscribe
(sub_id=None)¶ - Remove a subscription from AMPS.
Parameters: sub_id – The subscription id to remove.
-
class
-
exception
AMPS.
ClientNameInUse
¶ Bases:
AMPS.ConnectionException
deprecated - use
NameInUseException
-
class
AMPS.
Command
¶ Bases:
object
A class to specify an AMPS command to run.
-
add_ack_type
()¶ Adds an ack type to self.
-
reset
()¶ - Resets this command with a new Command type and re-initializes all other fields.
Param: A string indicating the AMPS command.
-
set_batch_size
()¶ Sets the batch size of self. This option requests that the server return query results in batches consisting of this number of messages.
-
set_bookmark
()¶ Sets the bookmark of self.
-
set_command_id
()¶ Sets the command id of self.
-
set_correlation_id
()¶ Sets the correlation ID of self.
-
set_data
()¶ Sets the data of self. This option is used for
publish
commands and forsow_delete
commands.
-
set_expiration
()¶ 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.
-
set_filter
()¶ Sets the filter of self.
-
set_options
()¶ Sets the options of self.
-
set_order_by
()¶ Sets the order by clause of self. This option is only used for SOW query results.
-
set_sow_key
()¶ 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 apublish
when the topic is configured with aKey
field in the SOW file.Param: The sow key to set.
-
set_sow_keys
()¶ 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.
Param: The sow keys to set.
-
set_sub_id
()¶ Sets the subscription id of self.
-
set_timeout
()¶ Sets the timeout of self. This option tells the AMPS client how long to wait for a
processed
acknowledgement from the server.
-
set_top_n
()¶ Sets the top N field of self.
-
set_topic
()¶ Sets the topic of self.
-
-
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.
-
-
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 ServerChooser 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 anAuthenticator
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.
-
-
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.
-
class
AMPS.
ExponentialDelayStrategy
¶ 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 maxmimum delay of 20 seconds, a backoff exponent of 2.0, and has no limit to the amount of time to retry the connection.
Constructor parameters:
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
¶ 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 parameters:
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
¶ Bases:
AMPS.Client
AMPS HAClient Object used for highly-available client connections. Derives from
Client
. 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_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_server_chooser
()¶ Gets selfs 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_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=100us.
-
set_reconnect_delay
(reconnectDelay)¶ 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). :param reconnectDelay: The number of milliseconds to wait before reconnecting, after a disconnect occurs.
-
set_reconnect_delay_strategy
(reconnectDelayStrategy)¶ Sets the reconnect delay strategy object used to control delay behavior when connecting and reconnecting to servers.
Parameters: 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_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). :param 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.
-
get_unpersisted_count
()¶ Returns the number of messages published which have not been ACK’ed by the server.
-
set_resize_handler
()¶ Sets the object to call when the store needs to resize.
-
-
exception
AMPS.
InvalidMessageTypeOptions
¶ Bases:
AMPS.MessageTypeException
deprecated - use
MessageTypeException
-
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
-
class
AMPS.
MMapBookmarkStore
¶ Bases:
object
AMPS MMapBookmarkStore Object
Stores bookmarks in a local file. Construct with the filename to use or recover from.
-
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.
-
no_persisted_acks
(subid)¶ Flag the subscription as being on an older server without persisted acks. No persisted acks will be sent for any bookmarks.
-
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.
-
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.
-
no_persisted_acks
(subid)¶ Flag the subscription as being on an older server without persisted acks. No persisted acks will be sent for any bookmarks.
-
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.
-
get_unpersisted_count
()¶ Returns the number of messages published which have not been ACK’ed by the server.
-
set_resize_handler
()¶ Sets the object to call when the store needs to resize.
-
-
class
AMPS.
Message
¶ Bases:
object
AMPS Message Object
-
class
Options
¶ Bases:
object
AMPS Options Object used to build options strings for commands.
-
Message.
getAckType
()¶ Returns: The value of ack_type on this message.
-
Message.
getBatchSize
()¶ Returns: The value of batch_size on this message.
-
Message.
getBookmark
()¶ Returns: The value of bookmark on this message.
-
Message.
getClientName
()¶ Returns: The value of client_name on this message.
-
Message.
getCommand
()¶ Returns: The value of command on this message.
-
Message.
getCommandId
()¶ Returns: The value of command_id on this message.
-
Message.
getCorrelationId
()¶ Returns: The value of correlation_id on this message.
-
Message.
getData
()¶ Returns: The value of data on this message.
-
Message.
getExpiration
()¶ Returns: The value of expiration on this message.
-
Message.
getFilter
()¶ Returns: The value of filter on this message.
-
Message.
getGroupSequenceNumber
()¶ Returns: The value of group_seq_no on this message.
-
Message.
getLeasePeriod
()¶ Returns: The value of lease_period on this message.
-
Message.
getMatches
()¶ Returns: The value of matches on this message.
-
Message.
getMessageLength
()¶ Returns: The value of message_size on this message.
-
Message.
getMessageType
()¶ Returns: The value of message_type on this message.
-
Message.
getOptions
()¶ Returns: The value of options on this message.
-
Message.
getPassword
()¶ Returns: The value of password on this message.
-
Message.
getQueryID
()¶ Returns: The value of query_id on this message.
-
Message.
getReason
()¶ Returns: The value of reason on this message.
-
Message.
getRecordsInserted
()¶ Returns: The value of records_inserted on this message.
-
Message.
getRecordsReturned
()¶ Returns: The value of records_returned on this message.
-
Message.
getRecordsUpdated
()¶ Returns: The value of records_updated on this message.
-
Message.
getSequence
()¶ Returns: The value of sequence on this message.
-
Message.
getSowDelete
()¶ Returns: The value of sow_deleted on this message.
-
Message.
getSowKey
()¶ Returns: The value of sow_key on this message.
-
Message.
getSowKeys
()¶ Returns: The value of sow_keys on this message.
-
Message.
getStatus
()¶ Returns: The value of status on this message.
-
Message.
getSubscriptionId
()¶ Returns: The value of sub_id on this message.
-
Message.
getSubscriptionIds
()¶ Returns: The value of sub_ids on this message.
-
Message.
getTimestamp
()¶ Returns: The value of timestamp on this message.
-
Message.
getTopNRecordsReturned
()¶ Returns: The value of top_n on this message.
-
Message.
getTopic
()¶ Returns: The value of topic on this message.
-
Message.
getTopicMatches
()¶ Returns: The value of topic_matches on this message.
-
Message.
getUserId
()¶ Returns: The value of user_id on this message.
-
Message.
get_ack_type
()¶ Returns: The value of ack_type on this message.
-
Message.
get_batch_size
()¶ Returns: The value of batch_size on this message.
-
Message.
get_bookmark
()¶ 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
()¶ Returns: The value of client_name on this message.
-
Message.
get_command
()¶ Returns: The value of command on this message.
-
Message.
get_command_id
()¶ Returns: The value of command_id on this message.
-
Message.
get_correlation_id
()¶ Returns: The value of correlation_id on this message.
-
Message.
get_data
()¶ 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
()¶ Returns: The value of expiration on this message.
-
Message.
get_filter
()¶ Returns: The value of filter on this message.
-
Message.
get_group_seq_no
()¶ Returns: The value of group_seq_no on this message.
-
Message.
get_lease_period
()¶ Returns: The value of lease_period on this message.
-
Message.
get_matches
()¶ Returns: The value of matches on this message.
-
Message.
get_message_size
()¶ Returns: The value of message_size on this message.
-
Message.
get_message_type
()¶ Returns: The value of message_type on this message.
-
Message.
get_options
()¶ Returns: The value of options on this message.
-
Message.
get_password
()¶ Returns: The value of password on this message.
-
Message.
get_query_id
()¶ Returns: The value of query_id on this message.
-
Message.
get_reason
()¶ Returns: The value of reason on this message.
-
Message.
get_records_inserted
()¶ Returns: The value of records_inserted on this message.
-
Message.
get_records_returned
()¶ Returns: The value of records_returned on this message.
-
Message.
get_records_updated
()¶ Returns: The value of records_updated on this message.
-
Message.
get_sequence
()¶ Returns: The value of sequence on this message.
-
Message.
get_sow_deleted
()¶ Returns: The value of sow_deleted on this message.
-
Message.
get_sow_key
()¶ Returns: The value of sow_key on this message.
-
Message.
get_sow_keys
()¶ Returns: The value of sow_keys on this message.
-
Message.
get_status
()¶ Returns: The value of status on this message.
-
Message.
get_sub_id
()¶ Returns: The value of sub_id on this message.
-
Message.
get_sub_ids
()¶ Returns: The value of sub_ids on this message.
-
Message.
get_timestamp
()¶ Returns: The value of timestamp on this message.
-
Message.
get_top_n
()¶ Returns: The value of top_n on this message.
-
Message.
get_topic
()¶ Returns: The value of topic on this message.
-
Message.
get_topic_matches
()¶ Returns: The value of topic_matches on this message.
-
Message.
get_user_id
()¶ Returns: The value of user_id on this message.
-
Message.
reset
()¶ Resets the contents of this message.
-
Message.
setAckType
(value)¶ Sets the value of ack_type on this message.
Parameters: value – The new value for ack_type.
-
Message.
setBatchSize
(value)¶ Sets the value of batch_size on this message.
Parameters: value – The new value for batch_size.
-
Message.
setBookmark
(value)¶ Sets the value of bookmark on this message.
Parameters: value – The new value for bookmark.
-
Message.
setClientName
(value)¶ Sets the value of client_name on this message.
Parameters: value – The new value for client_name.
-
Message.
setCommand
(value)¶ Sets the value of command on this message.
Parameters: value – The new value for command.
-
Message.
setCommandId
(value)¶ Sets the value of command_id on this message.
Parameters: value – The new value for command_id.
-
Message.
setCorrelationId
(value)¶ Sets the value of correlation_id on this message.
Parameters: value – The new value for correlation_id.
-
Message.
setData
(value)¶ Sets the value of data on this message.
Parameters: value – The new value for data.
-
Message.
setExpiration
(value)¶ Sets the value of expiration on this message.
Parameters: value – The new value for expiration.
-
Message.
setFilter
(value)¶ Sets the value of filter on this message.
Parameters: value – The new value for filter.
-
Message.
setGroupSequenceNumber
(value)¶ Sets the value of group_seq_no on this message.
Parameters: value – The new value for group_seq_no.
-
Message.
setLeasePeriod
(value)¶ Sets the value of lease_period on this message.
Parameters: value – The new value for lease_period.
-
Message.
setMatches
(value)¶ Sets the value of matches on this message.
Parameters: value – The new value for matches.
-
Message.
setMessageLength
(value)¶ Sets the value of message_size on this message.
Parameters: value – The new value for message_size.
-
Message.
setMessageType
(value)¶ Sets the value of message_type on this message.
Parameters: value – The new value for message_type.
-
Message.
setOptions
(value)¶ Sets the value of options on this message.
Parameters: value – The new value for options.
-
Message.
setPassword
(value)¶ Sets the value of password on this message.
Parameters: value – The new value for password.
-
Message.
setQueryID
(value)¶ Sets the value of query_id on this message.
Parameters: value – The new value for query_id.
-
Message.
setReason
(value)¶ Sets the value of reason on this message.
Parameters: value – The new value for reason.
-
Message.
setRecordsInserted
(value)¶ Sets the value of records_inserted on this message.
Parameters: value – The new value for records_inserted.
-
Message.
setRecordsReturned
(value)¶ Sets the value of records_returned on this message.
Parameters: value – The new value for records_returned.
-
Message.
setRecordsUpdated
(value)¶ Sets the value of records_updated on this message.
Parameters: value – The new value for records_updated.
-
Message.
setSequence
(value)¶ Sets the value of sequence on this message.
Parameters: value – The new value for sequence.
-
Message.
setSowDelete
(value)¶ Sets the value of sow_deleted on this message.
Parameters: value – The new value for sow_deleted.
-
Message.
setSowKey
(value)¶ Sets the value of sow_key on this message.
Parameters: value – The new value for sow_key.
-
Message.
setSowKeys
(value)¶ Sets the value of sow_keys on this message.
Parameters: value – The new value for sow_keys.
-
Message.
setStatus
(value)¶ Sets the value of status on this message.
Parameters: value – The new value for status.
-
Message.
setSubscriptionId
(value)¶ Sets the value of sub_id on this message.
Parameters: value – The new value for sub_id.
-
Message.
setSubscriptionIds
(value)¶ Sets the value of sub_ids on this message.
Parameters: value – The new value for sub_ids.
-
Message.
setTimestamp
(value)¶ Sets the value of timestamp on this message.
Parameters: value – The new value for timestamp.
-
Message.
setTopNRecordsReturned
(value)¶ Sets the value of top_n on this message.
Parameters: value – The new value for top_n.
-
Message.
setTopic
(value)¶ Sets the value of topic on this message.
Parameters: value – The new value for topic.
-
Message.
setTopicMatches
(value)¶ Sets the value of topic_matches on this message.
Parameters: value – The new value for topic_matches.
-
Message.
setUserId
(value)¶ Sets the value of user_id on this message.
Parameters: value – The new value for user_id.
-
Message.
set_ack_type
(value)¶ Sets the value of ack_type on this message.
Parameters: value – The new value for ack_type.
-
Message.
set_batch_size
(value)¶ Sets the value of batch_size on this message.
Parameters: value – The new value for batch_size.
-
Message.
set_bookmark
(value)¶ Sets the value of bookmark on this message.
Parameters: value – The new value for bookmark.
-
Message.
set_client_name
(value)¶ Sets the value of client_name on this message.
Parameters: value – The new value for client_name.
-
Message.
set_command
(value)¶ Sets the value of command on this message.
Parameters: value – The new value for command.
-
Message.
set_command_id
(value)¶ Sets the value of command_id on this message.
Parameters: value – The new value for command_id.
-
Message.
set_correlation_id
(value)¶ Sets the value of correlation_id on this message.
Parameters: value – The new value for correlation_id.
-
Message.
set_data
(value)¶ Sets the value of data on this message.
Parameters: value – The new value for data.
-
Message.
set_expiration
(value)¶ Sets the value of expiration on this message.
Parameters: value – The new value for expiration.
-
Message.
set_filter
(value)¶ Sets the value of filter on this message.
Parameters: value – The new value for filter.
-
Message.
set_group_seq_no
(value)¶ Sets the value of group_seq_no on this message.
Parameters: value – The new value for group_seq_no.
-
Message.
set_lease_period
(value)¶ Sets the value of lease_period on this message.
Parameters: value – The new value for lease_period.
-
Message.
set_matches
(value)¶ Sets the value of matches on this message.
Parameters: value – The new value for matches.
-
Message.
set_message_size
(value)¶ Sets the value of message_size on this message.
Parameters: value – The new value for message_size.
-
Message.
set_message_type
(value)¶ Sets the value of message_type on this message.
Parameters: value – The new value for message_type.
-
Message.
set_options
(value)¶ Sets the value of options on this message.
Parameters: value – The new value for options.
-
Message.
set_password
(value)¶ Sets the value of password on this message.
Parameters: value – The new value for password.
-
Message.
set_query_id
(value)¶ Sets the value of query_id on this message.
Parameters: value – The new value for query_id.
-
Message.
set_reason
(value)¶ Sets the value of reason on this message.
Parameters: value – The new value for reason.
-
Message.
set_records_inserted
(value)¶ Sets the value of records_inserted on this message.
Parameters: value – The new value for records_inserted.
-
Message.
set_records_returned
(value)¶ Sets the value of records_returned on this message.
Parameters: value – The new value for records_returned.
-
Message.
set_records_updated
(value)¶ Sets the value of records_updated on this message.
Parameters: value – The new value for records_updated.
-
Message.
set_sequence
(value)¶ Sets the value of sequence on this message.
Parameters: value – The new value for sequence.
-
Message.
set_sow_deleted
(value)¶ Sets the value of sow_deleted on this message.
Parameters: value – The new value for sow_deleted.
-
Message.
set_sow_key
(value)¶ Sets the value of sow_key on this message.
Parameters: value – The new value for sow_key.
-
Message.
set_sow_keys
(value)¶ Sets the value of sow_keys on this message.
Parameters: value – The new value for sow_keys.
-
Message.
set_status
(value)¶ Sets the value of status on this message.
Parameters: value – The new value for status.
-
Message.
set_sub_id
(value)¶ Sets the value of sub_id on this message.
Parameters: value – The new value for sub_id.
-
Message.
set_sub_ids
(value)¶ Sets the value of sub_ids on this message.
Parameters: value – The new value for sub_ids.
-
Message.
set_timestamp
(value)¶ Sets the value of timestamp on this message.
Parameters: value – The new value for timestamp.
-
Message.
set_top_n
(value)¶ Sets the value of top_n on this message.
Parameters: value – The new value for top_n.
-
Message.
set_topic
(value)¶ Sets the value of topic on this message.
Parameters: value – The new value for topic.
-
Message.
set_topic_matches
(value)¶ Sets the value of topic_matches on this message.
Parameters: value – The new value for topic_matches.
-
Message.
set_user_id
(value)¶ Sets the value of user_id on this message.
Parameters: value – The new value for user_id.
-
class
-
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.
- :param maxDepth The maximum number of messages that are buffered in this stream
- before pushback on the network connection.
-
next
¶
-
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
-
class
AMPS.
NVFIXBuilder
¶ Bases:
object
Convenience class for easily creating NVFIX strings. Constructor arguments:
Parameters: delimiter – The delimiter to use between NFVIX fields. Defaults to \x01 if no delimiter is provided. -
append
(tag, value, (optional)offset, (optional)length)¶ Appends tag=value to self.
Parameters: - tag (int) – The tag to use.
- value (str) – The value for the given tag.
- offset (int) – Optional. The offset into value at which the value actually starts.
- length – Optional. The length of the actual value within value. 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
¶ Bases:
object
Convenience class for easily processing NVFIX strings. Constructor arguments:
Parameters: separator – The delimiter to expect between NFVIX 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.
-
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.
-
get_unpersisted_count
()¶ Returns the number of messages published which have not been ACK’ed by the server.
-
set_resize_handler
()¶ Sets the object to call when the store needs to resize.
-
truncate_on_close
()¶ Sets if the PublishStore should truncate the file to initial capacity when it closes if it is empty.
-
-
class
AMPS.
Reason
¶ Bases:
object
AMPS Reason Object
-
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.
-
no_persisted_acks
(subid)¶ Flag the subscription as being on an older server without persisted acks. No persisted acks will be sent for any bookmarks.
-
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.
Store
¶ Bases:
object
AMPS Store Object
-
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.
-
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 maintennce 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 maintennce 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_init
()¶ Initializes SSL support in the AMPS module.
Parameters: dllpath – The path to the OpenSSL DLL or shared library to use for SSL functionality.
-
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).