1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/python/which/README.txt Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,229 @@
1.4 +which.py -- a portable GNU which replacement
1.5 +============================================
1.6 +
1.7 +Download the latest which.py packages from here:
1.8 + (source) http://trentm.com/downloads/which/1.1.0/which-1.1.0.zip
1.9 +
1.10 +
1.11 +Home : http://trentm.com/projects/which/
1.12 +License : MIT (see LICENSE.txt)
1.13 +Platforms : Windows, Linux, Mac OS X, Unix
1.14 +Current Version : 1.1
1.15 +Dev Status : mature, has been heavily used in a commercial product for
1.16 + over 2 years
1.17 +Requirements : Python >= 2.3 (http://www.activestate.com/ActivePython/)
1.18 +
1.19 +
1.20 +What's new?
1.21 +-----------
1.22 +
1.23 +I have moved hosting of `which.py` from my old [Starship
1.24 +pages](http://starship.python.net/~tmick/) to this site. These starter
1.25 +docs have been improved a little bit. See the [Change Log](#changelog)
1.26 +below for more.
1.27 +
1.28 +**WARNING**: If you are upgrading your `which.py` and you also use my
1.29 +[process.py](../process/) module, you must upgrade `process.py` as well
1.30 +because of the `_version_/__version__` change in v1.1.0.
1.31 +
1.32 +
1.33 +Why which.py?
1.34 +-------------
1.35 +
1.36 +`which.py` is a small GNU-which replacement. It has the following
1.37 +features:
1.38 +
1.39 +- it is portable (Windows, Linux, Mac OS X, Un*x);
1.40 +- it understands PATHEXT and "App Paths" registration on Windows
1.41 + (i.e. it will find everything that `start` does from the command shell);
1.42 +- it can print all matches on the PATH;
1.43 +- it can note "near misses" on the PATH (e.g. files that match but may
1.44 + not, say, have execute permissions); and
1.45 +- it can be used as a Python module.
1.46 +
1.47 +I also would be happy to have this be a replacement for the `which.py` in the
1.48 +Python CVS tree at `dist/src/Tools/scripts/which.py` which is
1.49 +Unix-specific and not usable as a module; and perhaps for inclusion in
1.50 +the stdlib.
1.51 +
1.52 +Please send any feedback to [Trent Mick](mailto:TrentM@ActiveState.com).
1.53 +
1.54 +
1.55 +Install Notes
1.56 +-------------
1.57 +
1.58 +Download the latest `which.py` source package, unzip it, and run
1.59 +`python setup.py install`:
1.60 +
1.61 + unzip which-1.1.0.zip
1.62 + cd which-1.1.0
1.63 + python setup.py install
1.64 +
1.65 +If your install fails then please visit [the Troubleshooting
1.66 +FAQ](http://trentm.com/faq.html#troubleshooting-python-package-installation).
1.67 +
1.68 +`which.py` can be used both as a module and as a script. By default,
1.69 +`which.py` will be installed into your Python's `site-packages`
1.70 +directory so it can be used as a module. On *Windows only*, `which.py`
1.71 +(and the launcher stub `which.exe`) will be installed in the Python
1.72 +install dir to (hopefully) put `which` on your PATH.
1.73 +
1.74 +On Un*x platforms (including Linux and Mac OS X) there is often a
1.75 +`which` executable already on your PATH. To use this `which` instead of
1.76 +your system's on those platforms you can manually do one of the
1.77 +following:
1.78 +
1.79 +- Copy `which.py` to `which` somewhere on your PATH ahead of the system
1.80 + `which`. This can be a symlink, as well:
1.81 +
1.82 + ln -s /PATH/TO/site-packages/which.py /usr/local/bin/which
1.83 +
1.84 +- Python 2.4 users might want to use Python's new '-m' switch and setup
1.85 + and alias:
1.86 +
1.87 + alias which='python -m which'
1.88 +
1.89 + or stub script like this:
1.90 +
1.91 + #!/bin/sh
1.92 + python -m which $@
1.93 +
1.94 +
1.95 +Getting Started
1.96 +---------------
1.97 +
1.98 +Currently the best intro to using `which.py` as a module is its module
1.99 +documentation. Either install `which.py` and run:
1.100 +
1.101 + pydoc which
1.102 +
1.103 +take a look at `which.py` in your editor or [here](which.py), or read
1.104 +on. Most commonly you'll use the `which()` method to find an
1.105 +executable:
1.106 +
1.107 + >>> import which
1.108 + >>> which.which("perl")
1.109 + '/usr/local/bin/perl'
1.110 +
1.111 +Or you might want to know if you have multiple versions on your path:
1.112 +
1.113 + >>> which.whichall("perl")
1.114 + ['/usr/local/bin/perl', '/usr/bin/perl']
1.115 +
1.116 +Use `verbose` to see where your executable is being found. (On Windows
1.117 +this might not always be so obvious as your PATH environment variable.
1.118 +There is an "App Paths" area of the registry where the `start` command
1.119 +will find "registered" executables -- `which.py` mimics this.)
1.120 +
1.121 + >>> which.whichall("perl", verbose=True)
1.122 + [('/usr/local/bin/perl', 'from PATH element 10'),
1.123 + ('/usr/bin/perl', 'from PATH element 15')]
1.124 +
1.125 +You can restrict the searched path:
1.126 +
1.127 + >>> which.whichall("perl", path=["/usr/bin"])
1.128 + ['/usr/bin/perl']
1.129 +
1.130 +There is a generator interface:
1.131 +
1.132 + >>> for perl in which.whichgen("perl"):
1.133 + ... print "found a perl here:", perl
1.134 + ...
1.135 + found a perl here: /usr/local/bin/perl
1.136 + found a perl here: /usr/bin/perl
1.137 +
1.138 +An exception is raised if your executable is not found:
1.139 +
1.140 + >>> which.which("fuzzywuzzy")
1.141 + Traceback (most recent call last):
1.142 + ...
1.143 + which.WhichError: Could not find 'fuzzywuzzy' on the path.
1.144 + >>>
1.145 +
1.146 +There are some other options too:
1.147 +
1.148 + >>> help(which.which)
1.149 + ...
1.150 +
1.151 +Run `which --help` to see command-line usage:
1.152 +
1.153 + $ which --help
1.154 + Show the full path of commands.
1.155 +
1.156 + Usage:
1.157 + which [<options>...] [<command-name>...]
1.158 +
1.159 + Options:
1.160 + -h, --help Print this help and exit.
1.161 + -V, --version Print the version info and exit.
1.162 +
1.163 + -a, --all Print *all* matching paths.
1.164 + -v, --verbose Print out how matches were located and
1.165 + show near misses on stderr.
1.166 + -q, --quiet Just print out matches. I.e., do not print out
1.167 + near misses.
1.168 +
1.169 + -p <altpath>, --path=<altpath>
1.170 + An alternative path (list of directories) may
1.171 + be specified for searching.
1.172 + -e <exts>, --exts=<exts>
1.173 + Specify a list of extensions to consider instead
1.174 + of the usual list (';'-separate list, Windows
1.175 + only).
1.176 +
1.177 + Show the full path to the program that would be run for each given
1.178 + command name, if any. Which, like GNU's which, returns the number of
1.179 + failed arguments, or -1 when no <command-name> was given.
1.180 +
1.181 + Near misses include duplicates, non-regular files and (on Un*x)
1.182 + files without executable access.
1.183 +
1.184 +
1.185 +Change Log
1.186 +----------
1.187 +
1.188 +### v1.1.0
1.189 +- Change version attributes and semantics. Before: had a _version_
1.190 + tuple. After: __version__ is a string, __version_info__ is a tuple.
1.191 +
1.192 +### v1.0.3
1.193 +- Move hosting of which.py to trentm.com. Tweaks to associated bits
1.194 + (README.txt, etc.)
1.195 +
1.196 +### v1.0.2:
1.197 +- Rename mainline handler function from _main() to main(). I can
1.198 + conceive of it being called from externally.
1.199 +
1.200 +### v1.0.1:
1.201 +- Add an optimization for Windows to allow the optional
1.202 + specification of a list of exts to consider when searching the
1.203 + path.
1.204 +
1.205 +### v1.0.0:
1.206 +- Simpler interface: What was which() is now called whichgen() -- it
1.207 + is a generator of matches. The simpler which() and whichall()
1.208 + non-generator interfaces were added.
1.209 +
1.210 +### v0.8.1:
1.211 +- API change: 0.8.0's API change making "verbose" output the default
1.212 + was a mistake -- it breaks backward compatibility for existing
1.213 + uses of which in scripts. This makes verbose, once again, optional
1.214 + but NOT the default.
1.215 +
1.216 +### v0.8.0:
1.217 +- bug fix: "App Paths" lookup had been crippled in 0.7.0. Restore that.
1.218 +- feature/module API change: Now print out (and return for the module
1.219 + interface) from where a match was found, e.g. "(from PATH element 3)".
1.220 + The module interfaces now returns (match, from-where) tuples.
1.221 +- bug fix: --path argument was broken (-p shortform was fine)
1.222 +
1.223 +### v0.7.0:
1.224 +- bug fix: Handle "App Paths" registered executable that does not
1.225 + exist.
1.226 +- feature: Allow an alternate PATH to be specified via 'path'
1.227 + optional argument to which.which() and via -p|--path command line
1.228 + option.
1.229 +
1.230 +### v0.6.1:
1.231 +- first public release
1.232 +
