osrf_pycommon - Man Page

Commonly used, CLI related functions.

osrf_pycommon.cli_utils.common.extract_argument_group(args, delimiting_option)

Extract a group of arguments from a list of arguments using a delimiter.

Here is an example:

>>> extract_argument_group(['foo', '--args', 'bar', '--baz'], '--args')
(['foo'], ['bar', '--baz'])

The group can always be ended using the double hyphen --. In order to pass a double hyphen as arguments, use three hyphens ---. Any set of hyphens encountered after the delimiter, and up to --, which have three or more hyphens and are isolated, will be captured and reduced by one hyphen.

For example:

>> extract_argument_group(['foo',
                           '--args', 'bar', '--baz', '---', '--',
                           '--foo-option'], '--args')
(['foo', '--foo-option'], ['bar', '--baz', '--'])

In the result the -- comes from the --- in the input. The --args and the corresponding -- are removed entirely.

The delimiter and -- terminator combination can also happen multiple times, in which case the bodies of arguments are combined and returned in the order they appeared.

For example:

>> extract_argument_group(['foo',
                           '--args', 'ping', '--',
                           'bar',
                           '--args', 'pong', '--',
                           'baz',
                           '--args', '--'], '--args')
(['foo', 'bar', 'baz'], ['ping', 'pong'])

Note: -- cannot be used as the delimiting_option.

Parameters

• args (list) -- list of strings which are ordered arguments.
• delimiting_option (str) -- option which denotes where to split the args.

Returns

tuple of arguments before and after the delimiter.

Return type

tuple

Raises

ValueError if the delimiting_option is --.

osrf_pycommon.cli_utils.common.extract_jobs_flags(arguments)

Extracts make job flags from a list of other make flags, i.e. -j8 -l8

The input arguments are given as a string separated by whitespace. Make job flags are matched and removed from the arguments, and the Make job flags and what is left over from the input arguments are returned.

If no job flags are encountered, then an empty string is returned as the first element of the returned tuple.

Examples:

>> extract_jobs_flags('-j8 -l8')
('-j8 -l8', '')
>> extract_jobs_flags('-j8 ')
('-j8', ' ')
>> extract_jobs_flags('target -j8 -l8 --some-option')
('-j8 -l8', 'target --some-option')
>> extract_jobs_flags('target --some-option')
('', 'target --some-option')

Parameters

arguments (str) -- string of space separated arguments which may or may not contain make job flags

Returns

tuple of make jobs flags as a space separated string and leftover arguments as a space separated string

Return type

tuple

The verb pattern is a pattern where a single command aggregates multiple related commands by taking a required positional argument which is the "verb" for the action you want to perform. For example, catkin build is an example of a command and verb pair, where catkin is the command and build is the verb. In this example, the catkin command groups "actions" which are related to catkin together using verbs like build which will build a workspace of catkin packages.

This is an example boilerplate of a command which will use verbs:

from __future__ import print_function

import argparse
import sys

from osrf_pycommon.cli_utils.verb_pattern import create_subparsers
from osrf_pycommon.cli_utils.verb_pattern import list_verbs
from osrf_pycommon.cli_utils.verb_pattern import split_arguments_by_verb

COMMAND_NAME = '<INSERT COMMAND NAME HERE>'

VERBS_ENTRY_POINT = '{0}.verbs'.format(COMMAND_NAME)


