amps-python-client 5.3.4.1__zip → 5.3.4.3__zip

amps-python-client-5.3.4.3/src/cmessagehandler.cpp

@@ -0,0 +1,161 @@
+////////////////////////////////////////////////////////////////////////////
+//
+// Copyright (c) 2010-2024 60East Technologies Inc., All Rights Reserved.
+//
+// This computer software is owned by 60East Technologies Inc. and is
+// protected by U.S. copyright laws and other laws and by international
+// treaties.  This computer software is furnished by 60East Technologies
+// Inc. pursuant to a written license agreement and may be used, copied,
+// transmitted, and stored only in accordance with the terms of such
+// license agreement and with the inclusion of the above copyright notice.
+// This computer software or any other copies thereof may not be provided
+// or otherwise made available to any other person.
+//
+// U.S. Government Restricted Rights.  This computer software: (a) was
+// developed at private expense and is in all respects the proprietary
+// information of 60East Technologies Inc.; (b) was not developed with
+// government funds; (c) is a trade secret of 60East Technologies Inc.
+// for all purposes of the Freedom of Information Act; and (d) is a
+// commercial item and thus, pursuant to Section 12.212 of the Federal
+// Acquisition Regulations (FAR) and DFAR Supplement Section 227.7202,
+// Government's use, duplication or disclosure of the computer software
+// is subject to the restrictions set forth by 60East Technologies Inc..
+//
+////////////////////////////////////////////////////////////////////////////
+
+#define PY_SSIZE_T_CLEAN 1
+#include <Python.h>
+#include <amps/ampsplusplus.hpp>
+#include <ampspy_types.hpp>
+#include <ampspy_defs.hpp>
+
+using namespace AMPS;
+namespace ampspy
+{
+  namespace cmessagehandler
+  {
+
+    ampspy::ampspy_type_object cmessagehandler_type;
+
+    static PyObject* toPySizeT(PyObject* object)
+    {
+      PyObject* ctypesModule = PyImport_ImportModule("ctypes");
+      PyObject* ctypesDict = PyModule_GetDict(ctypesModule);
+      // Get cast function
+      PyObject* castFunction = PyDict_GetItemString(ctypesDict, "cast");
+      // Get c_void_p constant
+      PyObject* c_void_p = PyDict_GetItemString(ctypesDict, "c_void_p");
+
+
+      PyObject* result = PyObject_CallFunctionObjArgs(castFunction, object, c_void_p);
+      PyObject* value = PyObject_GetAttrString(result, "value");
+      Py_XDECREF(result);
+      Py_XDECREF(c_void_p);
+      Py_XDECREF(castFunction);
+      Py_DECREF(ctypesDict);
+      Py_DECREF(ctypesModule);
+      return value;
+    }
+
+    static void* toCPtr(PyObject* pySizeT)
+    {
+      if (PyInt_Check(pySizeT))
+      {
+        return (void*)PyInt_AsSsize_t(pySizeT);
+      }
+      return NULL;
+    }
+//    def __init__(self, name):
+    static int _ctor(obj* self, PyObject* args, PyObject* kwds)
+    {
+      PyObject* function = NULL;
+      PyObject* userdata = NULL;
+      if (!PyArg_ParseTuple(args, "O|O", &function, &userdata) || !function)
+      {
+        return -1;
+      }
+
+      // Use the ctypes module to establish the real function pointer and any userdata.
+      self->function = toPySizeT(function);
+      self->userdata = toPySizeT(userdata);
+
+      Py_XINCREF(self->function);
+      Py_XINCREF(self->userdata);
+      return 0;
+    }
+
+    AMPSDLL AMPS::MessageHandler getMessageHandler(PyObject* pySelf)
+    {
+      obj* self = (obj*)pySelf;
+
+      // now extract the void ptr
+      AMPS::MessageHandlerFunc pFunction = (AMPS::MessageHandlerFunc)toCPtr(
+                                             self->function);
+      void* pUserdata = (void*)toCPtr(self->userdata);
+      return AMPS::MessageHandler(pFunction, pUserdata);
+    }
+
+    static void _dtor(obj* self)
+    {
+      Py_XDECREF(self->function);
+      Py_XDECREF(self->userdata);
+      shims::free(self);
+    }
+
+
+    static PyObject* call(obj* self, PyObject* args, PyObject* kw)
+    {
+      message::obj* myMessage;
+      if (!PyArg_ParseTuple(args, "O!", message::message_type.pPyObject(),
+                            ( (PyObject**)&myMessage) ))
+      {
+        return NULL;
+      }
+      getMessageHandler((PyObject*)self).invoke(*(myMessage->pMessage));
+
+      NONE;
+    }
+    static const char* cmessage_doc = R"docstring(
+    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.
+    )docstring";
+
+    bool isCHandler(PyObject* obj)
+    {
+      return cmessagehandler_type.isInstanceOf(obj);
+    }
+
+    void add_types(PyObject* module_)
+    {
+      cmessagehandler_type.setName("AMPS.CMessageHandler")
+      .setBasicSize(sizeof(obj))
+      .setBaseType()
+      .setConstructorFunction(&_ctor)
+      .setDestructorFunction(&_dtor)
+      .setCallFunction(&call)
+      .setDoc(cmessage_doc)
+      .notCopyable()
+      .createType()
+      .registerType("CMessageHandler", module_);
+    }
+
+  } // namespace cmessagehandler
+} // namespace ampspy

