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

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 """ 

17 Abstract base class defining all platform directory properties, their :class:`~pathlib.Path` variants, and 

18 iterators. 

19 

20 Platform-specific subclasses (e.g. :class:`~platformdirs.windows.Windows`, 

21 :class:`~platformdirs.macos.MacOS`, :class:`~platformdirs.unix.Unix`) implement the abstract 

22 properties to return the appropriate paths for each operating system. 

23 

24 """ 

25 

26 def __init__( # noqa: PLR0913, PLR0917 

27 self, 

28 appname: str | None = None, 

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

30 version: str | None = None, 

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

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

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

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

35 use_site_for_root: bool = False, # noqa: FBT001, FBT002 

36 ) -> None: 

37 """ 

38 Create a new platform directory. 

39 

40 :param appname: See `appname`. 

41 :param appauthor: See `appauthor`. 

42 :param version: See `version`. 

43 :param roaming: See `roaming`. 

44 :param multipath: See `multipath`. 

45 :param opinion: See `opinion`. 

46 :param ensure_exists: See `ensure_exists`. 

47 :param use_site_for_root: See `use_site_for_root`. 

48 

49 """ 

50 self.appname = appname #: The name of the application. 

51 self.appauthor = appauthor 

52 """ 

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

54 

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

56 

57 """ 

58 self.version = version 

59 """ 

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

61 

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

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

64 

65 """ 

66 self.roaming = roaming 

67 """ 

68 Whether to use the roaming appdata directory on Windows. 

69 

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

71 login (see 

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

73 

74 """ 

75 self.multipath = multipath 

76 """ 

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

78 

79 By default, the first item would only be returned. Only affects ``site_data_dir`` and ``site_config_dir`` on 

80 Unix and macOS. 

81 

82 """ 

83 self.opinion = opinion 

84 """ 

85 Whether to use opinionated values. 

86 

87 When enabled, appends an additional subdirectory for certain directories: e.g. ``Cache`` for cache and ``Logs`` 

88 for logs on Windows, ``log`` for logs on Unix. 

89 

90 """ 

91 self.ensure_exists = ensure_exists 

92 """ 

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

94 

95 By default, no directories are created. 

96 

97 """ 

98 self.use_site_for_root = use_site_for_root 

99 """ 

100 Whether to redirect ``user_*_dir`` calls to their ``site_*_dir`` equivalents when running as root (uid 0). 

101 

102 Only has an effect on Unix. Disabled by default for backwards compatibility. When enabled, XDG user environment 

103 variables (e.g. ``XDG_DATA_HOME``) are bypassed for the redirected directories. 

104 

105 """ 

106 

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

108 params = list(base[1:]) 

109 if self.appname: 

110 params.append(self.appname) 

111 if self.version: 

112 params.append(self.version) 

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

114 self._optionally_create_directory(path) 

115 return path 

116 

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

118 if self.ensure_exists: 

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

120 

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

122 if self.multipath: 

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

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

125 return Path(directory) 

126 

127 @property 

128 @abstractmethod 

129 def user_data_dir(self) -> str: 

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

131 

132 @property 

133 @abstractmethod 

134 def site_data_dir(self) -> str: 

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

136 

137 @property 

138 @abstractmethod 

139 def user_config_dir(self) -> str: 

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

141 

142 @property 

143 @abstractmethod 

144 def site_config_dir(self) -> str: 

145 """:return: config directory shared by users""" 

146 

147 @property 

148 @abstractmethod 

149 def user_cache_dir(self) -> str: 

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

151 

152 @property 

153 @abstractmethod 

154 def site_cache_dir(self) -> str: 

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

156 

157 @property 

158 @abstractmethod 

159 def user_state_dir(self) -> str: 

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

161 

162 @property 

163 @abstractmethod 

164 def site_state_dir(self) -> str: 

165 """:return: state directory shared by users""" 

166 

167 @property 

168 @abstractmethod 

169 def user_log_dir(self) -> str: 

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

171 

172 @property 

173 @abstractmethod 

174 def site_log_dir(self) -> str: 

175 """:return: log directory shared by users""" 

176 

177 @property 

178 @abstractmethod 

179 def user_documents_dir(self) -> str: 

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

181 

182 @property 

183 @abstractmethod 

184 def user_downloads_dir(self) -> str: 

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

186 

187 @property 

188 @abstractmethod 

189 def user_pictures_dir(self) -> str: 

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

191 

192 @property 

193 @abstractmethod 

194 def user_videos_dir(self) -> str: 

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

196 

197 @property 

198 @abstractmethod 

199 def user_music_dir(self) -> str: 

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

201 

202 @property 

203 @abstractmethod 

