Two other possible uses for this program, other than documenting an install, are as follow:

In addition to being the main program that users will run, the snapshot module also contains the code for displaying the menu and responding to user selections. Table 2-1 shows the function used in the snapshot module.

The snapshothelper module contains the functions that do most of the "heavy lifting" for the program. They essentially provide services, in the form of functions, to the main program when called upon. Table 2-2 describes the functions in the snapshothelper module.

This first part is quite simply a program header:

#=======================================#
#SNAPSHOT.PY                            #
#DIRECTORY/FILE SYSTEM SNAPSHOT PROGRAM #
#BY JAMES O. KNOWLTON, COPYRIGHT 2007   #
#=======================================#

When writing any code, including Python, it's always a good idea to create a header, which is just a formatted comment at the top of the source code file, indicating who wrote it, and what it's for. It's likely you are already familiar with this standard practice, but it is included here once to be thorough. From now on, we'll skip over the header in each source file.

In Python, quite often the first line of executable code you'll see in a source file is an import statement:

import sys, os, snapshothelper

In this case, you are importing three modules: the standard modules os and sys, and our helper module snapshothelper. Notice that the module we created is imported in the same way as the modules from the Standard Library (those that are included with Python). In fact, if you navigate to the lib directory under your Python program, you'll actually find os.py and sys.py, which are the python files (modules) you're importing. You can even open them in IDLE and look at them if you're curious.

We're going to skip over the menu() function for now because it actually makes more sense to do so, to follow the flow of the program.

The first thing the main program does is create a string variable called choice and assign it to nothing:

choice = ""

Although Python is a dynamically typed language (meaning it interprets the data types of members based on their context), variables still have to be assigned some kind of value before they can be used. That's why you have this line—to create memory space for a string variable called choice. If for some reason you want to initialize a variable but don't want to give it an initial value, you can assign it to None, as in the following example:

X = None

Next, you create a while loop that will form the bulk of your decision tree:

while choice != "5":
    choice = menu()
    if choice == "1":
        os.system('cls')
        print '''CREATE SNAPSHOT
        ===================================='''
        directory = raw_input 
                    ("Enter the directory name to create a snapshot of: ")
        filename = raw_input 

("Enter the name of the snapshot file to create: ")
        snapshothelper.createSnapshot(directory, filename)
    elif choice == "2":
        os.system('cls')
        print '''
        LIST SNAPSHOT FILES
        ====================================
        Enter the file extension for your snapshot files
        (for example, 'snp' if your files end in '.snp'):
        '''
        extension = raw_input("		")
        snapshothelper.listSnapshots(extension)
    elif choice == "3":
        os.system('cls')
        print '''
        COMPARE SNAPSHOTS
        ====================================
        '''
        snap1 = raw_input("Enter the filename of snapshot 1: ")
        snap2 = raw_input("Enter the filename of snapshot 2: ")
        snapshothelper.compareSnapshots(snap1, snap2)
    elif choice == "4":
        snapshothelper.showHelp()
         else:
        if choice != "5":
             snapshothelper.invalidChoice()

The while loop checks for the choice variable being assigned to the string "5".

while choice != "5":

Because the first time through the choice variable is an empty string, the while loop will execute at least once. The first thing it does is assign the variable choice to the return value of the function menu():

choice = menu()

Once the variable choice has been assigned a value (based on actions taken while the menu() function was run), the program determines what to do based on the user's menu selection. Because there is no case or switch statement in Python, the same functionality is developed through a series of if-elif statements. At the end, there is an else statement, which is the "fallback" option.

If the user enters 1, the program prompts the user to input a snapshot directory and filename for the snapshot file, respectively, and then assigns those values to variables (through the raw_input() function). It then executes the createSnapshot function, which is in the snapshothelper module:

if choice == "1":
        os.system('cls')
        print '''CREATE SNAPSHOT
        ===================================='''
        directory = raw_input 
                    ("Enter the directory name to create a snapshot of: ")
        filename = raw_input 
                   ("Enter the name of the snapshot file to create: ")
        snapshothelper.createSnapshot(directory, filename)

