[#336] rule files can now be submitted from a memory file object

Updated tests, doc strings and README to reflect changes.

Author: d-w-moore

README.rst

@@ -503,13 +503,18 @@ irods server log::
   r = irods.rule.Rule( session, rule_file = 'native1.r')
   r.execute()
 
-Release v1.1.0 includes the ability to target a specific rule engine instance by name, so if other rule engine instances are present, we may want
-to instantiate using::
-
-  Rule( ... , instance_name = 'irods_rule_engine_plugin-irods_rule_language-instance' )
-
-Additionally, if we wanted to have the :code:`native1.r` rule code print to stdout instead, we could also set :code:`*stream` in the :code:`INPUT`
-parameters for the rule and change the :code:`OUTPUT` parameter from :code:`null` to :code:`ruleExecOut` to accommodate the output stream::
+With release v1.1.1, not only can we target a specific rule engine instance by name (which is useful when
+more than one is present), but we can also use a file-like object for the :code:`rule_file` parameter::
+
+  Rule( session, rule_file = io.StringIO(u'''mainRule() { anotherRule(*x); writeLine('stdout',*x) }\n'''
+                                         u'''anotherRule(*OUT) {*OUT='hello world!'}\n\n'''
+                                         u'''OUTPUT ruleExecOut\n'''),
+        instance_name = 'irods_rule_engine_plugin-irods_rule_language-instance' )
+
+Incidentally, if we wanted to change the :code:`native1.r` rule code print to stdout also, we could set the
+:code:`INPUT` parameter, :code:`*stream`, using the Rule constructor's :code:`params` keyword argument.
+Similarly, we can change the :code:`OUTPUT` parameter from :code:`null` to :code:`ruleExecOut`, to accommodate
+the output stream, via the :code:`output` argument::
 
   r = irods.rule.Rule( session, rule_file = 'native1.r',
              instance_name = 'irods_rule_engine_plugin-irods_rule_language-instance',

irods/rule.py

@@ -4,6 +4,7 @@
 import irods.exception as ex
 from io import open as io_open
 from irods.message import Message, StringProperty
+import six
 
 class RemoveRuleMessage(Message):
     #define RULE_EXEC_DEL_INP_PI "str ruleExecId[NAME_LEN];"
@@ -20,8 +21,11 @@ def __init__(self, session, rule_file=None, body='', params=None, output='', ins
 
         Arguments:
         Use one of:
-          * rule_file : the name of an existing rule script ending in '.r' and containing iRODS rules
-          * body: the text of the rule code or rule call(s) to be run.
+          * rule_file : the name of an existing file containint "rule script" style code. In the context of
+            the native iRODS Rule Language, this is a file ending in '.r' and containing iRODS rules.
+            Optionally, this parameter can be a file-like object containing the rule script text.
+          * body: the text of block of rule code (possibly including rule calls) to be run as if it were
+            the body of a rule, e.g. the part between the braces of a rule definition in the iRODS rule language.
         * instance_name: the name of the rule engine instance in the context of which to run the rule(s).
         * output may be set to 'ruleExecOut' if console output is expected on stderr or stdout streams.
         * params are key/value pairs to be sent into a rule_file.
@@ -62,11 +66,37 @@ def remove_by_id(self,*ids):
                     raise RuntimeError("Error removing rule {id_}".format(**locals()))
 
     def load(self, rule_file, encoding = 'utf-8'):
+        """Load rule code with rule-file (*.r) semantics.
+
+        A "main" rule is defined first; name does not matter. Other rules may follow, which will be
+        callable from the first rule.  Any rules defined in active rule-bases within the server are
+        also callable.
+
+        The `rule_file' parameter is a filename or file-like object.  We give it either:
+           - a string holding the path to a rule-file in the local filesystem, or
+           - an in-memory object (eg. io.StringIO or io.BytesIO) whose content is that of a rule-file.
+
+        This addresses a regression in v1.1.0; see issue #336.  In v1.1.1+, if rule code is passed in literally via
+        the `body' parameter of the Rule constructor, it is interpreted as if it were the body of a rule, and
+        therefore it may not contain internal rule definitions.  However, if rule code is submitted as the content
+        of a file or file-like object referred to by the `rule_file' parameter of the Rule constructor, will be
+        interpreted as .r-file content.  Therefore, it must contain a main rule definition first, followed
+        possibly by others which will be callable from the main rule as if they were part of the core rule-base.
+
+        """
         self.body = '@external\n'
 
-        # parse rule file
-        with io_open(rule_file, encoding = encoding) as f:
+
+        with (io_open(rule_file, encoding = encoding) if isinstance(rule_file,six.string_types) else rule_file
+        ) as f:
+
+            # parse rule file line-by-line
             for line in f:
+
+                # convert input line to Unicode if necessary
+                if isinstance(line, bytes):
+                    line = line.decode(encoding)
+
                 # parse input line
                 if line.strip().lower().startswith('input'):
 

irods/test/rule_test.py

@@ -12,6 +12,7 @@
 from irods.rule import Rule
 import six
 from io import open as io_open
+import io
 
 
 RE_Plugins_installed_run_condition_args = ( os.environ.get('PYTHON_RULE_ENGINE_INSTALLED','*').lower()[:1]=='y',
@@ -341,6 +342,64 @@ def test_retrieve_std_streams_from_rule(self):
         os.remove(rule_file_path)
 
 
+    @staticmethod
+    def lines_from_stdout_buf(output):
+        buf = ""
+        if output and len(output.MsParam_PI):
+            buf = output.MsParam_PI[0].inOutStruct.stdoutBuf.buf
+            if buf:
+                buf = buf.rstrip(b'\0').decode('utf8')
+        return buf.splitlines()
+
+
+    def test_rulefile_in_file_like_object_1__336(self):
+
+        rule_file_contents = textwrap.dedent(u"""\
+        hw {
+                helloWorld(*message);
+                writeLine("stdout", "Message is: [*message] ...");
+        }
+        helloWorld(*OUT)
+        {
+          *OUT = "Hello world!"
+        }
+        """)
+        r = Rule(self.sess, rule_file = io.StringIO( rule_file_contents ),
+                            output = 'ruleExecOut', instance_name='irods_rule_engine_plugin-irods_rule_language-instance')
+        output = r.execute()
+        lines = self.lines_from_stdout_buf(output)
+        self.assertRegexpMatches (lines[0], '.*\[Hello world!\]')
+
+
+    def test_rulefile_in_file_like_object_2__336(self):
+
+        rule_file_contents = textwrap.dedent("""\
+        main {
+          other_rule()
+          writeLine("stdout","["++type(*msg2)++"][*msg2]");
+        }
+        other_rule {
+          writeLine("stdout","["++type(*msg1)++"][*msg1]");
+        }
+
+        INPUT *msg1="",*msg2=""
+        OUTPUT ruleExecOut
+        """)
+
+        r = Rule(self.sess, rule_file = io.BytesIO( rule_file_contents.encode('utf-8') ))
+        output = r.execute()
+        lines = self.lines_from_stdout_buf(output)
+        self.assertRegexpMatches (lines[0], '\[STRING\]\[\]')
+        self.assertRegexpMatches (lines[1], '\[STRING\]\[\]')
+
+        r = Rule(self.sess, rule_file = io.BytesIO( rule_file_contents.encode('utf-8') )
+                          , params = {'*msg1':5, '*msg2':'"A String"'})
+        output = r.execute()
+        lines = self.lines_from_stdout_buf(output)
+        self.assertRegexpMatches (lines[0], '\[INTEGER\]\[5\]')
+        self.assertRegexpMatches (lines[1], '\[STRING\]\[A String\]')
+
+
 if __name__ == '__main__':
     # let the tests find the parent irods lib
     sys.path.insert(0, os.path.abspath('../..'))