sarge 0.1.1

A subprocess wrapper which provides command pipeline functionality and easy data capture.

The sarge package provides a wrapper for subprocess which provides command
pipeline functionality.

This package leverages subprocess to provide easy-to-use cross-platform command
pipelines with a Posix flavour: you can have chains of commands using ``;``, ``&``, pipes using ``|`` and ``|&``, and redirection.

Here's a taster (example suggested by Kenneth Reitz's Envoy documentation):

>>> from sarge import capture_stdout
>>> p = capture_stdout('fortune|cowthink')
>>> p.returncode
0
>>> p.commands
[Command('fortune'), Command('cowthink')]
>>> p.returncodes
[0, 0]
>>> print(p.stdout.text)
____________________________________
( The last thing one knows in )
( constructing a work is what to put )
( first. )
( )
( -- Blaise Pascal )
------------------------------------
o ^__^
o (oo)\_______
(__)\ )\/\
||----w |
|| ||

The ``capture_stdout`` function is a convenient form of an underlying
function, ``run``. You can also use conditionals:

>>> from sarge import run
>>> p = run('false && echo foo')
>>> p.commands
[Command('false')]
>>> p.returncodes
[1]
>>> p.returncode
1
>>> p = run('false || echo foo')
foo
>>> p.commands
[Command('false'), Command('echo foo')]
>>> p.returncodes
[1, 0]
>>> p.returncode
0

The conditional logic is being done by sarge and not the shell -- which means
you can use the identical code on Windows. Here's an example of some more
involved use of pipes, which also works identically on Posix and Windows:

>>> cmd = 'echo foo | tee stdout.log 3>&1 1>&2 2>&3 | tee stderr.log > %s' % os.devnull
>>> p = run(cmd)
>>> p.commands
[Command('echo foo'), Command('tee stdout.log'), Command('tee stderr.log')]
>>> p.returncodes
[0, 0, 0]
>>>
vinay@eta-oneiric64:~/projects/sarge$ cat stdout.log
foo
vinay@eta-oneiric64:~/projects/sarge$ cat stderr.log
foo

In the above example, the first tee invocation swaps its ``stderr`` and
``stdout`` -- see `this post <http://goo.gl/Enl0c>`_ for a longer explanation
of this somewhat esoteric usage.

Documentation
-------------

Documentation is available at:

http://sarge.readthedocs.org/

Source code
-----------

The development repository for sarge can be found at:

https://bitbucket.org/vinay.sajip/sarge/