Add more API functions, prep 1.12.1 for release

kirsle · kirsle · commit 7b4a8c2b3f09 · 2016-05-31T11:41:05.000-07:00
diff --git a/Changes.md b/Changes.md
@@ -1,5 +1,11 @@
 Revision history for the Python package RiveScript.
 
+1.12.1  May 31 2016
+  - Added API functions: `get_global(name)`, `get_variable(name)`, and
+    `set_uservars(user || dict[, dict])` -- the latter is for setting many
+    variables for a user at once, or for setting many variables for many users.
+    Refer to the API documentation for details.
+
 1.12.0  May 10 2016
   - Add support for nested arrays, like `!array colors = @rgb white black`
     (PR #22)
diff --git a/rivescript/rivescript.py b/rivescript/rivescript.py
@@ -1371,7 +1371,7 @@ def call(self, rs, name, fields):
                         # name   = the name of the object being called
                         # fields = array of arguments passed to the object
                         return reply
-    """
+        """
 
         # Allow them to delete a handler too.
         if obj is None:
@@ -1417,6 +1417,14 @@ def set_global(self, name, value):
                 del self._gvars[name]
         self._gvars[name] = value
 
+    def get_global(self, name):
+        """Retrieve the current value of a global variable.
+
+        :param str name: The name of the variable to get.
+        :return str: The value of the variable or ``"undefined"``.
+        """
+        return self._gvars.get(name, "undefined")
+
     def set_variable(self, name, value):
         """Set a bot variable.
 
@@ -1432,6 +1440,14 @@ def set_variable(self, name, value):
                 del self._bvars[name]
         self._bvars[name] = value
 
+    def get_variable(self, name):
+        """Retrieve the current value of a bot variable.
+
+        :param str name: The name of the variable to get.
+        :return str: The value of the variable or ``"undefined"``.
+        """
+        return self._bvars.get(name, "undefined")
+
     def set_substitution(self, what, rep):
         """Set a substitution.
 
@@ -1477,6 +1493,75 @@ def set_uservar(self, user, name, value):
 
         self._users[user][name] = value
 
+    def set_uservars(self, user, data=None):
+        """Set many variables for a user, or set many variables for many users.
+
+        This function can be called in two ways::
+
+            # Set a dict of variables for a single user.
+            rs.set_uservars(username, vars)
+
+            # Set a nested dict of variables for many users.
+            rs.set_uservars(many_vars)
+
+        In the first syntax, ``vars`` is a simple dict of key/value string
+        pairs. In the second syntax, ``many_vars`` is a structure like this::
+
+            {
+                "username1": {
+                    "key": "value",
+                },
+                "username2": {
+                    "key": "value",
+                },
+            }
+
+        This way you can export *all* user variables via ``get_uservars()``
+        and then re-import them all at once, instead of setting them once per
+        user.
+
+        :param optional str user: The user ID to set many variables for.
+            Skip this parameter to set many variables for many users instead.
+        :param dict data: The dictionary of key/value pairs for user variables,
+            or else a dict of dicts mapping usernames to key/value pairs.
+
+        This may raise a ``TypeError`` exception if you pass it invalid data
+        types. Note that only the standard ``dict`` type is accepted, but not
+        variants like ``OrderedDict``, so if you have a dict-like type you
+        should cast it to ``dict`` first.
+        """
+
+        # Check the parameters to see how we're being used.
+        if type(user) is dict and data is None:
+            # Setting many variables for many users.
+            for uid, uservars in user.items():
+                if type(uservars) is not dict:
+                    raise TypeError(
+                        "In set_uservars(many_vars) syntax, the many_vars dict "
+                        "must be in the format of `many_vars['username'] = "
+                        "dict(key=value)`, but the contents of many_vars['{}']"
+                        " is not a dict.".format(uid)
+                    )
+
+                if not uid in self._users:
+                    self._users[uid] = dict(topic="random")
+
+                for key, value in uservars.items():
+                    self._users[uid][key] = value
+
+        elif type(user) in [text_type] and type(data) is dict:
+            # Setting variables for a single user.
+            for key, value in data.items():
+                self._users[user][key] = value
+
+        else:
+            raise TypeError(
+                "set_uservars() may only be called with types (str, dict) or "
+                "(dict<str, dict>) but you called it with types ({}, {})".format(
+                    type(user), type(data),
+                ),
+            )
+
     def get_uservar(self, user, name):
         """Get a variable about a user.
 
@@ -1899,7 +1984,7 @@ def _getreply(self, user, msg, context='normal', step=0, ignore_object_errors=Tr
             for trig in self._sorted["topics"][topic]:
                 # Process the triggers.
                 regexp = self._reply_regexp(user, trig)
-                self._say("Try to match %r against %r (%r)" % (msg, trig, regexp))
+                self._say("Try to match %r against %r (%r)" % (msg, trig, regexp.pattern))
 
                 # Python's regular expression engine is slow. Try a verbatim
                 # match if this is an atomic trigger.
diff --git a/tests/test_rivescript.py b/tests/test_rivescript.py
@@ -5,6 +5,7 @@
 
 import re
 import unittest
+from collections import OrderedDict
 
 from rivescript.rivescript import RS_ERR_MATCH
 
@@ -90,12 +91,22 @@ def test_bot_variables(self):
 
             + happy birthday
             - <bot age=6>Thanks!
+
+            + who is your master
+            - My master is <bot master>.
         """)
