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

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 defining all platform directory properties, their :class:`~pathlib.Path` variants, and iterators. 

17 

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

19 :class:`~platformdirs.unix.Unix`) implement the abstract properties to return the appropriate paths for each 

20 operating system. 

21 

22 """ 

23 

24 def __init__( # noqa: PLR0913, PLR0917 

25 self, 

26 appname: str | None = None, 

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

28 version: str | None = None, 

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

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

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

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

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

34 ) -> None: 

35 """Create a new platform directory. 

36 

37 :param appname: See `appname`. 

38 :param appauthor: See `appauthor`. 

39 :param version: See `version`. 

40 :param roaming: See `roaming`. 

41 :param multipath: See `multipath`. 

42 :param opinion: See `opinion`. 

43 :param ensure_exists: See `ensure_exists`. 

44 :param use_site_for_root: See `use_site_for_root`. 

45 

46 """ 

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

48 self.appauthor = appauthor 

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

50 

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

52 

53 .. note:: 

54 

55 On Windows, the directory structure is ``<base>/<appauthor>/<appname>``. When ``appauthor`` is ``None`` (the 

56 default), it falls back to ``appname``, resulting in ``<base>/<appname>/<appname>`` (e.g. 

57 ``AppData/Local/myapp/myapp``). Pass ``appauthor=False`` to omit the author directory entirely and get 

58 ``<base>/<appname>``. 

59 

60 """ 

61 self.version = version 

62 """An optional version path element to append to the path. 

63 

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

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

66 

67 """ 

68 self.roaming = roaming 

69 """Whether to use the roaming appdata directory on Windows. 

70 

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

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

73 

74 """ 

75 self.multipath = multipath 

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

77 

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

79 Unix and macOS. 

80 

81 """ 

82 self.opinion = opinion 

83 """Whether to use opinionated values. 

84 

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

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

87 

88 """ 

89 self.ensure_exists = ensure_exists 

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

91 

92 By default, no directories are created. 

93 

94 """ 

95 self.use_site_for_root = use_site_for_root 

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

97 

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

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

100 

