Improve class documentation for xapp writers

Also bump RMR version used in test from 4.0.5 to 4.1.2

Signed-off-by: Lott, Christopher (cl778h) <cl778h@att.com>
Change-Id: I6179a12d460c609bde9af6b41f58abfae96ad0ab

diff --git a/.gitreview b/.gitreview
index f5eadb0..cebbb53 100644 (file)
--- a/.gitreview
+++ b/.gitreview
@@ -3,3 +3,4 @@ host=gerrit.o-ran-sc.org
 port=29418
 project=ric-plt/xapp-frame-py
 defaultbranch=master
 port=29418
 project=ric-plt/xapp-frame-py
 defaultbranch=master

+defaultremote=origin

diff --git a/Dockerfile-Unit-Test b/Dockerfile-Unit-Test
index 2cc7e7a..ee754ce 100644 (file)
--- a/Dockerfile-Unit-Test
+++ b/Dockerfile-Unit-Test
@@ -20,7 +20,7 @@ FROM python:3.8-alpine
 RUN apk update && apk add gcc musl-dev
 
 # copy rmr libraries from builder image in lieu of an Alpine package
 RUN apk update && apk add gcc musl-dev
 
 # copy rmr libraries from builder image in lieu of an Alpine package

-COPY --from=nexus3.o-ran-sc.org:10002/o-ran-sc/bldr-alpine3-rmr:4.0.5 /usr/local/lib64/librmr* /usr/local/lib64/
+COPY --from=nexus3.o-ran-sc.org:10002/o-ran-sc/bldr-alpine3-rmr:4.1.2 /usr/local/lib64/librmr* /usr/local/lib64/

 
 # Upgrade pip, install tox
 RUN pip install --upgrade pip && pip install tox
 
 # Upgrade pip, install tox
 RUN pip install --upgrade pip && pip install tox

diff --git a/docs/installation-guide.rst b/docs/installation-guide.rst
old mode 100755 (executable)
new mode 100644 (file)

diff --git a/ricxappframe/xapp_frame.py b/ricxappframe/xapp_frame.py
index 994e52b..0d37f28 100644 (file)
--- a/ricxappframe/xapp_frame.py
+++ b/ricxappframe/xapp_frame.py
@@ -15,8 +15,8 @@
 #   limitations under the License.
 # ==================================================================================
 """
 #   limitations under the License.
 # ==================================================================================
 """

-This framework for Python Xapps provides classes that Xapp writers should
-instantiate and/or subclass depending on their needs.
+This framework for Python Xapps provides classes that Xapp writers
+should instantiate and/or subclass depending on their needs.

 """
 
 import json
 """
 
 import json


@@ -36,38 +36,39 @@ RIC_HEALTH_CHECK_RESP = 101
 # environment variable with path to configuration file
 CONFIG_FILE_ENV = "CONFIG_FILE"
 
 # environment variable with path to configuration file
 CONFIG_FILE_ENV = "CONFIG_FILE"
 

-# Private base class; not for direct client use
-

 
 class _BaseXapp:
     """
 
 class _BaseXapp:
     """

-    This base class initializes RMR by starting a thread that checks for
-    incoming messages, and provisions an SDL object.
-
-    If environment variable CONFIG_FILE_ENV is defined, and that value is a
-    path to an existing file, a watcher is defined to monitor modifications
-    (writes) to that file using the Linux kernel's inotify feature, and the
-    configuration-change handler function is invoked.  The watcher can be
-    polled by calling method config_check().
+    This class initializes RMR, starts a thread that checks for incoming
+    messages, provisions an SDL object and optionally creates a
+    config-file watcher.  This private base class should not be
+    instantiated by clients directly, but it defines many public methods
+    that may be used by clients.
+
+    If environment variable CONFIG_FILE is defined, and that variable
+    contains a path to an existing file, a watcher is defined to monitor
+    modifications (writes) to that file using the Linux kernel's inotify
+    feature. The watcher must be polled by calling method
+    config_check().

 
     Parameters
     ----------
 
     Parameters
     ----------

