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

Type PurgeItemList

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.
Method Summary
  __init__(self)
Initializes a list with no configured exclusions.
  addDirContents(self, path, recursive)
Adds the contents of a directory to the list.
  purgeItems(self)
Purges all items in the list.
  removeYoungFiles(self, daysOld)
Removes from the list files younger than a certain age (in days).
    Inherited from FilesystemList
  addDir(self, path)
Adds a directory to the list.
  addFile(self, path)
Adds a file to the list.
  normalize(self)
Normalizes the list, ensuring that each entry is unique.
  removeDirs(self, pattern)
Removes directory entries from the list.
  removeFiles(self, pattern)
Removes file entries from the list.
  removeInvalid(self)
Removes from the list all entries that do not exist on disk.
  removeLinks(self, pattern)
Removes soft link entries from the list.
  removeMatch(self, pattern)
Removes from the list all entries matching a pattern.
  verify(self)
Verifies that all entries in the list exist on disk.
  _addDirContentsInternal(self, path, includePath, recursive)
Internal implementation of addDirContents.
  _getExcludeDirs(self)
Property target used to get the exclude directories flag.
  _getExcludeFiles(self)
Property target used to get the exclude files flag.
  _getExcludeLinks(self)
Property target used to get the exclude soft links flag.
  _getExcludePaths(self)
Property target used to get the absolute exclude paths list.
  _getExcludePatterns(self)
Property target used to get the exclude patterns list.
  _getIgnoreFile(self)
Property target used to get the ignore file.
  _setExcludeDirs(self, value)
Property target used to set the exclude directories flag.
  _setExcludeFiles(self, value)
Property target used to set the exclude files flag.
  _setExcludeLinks(self, value)
Property target used to set the exclude soft links flag.
  _setExcludePaths(self, value)
Property target used to set the exclude paths list.
  _setExcludePatterns(self, value)
Property target used to set the exclude patterns list.
  _setIgnoreFile(self, value)
Property target used to set the ignore file.
    Inherited from list
  __add__(x, y)
x.__add__(y) <==> x+y
  __contains__(x, y)
x.__contains__(y) <==> y in x
  __delitem__(x, y)
x.__delitem__(y) <==> del x[y]
  __delslice__(x, i, j)
Use of negative indices is not supported.
  __eq__(x, y)
x.__eq__(y) <==> x==y
  __ge__(x, y)
x.__ge__(y) <==> x>=y
  __getattribute__(...)
x.__getattribute__('name') <==> x.name
  __getitem__(x, y)
x.__getitem__(y) <==> x[y]
  __getslice__(x, i, j)
Use of negative indices is not supported.
  __gt__(x, y)
x.__gt__(y) <==> x>y
  __hash__(x)
x.__hash__() <==> hash(x)
  __iadd__(x, y)
x.__iadd__(y) <==> x+=y
  __imul__(x, y)
x.__imul__(y) <==> x*=y
  __iter__(x)
x.__iter__() <==> iter(x)
  __le__(x, y)
x.__le__(y) <==> x<=y
  __len__(x)
x.__len__() <==> len(x)
  __lt__(x, y)
x.__lt__(y) <==> x<y
  __mul__(x, n)
x.__mul__(n) <==> x*n
  __ne__(x, y)
x.__ne__(y) <==> x!=y
  __new__(T, S, ...)
T.__new__(S, ...) -> a new object with type S, a subtype of T
  __repr__(x)
x.__repr__() <==> repr(x)
  __rmul__(x, n)
x.__rmul__(n) <==> n*x
  __setitem__(x, i, y)
x.__setitem__(i, y) <==> x[i]=y
  __setslice__(x, i, j, y)
Use of negative indices is not supported.
  append(...)
L.append(object) -- append object to end
  count(L, value)
L.count(value) -> integer -- return number of occurrences of value
  extend(...)
L.extend(iterable) -- extend list by appending elements from the iterable
  index(...)
L.index(value, [start, [stop]]) -> integer -- return first index of value
  insert(...)
L.insert(index, object) -- insert object before index
  pop(L, index)
L.pop([index]) -> item -- remove and return item at index (default last)
  remove(...)
L.remove(value) -- remove first occurrence of value
  reverse(...)
L.reverse() -- reverse *IN PLACE*
  sort(...)
L.sort(cmpfunc=None) -- stable sort *IN PLACE*; cmpfunc(x, y) -> -1, 0, 1
    Inherited from object
  __delattr__(...)
x.__delattr__('name') <==> del x.name
  __reduce__(...)
helper for pickle
  __reduce_ex__(...)
helper for pickle
  __setattr__(...)
x.__setattr__('name', value) <==> x.name = value
  __str__(x)
x.__str__() <==> str(x)

Property Summary
    Inherited from FilesystemList
  excludeDirs: Boolean indicating whether directories should be excluded.
  excludeFiles: Boolean indicating whether files should be excluded.
  excludeLinks: Boolean indicating whether soft links should be excluded.
  excludePaths: List of absolute paths to be excluded.
  excludePatterns: List of regular expression patterns to be excluded.
  ignoreFile: Name of file which will cause directory contents to be ignored.

Method Details

__init__(self)
(Constructor)

Initializes a list with no configured exclusions.
Overrides:
CedarBackup2.filesystem.FilesystemList.__init__

addDirContents(self, path, recursive=True)

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 - Directory path whose contents should be added to the list
           (type=String representing a path on disk)
recursive - Indicates whether directory contents should be added recursively.
           (type=Boolean value)
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:
CedarBackup2.filesystem.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.

purgeItems(self)

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

removeYoungFiles(self, daysOld)

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 - Minimum age of files that are to be kept in the list.
           (type=Integer value >= 0.)
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.


Generated by Epydoc 2.1 on Mon Sep 4 13:49:33 2006 http://epydoc.sf.net