Package CedarBackup2 :: Module filesystem :: Class PurgeItemList
[hide private]
[frames] | no frames]

Class PurgeItemList

source code

object --+        
         |        
      list --+    
             |    
FilesystemList --+
                 |
                PurgeItemList

List of files and directories to be purged.

A PurgeItemList is a FilesystemList containing a list of files and directories to be purged. On top of the generic functionality provided by FilesystemList, this class adds functionality to remove items that are too young to be purged, and to actually remove each item in the list from the filesystem.

The other main difference is that when you add a directory's contents to a purge item list, the directory itself is not added to the list. This way, if someone asks to purge within in /opt/backup/collect, that directory doesn't get removed once all of the files within it is gone.

Instance Methods [hide private]
 
__init__(self)
Initializes a list with no configured exclusions.
source code
 
addDirContents(self, path, recursive=True, addSelf=True)
Adds the contents of a directory to the list.
source code
 
removeYoungFiles(self, daysOld)
Removes from the list files younger than a certain age (in days).
source code
 
purgeItems(self)
Purges all items in the list.
source code

Inherited from FilesystemList: addDir, addFile, normalize, removeDirs, removeFiles, removeInvalid, removeLinks, removeMatch, verify

Inherited from list: __add__, __contains__, __delitem__, __delslice__, __eq__, __ge__, __getattribute__, __getitem__, __getslice__, __gt__, __hash__, __iadd__, __imul__, __iter__, __le__, __len__, __lt__, __mul__, __ne__, __new__, __repr__, __reversed__, __rmul__, __setitem__, __setslice__, append, count, extend, index, insert, pop, remove, reverse, sort

Inherited from object: __delattr__, __reduce__, __reduce_ex__, __setattr__, __str__

Properties [hide private]

Inherited from FilesystemList: excludeBasenamePatterns, excludeDirs, excludeFiles, excludeLinks, excludePaths, excludePatterns, ignoreFile

Inherited from object: __class__

Method Details [hide private]

__init__(self)
(Constructor)

source code 
Initializes a list with no configured exclusions.
Returns:
new list

Overrides: FilesystemList.__init__

addDirContents(self, path, recursive=True, addSelf=True)

source code 

Adds the contents of a directory to the list.

The path must exist and must be a directory or a link to a directory. The contents of the directory (but not the directory path itself) will be recursively added to the list, subject to any exclusions that are in place. If you only want the directory and its contents to be added, then pass in recursive=False.
Parameters:
  • path (String representing a path on disk) - Directory path whose contents should be added to the list
  • recursive (Boolean value) - Indicates whether directory contents should be added recursively.
  • addSelf - Ignored in this subclass.
Returns:
Number of items recursively added to the list
Raises:
  • ValueError - If path is not a directory or does not exist.
  • ValueError - If the path could not be encoded properly.
Overrides: FilesystemList.addDirContents
Notes:
  • If a directory's absolute path matches an exclude pattern or path, or if the directory contains the configured ignore file, then the directory and all of its contents will be recursively excluded from the list.
  • If the passed-in directory happens to be a soft link, it will still be recursed. However, any soft links within the directory will only be added by name, not recursively. Any invalid soft links (i.e. soft links that point to non-existent items) will be silently ignored.
  • The excludeDirs flag only controls whether any given soft link path itself is added to the list once it has been discovered. It does not modify any behavior related to directory recursion.
  • The excludeDirs flag only controls whether any given directory path itself is added to the list once it has been discovered. It does not modify any behavior related to directory recursion.

removeYoungFiles(self, daysOld)

source code 

Removes from the list files younger than a certain age (in days).

Any file whose "age" in days is less than (<) the value of the daysOld parameter will be removed from the list so that it will not be purged later when purgeItems is called. Directories and soft links will be ignored.

The "age" of a file is the amount of time since the file was last used, per the most recent of the file's st_atime and st_mtime values.
Parameters:
  • daysOld (Integer value >= 0.) - Minimum age of files that are to be kept in the list.
Returns:
Number of entries removed

Note: Some people find the "sense" of this method confusing or "backwards". Keep in mind that this method is used to remove items from the list, not from the filesystem! It removes from the list those items that you would not want to purge because they are too young. As an example, passing in daysOld of zero (0) would remove from the list no files, which would result in purging all of the files later. I would be happy to make a synonym of this method with an easier-to-understand "sense", if someone can suggest one.

purgeItems(self)

source code 

Purges all items in the list.

Every item in the list will be purged. Directories in the list will not be purged recursively, and hence will only be removed if they are empty. Errors will be ignored.

To faciliate easy removal of directories that will end up being empty, the delete process happens in two passes: files first (including soft links), then directories.
Returns:
Tuple containing count of (files, dirs) removed