author
======
Todd Mueller
[email protected]
https://github.com/microlinux/python-shell

version
=======
2.0

history
=======
20130401 1.0   Initial release.
20130402 1.1b  Eliminate need for external timeout binary, now
                 uses threading.Timer().
               retval values have changed.
               Tests updated and moved to test/.
               Added installer.
               Added runtime to results.
               close_fds is now False when running subprocesses.
               Added pid to results.
20130408 1.2   Various clean ups and minor internal changes.
               Removed compressed version, mostly laziness.
20130802 1.3b  Added stdin support.
               Reworked function param checks.
20160926 2.0   Big changes. 
               Re-factored and cleaned up.
               stdout/stderr now returned separately.
               stdout/stderr now returned as strings. 
               namedtuple command field now 'cmd'.
               namedtuple runtime field now in milliseconds.
               timeout retval now 254.
               Python exception retval now 255.
               Got rid of setup script/files.
               Added 'test' function for . . . testing.
               I'm three years older.
            
truth
=====
This program is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the Free
Software Foundation, version 3 of the License.

This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
more details.

You should have received a copy of the GNU General Public License along
with this program. If not, see <http://www.gnu.org/licenses/>.

This program may contain bugs or do very bad things. I have done fairly
extensive testing, but certainly may not have uncovered all bugs or corner
cases. I am not a professional programmer. Criticisms and fixes welcome.

shell
=====
shell provides two user facing functions that execute shell commands and
return results in a normalized manner.

command() returns a namedtuple and multi_command() returns a namedtuple
generator:

result.cmd      <str>   command executed
result.pid      <int>   pid of process
result.retval   <int>   retval
result.runtime  <int>   runtime in milliseconds
result.stdout   <str>   stdout stripped of vertical and horizontal 
                        whitespace
result.stderr   <str>   stderr stripped of vertical and horizontal 
                        whitespace

retval = 127 on command not found
retval = 254 on command timeout
retval = 255 on Python exception

On retval 127 or 254 a standard description is returned in stderr. On retval
255, traceback.format_exc() is returned in stderr.

----------------------------------------------------------------
command(<str> command, <int> timeout=10, <str> stdin=None)
----------------------------------------------------------------
Executes a command with a timeout. Returns the result as a namedtuple.

result = command('whoami')

print
print result.cmd
print result.pid
print result.retval
print result.runtime
print result.stdout
print result.stderr

-----------------------------------------------------------------------
multi_command(<list> commands, <int> timeout=10, <int> workers=4,
              <list> stdins=None
-----------------------------------------------------------------------
Executes commands concurrently with individual timeouts in a pool of workers.
Length of stdins must match commands, empty indexes must contain None. Returns
ordered results as a namedtuple generator.

results = multi_command(['whoami', 'uptime'])

for result in results:
    print
    print result.cmd
    print result.pid
    print result.retval
    print result.runtime
    print result.stdout
    print result.stderr