Allow disabling printing stats to stdout

Correct failing Python API tests

Re ECFLOW-1944

Author: marcosbento

Pyext/src/ecflow/python/ClientDoc.cpp

@@ -680,13 +680,18 @@ const char* ClientDoc::ping() {
 }
 
 const char* ClientDoc::stats() {
-    return "Returns the `ecflow_server`_ statistics as a string\n::\n\n"
-           "   string stats()\n"
+    return "Returns the `ecflow_server`_ statistics as a string\n\n"
+           ".. warning::\n\n"
+           "    When called without arguments, this function will print the statistics to :code:`stdout`,"
+           " before returning the information as a string.\n"
+           "    To avoid printing the output, set the boolean flag :code:`to_stdout` to :code:`False`.\n"
            "\nUsage:\n\n"
            ".. code-block:: python\n\n"
            "   try:\n"
            "       ci = Client()  # use default host(ECF_HOST) & port(ECF_PORT)\n"
-           "       stats = ci.stats()\n"
+           "       stats = ci.stats()      # prints to stdout\n"
+           "       stats = ci.stats(True)  # prints to stdout\n"
+           "       stats = ci.stats(False) # does not print to stdout\n"
            "       print(stats)\n"
            "   except RuntimeError, e:\n"
            "       print(str(e))\n";

Pyext/src/ecflow/python/ExportClient.cpp

@@ -130,13 +130,16 @@ class CliSetter {
 private:
     ClientInvoker* _self;
 };
-const std::string& stats(ClientInvoker* self) {
+
+const std::string& stats(ClientInvoker* self, bool to_stdout = true) {
     self->stats();
-    // The statistics are printed to stdout for backward compatibility with previous python client versions
-    // TODO: remove printing to stdout in the next release
-    std::cout << self->server_reply().get_string() << std::endl;
+    if (to_stdout) {
+        std::cout << self->server_reply().get_string() << std::endl;
+    }
     return self->server_reply().get_string();
 }
+BOOST_PYTHON_FUNCTION_OVERLOADS(stats_overloads, stats, 1, 2)
+
 void stats_reset(ClientInvoker* self) {
     self->stats_reset();
 }
@@ -577,7 +580,7 @@ void export_Client() {
         .def("free_all_dep", &free_all_dep, ClientDoc::free_all_dep())
         .def("free_all_dep", &free_all_dep1)
         .def("ping", &ClientInvoker::pingServer, ClientDoc::ping())
-        .def("stats", &stats, return_value_policy<copy_const_reference>(), ClientDoc::stats())
+        .def("stats", &stats, stats_overloads(args("to_stdout"), ClientDoc::stats())[return_value_policy<copy_const_reference>()])
         .def("stats_reset", &stats_reset, ClientDoc::stats_reset())
         .def("get_file",
              &get_file,

Pyext/test/py_s_TestClientApi.py

@@ -14,6 +14,7 @@
 import time
 import os
 import pwd
+import select
 from datetime import datetime
 import shutil   # used to remove directory tree
 
@@ -529,20 +530,66 @@ def test_client_free_dep(ci):
         time.sleep(3)       
 
     dir_to_remove = Test.ecf_home(the_port) + "/" + "test_client_free_dep"
-    shutil.rmtree(dir_to_remove, ignore_errors=True)   
+    shutil.rmtree(dir_to_remove, ignore_errors=True)
+
+
+class CustomStdOut:
+    def __enter__(self):
+        # create a pipe to store some content temporarily
+        self.read_pipe, self.write_pipe = os.pipe()
+        # save the original ouput fd
+        self.stdout = os.dup(1)
+        # redirect stdout into the write pipe
+        fd = os.dup2(self.write_pipe, 1)
+        return self
+
+    def __exit__(self, exc_type, exc_value, exc_traceback):
+        # restore the original output fd
+        os.dup2(self.stdout, 1)
+
+    def _more_data(self):
+        # check if there is more data in the read pipe
+        r, _, _ = select.select([self.read_pipe], [], [], 0)
+        return bool(r)
+
+    def value(self):
+        out = ''
+        while self._more_data():
+            out += os.read(self.read_pipe, 1024).decode('utf-8')
+        return out
 
 
 def test_client_stats(ci):
     print_test(ci,"test_client_stats")
-    stats = ci.stats()
-    assert "statistics" in s, "Expected statistics in the response"
-    
+    with CustomStdOut() as out:
+        stats = ci.stats()
+        assert "statistics" in stats, "Expected 'statistics' in the response"
+        assert "statistics" in out.value(), "Expected 'statistics' in the captured output"
+
+
+def test_client_stats_with_stdout(ci):
+    print_test(ci,"test_client_stats_with_stdout")
+    with CustomStdOut() as out:
+        stats = ci.stats(True)
+        assert "statistics" in stats, "Expected 'statistics' in the response"
+        assert "statistics" in out.value(), "Expected 'statistics' in the captured output"
+
+
+def test_client_stats_without_stdout(ci):
+    print_test(ci,"test_client_stats_without_stdout")
+    with CustomStdOut() as out:
+        stats = ci.stats(False)
+        assert "statistics" in stats, "Expected 'statistics' in the response"
+        assert not out.value() , "No captured output expected"
+
+
 def test_client_stats_reset(ci):
     print_test(ci,"test_client_stats_reset")
     ci.stats_reset()   
-    statis = ci.stats()
-    assert "statistics" in s, "Expected statistics in the response"
-            
+    stats = ci.stats()
+    assert "statistics" in stats, "Expected 'statistics' in the response"
+
+
 def test_client_debug_server_on_off(ci):
     print_test(ci,"test_client_debug_server_on_off")
     ci.debug_server_on()  # writes to standard out
@@ -2058,7 +2105,9 @@ def do_tests(ci,the_port):
     test_client_check(ci)  
     test_client_check_defstatus(ci)  
 
-    test_client_stats(ci)             
+    test_client_stats(ci)
+    test_client_stats_with_stdout(ci)
+    test_client_stats_without_stdout(ci)
     test_client_stats_reset(ci)             
     test_client_debug_server_on_off(ci)    
 

docs/python_api/Client.rst

@@ -2259,21 +2259,25 @@ Usage:
 sort_attributes( (Client)arg1, (list)paths, (str)attribute_name [, (bool)recursive=True]) -> None
 
 
-.. py:method:: Client.stats( (Client)arg1) -> str :
+.. py:method:: Client.stats( (Client)arg1 [, (bool)to_stdout]) -> str :
    :module: ecflow
 
 Returns the :term:`ecflow_server` statistics as a string
-::
 
-   string stats()
+.. warning::
+
+    When called without arguments, this function will print the statistics to :code:`stdout`, before returning the information as a string.
+    To avoid printing the output, set the boolean flag :code:`to_stdout` to :code:`False`.
 
 Usage:
 
 .. code-block:: python
 
    try:
        ci = Client()  # use default host(ECF_HOST) & port(ECF_PORT)
-       stats = ci.stats()
+       stats = ci.stats()      # prints to stdout
+       stats = ci.stats(True)  # prints to stdout
+       stats = ci.stats(False) # does not print to stdout
        print(stats)
    except RuntimeError, e:
        print(str(e))