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

Type FilesystemList

object --+    
         |    
      list --+
             |
            FilesystemList

Known Subclasses:
BackupFileList, PurgeItemList

Represents a list of filesystem items.

This is a generic class that represents a list of filesystem items. Callers can add individual files or directories to the list, or can recursively add the contents of a directory. The class also allows for up-front exclusions in several forms (all files, all directories, all items matching a pattern, all items whose basename matches a pattern, or all directories containing a specific "ignore file"). Symbolic links are typically backed up non-recursively, i.e. the link to a directory is backed up, but not the contents of that link (we don't want to deal with recursive loops, etc.).

The custom methods such as addFile will only add items if they exist on the filesystem and do not match any exclusions that are already in place. However, since a FilesystemList is a subclass of Python's standard list class, callers can also add items to the list in the usual way, using methods like append() or insert(). No validations apply to items added to the list in this way; however, many list-manipulation methods deal "gracefully" with items that don't exist in the filesystem, often by ignoring them.

Once a list has been created, callers can remove individual items from the list using standard methods like pop() or remove() or they can use custom methods to remove specific types of entries or entries which match a particular pattern.

Notes:

Method Summary
  __init__(self)
Initializes a list with no configured exclusions.
  addFile(self, path)
Adds a file to the list.
  addDir(self, path)
Adds a directory to the list.
  addDirContents(self, path, recursive, addSelf)
Adds the contents of a directory to the list.
  removeFiles(self, pattern)
Removes file entries from the list.
  removeDirs(self, pattern)
Removes directory entries from the list.
  removeLinks(self, pattern)
Removes soft link entries from the list.
  removeMatch(self, pattern)
Removes from the list all entries matching a pattern.
  removeInvalid(self)
Removes from the list all entries that do not exist on disk.
  normalize(self)
Normalizes the list, ensuring that each entry is unique.
  verify(self)
Verifies that all entries in the list exist on disk.
  _addDirContentsInternal(self, path, includePath, recursive)
Internal implementation of addDirContents.
  _getExcludeBasenamePatterns(self)
Property target used to get the exclude basename patterns list.
  _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.
  _setExcludeBasenamePatterns(self, value)
Property target used to set the exclude basename patterns list.
  _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)
  __reversed__(...)