-    rmr_port: int
-        port to listen on
-
-    rmr_wait_for_ready: bool (optional)
-        If this is True, then init waits until rmr is ready to send, which
-        includes having a valid routing file. This can be set to
-        False if the client only wants to *receive only*.
-
-    use_fake_sdl: bool (optional)
-        if this is True, it uses the dbaas "fake dict backend" instead
-        of Redis or other backends. Set this to true when developing
-        an xapp or during unit testing to eliminate the need for DBAAS.
-
-    post_init: function (optional)
-        Runs this user-provided function after the base xapp is
-        initialized; its signature should be post_init(self)
+    rmr_port: int (optional, default is 4562)
+        Port on which the RMR library listens for incoming messages.
+
+    rmr_wait_for_ready: bool (optional, default is True)
+        If this is True, then init waits until RMR is ready to send,
+        which includes having a valid routing file. This can be set
+        to False if the client wants to *receive only*.
+
+    use_fake_sdl: bool (optional, default is False)
+        if this is True, it uses the DBaaS "fake dict backend" instead
+        of Redis or other backends. Set this to True when developing
+        an xapp or during unit testing to eliminate the need for DBaaS.
+
+    post_init: function (optional, default is None)
+        Runs this user-provided function at the end of the init method;
+        its signature should be post_init(self)

     """
 
     def __init__(self, rmr_port=4562, rmr_wait_for_ready=True, use_fake_sdl=False, post_init=None):
     """
 
     def __init__(self, rmr_port=4562, rmr_wait_for_ready=True, use_fake_sdl=False, post_init=None):


@@ -191,14 +192,14 @@ class _BaseXapp:
 
     # Convenience (pass-thru) function for invoking SDL.
 
 
     # Convenience (pass-thru) function for invoking SDL.
 

-    def sdl_set(self, ns, key, value, usemsgpack=True):
+    def sdl_set(self, namespace, key, value, usemsgpack=True):

         """
         Stores a key-value pair to SDL, optionally serializing the value
         to bytes using msgpack.
 
         Parameters
         ----------
         """
         Stores a key-value pair to SDL, optionally serializing the value
         to bytes using msgpack.
 
         Parameters
         ----------

-        ns: string
+        namespace: string

             SDL namespace
         key: string
             SDL key
             SDL namespace
         key: string
             SDL key


@@ -212,16 +213,16 @@ class _BaseXapp:
             that is serializable by msgpack.
             If usemsgpack is False, the value must be bytes.
         """
             that is serializable by msgpack.
             If usemsgpack is False, the value must be bytes.
         """

-        self._sdl.set(ns, key, value, usemsgpack)
+        self._sdl.set(namespace, key, value, usemsgpack)

 
 

-    def sdl_get(self, ns, key, usemsgpack=True):
+    def sdl_get(self, namespace, key, usemsgpack=True):

         """
         Gets the value for the specified namespace and key from SDL,
         optionally deserializing stored bytes using msgpack.
 
         Parameters
         ----------
         """
         Gets the value for the specified namespace and key from SDL,
         optionally deserializing stored bytes using msgpack.
 
         Parameters
         ----------

-        ns: string
+        namespace: string

             SDL namespace
         key: string
             SDL key
             SDL namespace
         key: string
             SDL key


@@ -237,9 +238,9 @@ class _BaseXapp:
             See the usemsgpack parameter for an explanation of the returned value type.
             Answers None if the key is not found.
         """
             See the usemsgpack parameter for an explanation of the returned value type.
             Answers None if the key is not found.
         """

-        return self._sdl.get(ns, key, usemsgpack)
+        return self._sdl.get(namespace, key, usemsgpack)

 
 

-    def sdl_find_and_get(self, ns, prefix, usemsgpack=True):
+    def sdl_find_and_get(self, namespace, prefix, usemsgpack=True):

         """
         Gets all key-value pairs in the specified namespace
         with keys that start with the specified prefix,
         """
         Gets all key-value pairs in the specified namespace
         with keys that start with the specified prefix,


@@ -247,7 +248,7 @@ class _BaseXapp:
 
         Parameters
         ----------
 
         Parameters
         ----------

-        ns: string
+        nnamespaces: string

            SDL namespace
         prefix: string
             the key prefix
            SDL namespace
         prefix: string
             the key prefix