Notice that the module name has to be entered first, followed by the function name, in dot notation. If a function resides in the same module where it is being called (such as the menu() function in this module), then the module name is not required. The values of the two entered variables are passed to the function as parameters.

If the user enters 2, the program prompts the user for the extension they have used for their snapshot files. This response is assigned to a variable (again through the raw_input command) and the listSnapshots method in snapshothelper is called, passing the snapshot file extension to it:

elif choice == "2":
        os.system('cls')
        print '''
        LIST SNAPSHOT FILES
        ====================================
        Enter the file extension for your snapshot files
        (for example, 'snp' if your files end in '.snp'):
        '''
        extension = raw_input("		")
        snapshothelper.listSnapshots(extension)

If the user enters 3, the user is prompted for the names of the two snapshot files to compare. Then the compareSnapshots function is called, passing the names of the snapshot files as parameters:

elif choice == "3":
        os.system('cls')
        print '''
        COMPARE SNAPSHOTS
        ====================================
        '''
        snap1 = raw_input("Enter the filename of snapshot 1: ")
        snap2 = raw_input("Enter the filename of snapshot 2: ")
        snapshothelper.compareSnapshots(snap1, snap2)

If the user enters 4, the showHelp method in snapshothelper is called, which simply displays the help text.

elif choice == "4":
    snapshothelper.showHelp()
else:
    snapshothelper.invalidChoice()

What if the user enters 5? Well, remember our while loop? It only executes while choice does not equal 5. If the user enters 5, then it breaks out of the loop, and because there is no more code outside the while loop, the programs ends.

Let's now look at the menu() function, as control is passing to it at this point:

#MENU
def menu():
    os.system('cls')
    print '''
    DIRECTORY/FILE COMPARISON TOOL
    ====================================
    Please type a number and press enter:

    1.  Create a snapshot
    2.  List snapshot files
    3.  Compare snapshots
    4.  Help
    5.  Exit
    '''
    choice = raw_input("	")
    return choice

As you can see, the first thing the menu program does is clear the screen by accessing the os.system() function. Remember when we imported the os module? This is why. Importing a module enables you to use its resources. The os module is especially useful, as it gives you access to operating system resources. For example, the os.system() function enables you to run any command you could run at a system prompt (such as cls to clear the screen on a Windows command prompt).

