python/which/README.txt

   1 which.py -- a portable GNU which replacement
   2 ============================================
   3
   4 Download the latest which.py packages from here:
   5     (source) http://trentm.com/downloads/which/1.1.0/which-1.1.0.zip
   6
   7
   8 Home            : http://trentm.com/projects/which/
   9 License         : MIT (see LICENSE.txt)
  10 Platforms       : Windows, Linux, Mac OS X, Unix
  11 Current Version : 1.1
  12 Dev Status      : mature, has been heavily used in a commercial product for
  13                   over 2 years
  14 Requirements    : Python >= 2.3 (http://www.activestate.com/ActivePython/)
  15
  16
  17 What's new?
  18 -----------
  19
  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)
  23 below for more.
  24
  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.
  28
  29
  30 Why which.py?
  31 -------------
  32
  33 `which.py` is a small GNU-which replacement. It has the following
  34 features:
  35
  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.
  43
  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
  47 the stdlib.
  48
  49 Please send any feedback to [Trent Mick](mailto:TrentM@ActiveState.com).
  50
  51
  52 Install Notes
  53 -------------
  54
  55 Download the latest `which.py` source package, unzip it, and run
  56 `python setup.py install`:
  57
  58     unzip which-1.1.0.zip
  59     cd which-1.1.0
  60     python setup.py install
  61
  62 If your install fails then please visit [the Troubleshooting
  63 FAQ](http://trentm.com/faq.html#troubleshooting-python-package-installation).
  64
  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.
  70
  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
  74 following:
  75
  76 - Copy `which.py` to `which` somewhere on your PATH ahead of the system
  77   `which`. This can be a symlink, as well:
  78
  79         ln -s /PATH/TO/site-packages/which.py /usr/local/bin/which
  80
  81 - Python 2.4 users might want to use Python's new '-m' switch and setup
  82   and alias:
  83
  84         alias which='python -m which'
  85
  86   or stub script like this:
  87
  88         #!/bin/sh
  89         python -m which $@
  90
  91
  92 Getting Started
  93 ---------------
  94
  95 Currently the best intro to using `which.py` as a module is its module
  96 documentation.  Either install `which.py` and run:
  97
  98     pydoc which
  99
 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
 102 executable:
 103
 104     >>> import which
 105     >>> which.which("perl")
 106     '/usr/local/bin/perl'
 107
 108 Or you might want to know if you have multiple versions on your path:
 109
 110     >>> which.whichall("perl")
 111     ['/usr/local/bin/perl', '/usr/bin/perl']
 112
 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.)
 117
 118     >>> which.whichall("perl", verbose=True)
 119     [('/usr/local/bin/perl', 'from PATH element 10'),
 120      ('/usr/bin/perl', 'from PATH element 15')]
 121
 122 You can restrict the searched path:
 123
 124     >>> which.whichall("perl", path=["/usr/bin"])
 125     ['/usr/bin/perl']
 126
 127 There is a generator interface:
 128
 129     >>> for perl in which.whichgen("perl"):
 130     ...     print "found a perl here:", perl
 131     ...
 132     found a perl here: /usr/local/bin/perl
 133     found a perl here: /usr/bin/perl
 134
 135 An exception is raised if your executable is not found:
 136
 137     >>> which.which("fuzzywuzzy")
 138     Traceback (most recent call last):
 139       ...
 140     which.WhichError: Could not find 'fuzzywuzzy' on the path.
 141     >>>
 142
 143 There are some other options too:
 144
 145     >>> help(which.which)
 146     ...
 147
 148 Run `which --help` to see command-line usage:
 149
 150     $ which --help
 151     Show the full path of commands.
 152
 153     Usage:
 154         which [<options>...] [<command-name>...]
 155
 156     Options:
 157         -h, --help      Print this help and exit.
 158         -V, --version   Print the version info and exit.
 159
 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
 164                         near misses.
 165
 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
 172                         only).
 173
 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.
 177
 178     Near misses include duplicates, non-regular files and (on Un*x)
 179     files without executable access.
 180
 181
 182 Change Log
 183 ----------
 184
 185 ### v1.1.0
 186 - Change version attributes and semantics. Before: had a _version_
 187   tuple. After: __version__ is a string, __version_info__ is a tuple.
 188
 189 ### v1.0.3
 190 - Move hosting of which.py to trentm.com. Tweaks to associated bits
 191   (README.txt, etc.)
 192
 193 ### v1.0.2:
 194 - Rename mainline handler function from _main() to main(). I can
 195   conceive of it being called from externally.
 196
 197 ### v1.0.1:
 198 - Add an optimization for Windows to allow the optional
 199   specification of a list of exts to consider when searching the
 200   path.
 201
 202 ### v1.0.0:
 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.
 206
 207 ### v0.8.1:
 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
 211   but NOT the default.
 212
 213 ### v0.8.0:
 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)
 219
 220 ### v0.7.0:
 221 - bug fix: Handle "App Paths" registered executable that does not
 222   exist.
 223 - feature: Allow an alternate PATH to be specified via 'path'
 224   optional argument to which.which() and via -p|--path command line
 225   option.
 226
 227 ### v0.6.1:
 228 - first public release
 229