L.__reversed__() -- return a reverse iterator over the list
  __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(cmp=None, key=None, reverse=False) -- stable sort *IN PLACE*; cmp(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
  excludeFiles: Boolean indicating whether files should be excluded.
  excludeDirs: Boolean indicating whether directories 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 (matching complete path) to be excluded.
  excludeBasenamePatterns: List of regular expression patterns (matching basename) 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:
__builtin__.list.__init__

addFile(self, path)

Adds a file to the list.

The path must exist and must be a file or a link to an existing file. It will be added to the list subject to any exclusions that are in place.
Parameters:
path - File path to be added to the list
           (type=String representing a path on disk)
Returns:
Number of items added to the list.
Raises:
ValueError - If path is not a file or does not exist.
ValueError - If the path could not be encoded properly.

addDir(self, path)

Adds a directory to the list.

The path must exist and must be a directory or a link to an existing directory. It will be added to the list subject to any exclusions that are in place. The ignoreFile does not apply to this method, only to addDirContents.
Parameters:
path - Directory path to be added to the list
           (type=String representing a path on disk)
Returns:
Number of items 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.

addDirContents(self, path, recursive=True, addSelf=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 (as well as 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 immediate 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)
addSelf - Indicates whether the directory itself should be added to the list.
           (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.

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 directory path itself is added to the list once it has been discovered. It does not modify any behavior related to directory recursion.

removeFiles(self, pattern=None)

Removes file entries from the list.

If pattern is not passed in or is None, then all file entries will be removed from the list. Otherwise, only those file entries matching the pattern will be removed. Any entry which does not exist on disk will be ignored (use removeInvalid to purge those entries).

This method might be fairly slow for large lists, since it must check the type of each item in the list. If you know ahead of time that you want to exclude all files, then you will be better off setting excludeFiles to True before adding items to the list.
Parameters:
pattern - Regular expression pattern representing entries to remove
Returns:
Number of entries removed

removeDirs(self, pattern=None)

Removes directory entries from the list.

If pattern is not passed in or is None, then all directory entries will be removed from the list. Otherwise, only those directory entries matching the pattern will be removed. Any entry which does not exist on disk will be ignored (use removeInvalid to purge those entries).

This method might be fairly slow for large lists, since it must check the type of each item in the list. If you know ahead of time that you want to exclude all directories, then you will be better off setting excludeDirs to True before adding items to the list (note that this will not prevent you from recursively adding the contents of directories).
Parameters:
pattern - Regular expression pattern representing entries to remove
Returns:
Number of entries removed

removeLinks(self, pattern=None)

Removes soft link entries from the list.

If pattern is not passed in or is None, then all soft link entries will be removed from the list. Otherwise, only those soft link entries matching the pattern will be removed. Any entry which does not exist on disk will be ignored (use removeInvalid to purge those entries).

This method might be fairly slow for large lists, since it must check the type of each item in the list. If you know ahead of time that you want to exclude all soft links, then you will be better off setting excludeLinks to True before adding items to the list.
Parameters:
pattern - Regular expression pattern representing entries to remove
Returns:
Number of entries removed

removeMatch(self, pattern)

Removes from the list all entries matching a pattern.

This method removes from the list all entries which match the passed in pattern. Since there is no need to check the type of each entry, it is faster to call this method than to call the removeFiles, removeDirs or removeLinks methods individually. If you know which patterns you will want to remove ahead of time, you may be better off setting excludePatterns or excludeBasenamePatterns before adding items to the list.
Parameters:
pattern - Regular expression pattern representing entries to remove
Returns:
Number of entries removed.

Note: Unlike when using the exclude lists, the pattern here is not bounded at the front and the back of the string. You can use any pattern you want.

removeInvalid(self)

Removes from the list all entries that do not exist on disk.

This method removes from the list all entries which do not currently exist on disk in some form. No attention is paid to whether the entries are files or directories.
Returns:
Number of entries removed.

normalize(self)

Normalizes the list, ensuring that each entry is unique.

verify(self)

Verifies that all entries in the list exist on disk.
Returns:
True if all entries exist, False otherwise.

_addDirContentsInternal(self, path, includePath=True, recursive=True)

Internal implementation of addDirContents.

This internal implementation exists due to some refactoring. Basically, some subclasses have a need to add the contents of a directory, but not the directory itself. This is different than the standard FilesystemList behavior and actually ends up making a special case out of the first call in the recursive chain. Since I don't want to expose the modified interface, addDirContents ends up being wholly implemented in terms of this method.
Parameters:
path - Directory path whose contents should be added to the list.
includePath - Indicates whether to include the path as well as contents.
recursive - Indicates whether directory contents should be added recursively.
Returns:
Number of items recursively added to the list
Raises:
ValueError - If path is not a directory or does not exist.

_getExcludeBasenamePatterns(self)

Property target used to get the exclude basename patterns list.

_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.

_setExcludeBasenamePatterns(self, value)

Property target used to set the exclude basename patterns list. A None value is converted to an empty list.

_setExcludeDirs(self, value)

Property target used to set the exclude directories flag. No validations, but we normalize the value to True or False.

_setExcludeFiles(self, value)

Property target used to set the exclude files flag. No validations, but we normalize the value to True or False.

_setExcludeLinks(self, value)

Property target used to set the exclude soft links flag. No validations, but we normalize the value to True or False.

_setExcludePaths(self, value)

Property target used to set the exclude paths list. A None value is converted to an empty list. Elements do not have to exist on disk at the time of assignment.
Raises:
ValueError - If any list element is not an absolute path.

_setExcludePatterns(self, value)

Property target used to set the exclude patterns list. A None value is converted to an empty list.

_setIgnoreFile(self, value)

Property target used to set the ignore file. The value must be a non-empty string if it is not None.
Raises:
ValueError - If the value is an empty string.

Property Details

excludeFiles

Boolean indicating whether files should be excluded.
Get Method:
_getExcludeFiles(self)
Set Method:
_setExcludeFiles(self, value)

excludeDirs

Boolean indicating whether directories should be excluded.
Get Method:
_getExcludeDirs(self)
Set Method:
_setExcludeDirs(self, value)

excludeLinks

Boolean indicating whether soft links should be excluded.
Get Method:
_getExcludeLinks(self)
Set Method:
_setExcludeLinks(self, value)

excludePaths

List of absolute paths to be excluded.
Get Method:
_getExcludePaths(self)
Set Method:
_setExcludePaths(self, value)

excludePatterns

List of regular expression patterns (matching complete path) to be excluded.
Get Method:
_getExcludePatterns(self)
Set Method:
_setExcludePatterns(self, value)

excludeBasenamePatterns

List of regular expression patterns (matching basename) to be excluded.
Get Method:
_getExcludeBasenamePatterns(self)
Set Method:
_setExcludeBasenamePatterns(self, value)

ignoreFile

Name of file which will cause directory contents to be ignored.
Get Method:
_getIgnoreFile(self)
Set Method:
_setIgnoreFile(self, value)

Generated by Epydoc 2.1 on Thu Mar 29 20:58:27 2007 http://epydoc.sf.net