def main(sysargs=None):
    # Assign sysargs if not set
    sysargs = sys.argv[1:] if sysargs is None else sysargs

    # Create a top level parser
    parser = argparse.ArgumentParser(
        description="{0} command".format(COMMAND_NAME)
    )

    # Generate a list of verbs available
    verbs = list_verbs(VERBS_ENTRY_POINT)

    # Create the subparsers for each verb and collect the arg preprocessors
    argument_preprocessors, verb_subparsers = create_subparsers(
        parser,
        COMMAND_NAME,
        verbs,
        VERBS_ENTRY_POINT,
        sysargs,
    )

    # Determine the verb, splitting arguments into pre and post verb
    verb, pre_verb_args, post_verb_args = split_arguments_by_verb(sysargs)

    # Short circuit -h and --help
    if '-h' in pre_verb_args or '--help' in pre_verb_args:
        parser.print_help()
        sys.exit(0)

    # Error on no verb provided
    if verb is None:
        print(parser.format_usage())
        sys.exit("Error: No verb provided.")
    # Error on unknown verb provided
    if verb not in verbs:
        print(parser.format_usage())
        sys.exit("Error: Unknown verb '{0}' provided.".format(verb))

    # Short circuit -h and --help for verbs
    if '-h' in post_verb_args or '--help' in post_verb_args:
        verb_subparsers[verb].print_help()
        sys.exit(0)

    # First allow the verb's argument preprocessor to strip any args
    # and return any "extra" information it wants as a dict
    processed_post_verb_args, extras = \
        argument_preprocessors[verb](post_verb_args)
    # Then allow argparse to process the left over post-verb arguments along
    # with the pre-verb arguments and the verb itself
    args = parser.parse_args(pre_verb_args + [verb] + processed_post_verb_args)
    # Extend the argparse result with the extras from the preprocessor
    for key, value in extras.items():
        setattr(args, key, value)

    # Finally call the subparser's main function with the processed args
    # and the extras which the preprocessor may have returned
    sys.exit(args.main(args) or 0)

This function is mostly boilerplate in that it will likely not change much between commands of different types, but it would also be less transparent to have this function created for you. If you are using this boilerplate to implement your command, then you should be careful to update COMMAND_NAME to reflect your command's name.

This line defines the entry_point group for your command's verbs:

VERBS_ENTRY_POINT = '{0}.verbs'.format(COMMAND_NAME)

In the case that your command is called foo then this would become foo.verbs. This name is important because it is how verbs for this command can be provided by your Python package or others. For example, each verb for your command foo will need entry in the setup.py of its containing package, like this:

setup(
    ...
    entry_points={
        ...
        'foo.verbs': [
            'bar = foo.verbs.bar:entry_point_data',
        ],
    }
)

You can see here that you are defining bar to be a an entry_point of type foo.verbs which in turn points to a module and reference foo.verbs.bar and entry_point_data. At run time this verb pattern will let your command lookup all things defined as foo.verbs and load up the reference to which they point.

In order to add a verb to your command, a few things must happen.

First you must have an entry in the setup.py as described above. This allows the command to find the entry_point for your verb at run time. The entry_point for these verbs should point to a dictionary which describes the verb being added.

This is an example of an entry_point_data dictionary for a verb:

entry_point_data = dict(
    verb='build',
    description='Builds a workspace of packages',
    # Called for execution, given parsed arguments object
    main=main,
    # Called first to setup argparse, given argparse parser
    prepare_arguments=prepare_arguments,
    # Called after prepare_arguments, but before argparse.parse_args
    argument_preprocessor=argument_preprocessor,
)

As you can see this dictionary describes the verb and gives references to functions which allow the command to describe the verb, hook into argparse parameter creation for the verb, and to execute the verb. The verb, description, main, and prepare_arguments keys of the dictionary are required, but the argument_preprocessor key is optional.

• verb: This is the name of the verb, and is how the command knows which verb implementation to match to a verb on the command line.
• description: This is used by the argument parsing to describe the verb in --help.
• prepare_arguments: This function gets called to allow the verb to setup it's own argparse options. This function should always take one parameter which is the argparse.ArgumentParser for this verb, to which arguments can be added. It can optionally take a second parameter which are the current command line arguments. This is not always needed, but can be useful in some cases. This function should always return the parser.
• argument_preprocessor: This function is optional, but allows your verb an opportunity to process the raw arguments before they are passed to argparse's parse_args function. This can be useful when argparse is not capable of processing the options correctly.
• main: This is the implementation of the verb, it gets called last and is passed the parsed arguments. The return type of this function is used for sys.exit, a return type of None is interpreted as 0.

Here is an invented example of main, prepare_arguments, and argument_preprocessor:

def prepare_arguments(parser):
    parser.add_argument('--some-argument', action='store_true', default=False)
    return parser

def argument_preprocessor(args):
    extras = {}

    if '-strange-argument' in args:
        args.remove('-strange-argument')
        extras['strange_argument'] = True

    return args, extras

def main(options):
    print('--some-argument:', options.some_argument)
    print('-strange-argument:', options.strange_argument)
    if options.strange_argument:
        return 1
    return 0

The above example is simply to illustrate the signature of these functions and how they might be used.

API for implementing commands and verbs which used the verb pattern.

