Next / Previous / Contents / Shipman's homepage

2. The interface to the PathInfo object

To use the PathInfo object, import the pathinfo.py module like this:

from pathinfo import *      

Then, to take a snapshot of the state of a file or directory, instantiate a PathInfo object like this:

info = PathInfo ( path )

where path is the path name (absolute or relative) of the file of interest.

For example, suppose you want to take a snapshot of the state of the file /etc/crontab:

cronInfo = PathInfo ( "/etc/crontab" )

If the given path does not exist or is not accessible, the PathInfo constructor will raise an OSError exception.

Here are the attributes and methods of a PathInfo object.

.path

The pathname that was passed to the constructor. This is a read-only attribute: do not modify it in place.

.size

The size of the file in bytes.

.createEpoch

The creation time of the file as an epoch time. For more information on epoch time, refer to the Python documentation for the time module.

.modEpoch

The time when the file was last modified, as an epoch time.

.isFile()

A predicate that tests whether the PathInfo object describes an ordinary file.

.isDir()

A predicate that tests whether the object describes a directory.

.isLink()

A predicate that tests whether the object describes a soft (symbolic) link.

.absPath()

Returns the absolute path name to this file. If there are any soft links in the path, their names are not replaced with the real paths.

.realPath()

Returns the absolute path name to this file. If there are any soft links in the path, their names are replaced with the real paths.

.ownerCanRead()

A predicate that tests whether the file has read permission for the owner. A predicate is a method that returns a Boolean result: in this case, it returns a True result if the file has owner read permission, or a False result if not.

.ownerCanWrite()

A predicate that tests whether the file's owner has write permission.

.ownerCanExec()

A predicate that tests whether the file's owner has execute permission.

.groupCanRead()

A predicate that tests whether the file has group read permission.

.groupCanWrite()

Predicate to test for the group write permission.

.groupCanExec()

Predicate to test for the group execute permission.

.worldCanRead()

Predicate to test the world read permission.

.worldCanWrite()

Predicate to test the world write permission.

.worldCanExec()

Predicate to test the world execute permission.

.modTime()

This method formats the modification timestamp of the path as a string in a consistent format: "yyyy-mm-dd hh:mm:ss", where yyyy is the year, mm is the month number, and so on. The advantage of using month numbers instead of month names is that this string can be used as a sort key and will order records in chronological order.

We use local time because it is more user-friendly than Universal Time.

.__str__()

The class contains a special method named __str__(). This method is called whenever an instance needs to be converted into a string, as for example if you use a PathInfo object in a print statement, or when you call the str() function on a PathInfo instance.

The value returned by this function is intended to supply general information about the file, such as you might get from the Unix ls -l command. The author dislikes the output of ls -l because the data format is irregular. Here are two example lines to illustrate this:

-rw-r--r--    1 john     tcc          1235 Dec 30  2003 vdrybean
-rw-------    1 john     tcc         15738 Jul  4 08:32 x

File vdrybean was last modified in 2003, but we don't know what time that day. File x, on the other hand, was modified last July 4, and we know when, but note that the proper interpretation of this line requires the reader to know when the listing was made. Also, it is difficult to sort on this date format.

Therefore, the string returned by this method has the format drwxrwxrwx yyyy-mm-dd hh:mm:ss size p, where:

  • drwxrwxrwx shows the mode bits in the same format as the Unix ls -l command. The first character is “-” for an ordinary file, “d” for a directory, and “l” for a soft link. The next three letters show the read (r), write (w), and execute (x) permissions for the file owner. Next come the same three permissions for group members, then the world permissions.

  • The date format displays the modification time in the format described above under the .modTime() method.

  • The size is the file size in bytes. By default we allow a generous 8 digits in this field, enough for files up to 99,999,999 bytes, but the field will expand if necessary.

  • The pathname p follows.

.__cmp__()

Python allows classes to define a .__cmp__() method that is used whenever two objects of that class are compared. It affects the use of relational operators like “>=”, calls to the cmp() function, and use of the list type's .sort() method, among others.

This method takes two arguments, the usual self as its first argument, and a second argument that provides the other object to be compared. It should return a value using the same conventions as the built-in Python comparison function, cmp(): a negative number if self comes before other, a positive number if self should follow other, and zero if they are equal.

In this particular case, the .__cmp__() method orders PathInfo objects by their .path attributes.

.status

The status tuple for this file. This is a low-level data structure from which much of the other information is derived. It is exported to the caller as a safety valve for features that the PathInfo object does not support, such as access to the time when a file was last read. For more information on the status tuple, see the Python documentation on file-related operations.

.mode

The “mode bits” from the status tuple. This integer includes permissions and a few other fields. As with the .status attribute, this is exported in case the supplied methods are not sufficient for some applications.

Here's a brief conversational example showing use of the PathInfo object. First, here's the output from the “ls -l” command for a file called re:

-rw-r--r--    1 john     1659           30 Jul 20 11:03 re

Using Python's conversational mode, let's look at these same attributes through a PathInfo object.

>>> import pathinfo
>>> re=pathinfo.PathInfo('re')
>>> re.path
're'
>>> re.size
30L
>>> re.isFile()
1
>>> re.isDir()
0
>>> re.isLink()
0
>>> re.ownerCanRead()
256
>>> re.ownerCanWrite()
128
>>> re.ownerCanExec()
0
>>> re.worldCanRead()
4
>>> re.worldCanWrite()
0
>>> re.worldCanExec()
0
>>> re.modTime()
'2005-07-20 11:03:02'
>>> print re
-rw-r--r-- 2005-07-20 11:03:02       30 re
>>>