+        self.rs.set_variable("master", "kirsle")
+
         self.reply("What is your name?", "My name is Aiden.")
         self.reply("How old are you?", "I am 5.")
         self.reply("What are you?", "I'm undefined.")
         self.reply("Happy birthday!", "Thanks!")
         self.reply("How old are you?", "I am 6.")
+        self.reply("Who is your master?", "My master is kirsle.")
+
+        self.assertEqual(self.rs.get_variable("age"), "6")
+        self.assertEqual(self.rs.get_variable("master"), "kirsle")
+        self.assertEqual(self.rs.get_variable("fake"), "undefined")
 
 
     def test_global_variables(self):
@@ -107,10 +118,20 @@ def test_global_variables(self):
 
             + set debug mode *
             - <env debug=<star>>Switched to <star>.
+
+            + are you testing
+            - Testing: <env testing>
         """)
+        self.rs.set_global("testing", "true")
+
         self.reply("Debug mode.", "Debug mode is: false")
         self.reply("Set debug mode true", "Switched to true.")
         self.reply("Debug mode?", "Debug mode is: true")
+        self.reply("Are you testing?", "Testing: true")
+
+        self.assertEqual(self.rs.get_global("debug"), "true")
+        self.assertEqual(self.rs.get_global("testing"), "true")
+        self.assertEqual(self.rs.get_global("fake"), "undefined")
 
 
 class SubstitutionTests(RiveScriptTestCase):
@@ -680,6 +701,88 @@ def test_concat(self):
         self.reply("test concat second file", "Helloworld!")
 
 
+class APITest(RiveScriptTestCase):
+    """Miscellaneous API tests."""
+
+    def test_set_uservars(self):
+        self.new("""
+            + who am i
+            - You are <get name>, seeker!
+
+            + how old am i
+            - You are <get age> years old.
+        """)
+
+        # Test the base case, with no vars set.
+        self.reply("Who am I?", "You are undefined, seeker!")
+        self.reply("How old am I?", "You are undefined years old.")
+
+        # Set setting one variable at a time.
+        self.rs.set_uservar("localuser", "name", "Alice")
+        self.rs.set_uservar("localuser", "age", "10")
+        self.reply("Who am I?", "You are Alice, seeker!")
+        self.reply("How old am I?", "You are 10 years old.")
+
+        # Test setting a dict of variables for one user.
+        self.rs.set_uservars("localuser", {
+            "name": "Eliza",
+            "age": "20",
+        })
+        self.reply("Who am I?", "You are Eliza, seeker!")
+        self.reply("How old am I?", "You are 20 years old.")
+
+        # Test setting a partial dict which only updates named keys.
+        self.rs.set_uservars("localuser", dict(name="UltraHAL"))
+        self.reply("Who am I?", "You are UltraHAL, seeker!")
+        self.reply("How old am I?", "You are 20 years old.")
+
+        # Test setting a dict of many users to many keys.
+        self.rs.set_uservars({
+            "localuser": {
+                "age": "22",
+            },
+            "testuser": {
+                "name": "Bob",
+            }
+        })
+        self.reply("Who am I?", "You are UltraHAL, seeker!")
+        self.reply("How old am I?", "You are 22 years old.")
+        self.assertEqual(self.rs.get_uservar("testuser", "name"), "Bob")
+        self.assertEqual(self.rs.get_uservar("testuser", "age"), "undefined")
+
+        # Non-existing users return None, not "undefined"
+        self.assertEqual(self.rs.get_uservar("fake", "name"), None)
+
+        # Test calling with (str, None)
+        with self.assertRaises(TypeError):
+            self.rs.set_uservars("alice")
+
+        # Test calling with (str, str)
+        with self.assertRaises(TypeError):
+            self.rs.set_uservars("alice", "name")
+
+        # Test calling with (dict, dict)
+        with self.assertRaises(TypeError):
+            self.rs.set_uservars({"localuser": "hi"}, {"name": "Alice"})
+
+        # Test calling it in many-users mode, where one of the users isn't
+        # a dict.
+        with self.assertRaises(TypeError):
+            self.rs.set_uservars({
+                "localuser": {
+                    "name": "Mary",
+                },
+                "testuser": "not a dict",
+            })
+
+        # Test calling with dict-like objects.
+        with self.assertRaises(TypeError):
+            self.rs.set_uservars("localuser", OrderedDict(name="Alice"))
+
+        # But dict-like objects can be cast as dicts.
+        testdict = OrderedDict(name="Joe")
+        self.assertEqual(self.rs.set_uservars("localuser", dict(testdict)), None)
+
 class UnicodeTest(RiveScriptTestCase):
     """UTF-8 Tests."""
 