osrf_pycommon.cli_utils.verb_pattern.call_prepare_arguments(func, parser, sysargs=None)

Call a prepare_arguments function with the correct number of parameters.

The prepare_arguments function of a verb can either take one parameter, parser, or two parameters parser and args, where args are the current arguments being processed.

Parameters

• func (Callable) -- Callable prepare_arguments function.
• parser (argparse.ArgumentParser) -- parser which is always passed to the function
• sysargs (list) -- arguments to optionally pass to the function, if needed

Returns

return value of function or the parser if the function returns None.

Return type

argparse.ArgumentParser

Raises

ValueError if a function with the wrong number of parameters is given

osrf_pycommon.cli_utils.verb_pattern.create_subparsers(parser, cmd_name, verbs, group, sysargs, title=None)

Creates argparse subparsers for each verb which can be discovered.

Using the verbs parameter, the available verbs are iterated through. For each verb a subparser is created for it using the parser parameter. The cmd_name is used to fill the title and description of the add_subparsers function call. The group parameter is used with each verb to load the verb's description, prepare_arguments function, and the verb's argument_preprocessors if available. Each verb's prepare_arguments function is called, allowing them to add arguments. Finally a list of argument_preprocessors functions and verb subparsers are returned, one for each verb.

Parameters

• parser (argparse.ArgumentParser) -- parser for this command
• cmd_name (str) -- name of the command to which the verbs are being added
• verbs (list) -- list of verbs (by name as a string)
• group (str) -- name of the entry_point group for the verbs
• sysargs (list) -- list of system arguments
• title (str) -- optional custom title for the command

Returns

tuple of argument_preprocessors and verb subparsers

Return type

tuple

osrf_pycommon.cli_utils.verb_pattern.default_argument_preprocessor(args)

Return unmodified args and an empty dict for extras

osrf_pycommon.cli_utils.verb_pattern.list_verbs(group)

List verbs available for a given entry_point group.

Parameters

group (str) -- entry_point group name for the verbs to list

Returns

list of verb names for the given entry_point group

Return type

list of str

osrf_pycommon.cli_utils.verb_pattern.load_verb_description(verb_name, group)

Load description of a verb in a given group by name.

Parameters

• verb_name (str) -- name of the verb to load, as a string
• group (str) -- entry_point group name which the verb is in

Returns

verb description

Return type

dict

osrf_pycommon.cli_utils.verb_pattern.split_arguments_by_verb(arguments)

Split arguments by verb.

Given a list of arguments (list of strings), the verb, the pre verb arguments, and the post verb arguments are returned.

For example:

>>> args = ['--command-arg1', 'verb', '--verb-arg1', '--verb-arg2']
>>> split_arguments_by_verb(args)
('verb', ['--command-arg1'], ['--verb-arg1', '--verb-arg2'])

Parameters

arguments (list) -- list of system arguments

Returns

the verb (str), pre verb args (list), and post verb args (list)

Return type

tuple

There is a function and class which can be used together with your custom asyncio run loop.

The osrf_pycommon.process_utils.async_execute_process() function is a coroutine which allows you to run a process and get the output back bit by bit in real-time, either with stdout and stderr separated or combined. This function also allows you to emulate the terminal using a pty simply by toggling a flag in the parameters.

Along side this coroutine is a Protocol class, osrf_pycommon.process_utils.AsyncSubprocessProtocol, from which you can inherit in order to customize how the yielded output is handled.

Because this coroutine is built on the asyncio framework's subprocess functions, it is portable and should behave the same on all major OS's. (including on Windows where an IOCP implementation is used)

async osrf_pycommon.process_utils.async_execute_process(protocol_class, cmd=None, cwd=None, env=None, shell=False, emulate_tty=False, stderr_to_stdout=True)

Coroutine to execute a subprocess and yield the output back asynchronously.

This function is meant to be used with the Python asyncio module, which is available in Python 3.5 or greater.

Here is an example of how to use this function:

import asyncio
from osrf_pycommon.process_utils import async_execute_process
from osrf_pycommon.process_utils import AsyncSubprocessProtocol
from osrf_pycommon.process_utils import get_loop


async def setup():
    transport, protocol = await async_execute_process(
        AsyncSubprocessProtocol, ['ls', '/usr'])
    returncode = await protocol.complete
    return returncode

retcode = get_loop().run_until_complete(setup())
get_loop().close()