204 def user_desktop_dir(self) -> str: 

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

206 

207 @property 

208 @abstractmethod 

209 def user_bin_dir(self) -> str: 

210 """:return: bin directory tied to the user""" 

211 

212 @property 

213 @abstractmethod 

214 def user_applications_dir(self) -> str: 

215 """:return: applications directory tied to the user""" 

216 

217 @property 

218 @abstractmethod 

219 def user_runtime_dir(self) -> str: 

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

221 

222 @property 

223 @abstractmethod 

224 def site_runtime_dir(self) -> str: 

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

226 

227 @property 

228 def user_data_path(self) -> Path: 

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

230 return Path(self.user_data_dir) 

231 

232 @property 

233 def site_data_path(self) -> Path: 

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

235 return Path(self.site_data_dir) 

236 

237 @property 

238 def user_config_path(self) -> Path: 

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

240 return Path(self.user_config_dir) 

241 

242 @property 

243 def site_config_path(self) -> Path: 

244 """:return: config path shared by users""" 

245 return Path(self.site_config_dir) 

246 

247 @property 

248 def user_cache_path(self) -> Path: 

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

250 return Path(self.user_cache_dir) 

251 

252 @property 

253 def site_cache_path(self) -> Path: 

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

255 return Path(self.site_cache_dir) 

256 

257 @property 

258 def user_state_path(self) -> Path: 

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

260 return Path(self.user_state_dir) 

261 

262 @property 

263 def site_state_path(self) -> Path: 

264 """:return: state path shared by users""" 

265 return Path(self.site_state_dir) 

266 

267 @property 

268 def user_log_path(self) -> Path: 

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

270 return Path(self.user_log_dir) 

271 

272 @property 

273 def site_log_path(self) -> Path: 

274 """:return: log path shared by users""" 

275 return Path(self.site_log_dir) 

276 

277 @property 

278 def user_documents_path(self) -> Path: 

279 """:return: documents path tied to the user""" 

280 return Path(self.user_documents_dir) 

281 

282 @property 

283 def user_downloads_path(self) -> Path: 

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

285 return Path(self.user_downloads_dir) 

286 

287 @property 

288 def user_pictures_path(self) -> Path: 

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

290 return Path(self.user_pictures_dir) 

291 

292 @property 

293 def user_videos_path(self) -> Path: 

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

295 return Path(self.user_videos_dir) 

296 

297 @property 

298 def user_music_path(self) -> Path: 

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

300 return Path(self.user_music_dir) 

301 

302 @property 

303 def user_desktop_path(self) -> Path: 

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

305 return Path(self.user_desktop_dir) 

306 

307 @property 

308 def user_bin_path(self) -> Path: 

309 """:return: bin path tied to the user""" 

310 return Path(self.user_bin_dir) 

311 

312 @property 

313 def user_applications_path(self) -> Path: 

314 """:return: applications path tied to the user""" 

315 return Path(self.user_applications_dir) 

316 

317 @property 

318 def user_runtime_path(self) -> Path: 

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

320 return Path(self.user_runtime_dir) 

321 

322 @property 

323 def site_runtime_path(self) -> Path: 

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

325 return Path(self.site_runtime_dir) 

326 

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

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

329 yield self.user_config_dir 

330 yield self.site_config_dir 

331 

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

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

334 yield self.user_data_dir 

335 yield self.site_data_dir 

336 

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

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

339 yield self.user_cache_dir 

340 yield self.site_cache_dir 

341 

342 def iter_state_dirs(self) -> Iterator[str]: 

343 """:yield: all user and site state directories.""" 

344 yield self.user_state_dir 

345 yield self.site_state_dir 

346 

347 def iter_log_dirs(self) -> Iterator[str]: 

348 """:yield: all user and site log directories.""" 

349 yield self.user_log_dir 

350 yield self.site_log_dir 

351 

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

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

354 yield self.user_runtime_dir 

355 yield self.site_runtime_dir 

356 

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

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

359 for path in self.iter_config_dirs(): 

360 yield Path(path) 

361 

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

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

364 for path in self.iter_data_dirs(): 

365 yield Path(path) 

366 

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

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

369 for path in self.iter_cache_dirs(): 

370 yield Path(path) 

371 

372 def iter_state_paths(self) -> Iterator[Path]: 

373 """:yield: all user and site state paths.""" 

374 for path in self.iter_state_dirs(): 

375 yield Path(path) 

376 

377 def iter_log_paths(self) -> Iterator[Path]: 

378 """:yield: all user and site log paths.""" 

379 for path in self.iter_log_dirs(): 

380 yield Path(path) 

381 

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

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

384 for path in self.iter_runtime_dirs(): 

385 yield Path(path)