amps-python-client-5.3.4.3/src/command.cpp

@@ -0,0 +1,164 @@
+////////////////////////////////////////////////////////////////////////////
+//
+// Copyright (c) 2010-2024 60East Technologies Inc., All Rights Reserved.
+//
+// This computer software is owned by 60East Technologies Inc. and is
+// protected by U.S. copyright laws and other laws and by international
+// treaties.  This computer software is furnished by 60East Technologies
+// Inc. pursuant to a written license agreement and may be used, copied,
+// transmitted, and stored only in accordance with the terms of such
+// license agreement and with the inclusion of the above copyright notice.
+// This computer software or any other copies thereof may not be provided
+// or otherwise made available to any other person.
+//
+// U.S. Government Restricted Rights.  This computer software: (a) was
+// developed at private expense and is in all respects the proprietary
+// information of 60East Technologies Inc.; (b) was not developed with
+// government funds; (c) is a trade secret of 60East Technologies Inc.
+// for all purposes of the Freedom of Information Act; and (d) is a
+// commercial item and thus, pursuant to Section 12.212 of the Federal
+// Acquisition Regulations (FAR) and DFAR Supplement Section 227.7202,
+// Government's use, duplication or disclosure of the computer software
+// is subject to the restrictions set forth by 60East Technologies Inc..
+//
+////////////////////////////////////////////////////////////////////////////
+
+#define PY_SSIZE_T_CLEAN 1
+#include <Python.h>
+#include <amps/ampsplusplus.hpp>
+#include <ampspy_types.hpp>
+#include <ampspy_defs.hpp>
+#include <set>
+#include <sstream>
+#include "command_docs.h"
+#include <deque>
+
+using namespace AMPS;
+namespace ampspy
+{
+  namespace command
+  {
+
+    AMPSDLL ampspy::ampspy_type_object command_type;
+
+//    def __init__(self, name):
+    static int _ctor(obj* self, PyObject* args, PyObject* kwds)
+    {
+      // placement new this object right here; we haven't been properly c++ constructed yet.
+      char* command = NULL;
+      if (!PyArg_ParseTuple(args, "s", &command))
+      {
+        return -1;
+      }
+      new (&(self->command)) AMPS::Command(command);
+      return 0;
+    }
+
+    static void _dtor(obj* self)
+    {
+      self->command.~Command();
+      shims::free(self);
+    }
+
+    static PyObject* get_sequence(obj* self)
+    {
+      CALL_RETURN_UINT64_T(self->command.getSequence());
+    }
+
+    static PyObject* get_ack_type(obj* self)
+    {
+      CALL_RETURN_STRING(self->command.getAckType());
+    }
+
+    static PyObject* get_ack_type_enum(obj* self)
+    {
+      CALL_RETURN_SIZE_T((size_t)(self->command.getAckTypeEnum()));
+    }
+
+#define COMMAND_UINT_SETTER(pyname,cppname) \
+  static obj* pyname(obj* self, PyObject *args) \
+  { \
+    unsigned value; \
+    if(!PyArg_ParseTuple(args, "I", &value)) \
+    { \
+      return NULL; \
+    } \
+    self->command.cppname (value); \
+    Py_INCREF(self);\
+    return self; \
+  }
+
+#define COMMAND_STRING_SETTER(pyname,cppname) \
+  static obj* pyname(obj* self, PyObject *args) \
+  { \
+    char *value = NULL; \
+    Py_ssize_t len = 0;\
+    if(!PyArg_ParseTuple(args, "s#", &value,&len)) \
+    { \
+      return NULL; \
+    } \
+    self->command.cppname (std::string(value,len)); \
+    Py_INCREF(self);\
+    return self; \
+  }
+
+    COMMAND_STRING_SETTER(reset, reset)
+    COMMAND_STRING_SETTER(set_sow_key, setSowKey)
+    COMMAND_STRING_SETTER(set_sow_keys, setSowKeys)
+    COMMAND_STRING_SETTER(set_command_id, setCommandId)
+    COMMAND_STRING_SETTER(set_correlation_id, setCorrelationId)
+    COMMAND_STRING_SETTER(set_topic, setTopic)
+    COMMAND_STRING_SETTER(set_filter, setFilter)
+    COMMAND_STRING_SETTER(set_order_by, setOrderBy)
+    COMMAND_STRING_SETTER(set_sub_id, setSubId)
+    COMMAND_STRING_SETTER(set_query_id, setQueryId)
+    COMMAND_STRING_SETTER(set_bookmark, setBookmark)
+    COMMAND_STRING_SETTER(set_options, setOptions)
+    COMMAND_STRING_SETTER(set_data, setData)
+    COMMAND_STRING_SETTER(add_ack_type, addAckType)
+    COMMAND_STRING_SETTER(set_ack_type, setAckType)
+    COMMAND_UINT_SETTER(set_ack_type_enum, setAckType)
+    COMMAND_UINT_SETTER(set_timeout, setTimeout)
+    COMMAND_UINT_SETTER(set_top_n, setTopN)
+    COMMAND_UINT_SETTER(set_batch_size, setBatchSize)
+    COMMAND_UINT_SETTER(set_expiration, setExpiration)
+    COMMAND_UINT_SETTER(set_sequence, setSequence)
+
+    void add_types(PyObject* module_)
+    {
+      command_type.setName("AMPS.Command")
+      .setBasicSize(sizeof(obj))
+      .setDestructorFunction(&_dtor)
+      .setConstructorFunction(&_ctor)
+      .setDoc(command_class_doc)
+      .notCopyable()
+      .addMethod("reset", reset, reset_doc)
+      .addMethod("add_ack_type", add_ack_type, add_ack_type_doc)
+      .addMethod("set_ack_type", set_ack_type, set_ack_type_doc)
+      .addMethod("set_ack_type_enum", set_ack_type_enum, set_ack_type_enum_doc)
+      .addMethod("get_ack_type", get_ack_type, get_ack_type_doc)
+      .addMethod("get_ack_type_enum", get_ack_type_enum, get_ack_type_enum_doc)
+      .addMethod("set_sow_key", set_sow_key, set_sow_key_doc)
+      .addMethod("set_sow_keys", set_sow_keys, set_sow_keys_doc)
+      .addMethod("set_command_id", set_command_id, set_command_id_doc)
+      .addMethod("set_correlation_id", set_correlation_id, set_correlation_id_doc)
+      .addMethod("set_topic", set_topic, set_topic_doc)
+      .addMethod("set_filter", set_filter, set_filter_doc)
+      .addMethod("set_order_by", set_order_by, set_order_by_doc)
+      .addMethod("set_sub_id", set_sub_id, set_sub_id_doc)
+      .addMethod("set_query_id", set_query_id, set_query_id_doc)
+      .addMethod("set_bookmark", set_bookmark, set_bookmark_doc)
+      .addMethod("set_options", set_options, set_options_doc)
+      .addMethod("set_data", set_data, set_data_doc)
+      .addMethod("set_timeout", set_timeout, set_timeout_doc)
+      .addMethod("set_top_n", set_top_n, set_top_n_doc)
+      .addMethod("set_batch_size", set_batch_size, set_batch_size_doc)
+      .addMethod("set_expiration", set_expiration, set_expiration_doc)
+      .addMethod("set_sequence", set_sequence, set_sequence_doc)
+      .addMethod("get_sequence", get_sequence, get_sequence_doc)
+      .createType().registerType("Command", module_);
+    }
+
+  }
+
+}

