Python Cookbook

Versioning Filenames

Credit: Robin Parmar

Problem

You want make a backup copy of a file, before you overwrite it, with the standard protocol of appending a three-digit version number to the name of the old file.

Solution

This simple approach to file versioning uses a function, rather than wrapping file objects into a class:

def VersionFile(file_spec, vtype='copy'):
    import os, shutil

    if os.path.isfile(file_spec):
        # or, do other error checking:
        if vtype not in 'copy', 'rename':
             vtype = 'copy'

        # Determine root filename so the extension doesn't get longer
        n, e = os.path.splitext(file_spec)

        # Is e an integer?
        try:
             num = int(e)
             root = n
        except ValueError:
             root = file_spec

        # Find next available file version
        for i in xrange(1000):
             new_file = '%s.%03d' % (root, i)
             if not os.path.isfile(new_file):
                  if vtype == 'copy':
                      shutil.copy(file_spec, new_file)
                  else:
                      os.rename(file_spec, new_file)
                  return 1

    return 0

if _ _name_ _ == '_ _main_ _':
      # test code (you will need a file named test.txt)
      print VersionFile('test.txt')
      print VersionFile('test.txt')
      print VersionFile('test.txt')

Discussion

The purpose of the VersionFile function is to ensure that an existing file is copied (or renamed, as indicated by the optional second parameter) before you open it for writing or updating and therefore modify it. It is polite to make such backups of files before you mangle them. The actual copy or renaming is performed by shutil.copy and os.rename, respectively, so the only issue is what name to use as the target.

A popular way to determine backups’ names is versioning (i.e., appending to the filename a gradually incrementing number). This recipe determines the new_name by first extracting the filename’s root (just in case you call it with an already-versioned filename) and then successively appending to that root the further extensions .000, .001, and so on, until a name built in this manner does not correspond to any existing file. Then, and only then, is the name used as the target of a copy or renaming. Note that VersionFile is limited to 1,000 versions, so you should have an archive plan after that. You also need the file to exist before it is first versioned—you cannot back up what does not yet exist.

This is a lightweight implementation of file versioning. For a richer, heavier, and more complete one, see Recipe 4.27.

See Also

Recipe 4.27; documentation for the os and shutil modules in the Library Reference.