filefinder.finder#

Main class.

Classes

Finder(root, pattern[, use_regex, ...])

Find files using a filename pattern.
class Finder(root, pattern, use_regex=False, scan_everything=False)#

Find files using a filename pattern.

The Finder object is the main entrance point to this library. Given a root directory and a filename pattern, it can search for all corresponding files.

Parameters:

  • root (str) – The root directory of the filetree where all files can be found.

  • pattern (str) – A regular expression with the addition of ‘groups’. See Find files for details.

  • use_regex (bool) – If True, characters outside of groups are considered as valid regex (and not escaped). Default is False.

  • scan_everything (bool) – If true, look into all sub-directories up to a depth of max_scan_depth . This is appropriate if the pattern contains optional sub-directories. If false (default), check that every sub-directory matches its part of the regular expression, thus avoiding some work.

find_files()#

Find files to scan and store them.

Is automatically called when accessing files or get_files(). Sort files alphabetically.

find_matches(filename, relative=True)#

Find matches for a given filename.

Apply regex to filename and return the results as a Matches object. Fixed values are applied as normal.

Parameters:

  • filename (str) – Filename to retrieve matches from.

  • relative (bool) – True if the filename is relative to the finder root directory (default). If False, the filename is made relative before being matched.

Returns:

matches – A Matches object, or None if the filename did not match.

Return type:

Matches | None

fix_group(key, value, fix_discard=False)#

Fix a group to a string.

Parameters:

  • key (int | str) – Can be the index of a group in the pattern (starts at 0), or the name of a group. If multiple groups share the same name, they are all fixed to the same value.

  • value (str | Any) – Will replace the match for all files. Can be a string, or a value that will be formatted using the group format string. A list of values will be joined by the regex ‘|’ OR. A string will be interpreted as a regular expression, so all special characters should be properly escaped.

  • fix_discard (bool) – If True, groups with the ‘discard’ option will still be fixed. Default is False.

fix_groups(fixes=None, fix_discard=False, **fixes_kw)#

Fix multiple groups at once.

Parameters:

  • fixes (dict[Any, str | Any] | None) – Dictionnary of {group key: value}. See fix_group() for details.

  • fix_discard (bool) – If True, groups with the ‘discard’ option will still be fixed. Default is False.

  • fixes_kw (str | Any) – Same as fixes. Takes precedence.

get_absolute(filename)#

Get absolute path to filename.

Parameters:

filename (str) –

Return type:

str

get_files(relative=False, nested=None)#

Return files that matches the regex.

Lazily scan files: if files were already scanned, just return the stored list of files. Scanned files are flushed if the regex is changed (by fixing group for instance).

Parameters:

  • relative (bool) – If True, filenames are returned relative to the finder root directory. If not, paths are absolute (default).

  • nested (Sequence[str | Sequence[str]] | None) – If not None, return nested list of filenames with each level corresponding to a group, or set of group. Last set in the list is at the innermost level.

Raises:

KeyError – A group name in nested is not found in the pattern.:

Return type:

list

get_groups(key)#

Return list of groups corresponding to key.

Parameters:

key (int, str, or list of int) – Can be group index, name, or group+name combination with the syntax: ‘group:name’.

Returns:

List of groups corresponding to key.

Raises:
Return type:

list[filefinder.group.Group]

get_pattern()#

Get filename pattern.

Return type:

str

get_regex()#

Return regex.

Return type:

str

get_regex_subdirs()#

Return regexes for each sub-directory.

Return type:

list[str]

get_relative(filename)#

Get filename path relative to root.

Parameters:

filename (str) –

Return type:

str

make_filename(fixes=None, relative=False, **kw_fixes)#

Return a filename.

Replace groups with provided values. All groups must be fixed prior, or with fixes argument.

Parameters:

  • fixes (dict | None) – Dictionnary of fixes (group name or index: value). For details, see fix_group(). Will (temporarily) supplant group fixed prior. If prior fix is a list, first item will be used.

  • relative (bool) – If the filename should be relative to the finder root directory. Default is False.

  • kw_fixes (Any) – Same as fixes. Takes precedence.

Raises:

ValueError – use_regex is activated.:

Return type:

str

set_pattern(pattern)#

Set pattern and parse for group objects.

Parameters:

pattern (str) –

set_scan_everything(scan_everything, /)#

Set value for attribute scan_everything.

Void cache if necessary.

Parameters:

scan_everything (bool) –

Return type:

None

set_use_regex(use_regex, /)#

Set value for attribute use_regex.

Parameters:

use_regex (bool) –

Return type:

None

unfix_groups(*keys)#

Unfix groups.

Parameters:

keys (str) – Keys to find groups to unfix. See get_groups(). If no key is provided, all groups will be unfixed.

property files: list[tuple[str, filefinder.matches.Matches]]#

List of filenames and their matches.

Will scan files when accessed and cache the result, if it has not already been done.

max_scan_depth: int = 32#

Maximum sub-directory depth to scan when scan_everything is True.

property n_groups: int#

Number of groups in pre-regex.

root: str#

The root directory of the finder.

scan_everything: bool#

Whether to scan all subdirectories.

scanned: bool#

True if files have been scanned with current parameters.

Is reset to False if the cache (of scanned files) is voided, for instance by operation like changing fixed values of groups.

use_regex: bool#

If True, characters outside of groups are considered as valid regex (and not escaped). Default is False.