Using Execute
=============

Execute currently only provides one pattern of sub-process
execution. That pattern is covered by the :func:`~execute.simple`
function described below.

Simple
------

The :func:`~execute.simple` function provides a simple way to run an
executable in a sub-process that requires no input and where you'd
like the output of both the standard and error output streams combined
and returned in one string.

For example, suppose you needed to execute the following python script
in a sub-process::

  import sys
  print sys.argv[1:]
  sys.stdout.flush()
  sys.stderr.write('An error occurred!\n')

.. -> source

.. invisible-code-block: python

   path = temp_dir.write('test.py',source,path=True)

As an aside, it's unlikely you'd want to do this. It's much more
likely that you'd want to use :func:`~execute.simple` to run something
that wasn't written in python.

However, if ``python`` contained the path to the python executable
you'd want to use to run the above script, and ``path`` contained the
path to the script on disk, you could use :func:`~execute.simple` to
run it and capture the output as follows: 

>>> from execute import simple
>>> output = simple(' '.join((python,path,'x=1 --y=2 a b')))

You now have the output in a string and you can do whatever you like
with it:

>>> print output
['x=1', '--y=2', 'a', 'b']
An error occurred!
<BLANKLINE>
