Description

A collection file related general purpose routines.

Functions

chext(path, new_ext)

Takes the path and replaces its extension with new_ext. The new_ext should include the dot ("."). For example,

        p = "test.dat"
        c = fileutils.chext(p, ".doc")

would have "c" equal to "test.doc".

eq_path(a,b)

Returns True if the path at a is equal to the path at b. This function is less strict than a == b, as it looks at each of the components, in lower-case form, and returns True if the components match. The check is made all the way to the root of the a and b.

find(pattern[, startdir]) [Lutz]

Performs a recursive search for a filename pattern.

Much like typing "dir .txt" will give you a listing of all the files with the extension "txt", this function will return a listing of all the files that match the given pattern (i.e. ".txt" or "silly").

Notice that this function will recursively traverse from the startdir.

predicate = lambda path: fnmatch.fnmatch(path, pattern) return filter(predicate, os.listdir(dir))

Arguments:

pattern : string

Search filename pattern.

startdir : string

Starting directory for the search (default = ".").

Returns:

A list of absolute paths that satisfy the pattern for the given starting directory and sub-directories.

findindir(pattern [,dir])

Returns the files found in a directory with the given pattern. The search is non-recursive.

Arguments:

pattern : string

Search filename pattern.

dir : string

Directory to search within (default=".").

Returns:

A list of strings representing files/directories that satisfy that pattern for the particular directory. Like find() all values returned are absolute paths.

getdir(path)

Takes a path and returns a the directory portion.

Assumes that if the path is just a filename, then the file resides in the local directory. Also, if the path is just a directory, it will return that directory back again. For example, consider we are in c:foobardirectory, then the following inputs would be,

blah.dat -> c:foobar c:foobar -> c:foobar c:foobarblah.dat -> c:foobar . -> c:foobar "" -> c:foobar

Arguments:

path : string

A path (all paths will be converted to absolute paths for this function).

Returns:

The directory portion of the path as explained above.

isreadonly(path)

Determines if a path is read only or not.

Assumes that the path is actually pointing to a file (satisfying os.path.isfile()), if it is not, then behavior is undefined.

This method only works on win32 machines, if you are running a non-win32 machine, this method will throw a RuntimeError.

Arguments:

path : string

A path that must point to a file that satisfies os.path.isfile() [2].

Returns:

Returns 0 if the file is not read only, returns 1 if the file is read-only.

makefilename(basename, extension)

Takes a basename and an extension and makes a file name (with the ".").

Just makes the code cleaner than using [basename]+"."+[extension]. Assumes both basename and extension are strings.

Arguments:

basename : string

The file's base name.

extension : string

Extension for the file.

Returns:

A file name of the form "<basename>.<extension>".

isfileinpath (path, fln[, cwdFlg, exeFlg])

Searches supplied path for file name and returns 1 if file is in the path. The search is non-recursive.

Arguments:

path : string

Paths delimited by os.pathsep.

fln : string

File name or path used as search argument.

cwdFlg : integer

1 prepends current working directory to path. 0 ignores current directory.(default=1).

exeFlg : integer

1 appends .exe to the file name if it has no extension. 0 does nothing.(default=0).

Returns:

0 - if file does not exist, 1 - if file exists in path, None - if error.

notfounderrormsg([parent, fln])

Returns a formatted error message to be displayed by the calling script when file is not found in path or has no associated spawning application.

Arguments:

parent : string

Name of calling script. (default=" ")

fln : string

File name either not in path or having no associated application. (default=" ")

Returns:

Formatted string:

[parent].py Error: [fln]

Incorrect path or path has no associated application. Please contact your System Administrator.

proper_case(path)

Evaluates the path and returns the path with the exact same case pattern as on the disk. For example, say your file, on the disk was TestFile.dat. If you ran,

proper_case("testfile.dat")

you would get back TestFile.dat.

remove_all(dirname)

Removes the directory and all its contents (include sub-directories). The os.removedirs function from python only works if the sub-directories are empty. This function will walk through the directories recursively removing files.

whereinpathisfile(path, fln[, cwdFlg])

Will find all occurrences in path that a regular file resides.

Arguments:

path : string

Paths of interest separated by os.pathsep

fln : string

File name of interest

cwdFlg : integer

If 1, prepends current directory to path prior to search. (default=1)

Returns:

List of strings that are the directories containing the file in the same order as path. (left to right).

lockfile

lockfile(path[, mode, lock_type])

New in 4.60.

The lockfile class is a file-like object that builds in locking mechanics. If you use the lockfile class to access a file on the disk, it will ensure that you can only have one reader/writer at a time.

You can open the object with the same path and mode rules as the standard file object. All other file object methods are also available (read, write, flush, etc.).

The lockfile class allows for different types of lock_type values.

• Exclusive (LOCK_EX): This means all other lock requests will block until the original lock is released. This means that if there is a lock on a file, an exclusive lock will not return until the lock has been released.
• Shared (LOCK_SH): This will allow "read" requests to the file, but not write requests.
• Non-Blocking (LOCK_NB): This will not block on a locked file, and will generate an fileutils.LockError immediately.

The locking mechanics only apply if you work with the lockfile object to access the same file. If you attempt to open a locked file using the standard file object, you will get undefined results.

An example of using the lock file is as follows,

        # Acquire an EXCLUSIVE lock on the file. If any other process had a lock
        # on the file, this call would block until a lock was released.
        fp = fileutils.lockfile(path, "wt", lock_type=fileutils.LOCK_EX)
        fp.write("test")
        
        # Still holding onto the lock, we will attempt to acquire another
        # lock, but this time it will be non-blocking. For demo purposes
        # we will only try 10 times.
        cnt = 0
        while cnt < 10:
            try:
                fp_o = fileutils.lockfile(path, "wt", lock_type=fileutils.LOCK_NB)
            except fileutils.LockError, e:
                print str(cnt) + str(e)
                cnt += 1
                
        fp.close() # This releases the orginal lock!
         

the above example illustrates how you can ensure that only one file at a time locks the code.

The original code was inspired by the portalocker [3] recipe on ActiveState.

Read Only File Like Object

ReadOnlyFileLike(data)

This object emulates a file-like interface in a read-only mode. This is useful if you have a chunk of in memory data that you want to keep in memory, but you want to supply a file-like interface.

A good example of this is the python zipfile module, which requires a file-like interface to unpack the data. If your "zip file" is in memory, you can wrap it with the ReadOnlyFileLike and it will let you "unpack in memory".

binary_data = load_from_somewhere()
filelike = fileutils.ReadOnlyFileLike(binary_data)
zfile = zipfile.ZipFile(filelike, mode='r')
# Do zip uncompression

in the above example, the ZipFile module will parse the filelike object as if it where a file.

This only provides "read" interfaces. If you want a "write" version, you should use the StringIO module provided by python.