Replace getProcess* helpers with a single, better, API.

[spiv]

I think the subprocess module has the right idea: give you a single good way to start a function, and declare whether you want to capture/discard/ignore the various stdio streams etc, and then return an object with useful attributes.

So I propose that instead of getProcessValue, getProcessOutput, getProcessOutputAndValue (did I miss any?) we have a single method, that takes args like:

  foo(stdout=fileLikeObject, ...)

and returns a Deferred that yields an object with a .exitValue attribute, and perhaps others (for finding out if a signal terminated it, maybe?). Returning an object certainly seems like a much better API than e.g. the tuples from getProcessOutputAndValue. Obviously this new function would need a better name than foo.

Probably any new API here should try to address the problems with the existing APIs described by exarkun in a comment at http://twistedmatrix.com/trac/ticket/280.

Quite possibly the proposal in this vague sketch could be improved even further. Please feel free to criticise, suggest improvements, suggest more precise details for the signature, etc. I figured it was better to capture a rough idea than forget it entirely.

[Screwtape]

A single, perfect, simple and powerful API that did everything with processes would be nice, but a difficult goal to attain.

A shorter-term stepping-stone might be to supply a few IProcessProtocol implementations that can be used with .spawnProcess() to handle common scenarios, including:

• adapting an ordinary Protocol to talk to a subprocess (hooked up to stdin/stdout, stderr and exit codes ignored)
• taking a string and writing it to the child's stdin; provides a Deferred that will be callback'd with the process's output if it exited cleanly, and errback'd if the process is killed by a signal.

I guess browsing the docs of the subprocess stdlib module and various uses of .spawnProcess in the Twisted codebase (and any other Twisted-based code you have handy) would be a good way of finding use-cases.

[glyph]

Replying to Screwtape:

* adapting an ordinary Protocol to talk to a subprocess (hooked up to stdin/stdout, stderr and exit codes ignored)

I want to do this all the time. connectProcess, maybe? Let's make that a separate ticket. (I am sympathetic to the goals of this ticket, but it is only distantly related; getProcess* are more about simple scripts that do one thing with a subprocess that fires a Deferred; connectProcess is more about an explicit mapping between IProcessProtocol and IProtocol (which should look much more different than they currently do).

[glyph]

OK, connectProcess would be a silly idea; it should be a process endpoint. This particular ticket may be too broad to be resolved usefully though, I'm thinking of closing it as invalid and just opening a new one for IProtocol→IProcessProtocol adapter.

[exarkun]

It would probably be a good idea to look at all of the "spawnProcess sucks" tickets and figure out a plan that addresses more than just one of them.