Tthe first argument is the default AsyncSubprocessProtocol protocol class, which simply prints output from stdout to stdout and output from stderr to stderr.

If you want to capture and do something with the output or write to the stdin, then you need to subclass from the AsyncSubprocessProtocol class, and override the on_stdout_received, on_stderr_received, and on_process_exited functions.

See the documentation for the AsyncSubprocessProtocol class for more details, but here is an example which uses asyncio from Python 3.5:

import asyncio
from osrf_pycommon.process_utils import async_execute_process
from osrf_pycommon.process_utils import AsyncSubprocessProtocol
from osrf_pycommon.process_utils import get_loop


class MyProtocol(AsyncSubprocessProtocol):
    def __init__(self, file_name, **kwargs):
        self.fh = open(file_name, 'w')
        AsyncSubprocessProtocol.__init__(self, **kwargs)

    def on_stdout_received(self, data):
        # Data has line endings intact, but is bytes in Python 3
        self.fh.write(data.decode('utf-8'))

    def on_stderr_received(self, data):
        self.fh.write(data.decode('utf-8'))

    def on_process_exited(self, returncode):
        self.fh.write("Exited with return code: {0}".format(returncode))
        self.fh.close()


async def log_command_to_file(cmd, file_name):

    def create_protocol(**kwargs):
        return MyProtocol(file_name, **kwargs)

    transport, protocol = await async_execute_process(
        create_protocol, cmd)
    returncode = await protocol.complete
    return returncode

get_loop().run_until_complete(
    log_command_to_file(['ls', '/'], '/tmp/out.txt'))
get_loop().close()

See the subprocess.Popen class for more details on some of the parameters to this function like cwd, env, and shell.

See the osrf_pycommon.process_utils.execute_process() function for more details on the emulate_tty parameter.

Parameters

• protocol_class (AsyncSubprocessProtocol or a subclass) -- Protocol class which handles subprocess callbacks
• cmd (list) -- list of arguments where the executable is the first item
• cwd (str) -- directory in which to run the command
• env (dict) -- a dictionary of environment variable names to values
• shell (bool) -- if True, the cmd variable is interpreted by a the shell
• emulate_tty (bool) -- if True, pty's are passed to the subprocess for stdout and stderr, see osrf_pycommon.process_utils.execute_process().
• stderr_to_stdout (bool) -- if True, stderr is directed to stdout, so they are not captured separately.

class osrf_pycommon.process_utils.AsyncSubprocessProtocol(stdin=None, stdout=None, stderr=None)

Protocol to subclass to get events from async_execute_process().

When subclassing this Protocol class, you should override these functions:

def on_stdout_received(self, data):
    # ...

def on_stderr_received(self, data):
    # ...

def on_process_exited(self, returncode):
    # ...

By default these functions just print the data received from stdout and stderr and does nothing when the process exits.

Data received by the on_stdout_received and on_stderr_received functions is always in bytes. Therefore, it may be necessary to call .decode() on the data before printing to the screen.

Additionally, the data received will not be stripped of new lines, so take that into consideration when printing the result.

You can also override these less commonly used functions:

def on_stdout_open(self):
    # ...

def on_stdout_close(self, exc):
    # ...

def on_stderr_open(self):
    # ...

def on_stderr_close(self, exc):
    # ...

These functions are called when stdout/stderr are opened and closed, and can be useful when using pty's for example. The exc parameter of the *_close functions is None unless there was an exception.

In addition to the overridable functions this class has a few useful public attributes. The stdin attribute is a reference to the PipeProto which follows the asyncio.WriteTransport interface. The stdout and stderr attributes also reference their PipeProto. The complete attribute is a asyncio.Future which is set to complete when the process exits and its result is the return code.

The complete attribute can be used like this:

import asyncio
from osrf_pycommon.process_utils import async_execute_process
from osrf_pycommon.process_utils import AsyncSubprocessProtocol
from osrf_pycommon.process_utils import get_loop


async def setup():
    transport, protocol = await async_execute_process(
        AsyncSubprocessProtocol, ['ls', '-G', '/usr'])
    retcode = await protocol.complete
    print("Exited with", retcode)

# This will block until the protocol.complete Future is done.
get_loop().run_until_complete(setup())
get_loop().close()

connection_made(transport)

Called when a connection is made.

