Skip to main content

easy to use `Popen`

Project description

Table of Content

Build Status




This library is considered production ready.


Utility to create sub process.


from pykit import proc

# execute a shell script

returncode, out, err = proc.shell_script('ls / | grep bin')
print returncode
print out
# output:
# > 0
# > bin
# > sbin

# Or run a command directly.
# Unlike the above snippet, following statement does not start an sh process.

returncode, out, err = proc.command('ls', 'a*', cwd='/usr/local')
import sys

with open('foo', 'w') as f:

import time
from pykit import proc

proc.start_daemon('python', './', 'test')
    with open('foo', 'r') as f:
        print repr(
except Exception as e:
    print repr(e)



syntax: proc.CalledProcessError(returncode, out, err, cmd, arguments, options)

It is sub class of subprocess.CalledProcessError.

It is raised if a sub process return code is not 0. Besides CalledProcessError.args, extended from super class Exception, it has 6 other attributes.


  • CalledProcessError.returncode: process exit code.
  • CalledProcessError.out: stdout in one string.
  • CalledProcessError.err: stderr in one string.
  • CalledProcessError.cmd: the command a process exec().
  • CalledProcessError.arguments: tuple of command arguments.
  • CalledProcessError.options: other options passed to this process. Such as close_fds, cwd etc.


It is an alias to proc.CalledProcessError.



syntax: proc.command(cmd, *arguments, **options)

Run a command with arguments arguments in a subprocess. It blocks until sub process exit.


  • cmd: The path of executable to run.

  • arguments: is tuple or list of arguments passed to cmd.

  • options: is a dictionary of additional options, which are same as subprocess.Popen. But with some different default value for easy use:

    • encoding: by default is the system default encoding.

    • env: by default inherit from parent process.

    It also accept the following additional options:

    • check=False: if True, raise CalledProcessError if returncode is not 0. By default it is False.

    • capture=True: whether to capture stdin, stdout and stderr. Otherwise inherit these fd from current process.

    • inherit_env=True: whether to inherit evironment vars from current process.

    • input=None: input to send to stdin, if it is not None.

    • timeout=None: seconds to wait for sub process to exit. By default it is None, for waiting for ever.

    • tty=False: whether to create a speudo tty to run sub process so that the sub process believes it is in a tty(just like controlled by a human).

return: a 3 element tuple that contains:

  • returncode: sub process exit code in int.
  • out: sub process stdout in a single string.
  • err: sub process stderr in a single string.


syntax: proc.command_ex(cmd, *arguments, **options)

It is the same as proc.command except that if sub process exit code is not 0, it raises exception proc.CalledProcessError.

See proc.CalledProcessError.

return: a 3 element tuple of returncode, out and err, or raise exception proc.CalledProcessError.


syntax: proc.shell_script(script_str, **options)

It is just a shortcut of:

options['stdin'] = script_str
return command('sh', **options)


syntax: proc.start_process(cmd, target, env, *args)

Create a child process and replace it with cmd. Besides stdin, stdout and stderr, all file descriptors from parent process will be closed in the child process. The parent process waits for the child process until it is completed.


  • cmd: The path of executable to run. Such as sh, bash, python.

  • target: The path of the script.

  • env: It is a dictionary to pass environment variables to the child process.

  • *args: Type is tuple or list. The arguments passed to the script. Type of every element must be str.

return: nothing


Zhang Yanpo (张炎泼)

Copyright and License

The MIT License (MIT)

Copyright (c) 2015 Zhang Yanpo (张炎泼)

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for pykit3proc, version 0.2.0
Filename, size File type Python version Upload date Hashes
Filename, size pykit3proc-0.2.0.tar.gz (6.0 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page