@@ -265,20 +266,20 @@ class _BaseXapp:
             but is either a Python object or raw bytes as discussed above.
             Answers an empty dictionary if no keys matched the prefix.
         """
             but is either a Python object or raw bytes as discussed above.
             Answers an empty dictionary if no keys matched the prefix.
         """

-        return self._sdl.find_and_get(ns, prefix, usemsgpack)
+        return self._sdl.find_and_get(namespace, prefix, usemsgpack)

 
 

-    def sdl_delete(self, ns, key):
+    def sdl_delete(self, namespace, key):

         """
         Deletes the key-value pair with the specified key in the specified namespace.
 
         Parameters
         ----------
         """
         Deletes the key-value pair with the specified key in the specified namespace.
 
         Parameters
         ----------

-        ns: string
+        namespace: string

            SDL namespace
         key: string
             SDL key
         """
            SDL namespace
         key: string
             SDL key
         """

-        self._sdl.delete(ns, key)
+        self._sdl.delete(namespace, key)

 
     # Health
 
 
     # Health
 


@@ -332,21 +333,24 @@ class _BaseXapp:
 
 class RMRXapp(_BaseXapp):
     """
 
 class RMRXapp(_BaseXapp):
     """

-    Represents an Xapp that reacts only to RMR messages; i.e., when
-    messages are received, the Xapp does something. When run is called,
-    the xapp framework waits for RMR messages, and calls the appropriate
-    client-registered consume callback on each.
-
-    If environment variable CONFIG_FILE_ENV is defined, and that value is a
-    path to an existing file, the configuration-change handler is invoked at
-    startup and on each configuration-file write event. If no handler is
-    supplied, this class defines a default handler that logs each invocation.
+    Represents an Xapp that reacts only to RMR messages; i.e., the Xapp
+    only performs an action when a message is received.  Clients should
+    invoke the run method, which has a loop that waits for RMR messages
+    and calls the appropriate client-registered consume callback on each.
+
+    If environment variable CONFIG_FILE is defined, and that variable
+    contains a path to an existing file, this class polls a watcher
+    defined on that file to detect file-write events, and invokes a
+    configuration-change handler on each event. The handler is also
+    invoked at startup.  If no handler function is supplied to the
+    constructor, this class defines a default handler that only logs a
+    message.

 
     Parameters
     ----------
     default_handler: function
 
     Parameters
     ----------
     default_handler: function

-        A function with the signature (summary, sbuf) to be called
-        when a message type is received for which no other handler is registered.
+        A function with the signature (summary, sbuf) to be called when a
+        message type is received for which no other handler is registered.

     default_handler argument summary: dict
         The RMR message summary, a dict of key-value pairs
     default_handler argument sbuf: ctypes c_void_p
     default_handler argument summary: dict
         The RMR message summary, a dict of key-value pairs
     default_handler argument sbuf: ctypes c_void_p


@@ -390,8 +394,8 @@ class RMRXapp(_BaseXapp):
         # the user can override this and register their own handler
         # if they wish since the "last registered callback wins".
         def handle_healthcheck(self, summary, sbuf):
         # the user can override this and register their own handler
         # if they wish since the "last registered callback wins".
         def handle_healthcheck(self, summary, sbuf):

-            ok = self.healthcheck()
-            payload = b"OK\n" if ok else b"ERROR [RMR or SDL is unhealthy]\n"
+            healthy = self.healthcheck()
+            payload = b"OK\n" if healthy else b"ERROR [RMR or SDL is unhealthy]\n"

             self.rmr_rts(sbuf, new_payload=payload, new_mtype=RIC_HEALTH_CHECK_RESP)
             self.rmr_free(sbuf)
 
             self.rmr_rts(sbuf, new_payload=payload, new_mtype=RIC_HEALTH_CHECK_RESP)
             self.rmr_free(sbuf)
 

diff --git a/rmr-version.yaml b/rmr-version.yaml
index d7b94dd..45ddaa2 100644 (file)
--- a/rmr-version.yaml
+++ b/rmr-version.yaml
@@ -1,3 +1,3 @@
 # CI script installs RMR from PackageCloud using this version
 ---
 # CI script installs RMR from PackageCloud using this version
 ---

-version: 4.0.5
+version: 4.1.2