NAME

tsearchpath - Python Module For Path Searching

SYNOPSIS

import tsearchpath

DESCRIPTION

'tsearchpath' is a Python module for searching a list of paths for a particular file system 'filename'. This can be the name of a directory, file, or any other entity in the file system. This makes it easy to add things like include- or configuration file paths to your own programs.

API DOCUMENTATION

tsearchpath(filename,

pathlist, PATHDELIM=DEFAULTDELIM

)

""" Find all instances of a filename in a list of paths.

Inputs:

filename - The name of the filesystem entity (file,

directory, ...) to look for.

pathlist - A list of paths to search separated by the

PATHDELIM character (Default: ":")

Output:

Returns a list of all instances of 'filename' found on the paths specified by 'pathlist'. These appear in order of path appearance in 'pathlist' and are returned as fully qualified real path names.

Options:

PATHDELIM=char

Can be used to specify the separator character used in 'pathlist'. Provided primarily for situations where you want to maintain compatibility with Windows-style paths that use ";" as a separator.

Side Effects:

Module does not check for duplicates in the the 'pathlist'. If multiple components there map to the same real path and 'filename' exists there, the returned list will have duplicate entries.

There is no space stripping around PATHDELIM characters. Spaces are treated as part of the path component. This is almost always a mistake:

"path1 :path2 :path3"

"""

EXAMPLES

Simple 'which' type functionatily:

print tsearchpath("ls", os.getenv("PATH"))

Look for a particular file in many paths:

print tsearchpath(".profile", "/:/etc:/usr/home/foo:/usr/home/bar")

Look for a particular subdirectory in many paths:

print tsearchpath("etc", "/:/usr/local")

Look for a configuration file for your program:

rcfile = tsearchpath(".myprogrc", "./:/usr/local/myprog:/etc/myprog")

TEST PROGRAM

The 'tsearchpath' distribution tarball contains a simple test driver program to experiment with this module. The syntax for use is:

testpath.py filename searchpath [Path Separator Character]

OTHER

You must have a reasonably current version of Python installed.

BUGS AND MISFEATURES

None known as of this release.

COPYRIGHT AND LICENSING

For terms of use, see the tsearchpath-license.txt file in the program distribution. If you install tsearchpath on a FreeBSD system using the 'ports' mechanism, you will also find this file in /usr/local/share/doc/tsearchpath.

AUTHOR

Tim Daneliuk
tsearchpath@tundraware.com

DOCUMENT REVISION INFORMATION

$Id: tsearchpath.rst,v 1.101 2010/06/25 16:19:33 tundra Exp $

You can find the latest version of this program at:

http://www.tundraware.com/Software/tsearchpath