2 """ Which - locate a command
4 * adapted from Brian Curtin's http://bugs.python.org/file15381/shutil_which.patch
5 * see http://bugs.python.org/issue444582
6 * uses ``PATHEXT`` on Windows
7 * searches current directory before ``PATH`` on Windows,
8 but not before an explicitly passed path
9 * accepts both string or iterable for an explicitly passed path, or pathext
10 * accepts an explicitly passed empty path, or pathext (either '' or [])
11 * does not search ``PATH`` for files that have a path specified in their name already
12 * moved defpath and defpathext lists initialization to module level,
13 instead of initializing them on each function call
14 * changed interface: which_files() returns generator, which() returns first match,
15 or raises IOError(errno.ENOENT)
17 .. function:: which_files(file [, mode=os.F_OK | os.X_OK[, path=None[, pathext=None]]])
19 Return a generator which yields full paths in which the *file* name exists
20 in a directory that is part of the file name, or on *path*,
21 and has the given *mode*.
22 By default, *mode* matches an inclusive OR of os.F_OK and os.X_OK - an
23 existing executable file.
24 The *path* is, by default, the ``PATH`` variable on the platform,
25 or the string/iterable passed in as *path*.
26 In the event that a ``PATH`` variable is not found, :const:`os.defpath` is used.
27 On Windows, a current directory is searched before using the ``PATH`` variable,
28 but not before an explicitly passed *path*.
29 The *pathext* is only used on Windows to match files with given extensions appended as well.
30 It defaults to the ``PATHEXT`` variable, or the string/iterable passed in as *pathext*.
31 In the event that a ``PATHEXT`` variable is not found,
32 default value for Windows XP/Vista is used.
33 The command is always searched without extension first,
34 even when *pathext* is explicitly passed.
36 .. function:: which(file [, mode=os.F_OK | os.X_OK[, path=None[, pathext=None]]])
37 Return first match generated by which_files(file, mode, path, pathext),
38 or raise IOError(errno.ENOENT).
41 __docformat__ = 'restructuredtext en'
42 __all__ = 'which which_files pathsep defpath defpathext F_OK R_OK W_OK X_OK'.split()
45 from os import access, defpath, pathsep, environ, F_OK, R_OK, W_OK, X_OK
46 from os.path import exists, dirname, split, join
48 windows = sys.platform.startswith('win')
50 defpath = environ.get('PATH', defpath).split(pathsep)
53 defpath.insert(0, '.') # can insert without checking, when duplicates are removed
54 # given the quite usual mess in PATH on Windows, let's rather remove duplicates
56 defpath = [dir for dir in defpath if dir.lower() not in seen and not seen.add(dir.lower())]
59 defpathext = [''] + environ.get('PATHEXT',
60 '.COM;.EXE;.BAT;.CMD;.VBS;.VBE;.JS;.JSE;.WSF;.WSH;.MSC').lower().split(pathsep)
64 def which_files(file, mode=F_OK | X_OK, path=None, pathext=None):
65 """ Locate a file in a path supplied as a part of the file name,
66 or the user's path, or a supplied path.
67 The function yields full paths (not necessarily absolute paths),
68 in which the given file name matches an existing file in a directory on the path.
70 >>> def test_which(expected, *args, **argd):
71 ... result = list(which_files(*args, **argd))
72 ... assert result == expected, 'which_files: %s != %s' % (result, expected)
75 ... result = [ which(*args, **argd) ]
78 ... assert result[:1] == expected[:1], 'which: %s != %s' % (result[:1], expected[:1])
80 >>> if windows: cmd = environ['COMSPEC']
81 >>> if windows: test_which([cmd], 'cmd')
82 >>> if windows: test_which([cmd], 'cmd.exe')
83 >>> if windows: test_which([cmd], 'cmd', path=dirname(cmd))
84 >>> if windows: test_which([cmd], 'cmd', pathext='.exe')
85 >>> if windows: test_which([cmd], cmd)
86 >>> if windows: test_which([cmd], cmd, path='<nonexistent>')
87 >>> if windows: test_which([cmd], cmd, pathext='<nonexistent>')
88 >>> if windows: test_which([cmd], cmd[:-4])
89 >>> if windows: test_which([cmd], cmd[:-4], path='<nonexistent>')
91 >>> if windows: test_which([], 'cmd', path='<nonexistent>')
92 >>> if windows: test_which([], 'cmd', pathext='<nonexistent>')
93 >>> if windows: test_which([], '<nonexistent>/cmd')
94 >>> if windows: test_which([], cmd[:-4], pathext='<nonexistent>')
96 >>> if not windows: sh = '/bin/sh'
97 >>> if not windows: test_which([sh], 'sh')
98 >>> if not windows: test_which([sh], 'sh', path=dirname(sh))
99 >>> if not windows: test_which([sh], 'sh', pathext='<nonexistent>')
100 >>> if not windows: test_which([sh], sh)
101 >>> if not windows: test_which([sh], sh, path='<nonexistent>')
102 >>> if not windows: test_which([sh], sh, pathext='<nonexistent>')
104 >>> if not windows: test_which([], 'sh', mode=W_OK) # not running as root, are you?
105 >>> if not windows: test_which([], 'sh', path='<nonexistent>')
106 >>> if not windows: test_which([], '<nonexistent>/sh')
108 filepath, file = split(file)
114 elif isinstance(path, str):
115 path = path.split(pathsep)
119 elif isinstance(pathext, str):
120 pathext = pathext.split(pathsep)
122 if not '' in pathext:
123 pathext.insert(0, '') # always check command without extension, even for custom pathext
126 basepath = join(dir, file)
128 fullpath = basepath + ext
129 if exists(fullpath) and access(fullpath, mode):
132 def which(file, mode=F_OK | X_OK, path=None, pathext=None):
133 """ Locate a file in a path supplied as a part of the file name,
134 or the user's path, or a supplied path.
135 The function returns full path (not necessarily absolute path),
136 in which the given file name matches an existing file in a directory on the path,
137 or raises IOError(errno.ENOENT).
139 >>> # for doctest see which_files()
142 return iter(which_files(file, mode, path, pathext)).next()
143 except StopIteration:
145 from errno import ENOENT
148 raise IOError(ENOENT, '%s not found' % (mode & X_OK and 'command' or 'file'), file)
151 if __name__ == '__main__':
155 # vim:expandtab:smartindent:tabstop=4:softtabstop=4:shiftwidth=4: