buildtest.utils.file

This module provides some generic file and directory level operation that include the following: 1. Check if path is a File or Directory via is_file(), is_dir() 2. Create a directory via create_dir() 3. Walk a directory tree based on single extension using walk_tree() 4. Resolve path including shell and user expansion along with getting realpath to file using resolve_path() 5. Read and write a file via read_file(), write_file()

Module Contents

Functions

is_file(→ bool)

Check if file exist and returns True/False

is_dir(→ bool)

Check if input directory exist and is a directory. If so return True otherwise returns False.

is_symlink(→ bool)

Check if the given link is a symlink and return True, if it is not a symlink or the symlink is broken return False.

search_files(root_dir, regex_pattern[, numfiles, ...])

This method will search for files in a directory based on a regex pattern.

walk_tree(root_dir[, ext, max_depth, numfiles, ...])

This method will traverse a directory tree and return list of files

create_dir(→ None)

Create a directory if it doesn't exist. If directory contains variable

resolve_path(→ str)

This method will resolve a file path to account for shell expansion and resolve paths in

read_file(→ str)

This method is used to read a file and return content of file.

create_file(→ None)

This method will create an empty file

write_file(→ None)

This method is used to write an input content to a file specified by

remove_file(→ None)

This method is responsible for removing a file. The input path is an absolute path

load_json(→ dict)

Given a filename, resolves full path to file and loads json file. This method will

Attributes

max_files_traversed

buildtest.utils.file.max_files_traversed = 999999
buildtest.utils.file.is_file(fname: str) → bool[source]

Check if file exist and returns True/False

Parameters:

fname (str) – file path to check

Returns:

True if path is a file and is a realpath otherwise returns False

Return type:

bool

buildtest.utils.file.is_dir(dirname: str) → bool[source]

Check if input directory exist and is a directory. If so return True otherwise returns False. We resolve path by invoking resolve_path()

Parameters:

dirname (str) – directory path to check

Returns:

True if directory exists otherwise returns False.

Return type:

bool

Check if the given link is a symlink and return True, if it is not a symlink or the symlink is broken return False.

Parameters:

filename (str) – Input filename to check if its a symbolic link

Returns:

True if filename is a symbolic link otherwise return False if its not a symbolic link or broken link

Return type:

bool

buildtest.utils.file.search_files(root_dir, regex_pattern, numfiles=None, max_depth=None, file_traverse_limit=999999, file_type='file')[source]

This method will search for files in a directory based on a regex pattern.

Parameters:

  • root_dir (str) – Root directory to search for files

  • regex_pattern (str) – A regex pattern to search for files

  • numfiles (int, optional) – Specify number of files to return. If not specified, all files will be returned.

  • max_depth (int, optional) – Specify maximum depth to traverse during directory walk.

  • file_traverse_limit (int, optional) – Maximum number of files to traverse during directory walk

  • file_type (str, optional) – Type of files to return, either ‘file’, ‘dir’, or ‘symlink’. Default is ‘file’.

Returns: A list of files that match the regex pattern

buildtest.utils.file.walk_tree(root_dir, ext=None, max_depth=None, numfiles=None, file_traverse_limit=999999, file_type='file')[source]

This method will traverse a directory tree and return list of files based on extension type. This method invokes is_dir() to check if directory exists before traversal.

Parameters:

  • root_dir (str) – directory path to traverse

  • ext (str or list, optional) – File extension or list of file extensions to search in traversal

  • max_depth (int, optional) – Maximum depth to traverse

  • numfiles (int, optional) – Number of files to return

  • file_traverse_limit (int, optional) – Maximum number of files to traverse during directory walk

  • file_type (str, optional) – Type of files to return, either ‘file’, ‘dir’, or ‘symlink’. Default is ‘file’.

Returns:

A list of file paths for a directory traversal based on extension type. If ext is None we retrieve all files

Return type:

list

buildtest.utils.file.create_dir(dirname: str) → None[source]

Create a directory if it doesn’t exist. If directory contains variable expansion ($HOME) or user expansion (~), we resolve this before creating directory. If there is an error creating directory we raise an exception BuildTestError

Parameters:

dirname (str) – directory path to create

Raises:

BuildTestError – If there is an error creating directory we raise an exception BuildTestError

Returns:

creates the directory or print an exception message upon failure

Return type:

None

buildtest.utils.file.resolve_path(path: str, exist: bool = True) → str[source]

This method will resolve a file path to account for shell expansion and resolve paths in when a symlink is provided in the file. This method assumes file already exists.

Parameters:

  • path (str) – file path to resolve

  • exist (bool) – a boolean to determine if filepath should be returned if filepath doesn’t exist on filesystem.

Returns:

Full path to file if file exists or exist=True is set. We could return None if path is not defined or file path doesn’t exist and exist=False

Return type:

str

Raises:

BuildTestError – If input path is not of type str

>>> a = resolve_path("$HOME/.bashrc")
>>> assert a
>>> b = resolve_path("$HOME/.bashrc1", exist=False)
>>> assert b
>>> c = resolve_path("$HOME/.bashrc1", exist=True)
>>> assert not c
buildtest.utils.file.read_file(filepath: str) → str[source]

This method is used to read a file and return content of file. If filepath is not a string we raise an error. We run resolve_path() to get realpath to file and account for shell or user expansion. The return will be a valid file or None so we check if input is an invalid file. Finally we read the file and return the content of the file as a string.

Parameters:

filepath (str) – File name to read

Raises:

BuildTestError –

  • if filepath is invalid

  • filepath is not an instance of type str.

  • An exception can be raised if there is an issue reading file with an exception of IOError

Returns:

content of input file

Return type:

str

buildtest.utils.file.create_file(filepath: str) → None[source]

This method will create an empty file

buildtest.utils.file.write_file(filepath: str, content: str) → None[source]

This method is used to write an input content to a file specified by filepath. Both filepath and content must be a str. An error is raised if filepath is not a string or a directory. If content is not a str, we return None since we can’t write the content to file. Finally, we write the content to file and return. A successful write will return nothing otherwise an exception will occur during the write process.

Parameters:

  • filepath (str) – file name to write

  • content (str) – content to write to file

Raises:

BuildTestError –

  • filepath is not str

  • filepath is directory via is_dir

  • content of file is not of type str

  • Error writing file with an exception of type IOError

buildtest.utils.file.remove_file(fpath: str) → None[source]

This method is responsible for removing a file. The input path is an absolute path to file. We check for exceptions first, and return immediately before removing file.

Parameters:

fpath (str) – full path to file to remove

Raises:

BuildTestError –

buildtest.utils.file.load_json(fname: str) → dict[source]

Given a filename, resolves full path to file and loads json file. This method will catch exception json.JSONDecodeError and raise an exception with useful message. If there is no error we return content of json file

Parameters:

fname (str) – Name of file to read and load json content

Raises:

BuildTestError – Raise exception if file is not resolved via resolve_path() or failure to load JSON document