Coverage for src / ezcompiler / utils / uploader_utils.py: 35.42%

1# /////////////////////////////////////////////////////////////// 

2# UPLOADER_UTILS - Uploader-specific utility functions 

3# Project: ezcompiler 

4# /////////////////////////////////////////////////////////////// 

5 

6""" 

7Uploader utilities - Uploader-specific utility functions for EzCompiler. 

8 

9This module provides specialized utility functions for uploader operations, 

10including source path validation, configuration validation, and backup 

11operations. Uses thematic utils (FileUtils, ValidationUtils) internally. 

12 

13Utils layer can only use DEBUG and ERROR log levels. 

14""" 

15 

16from __future__ import annotations 

17 

18# /////////////////////////////////////////////////////////////// 

19# IMPORTS 

20# /////////////////////////////////////////////////////////////// 

21# Standard library imports 

22from pathlib import Path 

23from typing import Any 

24 

25# Local imports 

26from ..shared.exceptions.utils import ( 

27 ServerConfigError, 

28 SourcePathError, 

29 UploaderTypeError, 

30) 

31 

32# /////////////////////////////////////////////////////////////// 

33# CLASSES 

34# /////////////////////////////////////////////////////////////// 

35 

36 

37class UploaderUtils: 

38 """ 

39 Utility class for uploader-specific operations. 

40 

41 Provides static methods for uploader-related tasks such as source path 

42 validation, configuration validation, and backup operations. 

43 Uses thematic utils (FileUtils) internally. 

44 

45 Example: 

46 >>> UploaderUtils.validate_source_path(Path("file.zip")) 

47 >>> UploaderUtils.validate_upload_type("disk") 

48 >>> backup_path = UploaderUtils.generate_backup_path(Path("file.zip")) 

49 """ 

50 

51 # //////////////////////////////////////////////// 

52 # VALIDATION METHODS 

53 # //////////////////////////////////////////////// 

54 

55 @staticmethod 

56 def validate_source_path(source_path: Path) -> None: 

57 """ 

58 Validate that the source path exists and is accessible. 

59 

60 Args: 

61 source_path: Path to validate 

62 

63 Raises: 

64 SourcePathError: If source path is invalid or inaccessible 

65 

66 Note: 

67 Uses FileUtils for file/directory existence checks. 

68 

69 Example: 

70 >>> UploaderUtils.validate_source_path(Path("file.zip")) 

71 """ 

72 if not source_path.exists(): 

73 raise SourcePathError(f"Source path does not exist: {source_path}") 

74 

75 if not source_path.is_file() and not source_path.is_dir(): 

76 raise SourcePathError( 

77 f"Source path is neither file nor directory: {source_path}" 

78 ) 

79 

80 @staticmethod 

81 def validate_upload_type(upload_type: str) -> None: 

82 """ 

83 Validate upload type string. 

84 

85 Args: 

86 upload_type: Upload type to validate 

87 

88 Raises: 

89 UploaderTypeError: If upload type is not supported 

90 

91 Example: 

92 >>> UploaderUtils.validate_upload_type("disk") 

93 >>> UploaderUtils.validate_upload_type("invalid") 

94 UploaderTypeError: Unsupported upload type: invalid 

95 """ 

96 valid_types = ["disk", "server"] 

97 if upload_type.lower() not in valid_types: 

98 raise UploaderTypeError(f"Unsupported upload type: {upload_type}") 

99 

100 @staticmethod 

101 def validate_server_url(server_url: str) -> None: 

102 """ 

103 Validate server URL format. 

104 

105 Args: 

106 server_url: Server URL to validate 

107 

108 Raises: 

109 ServerConfigError: If server URL is invalid 

110 

111 Example: 

112 >>> UploaderUtils.validate_server_url("https://example.com") 

113 >>> UploaderUtils.validate_server_url("invalid") 

114 ServerConfigError: server_url must start with http:// or https:// 

115 """ 

116 if not server_url: 

117 raise ServerConfigError("server_url is required") 

118 

119 if not server_url.startswith(("http://", "https://")): 

120 raise ServerConfigError("server_url must start with http:// or https://") 

121 

122 # //////////////////////////////////////////////// 

123 # BACKUP METHODS 

124 # //////////////////////////////////////////////// 

125 

126 @staticmethod 

127 def generate_backup_path(file_path: Path) -> Path: 

128 """ 

129 Generate a unique backup path for a file. 

130 

131 Args: 

132 file_path: Path to file that needs backup 

133 

134 Returns: 

135 Path: Unique backup path (with .backup suffix and counter if needed) 

136 

137 Example: 

138 >>> backup = UploaderUtils.generate_backup_path(Path("file.zip")) 

139 >>> print(backup) 

140 file.zip.backup 

141 """ 

142 backup_path = file_path.with_suffix(f"{file_path.suffix}.backup") 

143 counter = 1 

144 

145 # Find unique backup name 

146 while backup_path.exists(): 

147 backup_path = file_path.with_suffix(f"{file_path.suffix}.backup.{counter}") 

148 counter += 1 

149 

150 return backup_path 

151 

152 # //////////////////////////////////////////////// 

153 # CONFIGURATION HELPERS 

154 # //////////////////////////////////////////////// 

155 

156 @staticmethod 

157 def get_default_disk_config() -> dict[str, Any]: 

158 """ 

159 Get default configuration for disk uploader. 

160 

161 Returns: 

162 dict[str, Any]: Default disk uploader configuration 

163 

164 Example: 

165 >>> config = UploaderUtils.get_default_disk_config() 

166 >>> print(config) 

167 {'preserve_permissions': True, 'overwrite': True, 'create_backup': False} 

168 """ 

169 return { 

170 "preserve_permissions": True, 

171 "overwrite": True, 

172 "create_backup": False, 

173 } 

174 

175 @staticmethod 

176 def get_default_server_config() -> dict[str, Any]: 

177 """ 

178 Get default configuration for server uploader. 

179 

180 Returns: 

181 dict[str, Any]: Default server uploader configuration 

182 

183 Example: 

184 >>> config = UploaderUtils.get_default_server_config() 

185 >>> print(config) 

186 {'server_url': '', 'username': '', 'password': '', ...} 

187 """ 

188 return { 

189 "server_url": "", 

190 "username": "", 

191 "password": "", 

192 "api_key": "", 

193 "timeout": 30, 

194 "verify_ssl": True, 

195 "chunk_size": 8192, 

196 "retry_attempts": 3, 

197 }