Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/platformdirs/api.py: 13%

1"""Base API.""" 

2 

3from __future__ import annotations 

4 

5import os 

6from abc import ABC, abstractmethod 

7from pathlib import Path 

8from typing import TYPE_CHECKING 

9 

10if TYPE_CHECKING: 

11 from collections.abc import Iterator 

12 from typing import Literal 

13 

14 

15class PlatformDirsABC(ABC): # noqa: PLR0904 

16 """Abstract base class for platform directories.""" 

17 

18 def __init__( # noqa: PLR0913, PLR0917 

19 self, 

20 appname: str | None = None, 

21 appauthor: str | Literal[False] | None = None, 

22 version: str | None = None, 

23 roaming: bool = False, # noqa: FBT001, FBT002 

24 multipath: bool = False, # noqa: FBT001, FBT002 

25 opinion: bool = True, # noqa: FBT001, FBT002 

26 ensure_exists: bool = False, # noqa: FBT001, FBT002 

27 ) -> None: 

28 """ 

29 Create a new platform directory. 

30 

31 :param appname: See `appname`. 

32 :param appauthor: See `appauthor`. 

33 :param version: See `version`. 

34 :param roaming: See `roaming`. 

35 :param multipath: See `multipath`. 

36 :param opinion: See `opinion`. 

37 :param ensure_exists: See `ensure_exists`. 

38 

39 """ 

40 self.appname = appname #: The name of application. 

41 self.appauthor = appauthor 

42 """ 

43 The name of the app author or distributing body for this application. 

44 

45 Typically, it is the owning company name. Defaults to `appname`. You may pass ``False`` to disable it. 

46 

47 """ 

48 self.version = version 

49 """ 

50 An optional version path element to append to the path. 

51 

52 You might want to use this if you want multiple versions of your app to be able to run independently. If used, 

53 this would typically be ``<major>.<minor>``. 

54 

55 """ 

56 self.roaming = roaming 

57 """ 

58 Whether to use the roaming appdata directory on Windows. 

59 

60 That means that for users on a Windows network setup for roaming profiles, this user data will be synced on 

61 login (see 

62 `here <https://technet.microsoft.com/en-us/library/cc766489(WS.10).aspx>`_). 

63 

64 """ 

65 self.multipath = multipath 

66 """ 

67 An optional parameter which indicates that the entire list of data dirs should be returned. 

68 

69 By default, the first item would only be returned. 

70 

71 """ 

72 self.opinion = opinion #: A flag to indicating to use opinionated values. 

73 self.ensure_exists = ensure_exists 

74 """ 

75 Optionally create the directory (and any missing parents) upon access if it does not exist. 

76 

77 By default, no directories are created. 

78 

79 """ 

80 

81 def _append_app_name_and_version(self, *base: str) -> str: 

82 params = list(base[1:]) 

83 if self.appname: 

84 params.append(self.appname) 

85 if self.version: 

86 params.append(self.version) 

87 path = os.path.join(base[0], *params) # noqa: PTH118 

88 self._optionally_create_directory(path) 

89 return path 

90 

91 def _optionally_create_directory(self, path: str) -> None: 

92 if self.ensure_exists: 

93 Path(path).mkdir(parents=True, exist_ok=True) 

94 

95 def _first_item_as_path_if_multipath(self, directory: str) -> Path: 

96 if self.multipath: 

97 # If multipath is True, the first path is returned. 

98 directory = directory.partition(os.pathsep)[0] 

99 return Path(directory) 

100 

101 @property 

102 @abstractmethod 

103 def user_data_dir(self) -> str: 

104 """:return: data directory tied to the user""" 

105 

106 @property 

107 @abstractmethod 

108 def site_data_dir(self) -> str: 

109 """:return: data directory shared by users""" 

110 

111 @property 

112 @abstractmethod 

113 def user_config_dir(self) -> str: 

114 """:return: config directory tied to the user""" 

115 

116 @property 

117 @abstractmethod 

118 def site_config_dir(self) -> str: 

119 """:return: config directory shared by the users""" 

120 

121 @property 

122 @abstractmethod 

123 def user_cache_dir(self) -> str: 

124 """:return: cache directory tied to the user""" 

125 

126 @property 

127 @abstractmethod 

128 def site_cache_dir(self) -> str: 

129 """:return: cache directory shared by users""" 

130 

131 @property 

132 @abstractmethod 

133 def user_state_dir(self) -> str: 

134 """:return: state directory tied to the user""" 

135 

136 @property 

137 @abstractmethod 

138 def user_log_dir(self) -> str: 

139 """:return: log directory tied to the user""" 

140 

141 @property 

142 @abstractmethod 

143 def user_documents_dir(self) -> str: 

144 """:return: documents directory tied to the user""" 

145 

146 @property 

147 @abstractmethod 

148 def user_downloads_dir(self) -> str: 

149 """:return: downloads directory tied to the user""" 

150 

151 @property 

152 @abstractmethod 

