filename (str) – The file name to locate. The file name may contain references
to a user’s home directory (~user), environment variables
(${HOME}/bin), and shell wildcards (? and *); all of
which will be expanded.
cwd (bool) – Start by looking in the current working directory
[default: True]
mode (mask) – If not None, only return files that can be accessed for
reading/writing/executing. Valid values are the inclusive OR of
{os.R_OK, os.W_OK, os.X_OK} [default: os.R_OK]
ext (str or iterable of str) – If not None, also look for filename+ext [default: None]
pathlist (str or iterable of str) – A list of strings containing paths to search, each string
contains a single path. If pathlist is a string, then it is
first split using os.pathsep to generate the pathlist
[default: []].
allow_pathlist_deep_references (bool) – If allow_pathlist_deep_references is True and the filename
appears to be a relative path, allow deep reference matches
relative to directories in the pathlist (e.g., if filename is
foo/my.exe and /usr/bin is in the pathlist, then
find_file() could return /usr/bin/foo/my.exe). If
allow_pathlist_deep_references is False and the filename appears
to be a relative path, then only matches relative to the current
directory are allowed (assuming cwd==True). [default: True]