1
which.py -- a portable GNU which replacement
2
============================================
4
Download the latest which.py packages from here:
5
(source) http://trentm.com/downloads/which/1.1.0/which-1.1.0.zip
8
Home : http://trentm.com/projects/which/
9
License : MIT (see LICENSE.txt)
10
Platforms : Windows, Linux, Mac OS X, Unix
12
Dev Status : mature, has been heavily used in a commercial product for
14
Requirements : Python >= 2.3 (http://www.activestate.com/ActivePython/)
20
I have moved hosting of `which.py` from my old [Starship
21
pages](http://starship.python.net/~tmick/) to this site. These starter
22
docs have been improved a little bit. See the [Change Log](#changelog)
25
**WARNING**: If you are upgrading your `which.py` and you also use my
26
[process.py](../process/) module, you must upgrade `process.py` as well
27
because of the `_version_/__version__` change in v1.1.0.
33
`which.py` is a small GNU-which replacement. It has the following
36
- it is portable (Windows, Linux, Mac OS X, Un*x);
37
- it understands PATHEXT and "App Paths" registration on Windows
38
(i.e. it will find everything that `start` does from the command shell);
39
- it can print all matches on the PATH;
40
- it can note "near misses" on the PATH (e.g. files that match but may
41
not, say, have execute permissions); and
42
- it can be used as a Python module.
44
I also would be happy to have this be a replacement for the `which.py` in the
45
Python CVS tree at `dist/src/Tools/scripts/which.py` which is
46
Unix-specific and not usable as a module; and perhaps for inclusion in
49
Please send any feedback to [Trent Mick](mailto:TrentM@ActiveState.com).
55
Download the latest `which.py` source package, unzip it, and run
56
`python setup.py install`:
60
python setup.py install
62
If your install fails then please visit [the Troubleshooting
63
FAQ](http://trentm.com/faq.html#troubleshooting-python-package-installation).
65
`which.py` can be used both as a module and as a script. By default,
66
`which.py` will be installed into your Python's `site-packages`
67
directory so it can be used as a module. On *Windows only*, `which.py`
68
(and the launcher stub `which.exe`) will be installed in the Python
69
install dir to (hopefully) put `which` on your PATH.
71
On Un*x platforms (including Linux and Mac OS X) there is often a
72
`which` executable already on your PATH. To use this `which` instead of
73
your system's on those platforms you can manually do one of the
76
- Copy `which.py` to `which` somewhere on your PATH ahead of the system
77
`which`. This can be a symlink, as well:
79
ln -s /PATH/TO/site-packages/which.py /usr/local/bin/which
81
- Python 2.4 users might want to use Python's new '-m' switch and setup
84
alias which='python -m which'
86
or stub script like this:
95
Currently the best intro to using `which.py` as a module is its module
96
documentation. Either install `which.py` and run:
100
take a look at `which.py` in your editor or [here](which.py), or read
101
on. Most commonly you'll use the `which()` method to find an
105
>>> which.which("perl")
106
'/usr/local/bin/perl'
108
Or you might want to know if you have multiple versions on your path:
110
>>> which.whichall("perl")
111
['/usr/local/bin/perl', '/usr/bin/perl']
113
Use `verbose` to see where your executable is being found. (On Windows
114
this might not always be so obvious as your PATH environment variable.
115
There is an "App Paths" area of the registry where the `start` command
116
will find "registered" executables -- `which.py` mimics this.)
118
>>> which.whichall("perl", verbose=True)
119
[('/usr/local/bin/perl', 'from PATH element 10'),
120
('/usr/bin/perl', 'from PATH element 15')]
122
You can restrict the searched path:
124
>>> which.whichall("perl", path=["/usr/bin"])
127
There is a generator interface:
129
>>> for perl in which.whichgen("perl"):
130
... print "found a perl here:", perl
132
found a perl here: /usr/local/bin/perl
133
found a perl here: /usr/bin/perl
135
An exception is raised if your executable is not found:
137
>>> which.which("fuzzywuzzy")
138
Traceback (most recent call last):
140
which.WhichError: Could not find 'fuzzywuzzy' on the path.
143
There are some other options too:
145
>>> help(which.which)
148
Run `which --help` to see command-line usage:
151
Show the full path of commands.
154
which [<options>...] [<command-name>...]
157
-h, --help Print this help and exit.
158
-V, --version Print the version info and exit.
160
-a, --all Print *all* matching paths.
161
-v, --verbose Print out how matches were located and
162
show near misses on stderr.
163
-q, --quiet Just print out matches. I.e., do not print out
166
-p <altpath>, --path=<altpath>
167
An alternative path (list of directories) may
168
be specified for searching.
169
-e <exts>, --exts=<exts>
170
Specify a list of extensions to consider instead
171
of the usual list (';'-separate list, Windows
174
Show the full path to the program that would be run for each given
175
command name, if any. Which, like GNU's which, returns the number of
176
failed arguments, or -1 when no <command-name> was given.
178
Near misses include duplicates, non-regular files and (on Un*x)
179
files without executable access.
186
- Change version attributes and semantics. Before: had a _version_
187
tuple. After: __version__ is a string, __version_info__ is a tuple.
190
- Move hosting of which.py to trentm.com. Tweaks to associated bits
194
- Rename mainline handler function from _main() to main(). I can
195
conceive of it being called from externally.
198
- Add an optimization for Windows to allow the optional
199
specification of a list of exts to consider when searching the
203
- Simpler interface: What was which() is now called whichgen() -- it
204
is a generator of matches. The simpler which() and whichall()
205
non-generator interfaces were added.
208
- API change: 0.8.0's API change making "verbose" output the default
209
was a mistake -- it breaks backward compatibility for existing
210
uses of which in scripts. This makes verbose, once again, optional
214
- bug fix: "App Paths" lookup had been crippled in 0.7.0. Restore that.
215
- feature/module API change: Now print out (and return for the module
216
interface) from where a match was found, e.g. "(from PATH element 3)".
217
The module interfaces now returns (match, from-where) tuples.
218
- bug fix: --path argument was broken (-p shortform was fine)
221
- bug fix: Handle "App Paths" registered executable that does not
223
- feature: Allow an alternate PATH to be specified via 'path'
224
optional argument to which.which() and via -p|--path command line
228
- first public release
added
removed
lib/contrib/which/README.txt
