ahvn.utils.basic.file_utils module

ahvn.utils.basic.file_utils.touch_file(path, encoding=None, clear=False, content=None)

Create an empty file at the specified path, or write content to it.

Warning

An extra newline will be added at the end of the string to be consistent with the behavior of save_txt and append_txt.

Parameters:

• path (str) – The file path to create.

• encoding (str, optional) – Encoding to use for the file. Defaults to None.

• clear (bool, optional) – If True, clears the file if it exists. If False, do nothing if the file exists. Defaults to False.

• content (str, optional) – Content to write to the file (overwrite existing content). Only works if ckear is True or the file does not exist. Notice that an empty string content=”” is different from content=None, the former writes a linebreak to the file, while the latter creates an empty file. Defaults to None, which creates an empty file.

Returns:

The path to the created or cleared file.

Return type:

path (str)

Raises:

ValueError – If the path exists and is not a file.

ahvn.utils.basic.file_utils.touch_dir(path, clear=False)

Create an empty directory at the specified path.

Parameters:

• path (str) – The directory path to create.

• clear (bool, optional) – If True, clears the directory if it exists. If False, do nothing if the directory exists. Defaults to False.

Returns:

The path to the created or cleared directory.

Return type:

path (str)

ahvn.utils.basic.file_utils.exists_file(path)

Check if a file exists at the specified path.

Parameters:

path (str) – The file path to check.

Returns:

True if the file exists, False otherwise.

Return type:

bool

ahvn.utils.basic.file_utils.exists_dir(path)

Check if a directory exists at the specified path.

Parameters:

path (str) – The directory path to check.

Returns:

True if the directory exists, False otherwise.

Return type:

bool

ahvn.utils.basic.file_utils.exists_path(path)

Check if a path exists at the specified path.

Parameters:

path (str) – The path to check.

Returns:

True if the path exists, False otherwise.

Return type:

bool

ahvn.utils.basic.file_utils.list_files(path, ext=None, abs=False)

List all files in the specified directory with optional extension filtering. Guarantees an alphabetical sorted order (case-insensitive) of files.

Parameters:

• path (str) – The directory path to list files from.

• ext (Union[str, List[str]]) – The extension to check for. If None, return all files. If a string, checks for that specific extension. A string may contain multiple extensions separated by commas or semicolons, which will be split into a list. If a list, checks if the file has any of the extensions in the list. Each list item should be a string, which will check for that specific extension (preferably without a dot). Repeated extensions does NOT result in repeated files.

• abs (bool, optional) – If True, return absolute paths. Defaults to False.

Yields:

str – The file paths that match the criteria.

Return type:

Generator[str, None, None]

ahvn.utils.basic.file_utils.list_dirs(path, abs=False)

List all directories in the specified directory. Guarantees an alphabetical sorted order (case-insensitive) of directories.

Parameters:

• path (str) – The directory path to list directories from.

• abs (bool, optional) – If True, return absolute paths. Defaults to False.

Yields:

str – The directory paths.

Return type:

Generator[str, None, None]

ahvn.utils.basic.file_utils.list_paths(path, ext=None, abs=False)

List all directories and files in the specified directory with optional extension filtering. Directories are always listed before files. Guarantees an alphabetical sorted order (case-insensitive) of files.

Parameters:

• path (str) – The directory path to list paths from.

• ext (Union[str, List[str]]) – The extension to check for. If None, return all files. If a string, checks for that specific extension. A string may contain multiple extensions separated by commas or semicolons, which will be split into a list. If a list, checks if the file has any of the extensions in the list. Each list item should be a string, which will check for that specific extension (preferably without a dot). Repeated extensions does NOT result in repeated files.

• abs (bool, optional) – If True, return absolute paths. Defaults to False.

Yields:

str – The file and directory paths that match the criteria.

Return type:

Generator[str, None, None]

ahvn.utils.basic.file_utils.enum_files(path, ext=None, abs=False)

Enumerate all files in the specified directory with optional extension filtering. Guarantees an alphabetical sorted order (case-insensitive) of files.

Parameters:

• path (str) – The directory path to enumerate files from.

• ext (Union[str, List[str]]) – The extension to check for. If None, return all files. If a string, checks for that specific extension. A string may contain multiple extensions separated by commas or semicolons, which will be split into a list. If a list, checks if the file has any of the extensions in the list. Each list item should be a string, which will check for that specific extension (preferably without a dot). Repeated extensions does NOT result in repeated files.

• abs (bool, optional) – If True, return absolute paths. Defaults to False.

Yields:

str – The file path and its base name.

Return type:

Generator[str, None, None]

ahvn.utils.basic.file_utils.enum_dirs(path, abs=False)

Enumerate all directories in the specified directory. Guarantees an alphabetical sorted order (case-insensitive) of directories.

Parameters:

• path (str) – The directory path to enumerate directories from.

• abs (bool, optional) – If True, return absolute paths. Defaults to False.

Yields:

str – The directory path.

Return type:

Generator[str, None, None]

ahvn.utils.basic.file_utils.enum_paths(path, ext=None, abs=False)

Enumerate all directories and files in the specified directory with optional extension filtering. Directories are always listed before files. Guarantees an alphabetical sorted order (case-insensitive) of files.

Parameters:

• path (str) – The directory path to enumerate paths from.