After clearing the screen, print a menu to it. Notice the three single-quote characters used in this print statement ('''). This convention enables you to create a multi-line message and have Python output it exactly as you type it.

As you can see from the menu that's displayed, the user is presented with five options:

Then the local variable choice is assigned to the output of the raw_input() function. The raw_input() function is a built-in function that has tremendous value. It enables you to prompt the user and then assign what they type (after they press Enter) to a variable. In this case, we're already presenting the menu, so we don't want to put anything in the message of the raw_input() command, but we do want to move the cursor over a bit, so we can insert an escape character for a tab (" ") in the parameter for the prompt. This moves the cursor to where we want it.

The final line of the menu() function returns a value to the code that called it—in this case, returning the string representing the user's selection.

return choice

The createSnapshot() function takes a directory (to create the snapshot for) and a filename (the name of the snapshot file), and creates a snapshot file. Take a look at it in its entirety, and then we'll go through it piece by piece:

def createSnapshot(directory, filename):
    cumulative_directories = []
    cumulative_files = []

    for root, dirs, files in os.walk(directory):
        cumulative_directories = cumulative_directories + dirs
        cumulative_files = cumulative_files + files

    try:
        output = open(filename, 'wb')
        pickle.dump(cumulative_directories, output, −1)
        pickle.dump(cumulative_files, output, −1)
        output.close()
    except:
        print "Problems encounted trying to save snapshot file!"

    raw_input("Press [Enter] to continue...")
    return

The first thing it does is initialize two lists, one to hold a cumulative list of directories and another to hold a cumulative list of files:

cumulative_directories = []
cumulative_files = []

You then iterate through the chosen directory and build a list of all the directories and files found, using the useful os.walk() function:

for root, dirs, files in os.walk(directory):
        cumulative_directories = cumulative_directories + dirs
        cumulative_files = cumulative_files + files

At this point you have two lists—cumulative_directories[] has all the directories found, and cumulative_files[] has all the files found. However, you need some way to persistently store these data structures, in order to be able to refer to them later. The pickle module is the perfect solution. Consider pickles in a jar. They are stored and preserved for later access and use. The same applies here. Because sometimes there are issues saving a file to disk, I decided to put the routine to pickle our lists inside a try/except block, as shown here:

try:
        output = open(filename, 'wb')
        pickle.dump(cumulative_directories, output, −1)
        pickle.dump(cumulative_files, output, −1)
        output.close()
    except:
        print "Problems encounted trying to save snapshot file!"

This way, if there is a problem, the program won't crash. Instead, you'll get a nice error message. As you can see, the pickle routine uses the filename that was entered in the main program in the snapshot module to save the file.

The last bit of code simply prompts the user to press Enter and then returns control to the main program:

raw_input("Press [Enter] to continue...")
return

The listSnapshot() function lists all the snapshot files in the current directory. It takes in a file extension as a parameter and performs its file search based on that. Here is the code:

def listSnapshots(extension):
    snaplist = []
    filelist = os.listdir(os.curdir)
    for item in filelist:
        if item.find(extension)!= −1:
            snaplist.append(item)

    print '''
    Snapshot list:
    ========================
    '''
    printlist(snaplist)

    raw_input("Press [Enter] to continue...")

The first thing it does is initialize a couple of values:

snaplist = []
filelist = os.listdir(os.curdir)

snaplist is an (initially) empty list that will hold the list of snapshot files. In the second line of the preceding code, you run the os.listdir to generate a list of files (based on the current directory, thanks to the os.curdir member). You assign the output to a list with the identifier filelist.

You then run a for loop that narrows down the list:

for item in filelist:
        if item.find(extension)!= −1:
            snaplist.append(item)

This for loop iterates through each item in the filelist. It uses the find string method to determine whether the snapshot extension is present. If it is, then the file is added to the list snaplist. After the for loop is done iterating, snaplist contains a list of all the snapshot files.

The next piece of code prints out the snapshot list (for more information on the printList() function, see the corresponding section below):

print '''
Snapshot list:
========================
'''
printList(snaplist)

Control now passes back to the main program.

The compareSnapshots() method is the largest in the program, and probably the most important. It takes the names of the snapshot files to compare from the main program as parameters, compares two snapshots, and then displays the differences between the two:

def compareSnapshots(snapfile1, snapfile2):

    try:
        pkl_file = open(snapfile1, 'rb')
        dirs1 = pickle.load(pkl_file)
        files1 = pickle.load(pkl_file)
        pkl_file.close()

        pk2_file = open(snapfile2, 'rb')
        dirs2 = pickle.load(pk2_file)
        files2 = pickle.load(pk2_file)
        pk2_file.close()

except:
        print "Problems encountered accessing snapshot files!"
        raw_input("

Press [Enter] to continue...")
        return

    result_dirs = list(difflib.unified_diff(dirs1, dirs2))
    result_files = list(difflib.unified_diff(files1, files2))

    added_dirs = []
    removed_dirs = []
    added_files = []
    removed_files = []

    for result in result_files:
        if result.find("
") == −1:
            if result.startswith("+"):
                resultadd = result.strip('+')
                added_files.append(resultadd)
            elif result.startswith("-"):
                resultsubtract = result.strip('-')
                removed_files.append(resultsubtract)

    for result in result_dirs:
        if result.find("
") == −1:
            if result.startswith("+"):
                resultadd = result.strip('+')
                added_dirs.append(resultadd)
            elif result.startswith("-"):
                resultsubtract = result.strip('-')
                removed_dirs.append(resultsubtract)

    print "

Added Directories:
"
    printList(added_dirs)
    print "

Added Files:
"
    printList(added_files)
    print "

Removed Directories:
"
    printList(removed_dirs)
    print "

Removed Files:
"
    printList(removed_files)
    raw_input("

Press [Enter] to continue...")

Let's look at this section by section. The first thing the snapshot does is open the two snapshot files:

try:
        pkl_file = open(snapfile1, 'rb')
        dirs1 = pickle.load(pkl_file)
        files1 = pickle.load(pkl_file)
        pkl_file.close()

pk2_file = open(snapfile2, 'rb')
        dirs2 = pickle.load(pk2_file)
        files2 = pickle.load(pk2_file)
        pk2_file.close()
    except:
        print "Problems encountered accessing snapshot files!"
        raw_input("

Press [Enter] to continue...")
        return

Again, when dealing with files, it makes sense to encapsulate your code inside a try block. After opening a pickled file, you assign variable names to the data elements stored in the file. That's exactly what we did here. You encapsulated the retrieval of both files inside a single try block for code conciseness. You could have put each one in its own try block if you wanted to provide a more specific error message.

The next thing you do is the actual comparison. You have imported Python's difflib module in order to be able to compare two strings and show differences, so that's what you implement in these next two lines:

result_dirs = list(difflib.unified_diff(dirs1, dirs2))
result_files = list(difflib.unified_diff(files1, files2))

As you can see, you diff the directories and files, respectively, and assign the differences to the lists: result_dirs and result_files.

The next task is to separate the added files and directories from the removed files and directories. The unified_diff() method we accessed in the code appends a plus sign (+) to any files that have been added, and a minus sign (−) to any files that are missing. Based on that flag, you can parse them out:

for result in result_files:
        if result.find("
") == −1:
            if result[0] == "+":
                resultadd = result.strip('+')
                added_files.append(resultadd)
            elif result[0] == "-":
                resultsubtract = result.strip('-')
                removed_files.append(resultsubtract)
    for result in result_dirs:
        if result.find("
") == −1:
            if result[0] == "+":
                resultadd = result.strip('+')
                added_dirs.append(resultadd)
            elif result[0] == "-":
                resultsubtract = result.strip('-')
                removed_dirs.append(resultsubtract)

You basically built two lists based on whether the character found indicates the file (or directory) was added or removed. All that remains is to output the results to the screen:

print "

Added Directories:
"
    printList(added_dirs)
    print "

Added Files:
"
    printList(added_files)
    print "

Removed Directories:
"
    printList(removed_dirs)
    print "

Removed Files:
"
    printList(removed_files)

Control then passes back to the main program.

showHelp() is a very simple function. It simply displays the help screen and returns control back to the main program:

def showHelp():
    os.system('cls')
    print '''
    DIRECTORY/FILE SNAPSHOT TOOL
    ====================================
    Welcome to the directory/file snapshot tool.  This tool
    allows you to create snapshots of a directory/file tree,
    list the snapshots you have created in the current directory,
    and compare two snapshots, listing any directories and files
    added or deleted between the first snapshot and the second.

    To run the program follow the following procedure:
    1.  Create a snapshot
    2.  List snapshot files
    3.  Compare snapshots
    4.  Help (this screen)
    5.  Exit

 '''

As before, it uses the three single-quotes (''') to make it easy to format the display of large blocks of text.

This is simply an error-response function that executes when a user has entered the wrong input at the menu. Error-checking is critically important, so we implemented it here:

def invalidChoice():
    sys.stderr.write("INVALID CHOICE, TRY AGAIN!")
    raw_input("

Press [Enter] to continue...")
    return

The printList() method is just a helper method I created to print lists of items found. I created it because in testing the application, I found that without it the file list was displayed in one column, which is fine if you only have five files in the list, but not so fine if you have five hundred:

def printList(list):
    fulllist = ""
    indexnum = 1

    if len(list) > 20:
        for item in list:
            print "		" + item,
            if (indexnum)%3 == 0:
                print "
"
            indexnum = indexnum + 1
    else:
        for item in list:
            print "	" + item

It takes a list as a parameter. If the list contains more than 20 items, then the list is formatted in three columns. If the list contains 20 items or fewer, then the items appear in a single column.