CedarBackup2.filesystem.PurgeItemList

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]
new empty list |
__init__(self) Initializes a list with no configured exclusions. | source code
addDirContents(self, path, recursive=True, addSelf=True, linkDepth=0, dereference=False) 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 `FilesystemList` (private): `_addDirContentsInternal`, `_getExcludeBasenamePatterns`, `_getExcludeDirs`, `_getExcludeFiles`, `_getExcludeLinks`, `_getExcludePaths`, `_getExcludePatterns`, `_getIgnoreFile`, `_setExcludeBasenamePatterns`, `_setExcludeDirs`, `_setExcludeFiles`, `_setExcludeLinks`, `_setExcludePaths`, `_setExcludePatterns`, `_setIgnoreFile` Inherited from `list`: `__add__`, `__contains__`, `__delitem__`, `__delslice__`, `__eq__`, `__ge__`, `__getattribute__`, `__getitem__`, `__getslice__`, `__gt__`, `__iadd__`, `__imul__`, `__iter__`, `__le__`, `__len__`, `__lt__`, `__mul__`, `__ne__`, `__new__`, `__repr__`, `__reversed__`, `__rmul__`, `__setitem__`, `__setslice__`, `__sizeof__`, `append`, `count`, `extend`, `index`, `insert`, `pop`, `remove`, `reverse`, `sort` Inherited from `object`: `__delattr__`, `__format__`, `__reduce__`, `__reduce_ex__`, `__setattr__`, `__str__`, `__subclasshook__`

Class Variables | [hide private]
Inherited from `list`: `__hash__`

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 empty list Overrides: object.__init__

### addDirContents(self, path, recursive=True, addSelf=True, linkDepth=0, dereference=False) | 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. `linkDepth` (Integer value, where zero means not to follow any soft links) - Depth of soft links that should be followed `dereference` (Boolean value) - Indicates whether soft links, if followed, should be dereferenced 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 be recursed. However, the linkDepth parameter controls whether any soft links within the directory will be recursed. The link depth is maximum depth of the tree at which soft links should be followed. So, a depth of 0 does not follow any soft links, a depth of 1 follows only links within the passed-in directory, a depth of 2 follows the links at the next level down, etc. 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. If you call this method on a link to a directory that link will never be dereferenced (it may, however, be followed).

### 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