153 def user_pictures_dir(self) -> str: 

154 """:return: pictures directory tied to the user""" 

155 

156 @property 

157 @abstractmethod 

158 def user_videos_dir(self) -> str: 

159 """:return: videos directory tied to the user""" 

160 

161 @property 

162 @abstractmethod 

163 def user_music_dir(self) -> str: 

164 """:return: music directory tied to the user""" 

165 

166 @property 

167 @abstractmethod 

168 def user_desktop_dir(self) -> str: 

169 """:return: desktop directory tied to the user""" 

170 

171 @property 

172 @abstractmethod 

173 def user_runtime_dir(self) -> str: 

174 """:return: runtime directory tied to the user""" 

175 

176 @property 

177 @abstractmethod 

178 def site_runtime_dir(self) -> str: 

179 """:return: runtime directory shared by users""" 

180 

181 @property 

182 def user_data_path(self) -> Path: 

183 """:return: data path tied to the user""" 

184 return Path(self.user_data_dir) 

185 

186 @property 

187 def site_data_path(self) -> Path: 

188 """:return: data path shared by users""" 

189 return Path(self.site_data_dir) 

190 

191 @property 

192 def user_config_path(self) -> Path: 

193 """:return: config path tied to the user""" 

194 return Path(self.user_config_dir) 

195 

196 @property 

197 def site_config_path(self) -> Path: 

198 """:return: config path shared by the users""" 

199 return Path(self.site_config_dir) 

200 

201 @property 

202 def user_cache_path(self) -> Path: 

203 """:return: cache path tied to the user""" 

204 return Path(self.user_cache_dir) 

205 

206 @property 

207 def site_cache_path(self) -> Path: 

208 """:return: cache path shared by users""" 

209 return Path(self.site_cache_dir) 

210 

211 @property 

212 def user_state_path(self) -> Path: 

213 """:return: state path tied to the user""" 

214 return Path(self.user_state_dir) 

215 

216 @property 

217 def user_log_path(self) -> Path: 

218 """:return: log path tied to the user""" 

219 return Path(self.user_log_dir) 

220 

221 @property 

222 def user_documents_path(self) -> Path: 

223 """:return: documents a path tied to the user""" 

224 return Path(self.user_documents_dir) 

225 

226 @property 

227 def user_downloads_path(self) -> Path: 

228 """:return: downloads path tied to the user""" 

229 return Path(self.user_downloads_dir) 

230 

231 @property 

232 def user_pictures_path(self) -> Path: 

233 """:return: pictures path tied to the user""" 

234 return Path(self.user_pictures_dir) 

235 

236 @property 

237 def user_videos_path(self) -> Path: 

238 """:return: videos path tied to the user""" 

239 return Path(self.user_videos_dir) 

240 

241 @property 

242 def user_music_path(self) -> Path: 

243 """:return: music path tied to the user""" 

244 return Path(self.user_music_dir) 

245 

246 @property 

247 def user_desktop_path(self) -> Path: 

248 """:return: desktop path tied to the user""" 

249 return Path(self.user_desktop_dir) 

250 

251 @property 

252 def user_runtime_path(self) -> Path: 

253 """:return: runtime path tied to the user""" 

254 return Path(self.user_runtime_dir) 

255 

256 @property 

257 def site_runtime_path(self) -> Path: 

258 """:return: runtime path shared by users""" 

259 return Path(self.site_runtime_dir) 

260 

261 def iter_config_dirs(self) -> Iterator[str]: 

262 """:yield: all user and site configuration directories.""" 

263 yield self.user_config_dir 

264 yield self.site_config_dir 

265 

266 def iter_data_dirs(self) -> Iterator[str]: 

267 """:yield: all user and site data directories.""" 

268 yield self.user_data_dir 

269 yield self.site_data_dir 

270 

271 def iter_cache_dirs(self) -> Iterator[str]: 

272 """:yield: all user and site cache directories.""" 

273 yield self.user_cache_dir 

274 yield self.site_cache_dir 

275 

276 def iter_runtime_dirs(self) -> Iterator[str]: 

277 """:yield: all user and site runtime directories.""" 

278 yield self.user_runtime_dir 

279 yield self.site_runtime_dir 

280 

281 def iter_config_paths(self) -> Iterator[Path]: 

282 """:yield: all user and site configuration paths.""" 

283 for path in self.iter_config_dirs(): 

284 yield Path(path) 

285 

286 def iter_data_paths(self) -> Iterator[Path]: 

287 """:yield: all user and site data paths.""" 

288 for path in self.iter_data_dirs(): 

289 yield Path(path) 

290 

291 def iter_cache_paths(self) -> Iterator[Path]: 

292 """:yield: all user and site cache paths.""" 

293 for path in self.iter_cache_dirs(): 

294 yield Path(path) 

295 

296 def iter_runtime_paths(self) -> Iterator[Path]: 

297 """:yield: all user and site runtime paths.""" 

298 for path in self.iter_runtime_dirs(): 

299 yield Path(path)