call_python: Add documentation example

common/proto/call_python_client.py

@@ -1,3 +1,22 @@
+"""
+Permits calling arbitrary functions and passing some forms of data from C++
+to Python (only one direction) as a server-client pair.
+
+The server in this case is the C++ program, and the client is this binary.
+For an example of C++ usage, see `call_python_server_test.cc`.
+
+Here's an example of running with the C++ test program:
+
+    bazel build //common/proto:call_python_client //common/proto:call_python_server_test  # noqa
+    # Create default pipe file.
+    rm -f /tmp/python_rpc && mkfifo /tmp/python_rpc
+
+    # In Terminal 1, run client.
+    ./bazel-bin/common/proto/call_python_client_cli
+
+    # In Terminal 2, run server (or your C++ program).
+    ./bazel-bin/common/proto/call_python_server_test
+"""
 from __future__ import print_function
 import argparse
 import os
@@ -520,7 +539,9 @@ def _read_next(f, msg):
 
 def main(argv):
     _ensure_sigint_handler()
-    parser = argparse.ArgumentParser()
+    parser = argparse.ArgumentParser(
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter)
     parser.add_argument(
         "--no_wait", action='store_true',
         help="Close client after messages are processed. " +

common/proto/test/call_python_server_test.cc

@@ -8,6 +8,9 @@
 
 #include "drake/common/proto/call_python.h"
 
+// N.B. The following flags are used for testing only, and are not necessary if
+// you are writing your own client.
+
 DEFINE_string(file, "/tmp/python_rpc",
               "File written to by this binary, read by client.");
 // This file signals to `call_python_full_test.sh` that a full execution has
@@ -27,6 +30,9 @@ DEFINE_bool(sleep_at_end, false,
 namespace drake {
 namespace common {
 
+// N.B. This is NOT necessary for normal use; it is only done for testing.
+// If you use any `CallPython` calls prior to `CallPythonInit`, then the
+// default pipe will be used.
 GTEST_TEST(TestCallPython, Start) {
   CallPythonInit(FLAGS_file);
   // Tell client to expect a finishing signal.
@@ -162,6 +168,7 @@ GTEST_TEST(TestCallPython, Plot3d) {
   CallPython("eval", "print(len(x) + len(y) + len(Z))");
 }
 
+// N.B. This is NOT necessary for normal use; it is only done for testing.
 GTEST_TEST(TestCallPython, Finish) {
   if (FLAGS_sleep_at_end) {
     // If the Python client closes before this program closes the FIFO pipe,

common/proto/test/call_python_test.py

@@ -98,6 +98,14 @@ def run_server_and_client(self, with_error):
             client_status = client.wait()
             self.assertEqual(client_status, int(with_error))
 
+    def test_help(self):
+        text = subprocess.check_output(
+            [client_bin, "--help"], stderr=subprocess.STDOUT)
+        # Print output, since `assertIn` does not provide user-friendly
+        # multiline error messages.
+        print(text)
+        self.assertTrue("Here's an example" in text)
+
     def test_basic(self):
         for with_error in [False, True]:
             print("[ with_error: {} ]".format(with_error))