From ab64246f8fd3170f73f7e806fcc27f9724d6ef4c Mon Sep 17 00:00:00 2001
From: Per Cederqvist <ceder@lysator.liu.se>
Date: Sun, 26 Oct 2003 18:45:14 +0000
Subject: [PATCH] Documentation added.
---
pcl_expect/spawn.py | 63 +++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 63 insertions(+)
diff --git a/pcl_expect/spawn.py b/pcl_expect/spawn.py
index 04057b3..0694402 100644
--- a/pcl_expect/spawn.py
+++ b/pcl_expect/spawn.py
@@ -6,6 +6,11 @@
data to the procces, and wait for input using the normal Expectable
API.
+ The module uses the pty module. Not all systems support it.
+
+ stdout vs stderr
+ ================
+
If you need to differentiate between stdout and stderr of the
proces, you can use the spawn2() function. This will create a
pipe and a pty. The pty will be connected to stdin and stdout of
@@ -155,8 +160,36 @@ def _spawn(cmd, inherit_stty, stty_init, use_stderr_pipe):
return pid, fd, stderr_r
class Spawn(pcl_expect.Expectable):
+ """Talk to a subprocess via a pty.
+ """
+
def __init__(self, cmd, inherit_stty = None, stty_init = None,
use_stderr_pipe = False):
+ """Spawn a process via a pty.
+
+ Arguments:
+
+ - cmd -- A list of strings to be used as the argv vector
+ of os.execvp. cmd[0] will also be used as the
+ program to run. This can also be a string that will
+ be split on space to produce this list. There is no
+ way to quote a space, so unless the string is a
+ constant you should normally not use that form.
+
+ There are two documented optional arguments:
+
+ - inherit_stty -- True if the stty settings should be
+ inherited if stdin is a tty. This overrides the
+ global setting.
+
+ - stty_init -- String to pass to stty to initialize the
+ pty. This overrides the global setting.
+
+ If os.execvp fails (or if anything else fails in the child
+ process), a pcl_expect.remote_exception.Remote exception
+ will be raised.
+
+ """
self.__child_pid, fd, stderr = _spawn(
cmd,
@@ -166,13 +199,23 @@ class Spawn(pcl_expect.Expectable):
pcl_expect.Expectable.__init__(self, fd)
if use_stderr_pipe:
+ # The stderr attribute is explicitly not documented.
+ # The only published API to get this information is via
+ # the spawn2() function.
self.stderr = pcl_expect.Expectable(stderr)
def send(self, s):
+ """Send a string to the process."""
pcl_expect.debug("sending \"%s\" to fd %d" % (s, self.fileno()))
os.write(self.fileno(), s)
def close(self):
+ """Close the pty and wait for the child to die.
+
+ Return the exit status, as reported by os.waitpid().
+
+ """
+
os.close(self.fileno())
pcl_expect.Expectable.close(self)
if hasattr(self, "stderr"):
@@ -181,5 +224,25 @@ class Spawn(pcl_expect.Expectable):
return os.waitpid(self.__child_pid, 0)
def spawn2(cmd, *args, **kwargs):
+ """Spawn a process via a pty, but send stderr via a pipe.
+
+ See Spawn.__init__ for a description of the arguments.
+
+ This function returns a tuple of two instances:
+
+ - a Spawn instance that can be used to send data to stdin of
+ the process and to read the stdout from the process.
+
+ - an Expectable instance that can be used to read the stderr
+ from the process.
+
+ To clean up once the process terminates, you should call the
+ close() method of both objects.
+
+ Please see the module doc string for more information including
+ some caveats.
+
+ """
+
proc = Spawn(cmd, use_stderr_pipe=True, *args, **kwargs)
return proc, proc.stderr
--
GitLab