amps-python-client-5.3.4.3/src/command_docs.h

@@ -0,0 +1,274 @@
+////////////////////////////////////////////////////////////////////////////
+//
+// Copyright (c) 2010-2024 60East Technologies Inc., All Rights Reserved.
+//
+// This computer software is owned by 60East Technologies Inc. and is
+// protected by U.S. copyright laws and other laws and by international
+// treaties.  This computer software is furnished by 60East Technologies
+// Inc. pursuant to a written license agreement and may be used, copied,
+// transmitted, and stored only in accordance with the terms of such
+// license agreement and with the inclusion of the above copyright notice.
+// This computer software or any other copies thereof may not be provided
+// or otherwise made available to any other person.
+//
+// U.S. Government Restricted Rights.  This computer software: (a) was
+// developed at private expense and is in all respects the proprietary
+// information of 60East Technologies Inc.; (b) was not developed with
+// government funds; (c) is a trade secret of 60East Technologies Inc.
+// for all purposes of the Freedom of Information Act; and (d) is a
+// commercial item and thus, pursuant to Section 12.212 of the Federal
+// Acquisition Regulations (FAR) and DFAR Supplement Section 227.7202,
+// Government's use, duplication or disclosure of the computer software
+// is subject to the restrictions set forth by 60East Technologies Inc..
+//
+////////////////////////////////////////////////////////////////////////////
+
+
+#define COMMAND_SETTER_BOILERPLATE "\n\nNot 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.\n\n:param value: The new value to set for the header.\n\n:returns: This command."
+
+
+static const char* command_class_doc = R"docstring(Command(command_name)
+``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 :class:`AMPS.Message` class.
+
+The :class:`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
+:func:`AMPS.Client.execute_async()` to process messages asynchronously,
+or :func:`AMPS.Client.execute()` to process messages synchronously.
+
+**Constructor Arguments:**
+
+:param command_name: The name of the command to send to the server. 
+                     For example, ``sow``, ``sow_and_subscribe`` or ``publish``.
+)docstring";
+
+
+static const char* reset_doc = R"docstring(reset(command)
+Resets this command with a new Command type and re-initializes all other fields.
+
+:param command: A string indicating the AMPS command.
+)docstring";
+
+
+static const char* set_sow_key_doc = R"docstring(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.
+)docstring"
+COMMAND_SETTER_BOILERPLATE;
+
+
+static const char* set_sow_keys_doc = R"docstring(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 :meth:`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.
+)docstring"
+COMMAND_SETTER_BOILERPLATE;
+
+
+static const char* set_command_id_doc = R"docstring(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).
+
+:param value: The new value for this header.
+
+:returns: This command.
+)docstring";
+
+
+static const char* set_topic_doc = R"docstring(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.
+)docstring"
+COMMAND_SETTER_BOILERPLATE;
+
+
+static const char* set_filter_doc = R"docstring(set_filter(value)
+Sets the value of the filter header.
+)docstring"
+COMMAND_SETTER_BOILERPLATE;
+
+
+static const char* set_order_by_doc = R"docstring(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``).
+)docstring"
+COMMAND_SETTER_BOILERPLATE;;
+
+
+static const char* set_sub_id_doc = R"docstring(set_sub_id(value)
+Sets the subscription ID of self.
+)docstring"
+COMMAND_SETTER_BOILERPLATE;;
+
+
+static const char* set_query_id_doc = R"docstring(set_query_id(value)
+Sets the query ID of self.
+)docstring"
+COMMAND_SETTER_BOILERPLATE;
+
+
+static const char* set_bookmark_doc = R"docstring(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.
+)docstring"
+COMMAND_SETTER_BOILERPLATE;
+
+
+static const char* set_correlation_id_doc = R"docstring(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.
+)docstring"
+COMMAND_SETTER_BOILERPLATE;
+
+
+static const char* set_options_doc = R"docstring(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
+:class:`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.
+
+:param value: The value to set.
+
+:returns: This command.
+)docstring";
+
+
+static const char* add_ack_type_doc = R"docstring(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.
+
+:param value: The ack type to add.
+
+:returns: This command.
+)docstring";
+
+
+static const char* set_ack_type_doc = R"docstring(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.
+
+:param value: The ack type to set.
+
+:returns: This command.
+)docstring";
+
+
+static const char* set_ack_type_enum_doc = R"docstring(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.
+
+:param value: The ack type enum to set.
+
+:returns: This command.
+)docstring";
+
+
+static const char* get_ack_type_doc = R"docstring(get_ack_type()
+Gets the ack type for this command.
+
+:returns: The ack type as a string.
+)docstring";
+
+
+static const char* get_ack_type_enum_doc = R"docstring(get_ack_type_enum()
+Gets the ack type enum for this command.
+
+:returns: The ack type as an enum.
+)docstring";
+
+
+static const char* set_data_doc = R"docstring(set_data(value)
+Sets the data for this command. This is used for ``publish`` commands and for ``sow_delete`` commands.
+)docstring"
+COMMAND_SETTER_BOILERPLATE;
+
+
+static const char* set_timeout_doc = R"docstring(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.
+
+:param value: The value to set.
+
+:returns: This command.
+)docstring";
+
+
+static const char* set_top_n_doc = R"docstring(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.
+)docstring"
+COMMAND_SETTER_BOILERPLATE;
+
+
+static const char* set_batch_size_doc = R"docstring(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.
+)docstring"
+COMMAND_SETTER_BOILERPLATE;
+
+
+static const char* set_expiration_doc = R"docstring(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.
+)docstring"
+COMMAND_SETTER_BOILERPLATE;
+
+
+static const char* set_sequence_doc = R"docstring(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.
+)docstring"
+COMMAND_SETTER_BOILERPLATE;
+
+
+static const char* get_sequence_doc = R"docstring(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.
+)docstring";
+