• ext (Union[str, List[str]]) – The extension to check for. If None, return all files. If a string, checks for that specific extension. A string may contain multiple extensions separated by commas or semicolons, which will be split into a list. If a list, checks if the file has any of the extensions in the list. Each list item should be a string, which will check for that specific extension (preferably without a dot). Repeated extensions does NOT result in repeated files.

• abs (bool, optional) – If True, return absolute paths. Defaults to False.

Yields:

str – The directory or file path.

Return type:

Generator[str, None, None]

ahvn.utils.basic.file_utils.empty_dir(path, ext=None)

Check if a directory exists and is empty. If ext is provided, checks if there are any files with the specified extension(s) in the directory (recursively).

Parameters:

• path (str) – The directory path to check.

• ext (Union[str, List[str]]) – The extension to check for. If None, return all files. If a string, checks for that specific extension. A string may contain multiple extensions separated by commas or semicolons, which will be split into a list. If a list, checks if the file has any of the extensions in the list. Each list item should be a string, which will check for that specific extension (preferably without a dot). Repeated extensions does NOT result in repeated files.

Returns:

True if the directory exists and contains no items, False otherwise.

Return type:

bool

ahvn.utils.basic.file_utils.nonempty_dir(path, ext=None)

Check if a directory exists and is not empty. If ext is provided, checks if there are any files with the specified extension(s) in the directory (recursively).

Parameters:

• path (str) – The directory path to check.

• ext (Union[str, List[str]]) – The extension to check for. If None, return all files. If a string, checks for that specific extension. A string may contain multiple extensions separated by commas or semicolons, which will be split into a list. If a list, checks if the file has any of the extensions in the list. Each list item should be a string, which will check for that specific extension (preferably without a dot). Repeated extensions does NOT result in repeated files.

Returns:

True if the directory exists and contains at least one item, False otherwise.

Return type:

bool

ahvn.utils.basic.file_utils.copy_file(src, dst, mode='replace')

Copy a file from source to destination.

Parameters:

• src (str) – The source file path.

• dst (str) – The destination file path.

• mode (str, optional) – The copy mode. ‘replace’ to overwrite, ‘skip’ to skip if exists, ‘strict’ to raise an error if exists. Defaults to ‘replace’.

Returns:

The destination file path.

Return type:

str

Raises:

ValueError – If the source does not exist or is not a file, or if the destination exists and mode is ‘strict’.

ahvn.utils.basic.file_utils.copy_dir(src, dst, mode='merge', **kwargs)

Copy a directory from source to destination.

Parameters:

• src (str) – The source directory path.

• dst (str) – The destination directory path.

• mode (str, optional) – The copy mode. ‘replace’ to overwrite, ‘skip’ to skip if exists, ‘strict’ to raise an error if exists, ‘merge’ to merge contents. Defaults to ‘merge’.

• **kwargs – Additional arguments to pass to shutil.copytree().

Returns:

The destination directory path.

Return type:

str

Raises:

ValueError – If the source does not exist or is not a directory, or if the destination exists and mode is ‘strict’.

ahvn.utils.basic.file_utils.copy_path(src, dst, mode='merge', **kwargs)

Copy a path from source to destination, handling both files and directories.

Parameters:

• src (str) – The source path.

• dst (str) – The destination path.

• mode (str, optional) – The copy mode. ‘replace’ to overwrite, ‘skip’ to skip if exists, ‘strict’ to raise an error if exists, ‘merge’ to merge contents. Defaults to ‘merge’.

• **kwargs – Additional arguments to pass to shutil.copytree().

Returns:

The destination path.

Return type:

str

Raises:

ValueError – If the source does not exist or is not a file/directory, or if the destination exists and mode is ‘strict’.

ahvn.utils.basic.file_utils.delete_file(path)

Delete a file at the specified path.

Parameters:

path (str) – The file path to delete.

Returns:

True if the file exists and was deleted, False otherwise.

Return type:

bool

ahvn.utils.basic.file_utils.delete_dir(path)

Delete a directory at the specified path.

Parameters:

path (str) – The directory path to delete.

Returns:

True if the directory exists and was deleted, False otherwise.

Return type:

bool

ahvn.utils.basic.file_utils.delete_path(path)

Delete a path at the specified path.

Parameters:

path (str) – The path to delete.

Returns:

True if the path exists and was deleted, False otherwise.

Return type:

bool

ahvn.utils.basic.file_utils.folder_diagram(path, annotations=None, name=None, limit=16)

Build a tree diagram from a directory path or serialized data.

Creates a hierarchical tree structure showing the file/folder organization with optional annotations. This format is optimized for LLM understanding of the resource structure.

Parameters:

• path (str) – Directory path to build tree from.

• annotations (Optional[Dict[str, str]]) – File-level annotations to display.

• name (Optional[str]) – Custom label for the root node. Defaults to the basename of path.

• limit (int, optional) – Maximum number of entries to render per directory before collapsing the middle section. Defaults to 16, displaying at most 16 directories and 16 files per directory. It is recommended to set this to an even number.

Returns:

Formatted tree structure diagram with optional annotations.

Return type:

str

Example

>>> folder_diagram("/path/to/project", {"src/main.py": "Main entry point"})
'''
project/
├── file1.py
└── src/
    └── main.py  # Main entry point
'''