duplicity.selection module

class duplicity.selection.Select(path)

Bases: object

Iterate appropriate Paths in given directory

This class acts as an iterator on account of its next() method. Basically, it just goes through all the files in a directory in order (depth-first) and subjects each file to a bunch of tests (selection functions) in order. The first test that includes or excludes the file means that the file gets included (iterated) or excluded. The default is include, so with no tests we would just iterate all the files in the directory in order.

The one complication to this is that sometimes we don’t know whether or not to include a directory until we examine its contents. For instance, if we want to include all the **.py files. If /home/ben/foo.py exists, we should also include /home and /home/ben, but if these directories contain no **.py files, they shouldn’t be included. For this reason, a test may not include or exclude a directory, but merely “scan” it. If later a file in the directory gets included, so does the directory.

As mentioned above, each test takes the form of a selection function. The selection function takes a path, and returns:

None - means the test has nothing to say about the related file 0 - the file is excluded by the test 1 - the file is included 2 - the test says the file (must be directory) should be scanned

Also, a selection function f has a variable f.exclude which should be true if f could potentially exclude some file. This is used to signal an error if the last function only includes, which would be redundant and presumably isn’t what the user intends.

Iterate(path)

Return iterator yielding paths in path

This function looks a bit more complicated than it needs to be because it avoids extra recursion (and no extra function calls for non-directory files) while still doing the “directory scanning” bit.

ParseArgs(argtuples, filelists)

Create selection functions based on list of tuples

The tuples are created when the initial commandline arguments are read. They have the form (option string, additional argument) except for the filelist tuples, which should be (option-string, (additional argument, filelist_fp)).

Select(path)

Run through the selection functions and return dominant val 0/1/2

__init__(path)

Initializer, called with Path of root directory

add_selection_func(sel_func, add_to_start=None)

Add another selection function at the end or beginning

devfiles_get_sf()

Return a selection function to exclude all dev files

exclude_older_get_sf(date)

Return selection function based on files older than modification date

filelist_general_get_sfs(filelist_fp, inc_default, list_name, mode='globbing', ignore_case=False)

Return list of selection functions by reading fileobj

filelist_fp should be an open file object inc_default is true if this is an include list list_name is just the name of the list, used for logging mode indicates whether to glob, regex, or not

filelist_sanitise_line(line, include_default)

Sanitises lines of both normal and globbing filelists, returning (line, include) and line=None if blank/comment

The aim is to parse filelists in a consistent way, prior to the interpretation of globbing statements. The function removes whitespace, comment lines and processes modifiers (leading +/-) and quotes.

general_get_sf(pattern_str, include, mode='globbing', ignore_case=False)

Return selection function given by a pattern string

The selection patterns are interpretted in accordance with the mode argument, “globbing”, “literal”, or “regex”.

The ‘ignorecase:’ prefix is a legacy feature which historically lived on the globbing code path and was only ever documented as working for globs.

glob_get_sf(glob_str, include, ignore_case=False)

Return selection function based on glob_str

literal_get_sf(lit_str, include, ignore_case=False)

Return a selection function that matches a literal string while still including the contents of any folders which are matched

other_filesystems_get_sf(include)

Return selection function matching files on other filesystems

parse_catch_error(exc)

Deal with selection error exc

parse_files_from(filelist_fp, list_name)

Loads an explicit list of files to backup from a filelist, building a dictionary of directories and their contents which can be used later to emulate a filesystem walk over the listed files only.

Each specified path is unwound to identify the parents folder(s) as these are implicitly to be included.

Paths read are not to be stripped, checked for comments, etc. Every character on each line is significant and treated as part of the path.

parse_last_excludes()

Exit with error if last selection function isn’t an exclude

present_get_sf(filename, include)

Return selection function given by existence of a file in a directory

regexp_get_sf(regexp_string, include, ignore_case=False)

Return selection function given by regexp_string

select_fn_from_literal(lit_str, include, ignore_case=False)

Return a function test_fn(path) which test where a path matches a literal string. See also select_fn_from_blog() in globmatch.py

This function is separated from literal_get_sf() so that it can be used to test the prefix without creating a loop.

TODO: this doesn’t need to be part of the Select class type, but not sure where else to put it?

set_iter()

Initialize generator, prepare to iterate.