sh-1.11/0000775000175000017500000000000012451025515013124 5ustar amoffatamoffat00000000000000sh-1.11/AUTHORS.md0000664000175000017500000000043012447067575014611 0ustar amoffatamoffat00000000000000# Author * Andrew Moffat # Contributors * Dmitry Medvinsky * Jure Žiberna * Bahadır Kandemir * Jannis Leidel * tingletech * tdudziak * Arjen Stolk * nemec * fruch * Ralph Bean * Rory Kirchner * ahhentz sh-1.11/PKG-INFO0000664000175000017500000000203412451025515014220 0ustar amoffatamoffat00000000000000Metadata-Version: 1.1 Name: sh Version: 1.11 Summary: Python subprocess interface Home-page: https://github.com/amoffat/sh Author: Andrew Moffat Author-email: andrew.robert.moffat@gmail.com License: MIT Description: UNKNOWN Platform: UNKNOWN Classifier: Development Status :: 5 - Production/Stable Classifier: Environment :: Console Classifier: Intended Audience :: Developers Classifier: Intended Audience :: System Administrators Classifier: License :: OSI Approved :: MIT License Classifier: Programming Language :: Python Classifier: Programming Language :: Python :: 2 Classifier: Programming Language :: Python :: 2.6 Classifier: Programming Language :: Python :: 2.7 Classifier: Programming Language :: Python :: 3 Classifier: Programming Language :: Python :: 3.1 Classifier: Programming Language :: Python :: 3.2 Classifier: Programming Language :: Python :: 3.3 Classifier: Programming Language :: Python :: 3.4 Classifier: Topic :: Software Development :: Build Tools Classifier: Topic :: Software Development :: Libraries :: Python Modules sh-1.11/test.py0000664000175000017500000014651512451024633014471 0ustar amoffatamoffat00000000000000# -*- coding: utf8 -*- import os from os.path import exists, join, realpath import unittest import tempfile import sys import sh import platform from functools import wraps # we have to use the real path because on osx, /tmp is a symlink to # /private/tmp, and so assertions that gettempdir() == sh.pwd() will fail tempdir = realpath(tempfile.gettempdir()) IS_OSX = platform.system() == "Darwin" IS_PY3 = sys.version_info[0] == 3 if IS_PY3: unicode = str python = sh.Command(sh.which("python%d.%d" % sys.version_info[:2])) else: from sh import python THIS_DIR = os.path.dirname(os.path.abspath(__file__)) skipUnless = getattr(unittest, "skipUnless", None) if not skipUnless: # our stupid skipUnless wrapper for python2.6 def skipUnless(condition, reason): def wrapper(test): if condition: return test else: @wraps(test) def skip(*args, **kwargs): return return skip return wrapper requires_posix = skipUnless(os.name == "posix", "Requires POSIX") requires_utf8 = skipUnless(sh.DEFAULT_ENCODING == "UTF-8", "System encoding must be UTF-8") def create_tmp_test(code, prefix="tmp", delete=True): """ creates a temporary test file that lives on disk, on which we can run python with sh """ py = tempfile.NamedTemporaryFile(prefix=prefix, delete=delete) if IS_PY3: code = bytes(code, "UTF-8") py.write(code) py.flush() # we don't explicitly close, because close will remove the file, and we # don't want that until the test case is done. so we let the gc close it # when it goes out of scope return py @requires_posix class FunctionalTests(unittest.TestCase): def test_print_command(self): from sh import ls, which actual_location = which("ls") out = str(ls) self.assertEqual(out, actual_location) def test_unicode_arg(self): from sh import echo test = "漢字" if not IS_PY3: test = test.decode("utf8") p = echo(test, _encoding="utf8") output = p.strip() self.assertEqual(test, output) def test_number_arg(self): py = create_tmp_test(""" from optparse import OptionParser parser = OptionParser() options, args = parser.parse_args() print(args[0]) """) out = python(py.name, 3).strip() self.assertEqual(out, "3") def test_exit_code(self): from sh import ErrorReturnCode py = create_tmp_test(""" exit(3) """) self.assertRaises(ErrorReturnCode, python, py.name) def test_exit_code_with_hasattr(self): from sh import ErrorReturnCode py = create_tmp_test(""" exit(3) """) try: out = python(py.name, _iter=True) # hasattr can swallow exceptions hasattr(out, 'something_not_there') list(out) self.assertEqual(out.exit_code, 3) self.fail("Command exited with error, but no exception thrown") except ErrorReturnCode as e: pass def test_exit_code_from_exception(self): from sh import ErrorReturnCode py = create_tmp_test(""" exit(3) """) self.assertRaises(ErrorReturnCode, python, py.name) try: python(py.name) except Exception as e: self.assertEqual(e.exit_code, 3) def test_glob_warning(self): from sh import ls from glob import glob import warnings with warnings.catch_warnings(record=True) as w: warnings.simplefilter("always") ls(glob("ofjaoweijfaowe")) self.assertTrue(len(w) == 1) self.assertTrue(issubclass(w[-1].category, UserWarning)) self.assertTrue("glob" in str(w[-1].message)) def test_stdin_from_string(self): from sh import sed self.assertEqual(sed(_in="one test three", e="s/test/two/").strip(), "one two three") def test_ok_code(self): from sh import ls, ErrorReturnCode_1, ErrorReturnCode_2 exc_to_test = ErrorReturnCode_2 code_to_pass = 2 if IS_OSX: exc_to_test = ErrorReturnCode_1 code_to_pass = 1 self.assertRaises(exc_to_test, ls, "/aofwje/garogjao4a/eoan3on") ls("/aofwje/garogjao4a/eoan3on", _ok_code=code_to_pass) ls("/aofwje/garogjao4a/eoan3on", _ok_code=[code_to_pass]) ls("/aofwje/garogjao4a/eoan3on", _ok_code=range(code_to_pass + 1)) def test_quote_escaping(self): py = create_tmp_test(""" from optparse import OptionParser parser = OptionParser() options, args = parser.parse_args() print(args) """) out = python(py.name, "one two three").strip() self.assertEqual(out, "['one two three']") out = python(py.name, "one \"two three").strip() self.assertEqual(out, "['one \"two three']") out = python(py.name, "one", "two three").strip() self.assertEqual(out, "['one', 'two three']") out = python(py.name, "one", "two \"haha\" three").strip() self.assertEqual(out, "['one', 'two \"haha\" three']") out = python(py.name, "one two's three").strip() self.assertEqual(out, "[\"one two's three\"]") out = python(py.name, 'one two\'s three').strip() self.assertEqual(out, "[\"one two's three\"]") def test_multiple_pipes(self): from sh import tr, python import time py = create_tmp_test(""" import sys import os import time for l in "andrew": print(l) time.sleep(.2) """) class Derp(object): def __init__(self): self.times = [] self.stdout = [] self.last_received = None def agg(self, line): self.stdout.append(line.strip()) now = time.time() if self.last_received: self.times.append(now - self.last_received) self.last_received = now derp = Derp() p = tr( tr( tr( python(py.name, _piped=True), "aw", "wa", _piped=True), "ne", "en", _piped=True), "dr", "rd", _out=derp.agg) p.wait() self.assertEqual("".join(derp.stdout), "werdna") self.assertTrue(all([t > .15 for t in derp.times])) def test_manual_stdin_string(self): from sh import tr out = tr("[:lower:]", "[:upper:]", _in="andrew").strip() self.assertEqual(out, "ANDREW") def test_manual_stdin_iterable(self): from sh import tr test = ["testing\n", "herp\n", "derp\n"] out = tr("[:lower:]", "[:upper:]", _in=test) match = "".join([t.upper() for t in test]) self.assertEqual(out, match) def test_manual_stdin_file(self): from sh import tr import tempfile test_string = "testing\nherp\nderp\n" stdin = tempfile.NamedTemporaryFile() stdin.write(test_string.encode()) stdin.flush() stdin.seek(0) out = tr("[:lower:]", "[:upper:]", _in=stdin) self.assertEqual(out, test_string.upper()) def test_manual_stdin_queue(self): from sh import tr try: from Queue import Queue, Empty except ImportError: from queue import Queue, Empty test = ["testing\n", "herp\n", "derp\n"] q = Queue() for t in test: q.put(t) q.put(None) # EOF out = tr("[:lower:]", "[:upper:]", _in=q) match = "".join([t.upper() for t in test]) self.assertEqual(out, match) def test_environment(self): """ tests that environments variables that we pass into sh commands exist in the environment, and on the sh module """ import os # this is the environment we'll pass into our commands env = {"HERP": "DERP"} # python on osx will bizarrely add some extra environment variables that # i didn't ask for. for this test, we prune those out if they exist osx_cruft = [ "__CF_USER_TEXT_ENCODING", "__PYVENV_LAUNCHER__", "VERSIONER_PYTHON_PREFER_32_BIT", "VERSIONER_PYTHON_VERSION", ] # first we test that the environment exists in our child process as # we've set it py = create_tmp_test(""" import os osx_cruft = %s for key in osx_cruft: try: del os.environ[key] except: pass print(os.environ["HERP"] + " " + str(len(os.environ))) """ % osx_cruft) out = python(py.name, _env=env).strip() self.assertEqual(out, "DERP 1") py = create_tmp_test(""" import os, sys sys.path.insert(0, os.getcwd()) import sh osx_cruft = %s for key in osx_cruft: try: del os.environ[key] except: pass print(sh.HERP + " " + str(len(os.environ))) """ % osx_cruft) out = python(py.name, _env=env, _cwd=THIS_DIR).strip() self.assertEqual(out, "DERP 1") def test_which(self): from sh import which, ls self.assertEqual(which("fjoawjefojawe"), None) self.assertEqual(which("ls"), str(ls)) def test_foreground(self): return raise NotImplementedError def test_no_arg(self): import pwd from sh import whoami u1 = whoami().strip() u2 = pwd.getpwuid(os.geteuid())[0] self.assertEqual(u1, u2) def test_incompatible_special_args(self): from sh import ls self.assertRaises(TypeError, ls, _iter=True, _piped=True) def test_exception(self): from sh import ls, ErrorReturnCode_1, ErrorReturnCode_2 exc_to_test = ErrorReturnCode_2 if IS_OSX: exc_to_test = ErrorReturnCode_1 self.assertRaises(exc_to_test, ls, "/aofwje/garogjao4a/eoan3on") def test_command_not_found(self): from sh import CommandNotFound def do_import(): from sh import aowjgoawjoeijaowjellll self.assertRaises(ImportError, do_import) def do_import(): import sh sh.awoefaowejfw self.assertRaises(CommandNotFound, do_import) def do_import(): import sh sh.Command("ofajweofjawoe") self.assertRaises(CommandNotFound, do_import) def test_command_wrapper_equivalence(self): from sh import Command, ls, which self.assertEqual(Command(which("ls")), ls) def test_doesnt_execute_directories(self): save_path = os.environ['PATH'] bin_dir1 = tempfile.mkdtemp() bin_dir2 = tempfile.mkdtemp() gcc_dir1 = os.path.join(bin_dir1, 'gcc') gcc_file2 = os.path.join(bin_dir2, 'gcc') try: os.environ['PATH'] = os.pathsep.join((bin_dir1, bin_dir2)) # a folder named 'gcc', its executable, but should not be # discovered by internal which(1)-clone os.makedirs(gcc_dir1) # an executable named gcc -- only this should be executed bunk_header = '#!/bin/sh\necho $*' with open(gcc_file2, "w") as h: h.write(bunk_header) os.chmod(gcc_file2, int(0o755)) from sh import gcc if IS_PY3: self.assertEqual(gcc._path, gcc_file2.encode(sh.DEFAULT_ENCODING)) else: self.assertEqual(gcc._path, gcc_file2) self.assertEqual(gcc('no-error').stdout.strip(), 'no-error'.encode("ascii")) finally: os.environ['PATH'] = save_path if exists(gcc_file2): os.unlink(gcc_file2) if exists(gcc_dir1): os.rmdir(gcc_dir1) if exists(bin_dir1): os.rmdir(bin_dir1) if exists(bin_dir1): os.rmdir(bin_dir2) def test_multiple_args_short_option(self): py = create_tmp_test(""" from optparse import OptionParser parser = OptionParser() parser.add_option("-l", dest="long_option") options, args = parser.parse_args() print(len(options.long_option.split())) """) num_args = int(python(py.name, l="one two three")) self.assertEqual(num_args, 3) num_args = int(python(py.name, "-l", "one's two's three's")) self.assertEqual(num_args, 3) def test_multiple_args_long_option(self): py = create_tmp_test(""" from optparse import OptionParser parser = OptionParser() parser.add_option("-l", "--long-option", dest="long_option") options, args = parser.parse_args() print(len(options.long_option.split())) """) num_args = int(python(py.name, long_option="one two three")) self.assertEqual(num_args, 3) num_args = int(python(py.name, "--long-option", "one's two's three's")) self.assertEqual(num_args, 3) def test_short_bool_option(self): py = create_tmp_test(""" from optparse import OptionParser parser = OptionParser() parser.add_option("-s", action="store_true", default=False, dest="short_option") options, args = parser.parse_args() print(options.short_option) """) self.assertTrue(python(py.name, s=True).strip() == "True") self.assertTrue(python(py.name, s=False).strip() == "False") self.assertTrue(python(py.name).strip() == "False") def test_long_bool_option(self): py = create_tmp_test(""" from optparse import OptionParser parser = OptionParser() parser.add_option("-l", "--long-option", action="store_true", default=False, dest="long_option") options, args = parser.parse_args() print(options.long_option) """) self.assertTrue(python(py.name, long_option=True).strip() == "True") self.assertTrue(python(py.name).strip() == "False") def test_composition(self): from sh import ls, wc c1 = int(wc(ls("-A1"), l=True)) c2 = len(os.listdir(".")) self.assertEqual(c1, c2) def test_incremental_composition(self): from sh import ls, wc c1 = int(wc(ls("-A1", _piped=True), l=True).strip()) c2 = len(os.listdir(".")) self.assertEqual(c1, c2) def test_short_option(self): from sh import sh s1 = sh(c="echo test").strip() s2 = "test" self.assertEqual(s1, s2) def test_long_option(self): py = create_tmp_test(""" from optparse import OptionParser parser = OptionParser() parser.add_option("-l", "--long-option", action="store", default="", dest="long_option") options, args = parser.parse_args() print(options.long_option.upper()) """) self.assertTrue(python(py.name, long_option="testing").strip() == "TESTING") self.assertTrue(python(py.name).strip() == "") def test_raw_args(self): py = create_tmp_test(""" from optparse import OptionParser parser = OptionParser() parser.add_option("--long_option", action="store", default=None, dest="long_option1") parser.add_option("--long-option", action="store", default=None, dest="long_option2") options, args = parser.parse_args() if options.long_option1: print(options.long_option1.upper()) else: print(options.long_option2.upper()) """) self.assertEqual(python(py.name, {"long_option": "underscore"}).strip(), "UNDERSCORE") self.assertEqual(python(py.name, long_option="hyphen").strip(), "HYPHEN") def test_custom_separator(self): py = create_tmp_test(""" import sys print(sys.argv[1]) """) self.assertEqual(python(py.name, {"long-option": "underscore"}, _long_sep="=custom=").strip(), "--long-option=custom=underscore") # test baking too python_baked = python.bake(py.name, {"long-option": "underscore"}, _long_sep="=baked=") self.assertEqual(python_baked().strip(), "--long-option=baked=underscore") def test_command_wrapper(self): from sh import Command, which ls = Command(which("ls")) wc = Command(which("wc")) c1 = int(wc(ls("-A1"), l=True)) c2 = len(os.listdir(".")) self.assertEqual(c1, c2) def test_background(self): from sh import sleep import time start = time.time() sleep_time = .5 p = sleep(sleep_time, _bg=True) now = time.time() self.assertTrue(now - start < sleep_time) p.wait() now = time.time() self.assertTrue(now - start > sleep_time) def test_background_exception(self): from sh import ls, ErrorReturnCode_1, ErrorReturnCode_2 p = ls("/ofawjeofj", _bg=True) # should not raise exc_to_test = ErrorReturnCode_2 if IS_OSX: exc_to_test = ErrorReturnCode_1 self.assertRaises(exc_to_test, p.wait) # should raise def test_with_context(self): from sh import whoami import getpass py = create_tmp_test(""" import sys import os import subprocess print("with_context") subprocess.Popen(sys.argv[1:], shell=False).wait() """) cmd1 = python.bake(py.name, _with=True) with cmd1: out = whoami() self.assertTrue("with_context" in out) self.assertTrue(getpass.getuser() in out) def test_with_context_args(self): from sh import whoami import getpass py = create_tmp_test(""" import sys import os import subprocess from optparse import OptionParser parser = OptionParser() parser.add_option("-o", "--opt", action="store_true", default=False, dest="opt") options, args = parser.parse_args() if options.opt: subprocess.Popen(args[0], shell=False).wait() """) with python(py.name, opt=True, _with=True): out = whoami() self.assertTrue(getpass.getuser() == out.strip()) with python(py.name, _with=True): out = whoami() self.assertTrue(out == "") def test_err_to_out(self): py = create_tmp_test(""" import sys import os sys.stdout.write("stdout") sys.stdout.flush() sys.stderr.write("stderr") sys.stderr.flush() """) stdout = python(py.name, _err_to_out=True) self.assertTrue(stdout == "stdoutstderr") def test_out_redirection(self): import tempfile py = create_tmp_test(""" import sys import os sys.stdout.write("stdout") sys.stderr.write("stderr") """) file_obj = tempfile.TemporaryFile() out = python(py.name, _out=file_obj) self.assertTrue(len(out) == 0) file_obj.seek(0) actual_out = file_obj.read() file_obj.close() self.assertTrue(len(actual_out) != 0) # test with tee file_obj = tempfile.TemporaryFile() out = python(py.name, _out=file_obj, _tee=True) self.assertTrue(len(out) != 0) file_obj.seek(0) actual_out = file_obj.read() file_obj.close() self.assertTrue(len(actual_out) != 0) def test_err_redirection(self): import tempfile py = create_tmp_test(""" import sys import os sys.stdout.write("stdout") sys.stderr.write("stderr") """) file_obj = tempfile.TemporaryFile() p = python(py.name, _err=file_obj) file_obj.seek(0) stderr = file_obj.read().decode() file_obj.close() self.assertTrue(p.stdout == b"stdout") self.assertTrue(stderr == "stderr") self.assertTrue(len(p.stderr) == 0) # now with tee file_obj = tempfile.TemporaryFile() p = python(py.name, _err=file_obj, _tee="err") file_obj.seek(0) stderr = file_obj.read().decode() file_obj.close() self.assertTrue(p.stdout == b"stdout") self.assertTrue(stderr == "stderr") self.assertTrue(len(p.stderr) != 0) def test_err_redirection_actual_file(self): import tempfile file_obj = tempfile.NamedTemporaryFile() py = create_tmp_test(""" import sys import os sys.stdout.write("stdout") sys.stderr.write("stderr") """) stdout = python(py.name, _err=file_obj.name, u=True).wait() file_obj.seek(0) stderr = file_obj.read().decode() file_obj.close() self.assertTrue(stdout == "stdout") self.assertTrue(stderr == "stderr") def test_subcommand_and_bake(self): from sh import ls import getpass py = create_tmp_test(""" import sys import os import subprocess print("subcommand") subprocess.Popen(sys.argv[1:], shell=False).wait() """) cmd1 = python.bake(py.name) out = cmd1.whoami() self.assertTrue("subcommand" in out) self.assertTrue(getpass.getuser() in out) def test_multiple_bakes(self): from sh import whoami import getpass py = create_tmp_test(""" import sys import subprocess subprocess.Popen(sys.argv[1:], shell=False).wait() """) out = python.bake(py.name).bake("whoami")() self.assertTrue(getpass.getuser() == out.strip()) def test_bake_args_come_first(self): from sh import ls ls = ls.bake(h=True) ran = ls("-la").ran ft = ran.index("-h") self.assertTrue("-la" in ran[ft:]) def test_output_equivalence(self): from sh import whoami iam1 = whoami() iam2 = whoami() self.assertEqual(iam1, iam2) def test_stdout_callback(self): py = create_tmp_test(""" import sys import os for i in range(5): print(i) """) stdout = [] def agg(line): stdout.append(line) p = python(py.name, _out=agg, u=True) p.wait() self.assertTrue(len(stdout) == 5) def test_stdout_callback_no_wait(self): import time py = create_tmp_test(""" import sys import os import time for i in range(5): print(i) time.sleep(.5) """) stdout = [] def agg(line): stdout.append(line) p = python(py.name, _out=agg, u=True, _bg=True) # we give a little pause to make sure that the NamedTemporaryFile # exists when the python process actually starts time.sleep(.5) self.assertTrue(len(stdout) != 5) def test_stdout_callback_line_buffered(self): py = create_tmp_test(""" import sys import os for i in range(5): print("herpderp") """) stdout = [] def agg(line): stdout.append(line) p = python(py.name, _out=agg, _out_bufsize=1, u=True) p.wait() self.assertTrue(len(stdout) == 5) def test_stdout_callback_line_unbuffered(self): py = create_tmp_test(""" import sys import os for i in range(5): print("herpderp") """) stdout = [] def agg(char): stdout.append(char) p = python(py.name, _out=agg, _out_bufsize=0, u=True) p.wait() # + 5 newlines self.assertTrue(len(stdout) == (len("herpderp") * 5 + 5)) def test_stdout_callback_buffered(self): py = create_tmp_test(""" import sys import os for i in range(5): sys.stdout.write("herpderp") """) stdout = [] def agg(chunk): stdout.append(chunk) p = python(py.name, _out=agg, _out_bufsize=4, u=True) p.wait() self.assertTrue(len(stdout) == (len("herp") / 2 * 5)) def test_stdout_callback_with_input(self): py = create_tmp_test(""" import sys import os IS_PY3 = sys.version_info[0] == 3 if IS_PY3: raw_input = input for i in range(5): print(str(i)) derp = raw_input("herp? ") print(derp) """) def agg(line, stdin): if line.strip() == "4": stdin.put("derp\n") p = python(py.name, _out=agg, u=True, _tee=True) p.wait() self.assertTrue("derp" in p) def test_stdout_callback_exit(self): py = create_tmp_test(""" import sys import os for i in range(5): print(i) """) stdout = [] def agg(line): line = line.strip() stdout.append(line) if line == "2": return True p = python(py.name, _out=agg, u=True, _tee=True) p.wait() self.assertTrue("4" in p) self.assertTrue("4" not in stdout) def test_stdout_callback_terminate(self): import signal py = create_tmp_test(""" import sys import os import time for i in range(5): print(i) time.sleep(.5) """) stdout = [] def agg(line, stdin, process): line = line.strip() stdout.append(line) if line == "3": process.terminate() return True caught_signal = False try: p = python(py.name, _out=agg, u=True, _bg=True) p.wait() except sh.SignalException_SIGTERM: caught_signal = True self.assertTrue(caught_signal) self.assertEqual(p.process.exit_code, -signal.SIGTERM) self.assertTrue("4" not in p) self.assertTrue("4" not in stdout) def test_stdout_callback_kill(self): import signal import sh py = create_tmp_test(""" import sys import os import time for i in range(5): print(i) time.sleep(.5) """) stdout = [] def agg(line, stdin, process): line = line.strip() stdout.append(line) if line == "3": process.kill() return True caught_signal = False try: p = python(py.name, _out=agg, u=True, _bg=True) p.wait() except sh.SignalException_SIGKILL: caught_signal = True self.assertTrue(caught_signal) self.assertEqual(p.process.exit_code, -signal.SIGKILL) self.assertTrue("4" not in p) self.assertTrue("4" not in stdout) def test_general_signal(self): import signal from signal import SIGINT py = create_tmp_test(""" import sys import os import time import signal def sig_handler(sig, frame): print(10) exit(0) signal.signal(signal.SIGINT, sig_handler) for i in range(5): print(i) sys.stdout.flush() time.sleep(0.5) """) stdout = [] def agg(line, stdin, process): line = line.strip() stdout.append(line) if line == "3": process.signal(SIGINT) return True p = python(py.name, _out=agg, _tee=True) p.wait() self.assertEqual(p.process.exit_code, 0) self.assertEqual(p, "0\n1\n2\n3\n10\n") def test_iter_generator(self): py = create_tmp_test(""" import sys import os import time for i in range(42): print(i) sys.stdout.flush() """) out = [] for line in python(py.name, _iter=True): out.append(int(line.strip())) self.assertTrue(len(out) == 42 and sum(out) == 861) def test_nonblocking_iter(self): from errno import EWOULDBLOCK py = create_tmp_test(""" import time time.sleep(3) """) for line in python(py.name, _iter_noblock=True): break self.assertEqual(line, EWOULDBLOCK) def test_for_generator_to_err(self): py = create_tmp_test(""" import sys import os for i in range(42): sys.stderr.write(str(i)+"\\n") """) out = [] for line in python(py.name, _iter="err", u=True): out.append(line) self.assertTrue(len(out) == 42) # verify that nothing is going to stdout out = [] for line in python(py.name, _iter="out", u=True): out.append(line) self.assertTrue(len(out) == 0) def test_piped_generator(self): from sh import tr from string import ascii_uppercase import time py1 = create_tmp_test(""" import sys import os import time for letter in "andrew": time.sleep(0.6) print(letter) """) py2 = create_tmp_test(""" import sys import os import time while True: line = sys.stdin.readline() if not line: break print(line.strip().upper()) """) times = [] last_received = None letters = "" for line in python(python(py1.name, _piped="out", u=True), py2.name, _iter=True, u=True): if not letters: start = time.time() letters += line.strip() now = time.time() if last_received: times.append(now - last_received) last_received = now self.assertEqual("ANDREW", letters) self.assertTrue(all([t > .3 for t in times])) def test_generator_and_callback(self): py = create_tmp_test(""" import sys import os for i in range(42): sys.stderr.write(str(i * 2)+"\\n") print(i) """) stderr = [] def agg(line): stderr.append(int(line.strip())) out = [] for line in python(py.name, _iter=True, _err=agg, u=True): out.append(line) self.assertTrue(len(out) == 42) self.assertTrue(sum(stderr) == 1722) def test_bg_to_int(self): from sh import echo # bugs with background might cause the following error: # ValueError: invalid literal for int() with base 10: '' self.assertEqual(int(echo("123", _bg=True)), 123) def test_cwd(self): from sh import pwd from os.path import realpath self.assertEqual(str(pwd(_cwd="/tmp")), realpath("/tmp") + "\n") self.assertEqual(str(pwd(_cwd="/etc")), realpath("/etc") + "\n") def test_huge_piped_data(self): from sh import tr stdin = tempfile.NamedTemporaryFile() data = "herpderp" * 4000 + "\n" stdin.write(data.encode()) stdin.flush() stdin.seek(0) out = tr(tr("[:lower:]", "[:upper:]", _in=data), "[:upper:]", "[:lower:]") self.assertTrue(out == data) def test_tty_input(self): py = create_tmp_test(""" import sys import os if os.isatty(sys.stdin.fileno()): sys.stdout.write("password?\\n") sys.stdout.flush() pw = sys.stdin.readline().strip() sys.stdout.write("%s\\n" % ("*" * len(pw))) sys.stdout.flush() else: sys.stdout.write("no tty attached!\\n") sys.stdout.flush() """) test_pw = "test123" expected_stars = "*" * len(test_pw) d = {} def password_enterer(line, stdin): line = line.strip() if not line: return if line == "password?": stdin.put(test_pw + "\n") elif line.startswith("*"): d["stars"] = line return True pw_stars = python(py.name, _tty_in=True, _out=password_enterer) pw_stars.wait() self.assertEqual(d["stars"], expected_stars) response = python(py.name) self.assertEqual(response, "no tty attached!\n") def test_tty_output(self): py = create_tmp_test(""" import sys import os if os.isatty(sys.stdout.fileno()): sys.stdout.write("tty attached") sys.stdout.flush() else: sys.stdout.write("no tty attached") sys.stdout.flush() """) out = python(py.name, _tty_out=True) self.assertEqual(out, "tty attached") out = python(py.name, _tty_out=False) self.assertEqual(out, "no tty attached") def test_stringio_output(self): from sh import echo if IS_PY3: from io import StringIO from io import BytesIO as cStringIO else: from StringIO import StringIO from cStringIO import StringIO as cStringIO out = StringIO() echo("-n", "testing 123", _out=out) self.assertEqual(out.getvalue(), "testing 123") out = cStringIO() echo("-n", "testing 123", _out=out) self.assertEqual(out.getvalue().decode(), "testing 123") def test_stringio_input(self): from sh import cat if IS_PY3: from io import StringIO from io import BytesIO as cStringIO else: from StringIO import StringIO from cStringIO import StringIO as cStringIO input = StringIO() input.write("herpderp") input.seek(0) out = cat(_in=input) self.assertEqual(out, "herpderp") def test_internal_bufsize(self): from sh import cat output = cat(_in="a"*1000, _internal_bufsize=100, _out_bufsize=0) self.assertEqual(len(output), 100) output = cat(_in="a"*1000, _internal_bufsize=50, _out_bufsize=2) self.assertEqual(len(output), 100) def test_change_stdout_buffering(self): py = create_tmp_test(""" import sys import os # this proves that we won't get the output into our callback until we send # a newline sys.stdout.write("switch ") sys.stdout.flush() sys.stdout.write("buffering\\n") sys.stdout.flush() sys.stdin.read(1) sys.stdout.write("unbuffered") sys.stdout.flush() # this is to keep the output from being flushed by the process ending, which # would ruin our test. we want to make sure we get the string "unbuffered" # before the process ends, without writing a newline sys.stdin.read(1) """) d = { "newline_buffer_success": False, "unbuffered_success": False, } def interact(line, stdin, process): line = line.strip() if not line: return if line == "switch buffering": d["newline_buffer_success"] = True process.change_out_bufsize(0) stdin.put("a") elif line == "unbuffered": stdin.put("b") d["unbuffered_success"] = True return True # start with line buffered stdout pw_stars = python(py.name, _out=interact, _out_bufsize=1, u=True) pw_stars.wait() self.assertTrue(d["newline_buffer_success"]) self.assertTrue(d["unbuffered_success"]) def test_encoding(self): return raise NotImplementedError("what's the best way to test a different \ '_encoding' special keyword argument?") def test_timeout(self): from sh import sleep from time import time # check that a normal sleep is more or less how long the whole process # takes sleep_for = 3 started = time() sh.sleep(sleep_for).wait() elapsed = time() - started self.assertTrue(abs(elapsed - sleep_for) < 0.5) # now make sure that killing early makes the process take less time sleep_for = 3 timeout = 1 started = time() try: sh.sleep(sleep_for, _timeout=timeout).wait() except sh.TimeoutException: pass elapsed = time() - started self.assertTrue(abs(elapsed - timeout) < 0.5) def test_binary_pipe(self): binary = b'\xec;\xedr\xdbF\x92\xf9\x8d\xa7\x98\x02/\x15\xd2K\xc3\x94d\xc9' py1 = create_tmp_test(""" import sys import os sys.stdout = os.fdopen(sys.stdout.fileno(), "wb", 0) sys.stdout.write(%r) """ % binary) py2 = create_tmp_test(""" import sys import os sys.stdin = os.fdopen(sys.stdin.fileno(), "rb", 0) sys.stdout = os.fdopen(sys.stdout.fileno(), "wb", 0) sys.stdout.write(sys.stdin.read()) """) out = python(python(py1.name), py2.name) self.assertEqual(out.stdout, binary) def test_auto_change_buffering(self): binary = b'\xec;\xedr\xdbF\x92\xf9\x8d\xa7\x98\x02/\x15\xd2K\xc3\x94d\xc9' py1 = create_tmp_test(""" import sys import os import time sys.stdout = os.fdopen(sys.stdout.fileno(), "wb", 0) sys.stdout.write(b"testing") sys.stdout.flush() # to ensure that sh's select loop picks up the write before we write again time.sleep(0.5) sys.stdout.write(b"again\\n") sys.stdout.flush() time.sleep(0.5) sys.stdout.write(%r) sys.stdout.flush() """ % binary) out = python(py1.name, _out_bufsize=1) self.assertTrue(out.stdout == b'testingagain\n\xec;\xedr\xdbF\x92\xf9\x8d\xa7\x98\x02/\x15\xd2K\xc3\x94d\xc9') # designed to trigger the "... (%d more, please see e.stdout)" output # of the ErrorReturnCode class def test_failure_with_large_output(self): from sh import ErrorReturnCode_1 py = create_tmp_test(""" print("andrewmoffat" * 1000) exit(1) """) self.assertRaises(ErrorReturnCode_1, python, py.name) # designed to check if the ErrorReturnCode constructor does not raise # an UnicodeDecodeError def test_non_ascii_error(self): from sh import ls, ErrorReturnCode test = "/á" # coerce to unicode if IS_PY3: pass else: test = test.decode("utf8") self.assertRaises(ErrorReturnCode, ls, test) def test_no_out(self): py = create_tmp_test(""" import sys sys.stdout.write("stdout") sys.stderr.write("stderr") """) p = python(py.name, _no_out=True) self.assertEqual(p.stdout, b"") self.assertEqual(p.stderr, b"stderr") self.assertTrue(p.process._pipe_queue.empty()) def callback(line): pass p = python(py.name, _out=callback) self.assertEqual(p.stdout, b"") self.assertEqual(p.stderr, b"stderr") self.assertTrue(p.process._pipe_queue.empty()) p = python(py.name) self.assertEqual(p.stdout, b"stdout") self.assertEqual(p.stderr, b"stderr") self.assertFalse(p.process._pipe_queue.empty()) def test_no_err(self): py = create_tmp_test(""" import sys sys.stdout.write("stdout") sys.stderr.write("stderr") """) p = python(py.name, _no_err=True) self.assertEqual(p.stderr, b"") self.assertEqual(p.stdout, b"stdout") self.assertFalse(p.process._pipe_queue.empty()) def callback(line): pass p = python(py.name, _err=callback) self.assertEqual(p.stderr, b"") self.assertEqual(p.stdout, b"stdout") self.assertFalse(p.process._pipe_queue.empty()) p = python(py.name) self.assertEqual(p.stderr, b"stderr") self.assertEqual(p.stdout, b"stdout") self.assertFalse(p.process._pipe_queue.empty()) def test_no_pipe(self): from sh import ls # calling a command regular should fill up the pipe_queue p = ls() self.assertFalse(p.process._pipe_queue.empty()) # calling a command with a callback should not def callback(line): pass p = ls(_out=callback) self.assertTrue(p.process._pipe_queue.empty()) # calling a command regular with no_pipe also should not p = ls(_no_pipe=True) self.assertTrue(p.process._pipe_queue.empty()) def test_decode_error_handling(self): from functools import partial py = create_tmp_test(""" # -*- coding: utf8 -*- import sys import os sys.stdout = os.fdopen(sys.stdout.fileno(), 'wb') IS_PY3 = sys.version_info[0] == 3 if IS_PY3: sys.stdout.write(bytes("te漢字st", "utf8")) else: sys.stdout.write("te漢字st") """) fn = partial(python, py.name, _encoding="ascii") def s(fn): str(fn()) self.assertRaises(UnicodeDecodeError, s, fn) p = python(py.name, _encoding="ascii", _decode_errors="ignore") self.assertEqual(p, "test") def test_shared_secial_args(self): import sh if IS_PY3: from io import StringIO from io import BytesIO as cStringIO else: from StringIO import StringIO from cStringIO import StringIO as cStringIO out1 = sh.ls('.') out2 = StringIO() sh_new = sh(_out=out2) sh_new.ls('.') self.assertEqual(out1, out2.getvalue()) out2.close() def test_signal_exception(self): from sh import SignalException_15 def throw_terminate_signal(): py = create_tmp_test(""" import time while True: time.sleep(1) """) to_kill = python(py.name, _bg=True) to_kill.terminate() to_kill.wait() self.assertRaises(SignalException_15, throw_terminate_signal) def test_file_output_isnt_buffered(self): # https://github.com/amoffat/sh/issues/147 import time expected_time_increment = 0.2 py = create_tmp_test(""" from time import sleep import sys for i in range(5): print(i) i += 1 sleep(%.2f) """ % expected_time_increment) file_obj = tempfile.TemporaryFile() p = python(py.name, _out=file_obj, _bg=True) # now we're going to test that the output file receives a chunk of # data roughly every expected_time_increment seconds, to prove that # output is being flushed last_pos = 0 last_pos_time = 0 times = [] timeout = 5 started = time.time() for i in range(5): while True: now = time.time() if now - started > timeout: self.fail("test timed out") # check if the end of our file has grown file_obj.seek(0, 2) cur_pos = file_obj.tell() if cur_pos > last_pos: last_pos = cur_pos if last_pos_time == 0: delta = 0 else: delta = now - last_pos_time if last_pos_time > 0: self.assertTrue(abs(delta - expected_time_increment) <= expected_time_increment * 0.5) last_pos_time = now break p.wait() file_obj.close() def test_pushd(self): """ test that pushd is just a specialized form of sh.args """ import os old_wd = os.getcwd() with sh.pushd(tempdir): new_wd = sh.pwd().strip() self.assertNotEqual(old_wd, tempdir) self.assertEqual(old_wd, os.getcwd()) self.assertEqual(new_wd, tempdir) def test_args_context(self): """ test that we can use the args with-context to temporarily override command settings """ import os old_wd = os.getcwd() with sh.args(_cwd=tempdir): new_wd = sh.pwd().strip() # sanity self.assertNotEqual(old_wd, tempdir) self.assertEqual(old_wd, os.getcwd()) self.assertEqual(new_wd, tempdir) def test_piped_direct(self): from sh import ls, wc # sanity check that our ls shows something p1 = ls("-A1") self.assertNotEqual(str(p1), "") # now let's run it again with direct piping. this should yield no # visible output, because all the stdout is written to the process's # stdout fd p2 = ls("-A1", _piped="direct") p2.wait() self.assertEqual(str(p2), "") # now let us confirm that composing this function with another lets the # outer function read from that stdout fd directly c1 = int(wc(p2, l=True).strip()) c2 = len(os.listdir(".")) self.assertEqual(c1, c2) def test_non_existant_cwd(self): from sh import ls # sanity check non_exist_dir = join(tempdir, "aowjgoahewro") self.assertFalse(exists(non_exist_dir)) self.assertRaises(OSError, ls, _cwd=non_exist_dir) # https://github.com/amoffat/sh/issues/176 def test_baked_command_can_be_printed(self): from sh import ls ll = ls.bake("-l") self.assertTrue(str(ll).endswith("/ls -l")) # https://github.com/amoffat/sh/issues/185 def test_done_callback(self): import time class Callback(object): def __init__(self): self.called = False self.exit_code = None def __call__(self, p): self.called = True self.exit_code = p.exit_code py = create_tmp_test(""" from time import time, sleep sleep(1) print(time()) """) callback = Callback() p = python(py.name, _done=callback) # do a little setup to prove that a command with a _done callback is run # in the background wait_start = time.time() p.wait() wait_elapsed = time.time() - wait_start self.assertTrue(callback.called) self.assertTrue(abs(wait_elapsed - 1.0) < 0.1) self.assertEqual(callback.exit_code, 0) def test_done_cb_exc(self): from sh import ErrorReturnCode class Callback(object): def __init__(self): self.called = False def __call__(self, p): self.called = True py = create_tmp_test("exit(1)") callback = Callback() try: p = python(py.name, _done=callback) p.wait() except ErrorReturnCode: self.assertFalse(callback.called) else: self.fail("command should've thrown an exception") def test_stdin_unbuffered_bufsize(self): import sh from time import sleep # this tries to receive some known data and measures the time it takes # to receive it. since we're flushing by newline, we should only be # able to receive the data when a newline is fed in py = create_tmp_test(""" import sys from time import time started = time() data = sys.stdin.read(len("testing")) waited = time() - started sys.stdout.write(data + "\\n") sys.stdout.write(str(waited) + "\\n") started = time() data = sys.stdin.read(len("done")) waited = time() - started sys.stdout.write(data + "\\n") sys.stdout.write(str(waited) + "\\n") sys.stdout.flush() """) def create_stdin(): data = {"counter": 0} def stdin(): if data["counter"] == 0: data["counter"] += 1 return "test" elif data["counter"] == 1: data["counter"] += 1 sleep(1) return "ing" elif data["counter"] == 2: data["counter"] += 1 sleep(1) return "done" else: raise sh.DoneReadingForever return stdin out = python(py.name, _in=create_stdin(), _in_bufsize=0) word1, time1, word2, time2, _ = out.split("\n") time1 = float(time1) time2 = float(time2) self.assertEqual(word1, "testing") self.assertTrue(abs(1-time1) < 0.1) self.assertEqual(word2, "done") self.assertTrue(abs(1-time2) < 0.1) def test_stdin_newline_bufsize(self): import sh from time import sleep # this tries to receive some known data and measures the time it takes # to receive it. since we're flushing by newline, we should only be # able to receive the data when a newline is fed in py = create_tmp_test(""" import sys from time import time started = time() data = sys.stdin.read(len("testing\\n")) waited = time() - started sys.stdout.write(data) sys.stdout.write(str(waited) + "\\n") started = time() data = sys.stdin.read(len("done\\n")) waited = time() - started sys.stdout.write(data) sys.stdout.write(str(waited) + "\\n") sys.stdout.flush() """) # we'll feed in text incrementally, sleeping strategically before # sending a newline. we then measure the amount that we slept # indirectly in the child process def create_stdin(): data = {"counter": 0} def stdin(): if data["counter"] == 0: data["counter"] += 1 return "test" elif data["counter"] == 1: sleep(1) data["counter"] += 1 return "ing\n" elif data["counter"] == 2: sleep(1) return "done\n" else: raise sh.DoneReadingForever return stdin out = python(py.name, _in=create_stdin(), _in_bufsize=1) word1, time1, word2, time2, _ = out.split("\n") time1 = float(time1) time2 = float(time2) self.assertEqual(word1, "testing") self.assertTrue(abs(1-time1) < 0.1) self.assertEqual(word2, "done") self.assertTrue(abs(1-time2) < 0.1) def test_custom_timeout_signal(self): from sh import TimeoutException import signal py = create_tmp_test(""" import time time.sleep(3) """) try: python(py.name, _timeout=1, _timeout_signal=signal.SIGQUIT) except TimeoutException as e: self.assertEqual(e.exit_code, signal.SIGQUIT) else: self.fail("we should have handled a TimeoutException") def test_partially_applied_callback(self): from functools import partial py = create_tmp_test(""" for i in range(10): print(i) """) output = [] def fn(foo, line): output.append((foo, int(line.strip()))) log_line = partial(fn, "hello") out = python(py.name, _out=log_line) self.assertEqual(output, [("hello", i) for i in range(10)]) output = [] def fn(foo, line, stdin, proc): output.append((foo, int(line.strip()))) log_line = partial(fn, "hello") out = python(py.name, _out=log_line) self.assertEqual(output, [("hello", i) for i in range(10)]) class MiscTests(unittest.TestCase): def test_percent_doesnt_fail_logging(self): """ test that a command name doesn't interfere with string formatting in the internal loggers """ py = create_tmp_test(""" print("cool") """) out = python(py.name, "%") out = python(py.name, "%%") out = python(py.name, "%%%") @requires_utf8 def test_unicode_path(self): from sh import Command py = create_tmp_test("""#!/usr/bin/env python # -*- coding: utf8 -*- print("字") """, "字", delete=False) try: py.close() os.chmod(py.name, int(0o755)) cmd = Command(py.name) # all of these should behave just fine str(cmd) repr(cmd) unicode(cmd) running = cmd() str(running) repr(running) unicode(running) str(running.process) repr(running.process) unicode(running.process) finally: os.unlink(py.name) # https://github.com/amoffat/sh/issues/121 def test_wraps(self): from sh import ls wraps(ls)(lambda f: True) def test_signal_exception_aliases(self): """ proves that signal exceptions with numbers and names are equivalent """ import signal import sh sig_name = "SignalException_%d" % signal.SIGQUIT sig = getattr(sh, sig_name) from sh import SignalException_SIGQUIT self.assertEqual(sig, SignalException_SIGQUIT) class StreamBuffererTests(unittest.TestCase): def test_unbuffered(self): from sh import _disable_whitelist, StreamBufferer b = StreamBufferer(0) self.assertEqual(b.process(b"test"), [b"test"]) self.assertEqual(b.process(b"one"), [b"one"]) self.assertEqual(b.process(b""), [b""]) self.assertEqual(b.flush(), b"") def test_newline_buffered(self): from sh import _disable_whitelist, StreamBufferer b = StreamBufferer(1) self.assertEqual(b.process(b"testing\none\ntwo"), [b"testing\n", b"one\n"]) self.assertEqual(b.process(b"\nthree\nfour"), [b"two\n", b"three\n"]) self.assertEqual(b.flush(), b"four") def test_chunk_buffered(self): from sh import _disable_whitelist, StreamBufferer b = StreamBufferer(10) self.assertEqual(b.process(b"testing\none\ntwo"), [b"testing\non"]) self.assertEqual(b.process(b"\nthree\n"), [b"e\ntwo\nthre"]) self.assertEqual(b.flush(), b"e\n") if __name__ == "__main__": # if we're running a specific test, we can let unittest framework figure out # that test and run it itself. it will also handle setting the return code # of the process if any tests error or fail if len(sys.argv) > 1: unittest.main() # otherwise, it looks like we want to run all the tests else: suite = unittest.TestLoader().loadTestsFromModule(sys.modules[__name__]) result = unittest.TextTestRunner(verbosity=2).run(suite) if not result.wasSuccessful(): exit(1) sh-1.11/setup.py0000664000175000017500000000232712450675064014653 0ustar amoffatamoffat00000000000000from __future__ import print_function import os import sys import sh try: from distutils.core import setup except ImportError: from setuptools import setup setup( name="sh", version=sh.__version__, description="Python subprocess interface", author="Andrew Moffat", author_email="andrew.robert.moffat@gmail.com", url="https://github.com/amoffat/sh", license="MIT", py_modules=["sh"], classifiers=[ "Development Status :: 5 - Production/Stable", "Environment :: Console", "Intended Audience :: Developers", "Intended Audience :: System Administrators", "License :: OSI Approved :: MIT License", "Programming Language :: Python", "Programming Language :: Python :: 2", "Programming Language :: Python :: 2.6", "Programming Language :: Python :: 2.7", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.1", "Programming Language :: Python :: 3.2", "Programming Language :: Python :: 3.3", "Programming Language :: Python :: 3.4", "Topic :: Software Development :: Build Tools", "Topic :: Software Development :: Libraries :: Python Modules", ], ) sh-1.11/LICENSE.txt0000664000175000017500000000205112447067575014766 0ustar amoffatamoffat00000000000000Copyright (C) 2011-2012 by Andrew Moffat Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. sh-1.11/README.md0000664000175000017500000000222112450700616014401 0ustar amoffatamoffat00000000000000[![Build Status](https://travis-ci.org/amoffat/sh.png)](https://travis-ci.org/amoffat/sh) [![Coverage Status](https://coveralls.io/repos/amoffat/sh/badge.png?branch=master)](https://coveralls.io/r/amoffat/sh?branch=master) [![Version](https://pypip.in/v/sh/badge.png)](https://pypi.python.org/pypi/sh) [![Downloads](https://pypip.in/d/sh/badge.png)](https://pypi.python.org/pypi/sh) sh (previously [pbs](http://pypi.python.org/pypi/pbs)) is a full-fledged subprocess replacement for Python 2.6 - 3.4 that allows you to call any program as if it were a function: ```python from sh import ifconfig print ifconfig("eth0") ``` sh is not a collection of system commands implemented in Python. # Installation $> pip install sh # Complete documentation @ http://amoffat.github.com/sh # Testing First install the development requirements: $> pip install -r requirements-dev.txt Then use [tox](http://tox.readthedocs.org/en/latest/index.html) test runner: $> tox To run a single test for all environments: $> tox FunctionalTests.test_unicode_arg To run a single test for a single environment: $> tox -e py34 FunctionalTests.test_unicode_arg sh-1.11/CHANGELOG.md0000664000175000017500000001546412450675064014760 0ustar amoffatamoffat00000000000000# Changelog ## 1.10 - 12/30/14 * partially applied functions with `functools.partial` have been fixed for `_out` and `_err` callbacks [#160](https://github.com/amoffat/sh/issues/160) * `_out` or `_err` being callables no longer puts the running command in the background. to achieve the previous behavior, pass `_bg=True` to your command. * deprecated `_with` contexts [#195](https://github.com/amoffat/sh/issues/195) * `_timeout_signal` allows you to specify your own signal to kill a timed-out process with. use a constant from the `signal` stdlib module. [#171](https://github.com/amoffat/sh/issues/171) * signal exceptions can now be caught by number or name. `SignalException_9 == SignalException_SIGKILL` * child processes that timeout via `_timeout` raise `sh.TimeoutException` instead of `sh.SignalExeception_9` [#172](https://github.com/amoffat/sh/issues/172) * fixed `help(sh)` from the python shell and `pydoc sh` from the command line. [#173](https://github.com/amoffat/sh/issues/173) * program names can no longer be shadowed by names that sh.py defines internally. removed the requirement of trailing underscores for programs that could have their names shadowed, like `id`. * memory optimization when a child process's stdin is a newline-delimted string and our bufsize is newlines * feature, `_done` special keyword argument that accepts a callback to be called when the command completes successfully [#185](https://github.com/amoffat/sh/issues/185) * bugfix for being unable to print a baked command in python3+ [#176](https://github.com/amoffat/sh/issues/176) * bugfix for cwd not existing and causing the child process to continue running parent process code [#202](https://github.com/amoffat/sh/issues/202) * child process is now guaranteed to exit on exception between fork and exec. * fix python2 deprecation warning when running with -3 [PR #165](https://github.com/amoffat/sh/pull/165) * bugfix where sh.py was attempting to execute directories [#196](https://github.com/amoffat/sh/issues/196), [PR #189](https://github.com/amoffat/sh/pull/189) * only backgrounded processes will ignore SIGHUP * allowed `ok_code` to take a `range` object. [#PR 210](https://github.com/amoffat/sh/pull/210/files) * added `sh.args` with context which allows overriding of all command defaults for the duration of that context. * added `sh.pushd` with context which takes a directory name and changes to that directory for the duration of that with context. [PR #206](https://github.com/amoffat/sh/pull/206) * tests now include python 3.4 if available. tests also stop on the first python that suite that fails. * SIGABRT, SIGBUS, SIGFPE, SIGILL, SIGPIPE, SIGSYS have been added to the list of signals that throw an exception [PR #201](https://github.com/amoffat/sh/pull/201) * "callable" builtin has been faked for python3.1, which lacks it. * "direct" option added to `_piped` special keyword argument, which allows sh to hand off a process's stdout fd directly to another process, instead of buffering its stdout internally, then handing it off. [#119](https://github.com/amoffat/sh/issues/119) ## 1.09 - 9/08/13 * Fixed encoding errors related to a system encoding "ascii". [#123](https://github.com/amoffat/sh/issues/123) * Added exit_code attribute to SignalException and ErrorReturnCode exception classes. [#127](https://github.com/amoffat/sh/issues/127) * Making the default behavior of spawned processes to not be explicitly killed when the parent python process ends. Also making the spawned process ignore SIGHUP. [#139](https://github.com/amoffat/sh/issues/139) * Made OSX sleep hack to apply to PY2 as well as PY3. ## 1.08 - 1/29/12 * Added SignalException class and made all commands that end terminate by a signal defined in SIGNALS_THAT_SHOULD_THROW_EXCEPTION raise it. [#91](https://github.com/amoffat/sh/issues/91) * Bugfix where CommandNotFound was not being raised if Command was created by instantiation. [#113](https://github.com/amoffat/sh/issues/113) * Bugfix for Commands that are wrapped with functools.wraps() [#121](https://github.com/amoffat/sh/issues/121] * Bugfix where input arguments were being assumed as ascii or unicode, but never as a string in a different encoding. * _long_sep keyword argument added joining together a dictionary of arguments passed in to a command * Commands can now be passed a dictionary of args, and the keys will be interpretted "raw", with no underscore-to-hyphen conversion * Reserved Python keywords can now be used as subcommands by appending an underscore `_` to them ## 1.07 - 11/21/12 * Bugfix for PyDev when `locale.getpreferredencoding()` is empty. * Fixes for IPython3 that involve `sh.` and `sh?` * Added `_tee` special keyword argument to force stdout/stderr to store internally and make available for piping data that is being redirected. * Added `_decode_errors` to be passed to all stdout/stderr decoding of a process. * Added `_no_out`, `_no_err`, and `_no_pipe` special keyword arguments. These are used for long-running processes with lots of output. * Changed custom loggers that were created for each process to fixed loggers, so there are no longer logger references laying around in the logging module after the process ends and it garbage collected. ## 1.06 - 11/10/12 * Removed old undocumented cruft of ARG1..ARGN and ARGV. * Bugfix where `logging_enabled` could not be set from the importing module. * Disabled garbage collection before fork to prevent garbage collection in child process. * Major bugfix where cyclical references were preventing process objects (and their associated stdout/stderr buffers) from being garbage collected. * Bugfix in RunningCommand and OProc loggers, which could get really huge if a command was called that had a large number of arguments. ## 1.05 - 10/20/12 * Changing status from alpha to beta. * Python 3.3 officially supported. * Documentation fix. The section on exceptions now references the fact that signals do not raise an exception, even for signals that might seem like they should, e.g. segfault. * Bugfix with Python 3.3 where importing commands from the sh namespace resulted in an error related to `__path__` * Long-form and short-form options to commands may now be given False to disable the option from being passed into the command. This is useful to pass in a boolean flag that you flip to either True or False to enable or disable some functionality at runtime. ## 1.04 - 10/07/12 * Making `Command` class resolve the `path` parameter with `which` by default instead of expecting it to be resolved before it is passed in. This change shouldn't affect backwards compatibility. * Fixing a bug when an exception is raised from a program, and the error output has non-ascii text. This didn't work in Python < 3.0, because .decode()'s default encoding is typically ascii. sh-1.11/sh.py0000664000175000017500000023443412451024767014132 0ustar amoffatamoffat00000000000000""" http://amoffat.github.io/sh/ """ #=============================================================================== # Copyright (C) 2011-2015 by Andrew Moffat # # Permission is hereby granted, free of charge, to any person obtaining a copy # of this software and associated documentation files (the "Software"), to deal # in the Software without restriction, including without limitation the rights # to use, copy, modify, merge, publish, distribute, sublicense, and/or sell # copies of the Software, and to permit persons to whom the Software is # furnished to do so, subject to the following conditions: # # The above copyright notice and this permission notice shall be included in # all copies or substantial portions of the Software. # # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE # AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN # THE SOFTWARE. #=============================================================================== __version__ = "1.11" __project_url__ = "https://github.com/amoffat/sh" import platform if "windows" in platform.system().lower(): raise ImportError("sh %s is currently only supported on linux and osx. \ please install pbs 0.110 (http://pypi.python.org/pypi/pbs) for windows \ support." % __version__) import sys IS_PY3 = sys.version_info[0] == 3 import traceback import os import re from glob import glob as original_glob import time from types import ModuleType from functools import partial import inspect from contextlib import contextmanager from locale import getpreferredencoding DEFAULT_ENCODING = getpreferredencoding() or "UTF-8" if IS_PY3: from io import StringIO from io import BytesIO as cStringIO from queue import Queue, Empty # for some reason, python 3.1 removed the builtin "callable", wtf if not hasattr(__builtins__, "callable"): def callable(ob): return hasattr(ob, "__call__") else: from StringIO import StringIO from cStringIO import OutputType as cStringIO from Queue import Queue, Empty IS_OSX = platform.system() == "Darwin" THIS_DIR = os.path.dirname(os.path.realpath(__file__)) SH_LOGGER_NAME = "sh" import errno import warnings import pty import termios import signal import gc import select import threading import tty import fcntl import struct import resource from collections import deque import logging import weakref # TODO remove with contexts in next version def with_context_warning(): warnings.warn(""" with contexts are deprecated because they are not thread safe. they will be \ removed in the next version. use subcommands instead \ http://amoffat.github.io/sh/#sub-commands. see \ https://github.com/amoffat/sh/issues/195 """.strip(), stacklevel=3) if IS_PY3: raw_input = input unicode = str basestring = str _unicode_methods = set(dir(unicode())) def encode_to_py3bytes_or_py2str(s): """ takes anything and attempts to return a py2 string or py3 bytes. this is typically used when creating command + arguments to be executed via os.exec* """ fallback_encoding = "utf8" if IS_PY3: # if we're already bytes, do nothing if isinstance(s, bytes): pass else: s = str(s) try: s = bytes(s, DEFAULT_ENCODING) except UnicodeEncodeError: s = bytes(s, fallback_encoding) else: # attempt to convert the thing to unicode from the system's encoding try: s = unicode(s, DEFAULT_ENCODING) # if the thing is already unicode, or it's a number, it can't be # coerced to unicode with an encoding argument, but if we leave out # the encoding argument, it will convert it to a string, then to unicode except TypeError: s = unicode(s) # now that we have guaranteed unicode, encode to our system encoding, # but attempt to fall back to something try: s = s.encode(DEFAULT_ENCODING) except: s = s.encode(fallback_encoding) return s class ErrorReturnCode(Exception): """ base class for all exceptions as a result of a command's exit status being deemed an error. this base class is dynamically subclassed into derived classes with the format: ErrorReturnCode_NNN where NNN is the exit code number. the reason for this is it reduces boiler plate code when testing error return codes: try: some_cmd() except ErrorReturnCode_12: print("couldn't do X") vs: try: some_cmd() except ErrorReturnCode as e: if e.exit_code == 12: print("couldn't do X") it's not much of a savings, but i believe it makes the code easier to read """ truncate_cap = 750 def __init__(self, full_cmd, stdout, stderr): self.full_cmd = full_cmd self.stdout = stdout self.stderr = stderr if self.stdout is None: exc_stdout = "" else: exc_stdout = self.stdout[:self.truncate_cap] out_delta = len(self.stdout) - len(exc_stdout) if out_delta: exc_stdout += ("... (%d more, please see e.stdout)" % out_delta).encode() if self.stderr is None: exc_stderr = "" else: exc_stderr = self.stderr[:self.truncate_cap] err_delta = len(self.stderr) - len(exc_stderr) if err_delta: exc_stderr += ("... (%d more, please see e.stderr)" % err_delta).encode() msg = "\n\n RAN: %r\n\n STDOUT:\n%s\n\n STDERR:\n%s" % \ (full_cmd, exc_stdout.decode(DEFAULT_ENCODING, "replace"), exc_stderr.decode(DEFAULT_ENCODING, "replace")) super(ErrorReturnCode, self).__init__(msg) class SignalException(ErrorReturnCode): pass class TimeoutException(Exception): """ the exception thrown when a command is killed because a specified timeout (via _timeout) was hit """ def __init__(self, exit_code): self.exit_code = exit_code super(Exception, self).__init__() SIGNALS_THAT_SHOULD_THROW_EXCEPTION = ( signal.SIGABRT, signal.SIGBUS, signal.SIGFPE, signal.SIGILL, signal.SIGINT, signal.SIGKILL, signal.SIGPIPE, signal.SIGQUIT, signal.SIGSEGV, signal.SIGTERM, signal.SIGSYS, ) # we subclass AttributeError because: # https://github.com/ipython/ipython/issues/2577 # https://github.com/amoffat/sh/issues/97#issuecomment-10610629 class CommandNotFound(AttributeError): pass rc_exc_regex = re.compile("(ErrorReturnCode|SignalException)_((\d+)|SIG\w+)") rc_exc_cache = {} def get_exc_from_name(name): """ takes an exception name, like: ErrorReturnCode_1 SignalException_9 SignalException_SIGHUP and returns the corresponding exception. this is primarily used for importing exceptions from sh into user code, for instance, to capture those exceptions """ exc = None try: return rc_exc_cache[name] except KeyError: m = rc_exc_regex.match(name) if m: base = m.group(1) rc_or_sig_name = m.group(2) if base == "SignalException": try: rc = -int(rc_or_sig_name) except ValueError: rc = -getattr(signal, rc_or_sig_name) else: rc = int(rc_or_sig_name) exc = get_rc_exc(rc) return exc def get_rc_exc(rc_or_sig_name): """ takes a exit code, signal number, or signal name, and produces an exception that corresponds to that return code. positive return codes yield ErrorReturnCode exception, negative return codes yield SignalException we also cache the generated exception so that only one signal of that type exists, preserving identity """ try: rc = int(rc_or_sig_name) except ValueError: rc = -getattr(signal, rc_or_sig_name) try: return rc_exc_cache[rc] except KeyError: pass if rc > 0: name = "ErrorReturnCode_%d" % rc base = ErrorReturnCode else: name = "SignalException_%d" % abs(rc) base = SignalException exc = type(name, (base,), {"exit_code": rc}) rc_exc_cache[rc] = exc return exc def which(program): def is_exe(fpath): return (os.path.exists(fpath) and os.access(fpath, os.X_OK) and os.path.isfile(os.path.realpath(fpath))) fpath, fname = os.path.split(program) if fpath: if is_exe(program): return program else: if "PATH" not in os.environ: return None for path in os.environ["PATH"].split(os.pathsep): exe_file = os.path.join(path, program) if is_exe(exe_file): return exe_file return None def resolve_program(program): path = which(program) if not path: # our actual command might have a dash in it, but we can't call # that from python (we have to use underscores), so we'll check # if a dash version of our underscore command exists and use that # if it does if "_" in program: path = which(program.replace("_", "-")) if not path: return None return path # we add this thin wrapper to glob.glob because of a specific edge case where # glob does not expand to anything. for example, if you try to do # glob.glob("*.py") and there are no *.py files in the directory, glob.glob # returns an empty list. this empty list gets passed to the command, and # then the command fails with a misleading error message. this thin wrapper # ensures that if there is no expansion, we pass in the original argument, # so that when the command fails, the error message is clearer def glob(arg): return original_glob(arg) or arg class Logger(object): """ provides a memory-inexpensive logger. a gotcha about python's builtin logger is that logger objects are never garbage collected. if you create a thousand loggers with unique names, they'll sit there in memory until your script is done. with sh, it's easy to create loggers with unique names if we want our loggers to include our command arguments. for example, these are all unique loggers: ls -l ls -l /tmp ls /tmp so instead of creating unique loggers, and without sacrificing logging output, we use this class, which maintains as part of its state, the logging "context", which will be the very unique name. this allows us to get a logger with a very general name, eg: "command", and have a unique name appended to it via the context, eg: "ls -l /tmp" """ def __init__(self, name, context=None): self.name = name if context: context = context.replace("%", "%%") self.context = context self.log = logging.getLogger("%s.%s" % (SH_LOGGER_NAME, name)) def _format_msg(self, msg, *args): if self.context: msg = "%s: %s" % (self.context, msg) return msg % args def get_child(self, name, context): new_name = self.name + "." + name new_context = self.context + "." + context l = Logger(new_name, new_context) return l def info(self, msg, *args): self.log.info(self._format_msg(msg, *args)) def debug(self, msg, *args): self.log.debug(self._format_msg(msg, *args)) def error(self, msg, *args): self.log.error(self._format_msg(msg, *args)) def exception(self, msg, *args): self.log.exception(self._format_msg(msg, *args)) def friendly_truncate(s, max_len): if len(s) > max_len: s = "%s...(%d more)" % (s[:max_len], len(s) - max_len) return s class RunningCommand(object): """ this represents an executing Command object. it is returned as the result of __call__() being executed on a Command instance. this creates a reference to a OProc instance, which is a low-level wrapper around the process that was exec'd this is the class that gets manipulated the most by user code, and so it implements various convenience methods and logical mechanisms for the underlying process. for example, if a user tries to access a backgrounded-process's stdout/err, the RunningCommand object is smart enough to know to wait() on the process to finish first. and when the process finishes, RunningCommand is smart enough to translate exit codes to exceptions. """ def __init__(self, cmd, call_args, stdin, stdout, stderr): # self.ran is used for auditing what actually ran. for example, in # exceptions, or if you just want to know what was ran after the # command ran if IS_PY3: self.ran = " ".join([arg.decode(DEFAULT_ENCODING, "ignore") for arg in cmd]) else: self.ran = " ".join(cmd) friendly_cmd = friendly_truncate(self.ran, 20) friendly_call_args = friendly_truncate(str(call_args), 20) # we're setting up the logger string here, instead of __repr__ because # we reserve __repr__ to behave as if it was evaluating the child # process's output logger_str = "" % (friendly_cmd, friendly_call_args) self.log = Logger("command", logger_str) self.call_args = call_args self.cmd = cmd self.process = None self._process_completed = False should_wait = True spawn_process = True # with contexts shouldn't run at all yet, they prepend # to every command in the context if call_args["with"]: spawn_process = False Command._prepend_stack.append(self) if call_args["piped"] or call_args["iter"] or call_args["iter_noblock"]: should_wait = False # we're running in the background, return self and let us lazily # evaluate if call_args["bg"]: should_wait = False # redirection if call_args["err_to_out"]: stderr = OProc.STDOUT # set up which stream should write to the pipe # TODO, make pipe None by default and limit the size of the Queue # in oproc.OProc pipe = OProc.STDOUT if call_args["iter"] == "out" or call_args["iter"] is True: pipe = OProc.STDOUT elif call_args["iter"] == "err": pipe = OProc.STDERR if call_args["iter_noblock"] == "out" or call_args["iter_noblock"] is True: pipe = OProc.STDOUT elif call_args["iter_noblock"] == "err": pipe = OProc.STDERR # there's currently only one case where we wouldn't spawn a child # process, and that's if we're using a with-context with our command if spawn_process: self.log.info("starting process") self.process = OProc(self.log, cmd, stdin, stdout, stderr, self.call_args, pipe) if should_wait: self.wait() def wait(self): if not self._process_completed: self._process_completed = True exit_code = self.process.wait() if self.process.timed_out: # if we timed out, our exit code represents a signal, which is # negative, so let's make it positive to store in our # TimeoutException raise TimeoutException(-exit_code) else: self.handle_command_exit_code(exit_code) # https://github.com/amoffat/sh/issues/185 if self.call_args["done"]: self.call_args["done"](self) return self def handle_command_exit_code(self, code): """ here we determine if we had an exception, or an error code that we weren't expecting to see. if we did, we create and raise an exception """ if (code not in self.call_args["ok_code"] and (code > 0 or -code in SIGNALS_THAT_SHOULD_THROW_EXCEPTION)): exc = get_rc_exc(code) raise exc(self.ran, self.process.stdout, self.process.stderr) @property def stdout(self): self.wait() return self.process.stdout @property def stderr(self): self.wait() return self.process.stderr @property def exit_code(self): self.wait() return self.process.exit_code @property def pid(self): return self.process.pid def __len__(self): return len(str(self)) def __enter__(self): """ we don't actually do anything here because anything that should have been done would have been done in the Command.__call__ call. essentially all that has to happen is the comand be pushed on the prepend stack. """ with_context_warning() def __iter__(self): return self def next(self): """ allow us to iterate over the output of our command """ # we do this because if get blocks, we can't catch a KeyboardInterrupt # so the slight timeout allows for that. while True: try: chunk = self.process._pipe_queue.get(True, 0.001) except Empty: if self.call_args["iter_noblock"]: return errno.EWOULDBLOCK else: if chunk is None: self.wait() raise StopIteration() try: return chunk.decode(self.call_args["encoding"], self.call_args["decode_errors"]) except UnicodeDecodeError: return chunk # python 3 __next__ = next def __exit__(self, typ, value, traceback): if self.call_args["with"] and Command._prepend_stack: Command._prepend_stack.pop() def __str__(self): """ in python3, should return unicode. in python2, should return a string of bytes """ if IS_PY3: return self.__unicode__() else: return unicode(self).encode(self.call_args["encoding"]) def __unicode__(self): """ a magic method defined for python2. calling unicode() on a RunningCommand object will call this """ if self.process and self.stdout: return self.stdout.decode(self.call_args["encoding"], self.call_args["decode_errors"]) elif IS_PY3: return "" else: return unicode("") def __eq__(self, other): return unicode(self) == unicode(other) __hash__ = None # Avoid DeprecationWarning in Python < 3 def __contains__(self, item): return item in str(self) def __getattr__(self, p): # let these three attributes pass through to the OProc object if p in ("signal", "terminate", "kill"): if self.process: return getattr(self.process, p) else: raise AttributeError # see if strings have what we're looking for. we're looking at the # method names explicitly because we don't want to evaluate self unless # we absolutely have to, the reason being, in python2, hasattr swallows # exceptions, and if we try to run hasattr on a command that failed and # is being run with _iter=True, the command will be evaluated, throw an # exception, but hasattr will discard it if p in _unicode_methods: return getattr(unicode(self), p) raise AttributeError def __repr__(self): """ in python3, should return unicode. in python2, should return a string of bytes """ try: return str(self) except UnicodeDecodeError: if self.process: if self.stdout: return repr(self.stdout) return repr("") def __long__(self): return long(str(self).strip()) def __float__(self): return float(str(self).strip()) def __int__(self): return int(str(self).strip()) def output_redirect_is_filename(out): return out \ and not callable(out) \ and not hasattr(out, "write") \ and not isinstance(out, (cStringIO, StringIO)) class Command(object): """ represents an un-run system program, like "ls" or "cd". because it represents the program itself (and not a running instance of it), it should hold very little state. in fact, the only state it does hold is baked arguments. when a Command object is called, the result that is returned is a RunningCommand object, which represents the Command put into an execution state. """ _prepend_stack = [] _call_args = { # currently unsupported #"fg": False, # run command in foreground # run a command in the background. commands run in the background # ignore SIGHUP and do not automatically exit when the parent process # ends "bg": False, "with": False, # prepend the command to every command after it "in": None, "out": None, # redirect STDOUT "err": None, # redirect STDERR "err_to_out": None, # redirect STDERR to STDOUT # stdin buffer size # 1 for line, 0 for unbuffered, any other number for that amount "in_bufsize": 0, # stdout buffer size, same values as above "out_bufsize": 1, "err_bufsize": 1, # this is how big the output buffers will be for stdout and stderr. # this is essentially how much output they will store from the process. # we use a deque, so if it overflows past this amount, the first items # get pushed off as each new item gets added. # # NOTICE # this is not a *BYTE* size, this is a *CHUNK* size...meaning, that if # you're buffering out/err at 1024 bytes, the internal buffer size will # be "internal_bufsize" CHUNKS of 1024 bytes "internal_bufsize": 3 * 1024 ** 2, "env": None, "piped": None, "iter": None, "iter_noblock": None, "ok_code": 0, "cwd": None, # the separator delimiting between a long-argument's name and its value # for example, --arg=derp, '=' is the long_sep "long_sep": "=", # this is for programs that expect their input to be from a terminal. # ssh is one of those programs "tty_in": False, "tty_out": True, "encoding": DEFAULT_ENCODING, "decode_errors": "strict", # how long the process should run before it is auto-killed "timeout": 0, "timeout_signal": signal.SIGKILL, # TODO write some docs on "long-running processes" # these control whether or not stdout/err will get aggregated together # as the process runs. this has memory usage implications, so sometimes # with long-running processes with a lot of data, it makes sense to # set these to true "no_out": False, "no_err": False, "no_pipe": False, # if any redirection is used for stdout or stderr, internal buffering # of that data is not stored. this forces it to be stored, as if # the output is being T'd to both the redirected destination and our # internal buffers "tee": None, # will be called when a process terminates without exception. this # option also puts the command in the background, since it doesn't make # sense to have an un-backgrounded command with a done callback "done": None, # a tuple (rows, columns) of the desired size of both the stdout and # stdin ttys, if ttys are being used "tty_size": (20, 80), } # these are arguments that cannot be called together, because they wouldn't # make any sense _incompatible_call_args = ( #("fg", "bg", "Command can't be run in the foreground and background"), ("err", "err_to_out", "Stderr is already being redirected"), ("piped", "iter", "You cannot iterate when this command is being piped"), ("piped", "no_pipe", "Using a pipe doesn't make sense if you've \ disabled the pipe"), ("no_out", "iter", "You cannot iterate over output if there is no \ output"), ) # this method exists because of the need to have some way of letting # manual object instantiation not perform the underscore-to-dash command # conversion that resolve_program uses. # # there are 2 ways to create a Command object. using sh.Command() # or by using sh.. the method fed into sh.Command must be taken # literally, and so no underscore-dash conversion is performed. the one # for sh. must do the underscore-dash converesion, because we # can't type dashes in method names @classmethod def _create(cls, program, **default_kwargs): path = resolve_program(program) if not path: raise CommandNotFound(program) cmd = cls(path) if default_kwargs: cmd = cmd.bake(**default_kwargs) return cmd def __init__(self, path): found = which(path) if not found: raise CommandNotFound(path) self._path = encode_to_py3bytes_or_py2str(found) self._partial = False self._partial_baked_args = [] self._partial_call_args = {} # bugfix for functools.wraps. issue #121 self.__name__ = str(self) def __getattribute__(self, name): # convenience getattr = partial(object.__getattribute__, self) if name.startswith("_"): return getattr(name) if name == "bake": return getattr("bake") if name.endswith("_"): name = name[:-1] return getattr("bake")(name) @staticmethod def _extract_call_args(kwargs, to_override={}): kwargs = kwargs.copy() call_args = {} for parg, default in Command._call_args.items(): key = "_" + parg if key in kwargs: call_args[parg] = kwargs[key] del kwargs[key] elif parg in to_override: call_args[parg] = to_override[parg] # test for incompatible call args s1 = set(call_args.keys()) for args in Command._incompatible_call_args: args = list(args) error = args.pop() if s1.issuperset(args): raise TypeError("Invalid special arguments %r: %s" % (args, error)) return call_args, kwargs def _aggregate_keywords(self, keywords, sep, raw=False): processed = [] for k, v in keywords.items(): # we're passing a short arg as a kwarg, example: # cut(d="\t") if len(k) == 1: if v is not False: processed.append(encode_to_py3bytes_or_py2str("-" + k)) if v is not True: processed.append(encode_to_py3bytes_or_py2str(v)) # we're doing a long arg else: if not raw: k = k.replace("_", "-") if v is True: processed.append(encode_to_py3bytes_or_py2str("--" + k)) elif v is False: pass else: arg = encode_to_py3bytes_or_py2str("--%s%s%s" % (k, sep, v)) processed.append(arg) return processed def _compile_args(self, args, kwargs, sep): processed_args = [] # aggregate positional args for arg in args: if isinstance(arg, (list, tuple)): if not arg: warnings.warn("Empty list passed as an argument to %r. \ If you're using glob.glob(), please use sh.glob() instead." % self._path, stacklevel=3) for sub_arg in arg: processed_args.append(encode_to_py3bytes_or_py2str(sub_arg)) elif isinstance(arg, dict): processed_args += self._aggregate_keywords(arg, sep, raw=True) else: processed_args.append(encode_to_py3bytes_or_py2str(arg)) # aggregate the keyword arguments processed_args += self._aggregate_keywords(kwargs, sep) return processed_args # TODO needs documentation def bake(self, *args, **kwargs): fn = Command(self._path) fn._partial = True call_args, kwargs = self._extract_call_args(kwargs) pruned_call_args = call_args for k, v in Command._call_args.items(): try: if pruned_call_args[k] == v: del pruned_call_args[k] except KeyError: continue fn._partial_call_args.update(self._partial_call_args) fn._partial_call_args.update(pruned_call_args) fn._partial_baked_args.extend(self._partial_baked_args) sep = pruned_call_args.get("long_sep", self._call_args["long_sep"]) fn._partial_baked_args.extend(self._compile_args(args, kwargs, sep)) return fn def __str__(self): """ in python3, should return unicode. in python2, should return a string of bytes """ if IS_PY3: return self.__unicode__() else: return self.__unicode__().encode(DEFAULT_ENCODING) def __eq__(self, other): try: return str(self) == str(other) except: return False __hash__ = None # Avoid DeprecationWarning in Python < 3 def __repr__(self): """ in python3, should return unicode. in python2, should return a string of bytes """ return "" % str(self) def __unicode__(self): """ a magic method defined for python2. calling unicode() on a self will call this """ baked_args = " ".join(item.decode(DEFAULT_ENCODING) for item in self._partial_baked_args) if baked_args: baked_args = " " + baked_args return self._path.decode(DEFAULT_ENCODING) + baked_args def __enter__(self): with_context_warning() self(_with=True) def __exit__(self, typ, value, traceback): Command._prepend_stack.pop() def __call__(self, *args, **kwargs): kwargs = kwargs.copy() args = list(args) cmd = [] # aggregate any 'with' contexts call_args = Command._call_args.copy() for prepend in self._prepend_stack: # don't pass the 'with' call arg pcall_args = prepend.call_args.copy() try: del pcall_args["with"] except: pass call_args.update(pcall_args) cmd.extend(prepend.cmd) cmd.append(self._path) # here we extract the special kwargs and override any # special kwargs from the possibly baked command tmp_call_args, kwargs = self._extract_call_args(kwargs, self._partial_call_args) call_args.update(tmp_call_args) if not getattr(call_args["ok_code"], "__iter__", None): call_args["ok_code"] = [call_args["ok_code"]] if call_args["done"]: call_args["bg"] = True # check if we're piping via composition stdin = call_args["in"] if args: first_arg = args.pop(0) if isinstance(first_arg, RunningCommand): # it makes sense that if the input pipe of a command is running # in the background, then this command should run in the # background as well if first_arg.call_args["bg"]: call_args["bg"] = True if first_arg.call_args["piped"] == "direct": stdin = first_arg.process else: stdin = first_arg.process._pipe_queue else: args.insert(0, first_arg) processed_args = self._compile_args(args, kwargs, call_args["long_sep"]) # makes sure our arguments are broken up correctly split_args = self._partial_baked_args + processed_args final_args = split_args cmd.extend(final_args) # stdout redirection stdout = call_args["out"] if output_redirect_is_filename(stdout): stdout = open(str(stdout), "wb") # stderr redirection stderr = call_args["err"] if output_redirect_is_filename(stderr): stderr = open(str(stderr), "wb") return RunningCommand(cmd, call_args, stdin, stdout, stderr) def _start_daemon_thread(fn, *args): thrd = threading.Thread(target=fn, args=args) thrd.daemon = True thrd.start() return thrd def setwinsize(fd, rows_cols): """ set the terminal size of a tty file descriptor. borrowed logic from pexpect.py """ rows, cols = rows_cols TIOCSWINSZ = getattr(termios, 'TIOCSWINSZ', -2146929561) s = struct.pack('HHHH', rows, cols, 0, 0) fcntl.ioctl(fd, TIOCSWINSZ, s) def construct_streamreader_callback(process, handler): """ here we're constructing a closure for our streamreader callback. this is used in the case that we pass a callback into _out or _err, meaning we want to our callback to handle each bit of output we construct the closure based on how many arguments it takes. the reason for this is to make it as easy as possible for people to use, without limiting them. a new user will assume the callback takes 1 argument (the data). as they get more advanced, they may want to terminate the process, or pass some stdin back, and will realize that they can pass a callback of more args """ # implied arg refers to the "self" that methods will pass in. we need to # account for this implied arg when figuring out what function the user # passed in based on number of args implied_arg = 0 partial_args = 0 handler_to_inspect = handler if isinstance(handler, partial): partial_args = len(handler.args) handler_to_inspect = handler.func if inspect.ismethod(handler_to_inspect): implied_arg = 1 num_args = len(inspect.getargspec(handler_to_inspect).args) else: if inspect.isfunction(handler_to_inspect): num_args = len(inspect.getargspec(handler_to_inspect).args) # is an object instance with __call__ method else: implied_arg = 1 num_args = len(inspect.getargspec(handler_to_inspect.__call__).args) net_args = num_args - implied_arg - partial_args handler_args = () # just the chunk if net_args == 1: handler_args = () # chunk, stdin if net_args == 2: handler_args = (process.stdin,) # chunk, stdin, process elif net_args == 3: # notice we're only storing a weakref, to prevent cyclic references # (where the process holds a streamreader, and a streamreader holds a # handler-closure with a reference to the process handler_args = (process.stdin, weakref.ref(process)) def fn(chunk): # this is pretty ugly, but we're evaluating the process at call-time, # because it's a weakref args = handler_args if len(args) == 2: args = (handler_args[0], handler_args[1]()) return handler(chunk, *args) return fn def handle_process_exit_code(exit_code): """ this should only ever be called once for each child process """ # if we exited from a signal, let our exit code reflect that if os.WIFSIGNALED(exit_code): return -os.WTERMSIG(exit_code) # otherwise just give us a normal exit code elif os.WIFEXITED(exit_code): return os.WEXITSTATUS(exit_code) else: raise RuntimeError("Unknown child exit status!") class OProc(object): """ this class is instantiated by RunningCommand for a command to be exec'd. it handles all the nasty business involved with correctly setting up the input/output to the child process. it gets its name for subprocess.Popen (process open) but we're calling ours OProc (open process) """ _default_window_size = (24, 80) # used in redirecting STDOUT = -1 STDERR = -2 def __init__(self, parent_log, cmd, stdin, stdout, stderr, call_args, pipe): """ cmd is the full string that will be exec'd. it includes the program name and all its arguments stdin, stdout, stderr are what the child will use for standard input/output/err call_args is a mapping of all the special keyword arguments to apply to the child process """ self.call_args = call_args # I had issues with getting 'Input/Output error reading stdin' from dd, # until I set _tty_out=False if self.call_args["piped"] == "direct": self.call_args["tty_out"] = False self._single_tty = self.call_args["tty_in"] and self.call_args["tty_out"] # this logic is a little convoluted, but basically this top-level # if/else is for consolidating input and output TTYs into a single # TTY. this is the only way some secure programs like ssh will # output correctly (is if stdout and stdin are both the same TTY) if self._single_tty: self._stdin_fd, self._slave_stdin_fd = pty.openpty() self._stdout_fd = self._stdin_fd self._slave_stdout_fd = self._slave_stdin_fd self._stderr_fd = self._stdin_fd self._slave_stderr_fd = self._slave_stdin_fd # do not consolidate stdin and stdout. this is the most common use- # case else: # this check here is because we may be doing "direct" piping # (_piped="direct"), and so our stdin might be an instance of # OProc if isinstance(stdin, OProc): self._slave_stdin_fd = stdin._stdout_fd self._stdin_fd = None elif self.call_args["tty_in"]: self._slave_stdin_fd, self._stdin_fd = pty.openpty() # tty_in=False is the default else: self._slave_stdin_fd, self._stdin_fd = os.pipe() # tty_out=True is the default if self.call_args["tty_out"]: self._stdout_fd, self._slave_stdout_fd = pty.openpty() else: self._stdout_fd, self._slave_stdout_fd = os.pipe() # unless STDERR is going to STDOUT, it ALWAYS needs to be a pipe, # and never a PTY. the reason for this is not totally clear to me, # but it has to do with the fact that if STDERR isn't set as the # CTTY (because STDOUT is), the STDERR buffer won't always flush # by the time the process exits, and the data will be lost. # i've only seen this on OSX. if stderr is not OProc.STDOUT: self._stderr_fd, self._slave_stderr_fd = os.pipe() # this is a hack, but what we're doing here is intentionally throwing an # OSError exception if our child processes's directory doesn't exist, # but we're doing it BEFORE we fork. the reason for before the fork is # error handling. i'm currently too lazy to implement what # subprocess.py did and set up a error pipe to handle exceptions that # happen in the child between fork and exec. it has only been seen in # the wild for a missing cwd, so we'll handle it here. cwd = self.call_args["cwd"] if cwd is not None and not os.path.exists(cwd): os.chdir(cwd) gc_enabled = gc.isenabled() if gc_enabled: gc.disable() self.pid = os.fork() # child if self.pid == 0: # pragma: no cover try: # ignoring SIGHUP lets us persist even after the parent process # exits. only ignore if we're backgrounded if self.call_args["bg"] is True: signal.signal(signal.SIGHUP, signal.SIG_IGN) # this piece of ugliness is due to a bug where we can lose output # if we do os.close(self._slave_stdout_fd) in the parent after # the child starts writing. # see http://bugs.python.org/issue15898 if IS_OSX: time.sleep(0.01) os.setsid() if self.call_args["tty_out"]: # set raw mode, so there isn't any weird translation of # newlines to \r\n and other oddities. we're not outputting # to a terminal anyways # # we HAVE to do this here, and not in the parent process, # because we have to guarantee that this is set before the # child process is run, and we can't do it twice. tty.setraw(self._slave_stdout_fd) # if the parent-side fd for stdin exists, close it. the case # where it may not exist is if we're using piped="direct" if self._stdin_fd: os.close(self._stdin_fd) if not self._single_tty: os.close(self._stdout_fd) if stderr is not OProc.STDOUT: os.close(self._stderr_fd) if cwd: os.chdir(cwd) os.dup2(self._slave_stdin_fd, 0) os.dup2(self._slave_stdout_fd, 1) # we're not directing stderr to stdout? then set self._slave_stderr_fd to # fd 2, the common stderr fd if stderr is OProc.STDOUT: os.dup2(self._slave_stdout_fd, 2) else: os.dup2(self._slave_stderr_fd, 2) # don't inherit file descriptors max_fd = resource.getrlimit(resource.RLIMIT_NOFILE)[0] os.closerange(3, max_fd) # set our controlling terminal. tty_out defaults to true if self.call_args["tty_out"]: tmp_fd = os.open(os.ttyname(1), os.O_RDWR) os.close(tmp_fd) if self.call_args["tty_out"]: setwinsize(1, self.call_args["tty_size"]) # actually execute the process if self.call_args["env"] is None: os.execv(cmd[0], cmd) else: os.execve(cmd[0], cmd, self.call_args["env"]) # we must ensure that we ALWAYS exit the child process, otherwise # the parent process code will be executed twice on exception # https://github.com/amoffat/sh/issues/202 # # if your parent process experiences an exit code 255, it is most # likely that an exception occurred between the fork of the child # and the exec. this should be reported. finally: os._exit(255) # parent else: if gc_enabled: gc.enable() # used to determine what exception to raise. if our process was # killed via a timeout counter, we'll raise something different than # a SIGKILL exception self.timed_out = False self.started = time.time() self.cmd = cmd # exit code should only be manipulated from within self._wait_lock # to prevent race conditions self.exit_code = None self.stdin = stdin or Queue() # _pipe_queue is used internally to hand off stdout from one process # to another. by default, all stdout from a process gets dumped # into this pipe queue, to be consumed in real time (hence the # thread-safe Queue), or at a potentially later time self._pipe_queue = Queue() # this is used to prevent a race condition when we're waiting for # a process to end, and the OProc's internal threads are also checking # for the processes's end self._wait_lock = threading.Lock() # these are for aggregating the stdout and stderr. we use a deque # because we don't want to overflow self._stdout = deque(maxlen=self.call_args["internal_bufsize"]) self._stderr = deque(maxlen=self.call_args["internal_bufsize"]) if self.call_args["tty_in"]: setwinsize(self._stdin_fd, self.call_args["tty_size"]) self.log = parent_log.get_child("process", repr(self)) os.close(self._slave_stdin_fd) if not self._single_tty: os.close(self._slave_stdout_fd) if stderr is not OProc.STDOUT: os.close(self._slave_stderr_fd) self.log.debug("started process") if self.call_args["tty_in"]: attr = termios.tcgetattr(self._stdin_fd) attr[3] &= ~termios.ECHO termios.tcsetattr(self._stdin_fd, termios.TCSANOW, attr) # this represents the connection from a Queue object (or whatever # we're using to feed STDIN) to the process's STDIN fd self._stdin_stream = None if not isinstance(self.stdin, OProc): self._stdin_stream = \ StreamWriter(self.log.get_child("streamwriter", "stdin"), self._stdin_fd, self.stdin, self.call_args["in_bufsize"], self.call_args["encoding"], self.call_args["tty_in"]) stdout_pipe = None if pipe is OProc.STDOUT and not self.call_args["no_pipe"]: stdout_pipe = self._pipe_queue # this represents the connection from a process's STDOUT fd to # wherever it has to go, sometimes a pipe Queue (that we will use # to pipe data to other processes), and also an internal deque # that we use to aggregate all the output save_stdout = not self.call_args["no_out"] and \ (self.call_args["tee"] in (True, "out") or stdout is None) # if we're piping directly into another process's filedescriptor, we # bypass reading from the stdout stream altogether, because we've # already hooked up this processes's stdout fd to the other # processes's stdin fd self._stdout_stream = None if self.call_args["piped"] != "direct": if callable(stdout): stdout = construct_streamreader_callback(self, stdout) self._stdout_stream = \ StreamReader(self.log.get_child("streamreader", "stdout"), self._stdout_fd, stdout, self._stdout, self.call_args["out_bufsize"], self.call_args["encoding"], self.call_args["decode_errors"], stdout_pipe, save_data=save_stdout) if stderr is OProc.STDOUT or self._single_tty: self._stderr_stream = None else: stderr_pipe = None if pipe is OProc.STDERR and not self.call_args["no_pipe"]: stderr_pipe = self._pipe_queue save_stderr = not self.call_args["no_err"] and \ (self.call_args["tee"] in ("err",) or stderr is None) if callable(stderr): stderr = construct_streamreader_callback(self, stderr) self._stderr_stream = StreamReader(Logger("streamreader"), self._stderr_fd, stderr, self._stderr, self.call_args["err_bufsize"], self.call_args["encoding"], self.call_args["decode_errors"], stderr_pipe, save_data=save_stderr) # start the main io threads # stdin thread is not needed if we are connecting from another process's stdout pipe self._input_thread = None if self._stdin_stream: self._input_thread = _start_daemon_thread(self.input_thread, self._stdin_stream) self._output_thread = _start_daemon_thread(self.output_thread, self._stdout_stream, self._stderr_stream, self.call_args["timeout"], self.started, self.call_args["timeout_signal"]) def __repr__(self): return "" % (self.pid, self.cmd[:500]) def change_in_bufsize(self, buf): self._stdin_stream.stream_bufferer.change_buffering(buf) def change_out_bufsize(self, buf): self._stdout_stream.stream_bufferer.change_buffering(buf) def change_err_bufsize(self, buf): self._stderr_stream.stream_bufferer.change_buffering(buf) def input_thread(self, stdin): """ this is run in a separate thread. it writes into our process's stdin (a streamwriter) and waits the process to end AND everything that can be written to be written """ done = False while not done and self.is_alive(): self.log.debug("%r ready for more input", stdin) done = stdin.write() stdin.close() def output_thread(self, stdout, stderr, timeout, started, timeout_exc): """ this function is run in a separate thread. it reads from the process's stdout stream (a streamreader), and waits for it to claim that its done """ readers = [] errors = [] if stdout is not None: readers.append(stdout) errors.append(stdout) if stderr is not None: readers.append(stderr) errors.append(stderr) # this is our select loop for polling stdout or stderr that is ready to # be read and processed. if one of those streamreaders indicate that it # is done altogether being read from, we remove it from our list of # things to poll. when no more things are left to poll, we leave this # loop and clean up while readers: outputs, inputs, err = select.select(readers, [], errors, 0.1) # stdout and stderr for stream in outputs: self.log.debug("%r ready to be read from", stream) done = stream.read() if done: readers.remove(stream) for stream in err: pass # test if the process has been running too long if timeout: now = time.time() if now - started > timeout: self.log.debug("we've been running too long") self.timed_out = True self.signal(timeout_exc) # this is here because stdout may be the controlling TTY, and # we can't close it until the process has ended, otherwise the # child will get SIGHUP. typically, if we've broken out of # the above loop, and we're here, the process is just about to # end, so it's probably ok to aggressively poll self.is_alive() # # the other option to this would be to do the CTTY close from # the method that does the actual os.waitpid() call, but the # problem with that is that the above loop might still be # running, and closing the fd will cause some operation to # fail. this is less complex than wrapping all the ops # in the above loop with out-of-band fd-close exceptions while self.is_alive(): time.sleep(0.001) if stdout: stdout.close() if stderr: stderr.close() @property def stdout(self): return "".encode(self.call_args["encoding"]).join(self._stdout) @property def stderr(self): return "".encode(self.call_args["encoding"]).join(self._stderr) def signal(self, sig): self.log.debug("sending signal %d", sig) try: os.kill(self.pid, sig) except OSError: pass def kill(self): self.log.debug("killing") self.signal(signal.SIGKILL) def terminate(self): self.log.debug("terminating") self.signal(signal.SIGTERM) def is_alive(self): """ polls if our child process has completed, without blocking. this method has side-effects, such as setting our exit_code, if we happen to see our child exit while this is running """ if self.exit_code is not None: return False # what we're doing here essentially is making sure that the main thread # (or another thread), isn't calling .wait() on the process. because # .wait() calls os.waitpid(self.pid, 0), we can't do an os.waitpid # here...because if we did, and the process exited while in this # thread, the main thread's os.waitpid(self.pid, 0) would raise OSError # (because the process ended in another thread). # # so essentially what we're doing is, using this lock, checking if # we're calling .wait(), and if we are, let .wait() get the exit code # and handle the status, otherwise let us do it. acquired = self._wait_lock.acquire(False) if not acquired: if self.exit_code is not None: return False return True try: # WNOHANG is just that...we're calling waitpid without hanging... # essentially polling the process. the return result is (0, 0) if # there's no process status, so we check that pid == self.pid below # in order to determine how to proceed pid, exit_code = os.waitpid(self.pid, os.WNOHANG) if pid == self.pid: self.exit_code = handle_process_exit_code(exit_code) return False # no child process except OSError: return False else: return True finally: self._wait_lock.release() def wait(self): """ waits for the process to complete, handles the exit code """ self.log.debug("acquiring wait lock to wait for completion") # using the lock in a with-context blocks, which is what we want if # we're running wait() with self._wait_lock: self.log.debug("got wait lock") if self.exit_code is None: self.log.debug("exit code not set, waiting on pid") pid, exit_code = os.waitpid(self.pid, 0) # blocks self.exit_code = handle_process_exit_code(exit_code) else: self.log.debug("exit code already set (%d), no need to wait", self.exit_code) # we may not have a thread for stdin, if the pipe has been connected # via _piped="direct" if self._input_thread: self._input_thread.join() # wait for our stdout and stderr streamreaders to finish reading and # aggregating the process output self._output_thread.join() return self.exit_code class DoneReadingForever(Exception): pass class NotYetReadyToRead(Exception): pass def determine_how_to_read_input(input_obj): """ given some kind of input object, return a function that knows how to read chunks of that input object. each reader function should return a chunk and raise a DoneReadingForever exception, or return None, when there's no more data to read NOTE: the function returned does not need to care much about the requested buffering type (eg, unbuffered vs newline-buffered). the StreamBufferer will take care of that. these functions just need to return a reasonably-sized chunk of data. """ get_chunk = None if isinstance(input_obj, Queue): log_msg = "queue" get_chunk = get_queue_chunk_reader(input_obj) elif callable(input_obj): log_msg = "callable" get_chunk = get_callable_chunk_reader(input_obj) # also handles stringio elif hasattr(input_obj, "read"): log_msg = "file descriptor" get_chunk = get_file_chunk_reader(input_obj) elif isinstance(input_obj, basestring): log_msg = "string" get_chunk = get_iter_string_reader(input_obj) else: log_msg = "general iterable" get_chunk = get_iter_chunk_reader(iter(input_obj)) return get_chunk, log_msg def get_queue_chunk_reader(stdin): def fn(): try: chunk = stdin.get(True, 0.01) except Empty: raise NotYetReadyToRead if chunk is None: raise DoneReadingForever return chunk return fn def get_callable_chunk_reader(stdin): def fn(): try: return stdin() except: raise DoneReadingForever return fn def get_iter_string_reader(stdin): """ return an iterator that returns a chunk of a string every time it is called. notice that even though bufsize_type might be line buffered, we're not doing any line buffering here. that's because our StreamBufferer handles all buffering. we just need to return a reasonable-sized chunk. """ bufsize = 1024 iter_str = (stdin[i:i + bufsize] for i in range(0, len(stdin), bufsize)) return get_iter_chunk_reader(iter_str) def get_iter_chunk_reader(stdin): def fn(): try: if IS_PY3: chunk = stdin.__next__() else: chunk = stdin.next() return chunk except StopIteration: raise DoneReadingForever return fn def get_file_chunk_reader(stdin): bufsize = 1024 def fn(): chunk = stdin.read(bufsize) if not chunk: raise DoneReadingForever else: return chunk return fn def bufsize_type_to_bufsize(bf_type): """ for a given bufsize type, return the actual bufsize we will read. notice that although 1 means "newline-buffered", we're reading a chunk size of 1024. this is because we have to read something. we let a StreamBufferer instance handle splitting our chunk on newlines """ # newlines if bf_type == 1: bufsize = 1024 # unbuffered elif bf_type == 0: bufsize = 1 # or buffered by specific amount else: bufsize = bf_type return bufsize class StreamWriter(object): """ StreamWriter reads from some input (the stdin param) and writes to a fd (the stream param). the stdin may be a Queue, a callable, something with the "read" method, a string, or an iterable """ def __init__(self, log, stream, stdin, bufsize_type, encoding, tty_in): self.stream = stream self.stdin = stdin self.log = log self.encoding = encoding self.tty_in = tty_in self.stream_bufferer = StreamBufferer(bufsize_type, self.encoding) self.get_chunk, log_msg = determine_how_to_read_input(stdin) self.log.debug("parsed stdin as a %s", log_msg) def fileno(self): """ defining this allows us to do select.select on an instance of this class """ return self.stream def write(self): """ attempt to get a chunk of data to write to our child process's stdin, then write it. the return value answers the questions "are we done writing forever?" """ # get_chunk may sometimes return bytes, and sometimes returns trings # because of the nature of the different types of STDIN objects we # support try: chunk = self.get_chunk() if chunk is None: raise DoneReadingForever except DoneReadingForever: self.log.debug("done reading") if self.tty_in: # EOF time try: char = termios.tcgetattr(self.stream)[6][termios.VEOF] except: char = chr(4).encode() os.write(self.stream, char) return True except NotYetReadyToRead: self.log.debug("received no data") return False # if we're not bytes, make us bytes if IS_PY3 and hasattr(chunk, "encode"): chunk = chunk.encode(self.encoding) for proc_chunk in self.stream_bufferer.process(chunk): self.log.debug("got chunk size %d: %r", len(proc_chunk), proc_chunk[:30]) self.log.debug("writing chunk to process") try: os.write(self.stream, proc_chunk) except OSError: self.log.debug("OSError writing stdin chunk") return True def close(self): self.log.debug("closing, but flushing first") chunk = self.stream_bufferer.flush() self.log.debug("got chunk size %d to flush: %r", len(chunk), chunk[:30]) try: if chunk: os.write(self.stream, chunk) if not self.tty_in: self.log.debug("we used a TTY, so closing the stream") os.close(self.stream) except OSError: pass def determine_how_to_feed_output(handler, encoding, decode_errors): if callable(handler): process, finish = get_callback_chunk_consumer(handler, encoding, decode_errors) elif isinstance(handler, cStringIO): process, finish = get_cstringio_chunk_consumer(handler) elif isinstance(handler, StringIO): process, finish = get_stringio_chunk_consumer(handler, encoding, decode_errors) elif hasattr(handler, "write"): process, finish = get_file_chunk_consumer(handler) else: process = lambda chunk: False finish = lambda: None return process, finish def get_file_chunk_consumer(handler): def process(chunk): handler.write(chunk) # we should flush on an fd. chunk is already the correctly-buffered # size, so we don't need the fd buffering as well handler.flush() return False def finish(): if hasattr(handler, "flush"): handler.flush() return process, finish def get_callback_chunk_consumer(handler, encoding, decode_errors): def process(chunk): # try to use the encoding first, if that doesn't work, send # the bytes, because it might be binary try: chunk = chunk.decode(encoding, decode_errors) except UnicodeDecodeError: pass return handler(chunk) def finish(): pass return process, finish def get_cstringio_chunk_consumer(handler): def process(chunk): handler.write(chunk) return False def finish(): pass return process, finish def get_stringio_chunk_consumer(handler, encoding, decode_errors): def process(chunk): handler.write(chunk.decode(encoding, decode_errors)) return False def finish(): pass return process, finish class StreamReader(object): """ reads from some output (the stream) and sends what it just read to the handler. """ def __init__(self, log, stream, handler, buffer, bufsize_type, encoding, decode_errors, pipe_queue=None, save_data=True): self.stream = stream self.buffer = buffer self.save_data = save_data self.encoding = encoding self.decode_errors = decode_errors self.pipe_queue = None if pipe_queue: self.pipe_queue = weakref.ref(pipe_queue) self.log = log self.stream_bufferer = StreamBufferer(bufsize_type, self.encoding, self.decode_errors) self.bufsize = bufsize_type_to_bufsize(bufsize_type) self.process_chunk, self.finish_chunk_processor = \ determine_how_to_feed_output(handler, encoding, decode_errors) self.should_quit = False def fileno(self): """ defining this allows us to do select.select on an instance of this class """ return self.stream def close(self): chunk = self.stream_bufferer.flush() self.log.debug("got chunk size %d to flush: %r", len(chunk), chunk[:30]) if chunk: self.write_chunk(chunk) self.finish_chunk_processor() if self.pipe_queue and self.save_data: self.pipe_queue().put(None) try: os.close(self.stream) except OSError: pass def write_chunk(self, chunk): # in PY3, the chunk coming in will be bytes, so keep that in mind if not self.should_quit: self.should_quit = self.process_chunk(chunk) if self.save_data: self.buffer.append(chunk) if self.pipe_queue: self.log.debug("putting chunk onto pipe: %r", chunk[:30]) self.pipe_queue().put(chunk) def read(self): # if we're PY3, we're reading bytes, otherwise we're reading # str try: chunk = os.read(self.stream, self.bufsize) except OSError as e: self.log.debug("got errno %d, done reading", e.errno) return True if not chunk: self.log.debug("got no chunk, done reading") return True self.log.debug("got chunk size %d: %r", len(chunk), chunk[:30]) for chunk in self.stream_bufferer.process(chunk): self.write_chunk(chunk) class StreamBufferer(object): """ this is used for feeding in chunks of stdout/stderr, and breaking it up into chunks that will actually be put into the internal buffers. for example, if you have two processes, one being piped to the other, and you want that, first process to feed lines of data (instead of the chunks however they come in), OProc will use an instance of this class to chop up the data and feed it as lines to be sent down the pipe """ def __init__(self, buffer_type, encoding=DEFAULT_ENCODING, decode_errors="strict"): # 0 for unbuffered, 1 for line, everything else for that amount self.type = buffer_type self.buffer = [] self.n_buffer_count = 0 self.encoding = encoding self.decode_errors = decode_errors # this is for if we change buffering types. if we change from line # buffered to unbuffered, its very possible that our self.buffer list # has data that was being saved up (while we searched for a newline). # we need to use that up, so we don't lose it self._use_up_buffer_first = False # the buffering lock is used because we might chance the buffering # types from a different thread. for example, if we have a stdout # callback, we might use it to change the way stdin buffers. so we # lock self._buffering_lock = threading.RLock() self.log = Logger("stream_bufferer") def change_buffering(self, new_type): # TODO, when we stop supporting 2.6, make this a with context self.log.debug("acquiring buffering lock for changing buffering") self._buffering_lock.acquire() self.log.debug("got buffering lock for changing buffering") try: if new_type == 0: self._use_up_buffer_first = True self.type = new_type finally: self._buffering_lock.release() self.log.debug("released buffering lock for changing buffering") def process(self, chunk): # MAKE SURE THAT THE INPUT IS PY3 BYTES # THE OUTPUT IS ALWAYS PY3 BYTES # TODO, when we stop supporting 2.6, make this a with context self.log.debug("acquiring buffering lock to process chunk (buffering: %d)", self.type) self._buffering_lock.acquire() self.log.debug("got buffering lock to process chunk (buffering: %d)", self.type) try: # we've encountered binary, permanently switch to N size buffering # since matching on newline doesn't make sense anymore if self.type == 1: try: chunk.decode(self.encoding, self.decode_errors) except: self.log.debug("detected binary data, changing buffering") self.change_buffering(1024) # unbuffered if self.type == 0: if self._use_up_buffer_first: self._use_up_buffer_first = False to_write = self.buffer self.buffer = [] to_write.append(chunk) return to_write return [chunk] # line buffered # we must decode the bytes before we try to match on newline elif self.type == 1: total_to_write = [] chunk = chunk.decode(self.encoding, self.decode_errors) while True: newline = chunk.find("\n") if newline == -1: break chunk_to_write = chunk[:newline + 1] if self.buffer: # this is ugly, but it's designed to take the existing # bytes buffer, join it together, tack on our latest # chunk, then convert the whole thing to a string. # it's necessary, i'm sure. read the whole block to # see why. chunk_to_write = "".encode(self.encoding).join(self.buffer) \ + chunk_to_write.encode(self.encoding) chunk_to_write = chunk_to_write.decode(self.encoding) self.buffer = [] self.n_buffer_count = 0 chunk = chunk[newline + 1:] total_to_write.append(chunk_to_write.encode(self.encoding)) if chunk: self.buffer.append(chunk.encode(self.encoding)) self.n_buffer_count += len(chunk) return total_to_write # N size buffered else: total_to_write = [] while True: overage = self.n_buffer_count + len(chunk) - self.type if overage >= 0: ret = "".encode(self.encoding).join(self.buffer) + chunk chunk_to_write = ret[:self.type] chunk = ret[self.type:] total_to_write.append(chunk_to_write) self.buffer = [] self.n_buffer_count = 0 else: self.buffer.append(chunk) self.n_buffer_count += len(chunk) break return total_to_write finally: self._buffering_lock.release() self.log.debug("released buffering lock for processing chunk (buffering: %d)", self.type) def flush(self): self.log.debug("acquiring buffering lock for flushing buffer") self._buffering_lock.acquire() self.log.debug("got buffering lock for flushing buffer") try: ret = "".encode(self.encoding).join(self.buffer) self.buffer = [] return ret finally: self._buffering_lock.release() self.log.debug("released buffering lock for flushing buffer") @contextmanager def pushd(path): """ pushd is just a specialized form of args, where we're passing in the current working directory """ with args(_cwd=path): yield @contextmanager def args(*args, **kwargs): """ allows us to temporarily override all the special keyword parameters in a with context """ call_args = Command._call_args old_args = call_args.copy() for key,value in kwargs.items(): key = key.lstrip("_") call_args[key] = value yield call_args.update(old_args) class Environment(dict): """ this allows lookups to names that aren't found in the global scope to be searched for as a program name. for example, if "ls" isn't found in this module's scope, we consider it a system program and try to find it. we use a dict instead of just a regular object as the base class because the exec() statement used in this file requires the "globals" argument to be a dictionary """ # this is a list of all of the names that the sh module exports that will # not resolve to functions. we don't want to accidentally shadow real # commands with functions/imports that we define in sh.py. for example, # "import time" may override the time system program whitelist = set([ "Command", "CommandNotFound", "DEFAULT_ENCODING", "DoneReadingForever", "ErrorReturnCode", "NotYetReadyToRead", "SignalException", "TimeoutException", "__project_url__", "__version__", "args", "glob", "pushd", ]) def __init__(self, globs, baked_args={}): self.globs = globs self.baked_args = baked_args self.disable_whitelist = False def __setitem__(self, k, v): self.globs[k] = v def __getitem__(self, k): # if we first import "_disable_whitelist" from sh, we can import # anything defined in the global scope of sh.py. this is useful for our # tests if k == "_disable_whitelist": self.disable_whitelist = True return None # we're trying to import something real (maybe), see if it's in our # global scope if k in self.whitelist or self.disable_whitelist: try: return self.globs[k] except KeyError: pass # somebody tried to be funny and do "from sh import *" if k == "__all__": raise AttributeError("Cannot import * from sh. \ Please import sh or import programs individually.") # check if we're naming a dynamically generated ReturnCode exception exc = get_exc_from_name(k) if exc: return exc # https://github.com/ipython/ipython/issues/2577 # https://github.com/amoffat/sh/issues/97#issuecomment-10610629 if k.startswith("__") and k.endswith("__"): raise AttributeError # how about an environment variable? try: return os.environ[k] except KeyError: pass # is it a custom builtin? builtin = getattr(self, "b_" + k, None) if builtin: return builtin # it must be a command then # we use _create instead of instantiating the class directly because # _create uses resolve_program, which will automatically do underscore- # to-dash conversions. instantiating directly does not use that return Command._create(k, **self.baked_args) # methods that begin with "b_" are custom builtins and will override any # program that exists in our path. this is useful for things like # common shell builtins that people are used to, but which aren't actually # full-fledged system binaries def b_cd(self, path): os.chdir(path) def b_which(self, program): return which(program) def run_repl(env): # pragma: no cover banner = "\n>> sh v{version}\n>> https://github.com/amoffat/sh\n" print(banner.format(version=__version__)) while True: try: line = raw_input("sh> ") except (ValueError, EOFError): break try: exec(compile(line, "", "single"), env, env) except SystemExit: break except: print(traceback.format_exc()) # cleans up our last line print("") # this is a thin wrapper around THIS module (we patch sys.modules[__name__]). # this is in the case that the user does a "from sh import whatever" # in other words, they only want to import certain programs, not the whole # system PATH worth of commands. in this case, we just proxy the # import lookup to our Environment class class SelfWrapper(ModuleType): def __init__(self, self_module, baked_args={}): # this is super ugly to have to copy attributes like this, # but it seems to be the only way to make reload() behave # nicely. if i make these attributes dynamic lookups in # __getattr__, reload sometimes chokes in weird ways... for attr in ["__builtins__", "__doc__", "__name__", "__package__"]: setattr(self, attr, getattr(self_module, attr, None)) # python 3.2 (2.7 and 3.3 work fine) breaks on osx (not ubuntu) # if we set this to None. and 3.3 needs a value for __path__ self.__path__ = [] self.__self_module = self_module self.__env = Environment(globals(), baked_args) def __setattr__(self, name, value): if hasattr(self, "__env"): self.__env[name] = value else: ModuleType.__setattr__(self, name, value) def __getattr__(self, name): if name == "__env": raise AttributeError return self.__env[name] # accept special keywords argument to define defaults for all operations # that will be processed with given by return SelfWrapper def __call__(self, **kwargs): return SelfWrapper(self.__self_module, kwargs) # we're being run as a stand-alone script if __name__ == "__main__": # pragma: no cover try: arg = sys.argv.pop(1) except: arg = None if arg == "test": import subprocess def run_test(version, locale): py_version = "python%s" % version py_bin = which(py_version) if py_bin: print("Testing %s, locale %r" % (py_version.capitalize(), locale)) env = os.environ.copy() env["LANG"] = locale p = subprocess.Popen([py_bin, os.path.join(THIS_DIR, "test.py")] + sys.argv[1:], env=env) return_code = p.wait() if return_code != 0: exit(1) else: print("Couldn't find %s, skipping" % py_version.capitalize()) versions = ("2.6", "2.7", "3.1", "3.2", "3.3", "3.4") locales = ("en_US.UTF-8", "C") for locale in locales: for version in versions: run_test(version, locale) else: env = Environment(globals()) run_repl(env) # we're being imported from somewhere else: self = sys.modules[__name__] sys.modules[__name__] = SelfWrapper(self)