API Reference

Easy to use file search and file path management.

FileManager class initializes file path management in the directory of interest. FileManager.add() is used to tag a set of file paths filtered based on different inclusion and exclusion criteria. FileManager.__getitem__() is used to retrieve file paths of interest based on a tag, filename, or pattern. find() is the core function for finding files, and it is based on os.walk and fnmatch.

class pyfilemanager.FileManager(base_dir: str, exclude_hidden: bool = True)

Easy to use file search and file path management. Add files using different inclusion and exclusion criteria under a ‘tag’. Provides dictionary-like access to file-paths where the tags serve as keys. Useful for managing files in not-so-obviously organized folders.

Parameters:

  • base_dir (str) – base directory for file search

  • exclude_hidden (bool, optional) – excludes hidden files when True. Defaults to True.

Variables:

  • base_dir (str) – base directory for file search

  • _files (dict) – {Tag: List of file paths}

  • _filters (dict) – {Tag: pattern list}

  • _inclusions (dict) – {Tag: inclusion criteria}

  • _exclusions (dict) – {Tag: exclusion criteria}

add(tag: str = 'all', pattern_list: str | list[str] = None, include: str | list[str] = None, exclude: str | list[str] = None, exclude_hidden: bool = None) → FileManager

Add files based on different inclusion and exclusion criteria. Call this method without any arguments to work with all the files in the directory using FileManager.__getitem__. Note that if a tag already exists, it will get overwritten with the new

Examples

Add files that match the pattern Camera.avi under the tag video

fm.add('video', '*Camera*.avi')

Add all files under the tag all (special case)

fm = FileManager(r'C:\videos').add()

Parameters:

  • tag (str, optional) – e.g. ‘video_files’. Defaults to all, meaning add all files in the directory recursively.

  • pattern_list (Union[str,list], optional) – e.g. ‘.avi’, [’.avi’, ‘.mp4’]. Defaults to *.

  • include (Union[str,list], optional) – Keep file paths that contain all of the supplied strings anywhere in the file path. Defaults to None.

  • exclude (Union[str,list], optional) – Disregard file paths that contain any of the supplied string anywhere in the file path. Defaults to None.

  • exclude_hidden (bool, optional) – Set the state for excluding hidden files. Defaults to the value of _exclude_hidden attribute, which defaults to True.

Returns:

Returns self. Useful for chaining commands.

Return type:

FileManager

add_by_depth(max_depth: int = 0, exclude_hidden: bool = None, include_directories: bool = False)

Add files and directories by their depth. Tags of name files0, and directories0 will be created for files and directories at depth0.

Parameters:

  • max_depth (int, optional) – Maximum depth for the search. Defaults to 0, adding the top level contents only.

  • exclude_hidden (bool, optional) – Include or exclude hidden files and directories. Defaults to the value of self._exclude_hidden, which defaults to True.

  • include_directories (bool, optional) – When set to true, one tag will be created for directories, and one for files at each depth. When set to False, only the files tag will be created at each depth. Defaults to False.

remove(tag: str) → None

Remove file paths stored under the given tag.

Parameters:

tag (str) – A tag created when using the add method.

Raises:

ValueError – If an unknown tag is supplied.

__getitem__(key: str) → list

Retrieve file paths based on -

  1. FileManager.filter method if key has special chacters such as *, ?, !, []

  2. tag

  3. exact match for the ‘stem’ of the file

  4. key is anywhere in the path

Try (0) if there are special characters in key. If not, try (2) only if (1) doesn’t return any results, and try (3) only if (2) doesn’t return any results.

Parameters:

key (str) – Either a tag, filename, or partial match.

Returns:

List of file paths.

Return type:

list

filter(pattern: str) → list

Filter self.all_files using fnmatch.filter.

Parameters:

pattern (str) – e.g. *.avi, *notes?.txt

Returns:

List of file paths.

Return type:

list

get_tags() → list

Return a list of tags created using the add method.

Returns:

List of tags.

Return type:

list

property all_files: list

Return a list of all files managed by the filemanager. Remove duplicates.

Returns:

List of file paths

Return type:

list

report(units: str = 'MB') → None

Print a report summarizing the size occupied by files under each tag.

Parameters:

units (str, optional) – One of (‘B’, ‘KB’, ‘MB’, ‘GB’, ‘TB). B is for bytes. Defaults to ‘MB’.

pyfilemanager.find(pattern: str, path: str = None, exclude_hidden: bool = True) → list

Core function for finding files based on os.walk and fnmatch.

Example

find('*.txt', r'C:\videos')

Parameters:

  • pattern (str) – Input for fnmatch.

  • path (str, optional) – Search for files in this path. Defaults to the results of os.getcwd().

  • exclude_hidden (bool, optional) – Whether to include filenames of hidden files. Defaults to True.

Returns:

List of file names.

Return type:

list