The argument is the transport representing the pipe connection. To receive data, wait for data_received() calls. When the connection is closed, connection_lost() is called.

pipe_data_received(fd, data)

Called when the subprocess writes data into stdout/stderr pipe.

fd is int file descriptor. data is bytes object.

process_exited()

Called when subprocess has exited.

In addtion to these functions, there is a utility function for getting the correct asyncio event loop:

osrf_pycommon.process_utils.get_loop()

This function will return the proper event loop for the subprocess async calls.

On Unix this just returns asyncio.get_event_loop(), but on Windows it will set and return a asyncio.ProactorEventLoop instead.

Like Python 3.4's subprocess.Popen (and newer versions), all of the process_utils functions do not close inheritable <https://docs.python.org/3.4/library/os.html#fd-inheritance> file descriptors before starting subprocesses. This is equivalent to passing close_fds=False to subprocess.Popen on all Python versions.

For historical context, in Python 3.2, the subprocess.Popen default for the close_fds option changed from False to True so that file descriptors opened by the parent process were closed before spawning the child process. In Python 3.4, PEP 0446 additionally made it so even when close_fds=False file descriptors which are non-inheritable are still closed before spawning the subprocess.

If you want to be able to pass file descriptors to subprocesses in Python 3.4 or higher, you will need to make sure they are inheritable <https://docs.python.org/3.4/library/os.html#fd-inheritance>.

For synchronous execution and output capture of subprocess, there are two functions:

• osrf_pycommon.process_utils.execute_process()
• osrf_pycommon.process_utils.execute_process_split()

These functions are not yet using the asyncio framework as a back-end and therefore on Windows will not stream the data from the subprocess as it does on Unix machines. Instead data will not be yielded until the subprocess is finished and all output is buffered (the normal warnings about long running programs with lots of output apply).

The streaming of output does not work on Windows because on Windows the select.select() method only works on sockets and not file-like objects which are used with subprocess pipes. asyncio implements Windows subprocess support by implementing a Proactor event loop based on Window's IOCP API. One future option will be to implement this synchronous style method using IOCP in this module, but another option is to just make synchronous the asynchronous calls, but there are issues with that as well. In the mean time, if you need streaming of output in both Windows and Unix, use the asynchronous calls.

osrf_pycommon.process_utils.execute_process(cmd, cwd=None, env=None, shell=False, emulate_tty=False)

Executes a command with arguments and returns output line by line.

All arguments, except emulate_tty, are passed directly to subprocess.Popen.

execute_process returns a generator which yields the output, line by line, until the subprocess finishes at which point the return code is yielded.

This is an example of how this function should be used:

from __future__ import print_function
from osrf_pycommon.process_utils import execute_process

cmd = ['ls', '-G']
for line in execute_process(cmd, cwd='/usr'):
    if isinstance(line, int):
        # This is a return code, the command has exited
        print("'{0}' exited with: {1}".format(' '.join(cmd), line))
        continue  # break would also be appropriate here
    # In Python 3, it will be a bytes array which needs to be decoded
    if not isinstance(line, str):
        line = line.decode('utf-8')
    # Then print it to the screen
    print(line, end='')

stdout and stderr are always captured together and returned line by line through the returned generator. New line characters are preserved in the output, so if re-printing the data take care to use end='' or first rstrip the output lines.

When emulate_tty is used on Unix systems, commands will identify that they are on a tty and should output color to the screen as if you were running it on the terminal, and therefore there should not be any need to pass arguments like -c color.ui=always to commands like git. Additionally, programs might also behave differently in when emulate_tty is being used, for example, Python will default to unbuffered output when it detects a tty.

emulate_tty works by using psuedo-terminals on Unix machines, and so if you are running this command many times in parallel (like hundreds of times) then you may get one of a few different OSError's. For example, "OSError: [Errno 24] Too many open files: '/dev/ttyp0'" or "OSError: out of pty devices". You should also be aware that you share pty devices with the rest of the system, so even if you are not using a lot, it is possible to get this error. You can catch this error before getting data from the generator, so when using emulate_tty you might want to do something like this:

from __future__ import print_function
from osrf_pycommon.process_utils import execute_process

cmd = ['ls', '-G', '/usr']
try:
    output = execute_process(cmd, emulate_tty=True)
except OSError:
    output = execute_process(cmd, emulate_tty=False)
