:py:mod:`buildtest.utils.file` ============================== .. py:module:: buildtest.utils.file .. autoapi-nested-parse:: 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 ~~~~~~~~~ .. autoapisummary:: buildtest.utils.file.is_file buildtest.utils.file.is_dir buildtest.utils.file.is_symlink buildtest.utils.file.search_files buildtest.utils.file.walk_tree buildtest.utils.file.create_dir buildtest.utils.file.resolve_path buildtest.utils.file.read_file buildtest.utils.file.create_file buildtest.utils.file.write_file buildtest.utils.file.remove_file buildtest.utils.file.load_json Attributes ~~~~~~~~~~ .. autoapisummary:: buildtest.utils.file.max_files_traversed .. py:data:: max_files_traversed :value: 999999 .. py:function:: is_file(fname: str) -> bool Check if file exist and returns True/False :param fname: file path to check :type fname: str :returns: True if path is a file and is a realpath otherwise returns False :rtype: bool .. py:function:: is_dir(dirname: str) -> bool Check if input directory exist and is a directory. If so return ``True`` otherwise returns ``False``. We resolve path by invoking :func:`resolve_path` :param dirname: directory path to check :type dirname: str :returns: True if directory exists otherwise returns False. :rtype: bool .. py:function:: is_symlink(filename: str) -> 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``. :param filename: Input filename to check if its a symbolic link :type filename: str :returns: True if filename is a symbolic link otherwise return False if its not a symbolic link or broken link :rtype: bool .. py:function:: search_files(root_dir, regex_pattern, numfiles=None, max_depth=None, file_traverse_limit=999999, file_type='file') This method will search for files in a directory based on a regex pattern. :param root_dir: Root directory to search for files :type root_dir: str :param regex_pattern: A regex pattern to search for files :type regex_pattern: str :param numfiles: Specify number of files to return. If not specified, all files will be returned. :type numfiles: int, optional :param max_depth: Specify maximum depth to traverse during directory walk. :type max_depth: int, optional :param file_traverse_limit: Maximum number of files to traverse during directory walk :type file_traverse_limit: int, optional :param file_type: Type of files to return, either 'file', 'dir', or 'symlink'. Default is 'file'. :type file_type: str, optional Returns: A list of files that match the regex pattern .. py:function:: walk_tree(root_dir, ext=None, max_depth=None, numfiles=None, file_traverse_limit=999999, file_type='file') This method will traverse a directory tree and return list of files based on extension type. This method invokes :func:`is_dir` to check if directory exists before traversal. :param root_dir: directory path to traverse :type root_dir: str :param ext: File extension or list of file extensions to search in traversal :type ext: str or list, optional :param max_depth: Maximum depth to traverse :type max_depth: int, optional :param numfiles: Number of files to return :type numfiles: int, optional :param file_traverse_limit: Maximum number of files to traverse during directory walk :type file_traverse_limit: int, optional :param file_type: Type of files to return, either 'file', 'dir', or 'symlink'. Default is 'file'. :type file_type: str, optional :returns: A list of file paths for a directory traversal based on extension type. If ``ext`` is **None** we retrieve all files :rtype: list .. py:function:: create_dir(dirname: str) -> None 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 :param dirname: directory path to create :type dirname: str :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 :rtype: None .. py:function:: resolve_path(path: str, exist: bool = True) -> str 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. :param path: file path to resolve :type path: str :param exist: a boolean to determine if filepath should be returned if filepath doesn't exist on filesystem. :type exist: bool :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`` :rtype: 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 .. py:function:: read_file(filepath: str) -> str 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 :func:`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. :param filepath: File name to read :type filepath: str :raises BuildTestError: - if filepath is invalid - filepath is not an instance of type :class:`str`. - An exception can be raised if there is an issue reading file with an exception of :class:`IOError` :returns: content of input file :rtype: str .. py:function:: create_file(filepath: str) -> None This method will create an empty file .. py:function:: write_file(filepath: str, content: str) -> None 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. :param filepath: file name to write :type filepath: str :param content: content to write to file :type content: str :raises BuildTestError: - filepath is not :class:`str` - filepath is directory via :class:`is_dir` - content of file is not of type :class:`str` - Error writing file with an exception of type :class:`IOError` .. py:function:: remove_file(fpath: str) -> None 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. :param fpath: full path to file to remove :type fpath: str :raises BuildTestError: - If fpath is not instance of :class:`str` - If fpath is not a file using :func:`is_file` - An exception of type :class:`OSError` when removing file via :func:`os.remove` .. py:function:: load_json(fname: str) -> dict Given a filename, resolves full path to file and loads json file. This method will catch exception :class:`json.JSONDecodeError` and raise an exception with useful message. If there is no error we return content of json file :param fname: Name of file to read and load json content :type fname: str :raises BuildTestError: Raise exception if file is not resolved via :func:`resolve_path` or failure to load JSON document