101 """ 

102 

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

104 params = list(base[1:]) 

105 if self.appname: 

106 params.append(self.appname) 

107 if self.version: 

108 params.append(self.version) 

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

110 self._optionally_create_directory(path) 

111 return path 

112 

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

114 if self.ensure_exists: 

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

116 

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

118 if self.multipath: 

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

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

121 return Path(directory) 

122 

123 @property 

124 @abstractmethod 

125 def user_data_dir(self) -> str: 

126 """:returns: data directory tied to the user""" 

127 

128 @property 

129 @abstractmethod 

130 def site_data_dir(self) -> str: 

131 """:returns: data directory shared by users""" 

132 

133 @property 

134 def _site_data_dirs(self) -> list[str]: 

135 raise NotImplementedError 

136 

137 @property 

138 @abstractmethod 

139 def user_config_dir(self) -> str: 

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

141 

142 @property 

143 @abstractmethod 

144 def site_config_dir(self) -> str: 

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

146 

147 @property 

148 def _site_config_dirs(self) -> list[str]: 

149 raise NotImplementedError 

150 

151 @property 

152 @abstractmethod 

153 def user_cache_dir(self) -> str: 

154 """:returns: cache directory tied to the user""" 

155 

156 @property 

157 @abstractmethod 

158 def site_cache_dir(self) -> str: 

159 """:returns: cache directory shared by users""" 

160 

161 @property 

162 @abstractmethod 

163 def user_state_dir(self) -> str: 

164 """:returns: state directory tied to the user""" 

165 

166 @property 

167 @abstractmethod 

168 def site_state_dir(self) -> str: 

169 """:returns: state directory shared by users""" 

170 

171 @property 

172 @abstractmethod 

173 def user_log_dir(self) -> str: 

174 """:returns: log directory tied to the user""" 

175 

176 @property 

177 @abstractmethod 

178 def site_log_dir(self) -> str: 

179 """:returns: log directory shared by users""" 

180 

181 @property 

182 @abstractmethod 

183 def user_documents_dir(self) -> str: 

184 """:returns: documents directory tied to the user""" 

185 

186 @property 

187 @abstractmethod 

188 def user_downloads_dir(self) -> str: 

189 """:returns: downloads directory tied to the user""" 

190 

191 @property 

192 @abstractmethod 

193 def user_pictures_dir(self) -> str: 

194 """:returns: pictures directory tied to the user""" 

195 

196 @property 

197 @abstractmethod 

198 def user_videos_dir(self) -> str: 

199 """:returns: videos directory tied to the user""" 

200 

201 @property 

202 @abstractmethod 

203 def user_music_dir(self) -> str: 

204 """:returns: music directory tied to the user""" 

205 

206 @property 

207 @abstractmethod 

208 def user_desktop_dir(self) -> str: 

209 """:returns: desktop directory tied to the user""" 

210 

211 @property 

212 @abstractmethod 

213 def user_bin_dir(self) -> str: 

214 """:returns: bin directory tied to the user""" 

215 

216 @property 

217 @abstractmethod 

218 def site_bin_dir(self) -> str: 

219 """:returns: bin directory shared by users""" 

220 

221 @property 

222 @abstractmethod 

223 def user_applications_dir(self) -> str: 

224 """:returns: applications directory tied to the user""" 

225 

226 @property 

227 @abstractmethod 

228 def site_applications_dir(self) -> str: 

229 """:returns: applications directory shared by users""" 

230 

231 @property 

232 def _site_applications_dirs(self) -> list[str]: 

233 raise NotImplementedError 

234 

235 @property 

236 @abstractmethod 

237 def user_runtime_dir(self) -> str: 

238 """:returns: runtime directory tied to the user""" 

239 

240 @property 

241 @abstractmethod 

242 def site_runtime_dir(self) -> str: 

243 """:returns: runtime directory shared by users""" 

244 

245 @property 

246 def user_data_path(self) -> Path: 

247 """:returns: data path tied to the user""" 

248 return Path(self.user_data_dir) 

249 

250 @property 

251 def site_data_path(self) -> Path: 

252 """:returns: data path shared by users""" 

253 return Path(self.site_data_dir) 

254 

255 @property 

256 def user_config_path(self) -> Path: 

257 """:returns: config path tied to the user""" 

258 return Path(self.user_config_dir) 

259 

260 @property 

261 def site_config_path(self) -> Path: 

262 """:returns: config path shared by users""" 

263 return Path(self.site_config_dir) 

264 

265 @property 

266 def user_cache_path(self) -> Path: 

267 """:returns: cache path tied to the user""" 

268 return Path(self.user_cache_dir) 

269 

270 @property 

271 def site_cache_path(self) -> Path: 

272 """:returns: cache path shared by users""" 

273 return Path(self.site_cache_dir) 

274 

275 @property 

276 def user_state_path(self) -> Path: 

277 """:returns: state path tied to the user""" 

278 return Path(self.user_state_dir) 

279 

280 @property 

281 def site_state_path(self) -> Path: 

282 """:returns: state path shared by users""" 

283 return Path(self.site_state_dir) 

284 

285 @property 

286 def user_log_path(self) -> Path: 

287 """:returns: log path tied to the user""" 

288 return Path(self.user_log_dir) 

289 

290 @property 

291 def site_log_path(self) -> Path: 

292 """:returns: log path shared by users""" 

293 return Path(self.site_log_dir) 

294 

295 @property 

296 def user_documents_path(self) -> Path: 

297 """:returns: documents path tied to the user""" 

298 return Path(self.user_documents_dir) 

299 

300 @property 

301 def user_downloads_path(self) -> Path: 

302 """:returns: downloads path tied to the user""" 

303 return Path(self.user_downloads_dir) 

304 

305 @property 

306 def user_pictures_path(self) -> Path: 

307 """:returns: pictures path tied to the user""" 

308 return Path(self.user_pictures_dir) 

309 

310 @property 

311 def user_videos_path(self) -> Path: 

312 """:returns: videos path tied to the user""" 

313 return Path(self.user_videos_dir) 

314 

315 @property 

316 def user_music_path(self) -> Path: 

317 """:returns: music path tied to the user""" 

318 return Path(self.user_music_dir) 

319 

320 @property 

321 def user_desktop_path(self) -> Path: 

322 """:returns: desktop path tied to the user""" 

323 return Path(self.user_desktop_dir) 

324 

325 @property 

326 def user_bin_path(self) -> Path: 

327 """:returns: bin path tied to the user""" 

328 return Path(self.user_bin_dir) 

329 

330 @property 

331 def site_bin_path(self) -> Path: 

332 """:returns: bin path shared by users""" 

333 return Path(self.site_bin_dir) 

334 

335 @property 

336 def user_applications_path(self) -> Path: 

337 """:returns: applications path tied to the user""" 

338 return Path(self.user_applications_dir) 

339 

340 @property 

341 def site_applications_path(self) -> Path: 

342 """:returns: applications path shared by users""" 

343 return Path(self.site_applications_dir) 

344 

345 @property 

346 def user_runtime_path(self) -> Path: 

347 """:returns: runtime path tied to the user""" 

348 return Path(self.user_runtime_dir) 

349 

350 @property 

351 def site_runtime_path(self) -> Path: 

352 """:returns: runtime path shared by users""" 

353 return Path(self.site_runtime_dir) 

354 

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

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

357 yield self.user_config_dir 

358 yield self.site_config_dir 

359 

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

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

362 yield self.user_data_dir 

363 yield self.site_data_dir 

364 

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

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

367 yield self.user_cache_dir 

368 yield self.site_cache_dir 

369 

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

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

372 yield self.user_state_dir 

373 yield self.site_state_dir 

374 

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

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

377 yield self.user_log_dir 

378 yield self.site_log_dir 

379 

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

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

382 yield self.user_runtime_dir 

383 yield self.site_runtime_dir 

384 

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

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

387 for path in self.iter_config_dirs(): 

388 yield Path(path) 

389 

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

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

392 for path in self.iter_data_dirs(): 

393 yield Path(path) 

394 

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

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

397 for path in self.iter_cache_dirs(): 

398 yield Path(path) 

399 

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

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

402 for path in self.iter_state_dirs(): 

403 yield Path(path) 

404 

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

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

407 for path in self.iter_log_dirs(): 

408 yield Path(path) 

409 

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

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

412 for path in self.iter_runtime_dirs(): 

413 yield Path(path)