for line in output:
    if isinstance(line, int):
        print("'{0}' exited with: {1}".format(' '.join(cmd), line))
        continue
    # In Python 3, it will be a bytes array which needs to be decoded
    if not isinstance(line, str):
        line = line.decode('utf-8')
    print(line, end='')

This way if a pty cannot be opened in order to emulate the tty then you can try again without emulation, and any other OSError should raise again with emulate_tty set to False. Obviously, you only want to do this if emulating the tty is non-critical to your processing, like when you are using it to capture color.

Any color information that the command outputs as ANSI escape sequences is captured by this command. That way you can print the output to the screen and preserve the color formatting.

If you do not want color to be in the output, then try setting emulate_tty to False, but that does not guarantee that there is no color in the output, instead it only will cause called processes to identify that they are not being run in a terminal. Most well behaved programs will not output color if they detect that they are not being executed in a terminal, but you shouldn't rely on that.

If you want to ensure there is no color in the output from an executed process, then use this function:

osrf_pycommon.terminal_color.remove_ansi_escape_sequences()

Exceptions can be raised by functions called by the implementation, for example, subprocess.Popen can raise an OSError when the given command is not found. If you want to check for the existence of an executable on the path, see: which(). However, this function itself does not raise any special exceptions.

Parameters

• cmd (list) -- list of strings with the first item being a command and subsequent items being any arguments to that command; passed directly to subprocess.Popen.
• cwd (str) -- path in which to run the command, defaults to None which means os.getcwd() is used; passed directly to subprocess.Popen.
• env (dict) -- environment dictionary to use for executing the command, default is None which uses the os.environ environment; passed directly to subprocess.Popen.
• shell (bool) -- If True the system shell is used to evaluate the command, default is False; passed directly to subprocess.Popen.
• emulate_tty (bool) -- If True attempts to use a pty to convince subprocess's that they are being run in a terminal. Typically this is useful for capturing colorized output from commands. This does not work on Windows (no pty's), so it is considered False even when True. Defaults to False.

Returns

a generator which yields output from the command line by line

Return type

generator which yields strings

Availability: Unix (streaming), Windows (blocking)

osrf_pycommon.process_utils.execute_process_split(cmd, cwd=None, env=None, shell=False, emulate_tty=False)

execute_process(), except stderr is returned separately.

Instead of yielding output line by line until yielding a return code, this function always a triplet of stdout, stderr, and return code. Each time only one of the three will not be None. Once you receive a non-None return code (type will be int) there will be no more stdout or stderr. Therefore you can use the command like this:

from __future__ import print_function
import sys
from osrf_pycommon.process_utils import execute_process_split

cmd = ['time', 'ls', '-G']
for out, err, ret in execute_process_split(cmd, cwd='/usr'):
    # In Python 3, it will be a bytes array which needs to be decoded
    out = out.decode('utf-8') if out is not None else None
    err = err.decode('utf-8') if err is not None else None
    if ret is not None:
        # This is a return code, the command has exited
        print("'{0}' exited with: {1}".format(' '.join(cmd), ret))
        break
    if out is not None:
        print(out, end='')
    if err is not None:
        print(err, end='', file=sys.stderr)

When using this, it is possible that the stdout and stderr data can be returned in a different order than what would happen on the terminal. This is due to the fact that the subprocess is given different buffers for stdout and stderr and so there is a race condition on the subprocess writing to the different buffers and this command reading the buffers. This can be avoided in most scenarios by using emulate_tty, because of the use of pty's, though the ordering can still not be guaranteed and the number of pty's is finite as explained in the documentation for execute_process(). For situations where output ordering between stdout and stderr are critical, they should not be returned separately and instead should share one buffer, and so execute_process() should be used.

For all other parameters and documentation see: execute_process()

Availability: Unix (streaming), Windows (blocking)

Currently there is only one utility function, a Python implementation of the which shell command.

osrf_pycommon.process_utils.which(cmd, mode=1, path=None, **kwargs)

Given a command, mode, and a PATH string, return the path which conforms to the given mode on the PATH, or None if there is no such file.

mode defaults to os.F_OK | os.X_OK. path defaults to the result of os.environ.get("PATH"), or can be overridden with a custom search path.

Backported from shutil.which() (https://docs.python.org/3.3/library/shutil.html#shutil.which), available in Python 3.3.