summaryrefslogtreecommitdiffstats
path: root/python/which/README.txt
diff options
context:
space:
mode:
Diffstat (limited to 'python/which/README.txt')
-rw-r--r--python/which/README.txt229
1 files changed, 229 insertions, 0 deletions
diff --git a/python/which/README.txt b/python/which/README.txt
new file mode 100644
index 000000000..6ece7f6de
--- /dev/null
+++ b/python/which/README.txt
@@ -0,0 +1,229 @@
+which.py -- a portable GNU which replacement
+============================================
+
+Download the latest which.py packages from here:
+ (source) http://trentm.com/downloads/which/1.1.0/which-1.1.0.zip
+
+
+Home : http://trentm.com/projects/which/
+License : MIT (see LICENSE.txt)
+Platforms : Windows, Linux, Mac OS X, Unix
+Current Version : 1.1
+Dev Status : mature, has been heavily used in a commercial product for
+ over 2 years
+Requirements : Python >= 2.3 (http://www.activestate.com/ActivePython/)
+
+
+What's new?
+-----------
+
+I have moved hosting of `which.py` from my old [Starship
+pages](http://starship.python.net/~tmick/) to this site. These starter
+docs have been improved a little bit. See the [Change Log](#changelog)
+below for more.
+
+**WARNING**: If you are upgrading your `which.py` and you also use my
+[process.py](../process/) module, you must upgrade `process.py` as well
+because of the `_version_/__version__` change in v1.1.0.
+
+
+Why which.py?
+-------------
+
+`which.py` is a small GNU-which replacement. It has the following
+features:
+
+- it is portable (Windows, Linux, Mac OS X, Un*x);
+- it understands PATHEXT and "App Paths" registration on Windows
+ (i.e. it will find everything that `start` does from the command shell);
+- it can print all matches on the PATH;
+- it can note "near misses" on the PATH (e.g. files that match but may
+ not, say, have execute permissions); and
+- it can be used as a Python module.
+
+I also would be happy to have this be a replacement for the `which.py` in the
+Python CVS tree at `dist/src/Tools/scripts/which.py` which is
+Unix-specific and not usable as a module; and perhaps for inclusion in
+the stdlib.
+
+Please send any feedback to [Trent Mick](mailto:TrentM@ActiveState.com).
+
+
+Install Notes
+-------------
+
+Download the latest `which.py` source package, unzip it, and run
+`python setup.py install`:
+
+ unzip which-1.1.0.zip
+ cd which-1.1.0
+ python setup.py install
+
+If your install fails then please visit [the Troubleshooting
+FAQ](http://trentm.com/faq.html#troubleshooting-python-package-installation).
+
+`which.py` can be used both as a module and as a script. By default,
+`which.py` will be installed into your Python's `site-packages`
+directory so it can be used as a module. On *Windows only*, `which.py`
+(and the launcher stub `which.exe`) will be installed in the Python
+install dir to (hopefully) put `which` on your PATH.
+
+On Un*x platforms (including Linux and Mac OS X) there is often a
+`which` executable already on your PATH. To use this `which` instead of
+your system's on those platforms you can manually do one of the
+following:
+
+- Copy `which.py` to `which` somewhere on your PATH ahead of the system
+ `which`. This can be a symlink, as well:
+
+ ln -s /PATH/TO/site-packages/which.py /usr/local/bin/which
+
+- Python 2.4 users might want to use Python's new '-m' switch and setup
+ and alias:
+
+ alias which='python -m which'
+
+ or stub script like this:
+
+ #!/bin/sh
+ python -m which $@
+
+
+Getting Started
+---------------
+
+Currently the best intro to using `which.py` as a module is its module
+documentation. Either install `which.py` and run:
+
+ pydoc which
+
+take a look at `which.py` in your editor or [here](which.py), or read
+on. Most commonly you'll use the `which()` method to find an
+executable:
+
+ >>> import which
+ >>> which.which("perl")
+ '/usr/local/bin/perl'
+
+Or you might want to know if you have multiple versions on your path:
+
+ >>> which.whichall("perl")
+ ['/usr/local/bin/perl', '/usr/bin/perl']
+
+Use `verbose` to see where your executable is being found. (On Windows
+this might not always be so obvious as your PATH environment variable.
+There is an "App Paths" area of the registry where the `start` command
+will find "registered" executables -- `which.py` mimics this.)
+
+ >>> which.whichall("perl", verbose=True)
+ [('/usr/local/bin/perl', 'from PATH element 10'),
+ ('/usr/bin/perl', 'from PATH element 15')]
+
+You can restrict the searched path:
+
+ >>> which.whichall("perl", path=["/usr/bin"])
+ ['/usr/bin/perl']
+
+There is a generator interface:
+
+ >>> for perl in which.whichgen("perl"):
+ ... print "found a perl here:", perl
+ ...
+ found a perl here: /usr/local/bin/perl
+ found a perl here: /usr/bin/perl
+
+An exception is raised if your executable is not found:
+
+ >>> which.which("fuzzywuzzy")
+ Traceback (most recent call last):
+ ...
+ which.WhichError: Could not find 'fuzzywuzzy' on the path.
+ >>>
+
+There are some other options too:
+
+ >>> help(which.which)
+ ...
+
+Run `which --help` to see command-line usage:
+
+ $ which --help
+ Show the full path of commands.
+
+ Usage:
+ which [<options>...] [<command-name>...]
+
+ Options:
+ -h, --help Print this help and exit.
+ -V, --version Print the version info and exit.
+
+ -a, --all Print *all* matching paths.
+ -v, --verbose Print out how matches were located and
+ show near misses on stderr.
+ -q, --quiet Just print out matches. I.e., do not print out
+ near misses.
+
+ -p <altpath>, --path=<altpath>
+ An alternative path (list of directories) may
+ be specified for searching.
+ -e <exts>, --exts=<exts>
+ Specify a list of extensions to consider instead
+ of the usual list (';'-separate list, Windows
+ only).
+
+ Show the full path to the program that would be run for each given
+ command name, if any. Which, like GNU's which, returns the number of
+ failed arguments, or -1 when no <command-name> was given.
+
+ Near misses include duplicates, non-regular files and (on Un*x)
+ files without executable access.
+
+
+Change Log
+----------
+
+### v1.1.0
+- Change version attributes and semantics. Before: had a _version_
+ tuple. After: __version__ is a string, __version_info__ is a tuple.
+
+### v1.0.3
+- Move hosting of which.py to trentm.com. Tweaks to associated bits
+ (README.txt, etc.)
+
+### v1.0.2:
+- Rename mainline handler function from _main() to main(). I can
+ conceive of it being called from externally.
+
+### v1.0.1:
+- Add an optimization for Windows to allow the optional
+ specification of a list of exts to consider when searching the
+ path.
+
+### v1.0.0:
+- Simpler interface: What was which() is now called whichgen() -- it
+ is a generator of matches. The simpler which() and whichall()
+ non-generator interfaces were added.
+
+### v0.8.1:
+- API change: 0.8.0's API change making "verbose" output the default
+ was a mistake -- it breaks backward compatibility for existing
+ uses of which in scripts. This makes verbose, once again, optional
+ but NOT the default.
+
+### v0.8.0:
+- bug fix: "App Paths" lookup had been crippled in 0.7.0. Restore that.
+- feature/module API change: Now print out (and return for the module
+ interface) from where a match was found, e.g. "(from PATH element 3)".
+ The module interfaces now returns (match, from-where) tuples.
+- bug fix: --path argument was broken (-p shortform was fine)
+
+### v0.7.0:
+- bug fix: Handle "App Paths" registered executable that does not
+ exist.
+- feature: Allow an alternate PATH to be specified via 'path'
+ optional argument to which.which() and via -p|--path command line
+ option.
+
+### v0.6.1:
+- first public release
+