Coverage for pyguymer3/return_folder_list.py: 64%

1#!/usr/bin/env python3 

2 

3# Define function ... 

4def return_folder_list( 

5 path, 

6 /, 

7 *, 

8 allowHidden = False, 

9 debug = __debug__, 

10 ensureNFC = True, 

11 follow_symlinks = True, 

12 return_symlinks = True, 

13): 

14 """Return a recursive list of folder names in a directory. 

15 

16 This function returns a sorted list of folder names recursively in a 

17 directory. 

18 

19 Parameters 

20 ---------- 

21 path : str 

22 the directory to search 

23 allowHidden : bool, optional 

24 allow hidden files 

25 debug : bool, optional 

26 print debug messages 

27 ensureNFC : bool, optional 

28 ensure that the Unicode encoding is NFC 

29 follow_symlinks : bool, optional 

30 follow symbolic links 

31 return_symlinks : bool, optional 

32 include symbolic links in the returned list 

33 

34 Returns 

35 ------- 

36 ans : list of str 

37 the sorted list of folder names 

38 

39 Notes 

40 ----- 

41 Copyright 2017 Thomas Guymer [1]_ 

42 

43 References 

44 ---------- 

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

46 """ 

47 

48 # Import standard modules ... 

49 import os 

50 

51 # Import sub-functions ... 

52 from .make_path_safe import make_path_safe 

53 

54 # Create empty list ... 

55 contents = [] 

56 

57 # Check it exists ... 

58 if os.path.exists(path): 

59 # Open folder ... 

60 with os.scandir(path) as scanObj: 

61 # Loop over folder contents ... 

62 for entry in scanObj: 

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

64 if debug: 

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

66 # identification ... 

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

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

69 

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

71 # identification ... 

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

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

74 

75 # Check if it might need following ... 

76 if entry.is_dir(follow_symlinks = follow_symlinks): 

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

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

79 # returning False on regular folders on FreeBSD (but 

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

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

82 # Recursively run this function again and add to the 

83 # list ... 

84 contents += return_folder_list( 

85 entry.path, 

86 allowHidden = allowHidden, 

87 debug = debug, 

88 ensureNFC = ensureNFC, 

89 follow_symlinks = follow_symlinks, 

90 return_symlinks = return_symlinks, 

91 ) 

92 elif debug: 

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

94 

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

96 if entry.is_dir(follow_symlinks = return_symlinks): 

97 # Add to the list ... 

98 contents.append(entry.path) 

99 elif debug: 

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

101 

102 # Return sorted list ... 

103 return sorted(contents)