• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1"""distutils.spawn
2
3Provides the 'spawn()' function, a front-end to various platform-
4specific functions for launching another program in a sub-process.
5Also provides the 'find_executable()' to search the path for a given
6executable name.
7"""
8
9import sys
10import os
11import subprocess
12
13from distutils.errors import DistutilsExecError
14from distutils.debug import DEBUG
15from distutils import log
16
17
18def spawn(cmd, search_path=1, verbose=0, dry_run=0, env=None):
19    """Run another program, specified as a command list 'cmd', in a new process.
20
21    'cmd' is just the argument list for the new process, ie.
22    cmd[0] is the program to run and cmd[1:] are the rest of its arguments.
23    There is no way to run a program with a name different from that of its
24    executable.
25
26    If 'search_path' is true (the default), the system's executable
27    search path will be used to find the program; otherwise, cmd[0]
28    must be the exact path to the executable.  If 'dry_run' is true,
29    the command will not actually be run.
30
31    Raise DistutilsExecError if running the program fails in any way; just
32    return on success.
33    """
34    # cmd is documented as a list, but just in case some code passes a tuple
35    # in, protect our %-formatting code against horrible death
36    cmd = list(cmd)
37
38    log.info(subprocess.list2cmdline(cmd))
39    if dry_run:
40        return
41
42    if search_path:
43        executable = find_executable(cmd[0])
44        if executable is not None:
45            cmd[0] = executable
46
47    env = env if env is not None else dict(os.environ)
48
49    if sys.platform == 'darwin':
50        from distutils.util import MACOSX_VERSION_VAR, get_macosx_target_ver
51        macosx_target_ver = get_macosx_target_ver()
52        if macosx_target_ver:
53            env[MACOSX_VERSION_VAR] = macosx_target_ver
54
55    try:
56        proc = subprocess.Popen(cmd, env=env)
57        proc.wait()
58        exitcode = proc.returncode
59    except OSError as exc:
60        if not DEBUG:
61            cmd = cmd[0]
62        raise DistutilsExecError(
63            "command %r failed: %s" % (cmd, exc.args[-1])) from exc
64
65    if exitcode:
66        if not DEBUG:
67            cmd = cmd[0]
68        raise DistutilsExecError(
69              "command %r failed with exit code %s" % (cmd, exitcode))
70
71
72def find_executable(executable, path=None):
73    """Tries to find 'executable' in the directories listed in 'path'.
74
75    A string listing directories separated by 'os.pathsep'; defaults to
76    os.environ['PATH'].  Returns the complete filename or None if not found.
77    """
78    _, ext = os.path.splitext(executable)
79    if (sys.platform == 'win32') and (ext != '.exe'):
80        executable = executable + '.exe'
81
82    if os.path.isfile(executable):
83        return executable
84
85    if path is None:
86        path = os.environ.get('PATH', None)
87        if path is None:
88            try:
89                path = os.confstr("CS_PATH")
90            except (AttributeError, ValueError):
91                # os.confstr() or CS_PATH is not available
92                path = os.defpath
93        # bpo-35755: Don't use os.defpath if the PATH environment variable is
94        # set to an empty string
95
96    # PATH='' doesn't match, whereas PATH=':' looks in the current directory
97    if not path:
98        return None
99
100    paths = path.split(os.pathsep)
101    for p in paths:
102        f = os.path.join(p, executable)
103        if os.path.isfile(f):
104            # the file exists, we have a shot at spawn working
105            return f
106    return None
107