The Tor Browser / file comparison
comparison: python/which/README.txt
python/which/README.txt
- branch
- TOR_BUG_9701
- changeset 15
- b8a032363ba2
equal
deleted
inserted
replaced
| -1:000000000000 | 0:a932a1506db9 |
|---|---|
| 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 |
