Coverage for pyguymer3/find_instances_of_a_file.py: 65%

1#!/usr/bin/env python3 

2 

3# Define function ... 

4def find_instances_of_a_file( 

5 path, 

6 basename, 

7 /, 

8 *, 

9 allowHidden = False, 

10 debug = __debug__, 

11 ensureNFC = True, 

12 follow_symlinks = True, 

13 return_symlinks = True, 

14): 

15 """Return a recursive list of file names in a directory that match a basename. 

16 

17 This function returns a sorted list of desired file names recursively in a directory that match a desired basename. 

18 

19 Parameters 

20 ---------- 

21 path : str 

22 the directory to search 

23 basename : str 

24 the desired basename 

25 allowHidden : bool, optional 

26 allow hidden files 

27 debug : bool, optional 

28 print debug messages 

29 ensureNFC : bool, optional 

30 ensure that the Unicode encoding is NFC 

31 follow_symlinks : bool, optional 

32 follow symbolic links 

33 return_symlinks : bool, optional 

34 include symbolic links in the returned list 

35 

36 Returns 

37 ------- 

38 ans : list of str 

39 the sorted list of desired file names 

40 

41 Notes 

42 ----- 

43 Copyright 2017 Thomas Guymer [1]_ 

44 

45 References 

46 ---------- 

47 .. [1] PyGuymer3, https://github.com/Guymer/PyGuymer3 

48 """ 

49 

50 # Import standard modules ... 

51 import os 

52 

53 # Import sub-functions ... 

54 from .make_path_safe import make_path_safe 

55 

56 # Create empty list ... 

57 contents = [] 

58 

59 # Check it exists ... 

60 if os.path.exists(path): 

61 # Open folder ... 

62 with os.scandir(path) as scanObj: 

63 # Loop over folder contents ... 

64 for entry in scanObj: 

65 # Check if the user wants to perform debugging ... 

66 if debug: 

67 # Test if this part is hidden and print the full path for 

68 # identification ... 

69 if not allowHidden and entry.name.startswith("."): 

70 print(f"WARNING: \"{entry.path}\" is hidden") 

71 

72 # Test if this part is illegal and print the full path for 

73 # identification ... 

74 if not entry.name.startswith(".") and entry.name != make_path_safe(entry.name, allowHidden = allowHidden, ensureNFC = ensureNFC): 

75 print(f"WARNING: \"{entry.path}\" is illegal") 

76 

77 # Check if it might need following ... 

78 if entry.is_dir(follow_symlinks = follow_symlinks): 

79 # Check that the directory is list-able ... 

80 # NOTE: On 20/Aug/2022 this was (incorrectly, in my opinion) 

81 # returning False on regular folders on FreeBSD (but 

82 # not MacOS) when passed "follow_symlinks = False". 

83 if os.access(entry, os.X_OK): 

84 # Recursively run this function again and add to the 

85 # list ... 

86 contents += find_instances_of_a_file( 

87 entry.path, 

88 basename, 

89 allowHidden = allowHidden, 

90 debug = debug, 

91 ensureNFC = ensureNFC, 

92 follow_symlinks = follow_symlinks, 

93 return_symlinks = return_symlinks, 

94 ) 

95 elif debug: 

96 print(f"WARNING: \"{entry.path}\" cannot be listed") 

97 

98 # Check if it might need adding to the list ... 

99 if entry.is_file(follow_symlinks = return_symlinks): 

100 # Check if it should be added to the list ... 

101 if entry.name == basename: 

102 # Add to the list ... 

103 contents.append(entry.path) 

104 elif debug: 

105 print(f"WARNING: \"{path}\" does not exist") 

106 

107 # Return sorted list ... 

108 return sorted(contents)