Skip to content

files

Filesystem helpers for listing, filtering, and creating temporary paths.

Examples:

>>> from ures.files import get_temp_folder
>>> import os
>>> os.path.isdir(get_temp_folder())
True

get_file_paths 

get_file_paths(directory: str) -> list[str]

Retrieve all file paths within the specified directory and its subdirectories.

This function walks through the given directory recursively and returns a list of absolute file paths for every file found.

Parameters:

  • directory (str) –

    The directory path to search in.

Returns:

  • list[str] –

    list[str]: A list containing the absolute paths of all files found.

Examples:

>>> paths = get_file_paths("/path/to/directory")
>>> isinstance(paths, list)
True
Source code in ures/files.py 
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
def get_file_paths(directory: str) -> list[str]:
    """
    Retrieve all file paths within the specified directory and its subdirectories.

    This function walks through the given directory recursively and returns a list of
    absolute file paths for every file found.

    Args:
        directory (str): The directory path to search in.

    Returns:
        list[str]: A list containing the absolute paths of all files found.

    Examples:
        >>> paths = get_file_paths("/path/to/directory")
        >>> isinstance(paths, list)
        True
    """
    file_paths = []
    # Walk through the directory and its subdirectories.
    for root, _, files in os.walk(directory):
        for file in files:
            # Join the root path with the file name to get the absolute path.
            file_path = os.path.join(root, file)
            file_paths.append(str(file_path))
    return file_paths

filter_files 

filter_files(part_file_name: str, directory: str, fuzz: bool = True) -> list[str]

Retrieve file paths in the specified directory that match a given file name pattern.

This function filters file paths within a directory by checking if the file name contains the provided keyword. When 'fuzz' is True, it returns all files that contain the keyword; otherwise, it returns only the files whose name exactly matches the keyword.

Parameters:

  • part_file_name (str) –

    The substring or keyword to search for in file names.

  • directory (str) –

    The directory path to search in.

  • fuzz (bool, default: True ) –

    If True, returns all files containing the keyword. If False, returns only files with an exact name match. Defaults to True.

Returns:

  • list[str] –

    list[str]: A list of file paths that match the search criteria.

Examples:

>>> matched = filter_files("exam", "/tmp/test", fuzz=True)
>>> isinstance(matched, list)
True
Source code in ures/files.py 
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
def filter_files(part_file_name: str, directory: str, fuzz: bool = True) -> list[str]:
    """
    Retrieve file paths in the specified directory that match a given file name pattern.

    This function filters file paths within a directory by checking if the file name contains
    the provided keyword. When 'fuzz' is True, it returns all files that contain the keyword;
    otherwise, it returns only the files whose name exactly matches the keyword.

    Args:
        part_file_name (str): The substring or keyword to search for in file names.
        directory (str): The directory path to search in.
        fuzz (bool, optional): If True, returns all files containing the keyword. If False,
            returns only files with an exact name match. Defaults to True.

    Returns:
        list[str]: A list of file paths that match the search criteria.

    Examples:
        >>> matched = filter_files("exam", "/tmp/test", fuzz=True)
        >>> isinstance(matched, list)
        True
    """
    # Note: Using get_file_paths instead of a non-existent fetch_file_paths.
    file_paths = get_file_paths(directory)
    if fuzz:
        return [
            str(file_path)
            for file_path in file_paths
            if part_file_name in os.path.basename(str(file_path))
        ]
    else:
        return [
            str(file_path)
            for file_path in file_paths
            if part_file_name == os.path.basename(str(file_path))
        ]

list_directories 

list_directories(path: str) -> list[str] | None

List all subdirectories in the specified path.

This function checks whether the given path exists and then returns a list of names for each entry in the path that is a directory.

Parameters:

  • path (str) –

    The path where directories should be listed.

Returns:

  • list[str] | None –

    list[str] | None: A list of directory names if the path exists; otherwise, None.

Examples:

>>> dirs = list_directories("/tmp")
>>> isinstance(dirs, list) or dirs is None
True
Source code in ures/files.py 
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
def list_directories(path: str) -> list[str] | None:
    """
    List all subdirectories in the specified path.

    This function checks whether the given path exists and then returns a list of names for
    each entry in the path that is a directory.

    Args:
        path (str): The path where directories should be listed.

    Returns:
        list[str] | None: A list of directory names if the path exists; otherwise, None.

    Examples:
        >>> dirs = list_directories("/tmp")
        >>> isinstance(dirs, list) or dirs is None
        True
    """
    if not os.path.exists(path):
        logger.warning("The specified path does not exist: %s", path)
        return None

    # List all entries in the path.
    entries = os.listdir(path)
    directories = [
        entry for entry in entries if os.path.isdir(os.path.join(path, entry))
    ]
    return directories

get_temp_folder 

get_temp_folder() -> str

Obtain the path of a new temporary folder.

This function creates a temporary directory using Python's tempfile module and returns its path.

Returns:

  • str ( str ) –

    The path to the newly created temporary folder.

Examples:

>>> temp_folder = get_temp_folder()
>>> os.path.isdir(temp_folder)
True
Source code in ures/files.py 
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
def get_temp_folder() -> str:
    """
    Obtain the path of a new temporary folder.

    This function creates a temporary directory using Python's tempfile module and returns
    its path.

    Returns:
        str: The path to the newly created temporary folder.

    Examples:
        >>> temp_folder = get_temp_folder()
        >>> os.path.isdir(temp_folder)
        True
    """
    return tempfile.TemporaryDirectory().name

get_temp_dir_with_specific_path 

get_temp_dir_with_specific_path(*args) -> str

Create (if necessary) and return a temporary directory with a specified subpath.

This function constructs a path within the system's temporary directory using the provided arguments. If the directory does not already exist, it is created.

Parameters:

  • *args (str, default: () ) –

    Subdirectory path components under the system temp directory.

Returns:

  • str ( str ) –

    The full path of the temporary directory created or existing.

Examples:

>>> temp_dir = get_temp_dir_with_specific_path("myapp", "cache")
>>> temp_dir.endswith(os.path.join("myapp", "cache"))
True
Source code in ures/files.py 
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
def get_temp_dir_with_specific_path(*args) -> str:
    """
    Create (if necessary) and return a temporary directory with a specified subpath.

    This function constructs a path within the system's temporary directory using the provided
    arguments. If the directory does not already exist, it is created.

    Args:
        *args (str): Subdirectory path components under the system temp directory.

    Returns:
        str: The full path of the temporary directory created or existing.

    Examples:
        >>> temp_dir = get_temp_dir_with_specific_path("myapp", "cache")
        >>> temp_dir.endswith(os.path.join("myapp", "cache"))
        True
    """
    temp_dir = tempfile.gettempdir()
    flame_temp = os.path.join(temp_dir, *args)
    if not os.path.isdir(flame_temp):
        os.makedirs(flame_temp, exist_ok=True)
    return flame_temp