Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/pip/_vendor/platformdirs/__init__.py: 58%

1""" 

2Utilities for determining application-specific dirs. See <https://github.com/platformdirs/platformdirs> for details and 

3usage. 

4""" 

5from __future__ import annotations 

6 

7import os 

8import sys 

9from pathlib import Path 

10 

11if sys.version_info >= (3, 8): # pragma: no cover (py38+) 

12 from typing import Literal 

13else: # pragma: no cover (py38+) 

14 from pip._vendor.typing_extensions import Literal 

15 

16from .api import PlatformDirsABC 

17from .version import __version__ 

18from .version import __version_tuple__ as __version_info__ 

19 

20 

21def _set_platform_dir_class() -> type[PlatformDirsABC]: 

22 if sys.platform == "win32": 

23 from pip._vendor.platformdirs.windows import Windows as Result 

24 elif sys.platform == "darwin": 

25 from pip._vendor.platformdirs.macos import MacOS as Result 

26 else: 

27 from pip._vendor.platformdirs.unix import Unix as Result 

28 

29 if os.getenv("ANDROID_DATA") == "/data" and os.getenv("ANDROID_ROOT") == "/system": 

30 if os.getenv("SHELL") or os.getenv("PREFIX"): 

31 return Result 

32 

33 from pip._vendor.platformdirs.android import _android_folder 

34 

35 if _android_folder() is not None: 

36 from pip._vendor.platformdirs.android import Android 

37 

38 return Android # return to avoid redefinition of result 

39 

40 return Result 

41 

42 

43PlatformDirs = _set_platform_dir_class() #: Currently active platform 

44AppDirs = PlatformDirs #: Backwards compatibility with appdirs 

45 

46 

47def user_data_dir( 

48 appname: str | None = None, 

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

50 version: str | None = None, 

51 roaming: bool = False, 

52 ensure_exists: bool = False, 

53) -> str: 

54 """ 

55 :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 

56 :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`. 

57 :param version: See `version <platformdirs.api.PlatformDirsABC.version>`. 

58 :param roaming: See `roaming <platformdirs.api.PlatformDirsABC.roaming>`. 

59 :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`. 

60 :returns: data directory tied to the user 

61 """ 

62 return PlatformDirs( 

63 appname=appname, 

64 appauthor=appauthor, 

65 version=version, 

66 roaming=roaming, 

67 ensure_exists=ensure_exists, 

68 ).user_data_dir 

69 

70 

71def site_data_dir( 

72 appname: str | None = None, 

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

74 version: str | None = None, 

75 multipath: bool = False, 

76 ensure_exists: bool = False, 

77) -> str: 

78 """ 

79 :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 

80 :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`. 

81 :param version: See `version <platformdirs.api.PlatformDirsABC.version>`. 

82 :param multipath: See `roaming <platformdirs.api.PlatformDirsABC.multipath>`. 

83 :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`. 

84 :returns: data directory shared by users 

85 """ 

86 return PlatformDirs( 

87 appname=appname, 

88 appauthor=appauthor, 

89 version=version, 

90 multipath=multipath, 

91 ensure_exists=ensure_exists, 

92 ).site_data_dir 

93 

94 

95def user_config_dir( 

96 appname: str | None = None, 

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

98 version: str | None = None, 

99 roaming: bool = False, 

100 ensure_exists: bool = False, 

101) -> str: 

102 """ 

103 :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 

104 :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`. 

105 :param version: See `version <platformdirs.api.PlatformDirsABC.version>`. 

106 :param roaming: See `roaming <platformdirs.api.PlatformDirsABC.roaming>`. 

107 :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`. 

108 :returns: config directory tied to the user 

109 """ 

110 return PlatformDirs( 

111 appname=appname, 

112 appauthor=appauthor, 

113 version=version, 

114 roaming=roaming, 

115 ensure_exists=ensure_exists, 

116 ).user_config_dir 

117 

118 

119def site_config_dir( 

120 appname: str | None = None, 

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

122 version: str | None = None, 

123 multipath: bool = False, 

124 ensure_exists: bool = False, 

125) -> str: 

126 """ 

127 :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 

128 :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`. 

129 :param version: See `version <platformdirs.api.PlatformDirsABC.version>`. 

130 :param multipath: See `roaming <platformdirs.api.PlatformDirsABC.multipath>`. 

131 :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`. 

132 :returns: config directory shared by the users 

133 """ 

134 return PlatformDirs( 

135 appname=appname, 

136 appauthor=appauthor, 

137 version=version, 

138 multipath=multipath, 

139 ensure_exists=ensure_exists, 

140 ).site_config_dir 

141 

142 

143def user_cache_dir( 

144 appname: str | None = None, 

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

146 version: str | None = None, 

147 opinion: bool = True, 

148 ensure_exists: bool = False, 

149) -> str: 

150 """ 

151 :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 

152 :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`. 

153 :param version: See `version <platformdirs.api.PlatformDirsABC.version>`. 

154 :param opinion: See `roaming <platformdirs.api.PlatformDirsABC.opinion>`. 

155 :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`. 

156 :returns: cache directory tied to the user 

157 """ 

158 return PlatformDirs( 

159 appname=appname, 

160 appauthor=appauthor, 

161 version=version, 

162 opinion=opinion, 

163 ensure_exists=ensure_exists, 

164 ).user_cache_dir 

165 

166 

167def site_cache_dir( 

168 appname: str | None = None, 

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

170 version: str | None = None, 

171 opinion: bool = True, 

172 ensure_exists: bool = False, 

173) -> str: 

174 """ 

175 :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 

176 :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`. 

177 :param version: See `version <platformdirs.api.PlatformDirsABC.version>`. 

178 :param opinion: See `opinion <platformdirs.api.PlatformDirsABC.opinion>`. 

179 :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`. 

180 :returns: cache directory tied to the user 

181 """ 

182 return PlatformDirs( 

183 appname=appname, 

184 appauthor=appauthor, 

185 version=version, 

186 opinion=opinion, 

187 ensure_exists=ensure_exists, 

188 ).site_cache_dir 

189 

190 

191def user_state_dir( 

192 appname: str | None = None, 

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

194 version: str | None = None, 

195 roaming: bool = False, 

196 ensure_exists: bool = False, 

197) -> str: 

198 """ 

199 :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 

200 :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`. 

201 :param version: See `version <platformdirs.api.PlatformDirsABC.version>`. 

202 :param roaming: See `roaming <platformdirs.api.PlatformDirsABC.roaming>`. 

203 :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`. 

204 :returns: state directory tied to the user 

205 """ 

206 return PlatformDirs( 

207 appname=appname, 

208 appauthor=appauthor, 

209 version=version, 

210 roaming=roaming, 

211 ensure_exists=ensure_exists, 

212 ).user_state_dir 

213 

214 

215def user_log_dir( 

216 appname: str | None = None, 

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

218 version: str | None = None, 

219 opinion: bool = True, 

220 ensure_exists: bool = False, 

221) -> str: 

222 """ 

223 :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 

224 :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`. 

225 :param version: See `version <platformdirs.api.PlatformDirsABC.version>`. 

226 :param opinion: See `roaming <platformdirs.api.PlatformDirsABC.opinion>`. 

227 :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`. 

228 :returns: log directory tied to the user 

229 """ 

230 return PlatformDirs( 

231 appname=appname, 

232 appauthor=appauthor, 

233 version=version, 

234 opinion=opinion, 

235 ensure_exists=ensure_exists, 

236 ).user_log_dir 

237 

238 

239def user_documents_dir() -> str: 

240 """ 

241 :returns: documents directory tied to the user 

242 """ 

243 return PlatformDirs().user_documents_dir 

244 

245 

246def user_runtime_dir( 

247 appname: str | None = None, 

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

249 version: str | None = None, 

250 opinion: bool = True, 

251 ensure_exists: bool = False, 

252) -> str: 

253 """ 

254 :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 

255 :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`. 

256 :param version: See `version <platformdirs.api.PlatformDirsABC.version>`. 

257 :param opinion: See `opinion <platformdirs.api.PlatformDirsABC.opinion>`. 

258 :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`. 

259 :returns: runtime directory tied to the user 

260 """ 

261 return PlatformDirs( 

262 appname=appname, 

263 appauthor=appauthor, 

264 version=version, 

265 opinion=opinion, 

266 ensure_exists=ensure_exists, 

267 ).user_runtime_dir 

268 

269 

270def user_data_path( 

271 appname: str | None = None, 

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

273 version: str | None = None, 

274 roaming: bool = False, 

275 ensure_exists: bool = False, 

276) -> Path: 

277 """ 

278 :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 

279 :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`. 

280 :param version: See `version <platformdirs.api.PlatformDirsABC.version>`. 

281 :param roaming: See `roaming <platformdirs.api.PlatformDirsABC.roaming>`. 

282 :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`. 

283 :returns: data path tied to the user 

284 """ 

285 return PlatformDirs( 

286 appname=appname, 

287 appauthor=appauthor, 

288 version=version, 

289 roaming=roaming, 

290 ensure_exists=ensure_exists, 

291 ).user_data_path 

292 

293 

294def site_data_path( 

295 appname: str | None = None, 

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

297 version: str | None = None, 

298 multipath: bool = False, 

299 ensure_exists: bool = False, 

300) -> Path: 

301 """ 

302 :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 

303 :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`. 

304 :param version: See `version <platformdirs.api.PlatformDirsABC.version>`. 

305 :param multipath: See `multipath <platformdirs.api.PlatformDirsABC.multipath>`. 

306 :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`. 

307 :returns: data path shared by users 

308 """ 

309 return PlatformDirs( 

310 appname=appname, 

311 appauthor=appauthor, 

312 version=version, 

313 multipath=multipath, 

314 ensure_exists=ensure_exists, 

315 ).site_data_path 

316 

317 

318def user_config_path( 

319 appname: str | None = None, 

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

321 version: str | None = None, 

322 roaming: bool = False, 

323 ensure_exists: bool = False, 

324) -> Path: 

325 """ 

326 :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 

327 :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`. 

328 :param version: See `version <platformdirs.api.PlatformDirsABC.version>`. 

329 :param roaming: See `roaming <platformdirs.api.PlatformDirsABC.roaming>`. 

330 :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`. 

331 :returns: config path tied to the user 

332 """ 

333 return PlatformDirs( 

334 appname=appname, 

335 appauthor=appauthor, 

336 version=version, 

337 roaming=roaming, 

338 ensure_exists=ensure_exists, 

339 ).user_config_path 

340 

341 

342def site_config_path( 

343 appname: str | None = None, 

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

345 version: str | None = None, 

346 multipath: bool = False, 

347 ensure_exists: bool = False, 

348) -> Path: 

349 """ 

350 :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 

351 :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`. 

352 :param version: See `version <platformdirs.api.PlatformDirsABC.version>`. 

353 :param multipath: See `roaming <platformdirs.api.PlatformDirsABC.multipath>`. 

354 :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`. 

355 :returns: config path shared by the users 

356 """ 

357 return PlatformDirs( 

358 appname=appname, 

359 appauthor=appauthor, 

360 version=version, 

361 multipath=multipath, 

362 ensure_exists=ensure_exists, 

363 ).site_config_path 

364 

365 

366def site_cache_path( 

367 appname: str | None = None, 

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

369 version: str | None = None, 

370 opinion: bool = True, 

371 ensure_exists: bool = False, 

372) -> Path: 

373 """ 

374 :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 

375 :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`. 

376 :param version: See `version <platformdirs.api.PlatformDirsABC.version>`. 

377 :param opinion: See `opinion <platformdirs.api.PlatformDirsABC.opinion>`. 

378 :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`. 

379 :returns: cache directory tied to the user 

380 """ 

381 return PlatformDirs( 

382 appname=appname, 

383 appauthor=appauthor, 

384 version=version, 

385 opinion=opinion, 

386 ensure_exists=ensure_exists, 

387 ).site_cache_path 

388 

389 

390def user_cache_path( 

391 appname: str | None = None, 

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

393 version: str | None = None, 

394 opinion: bool = True, 

395 ensure_exists: bool = False, 

396) -> Path: 

397 """ 

398 :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 

399 :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`. 

400 :param version: See `version <platformdirs.api.PlatformDirsABC.version>`. 

401 :param opinion: See `roaming <platformdirs.api.PlatformDirsABC.opinion>`. 

402 :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`. 

403 :returns: cache path tied to the user 

404 """ 

405 return PlatformDirs( 

406 appname=appname, 

407 appauthor=appauthor, 

408 version=version, 

409 opinion=opinion, 

410 ensure_exists=ensure_exists, 

411 ).user_cache_path 

412 

413 

414def user_state_path( 

415 appname: str | None = None, 

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

417 version: str | None = None, 

418 roaming: bool = False, 

419 ensure_exists: bool = False, 

420) -> Path: 

421 """ 

422 :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 

423 :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`. 

424 :param version: See `version <platformdirs.api.PlatformDirsABC.version>`. 

425 :param roaming: See `roaming <platformdirs.api.PlatformDirsABC.roaming>`. 

426 :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`. 

427 :returns: state path tied to the user 

428 """ 

429 return PlatformDirs( 

430 appname=appname, 

431 appauthor=appauthor, 

432 version=version, 

433 roaming=roaming, 

434 ensure_exists=ensure_exists, 

435 ).user_state_path 

436 

437 

438def user_log_path( 

439 appname: str | None = None, 

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

441 version: str | None = None, 

442 opinion: bool = True, 

443 ensure_exists: bool = False, 

444) -> Path: 

445 """ 

446 :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 

447 :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`. 

448 :param version: See `version <platformdirs.api.PlatformDirsABC.version>`. 

449 :param opinion: See `roaming <platformdirs.api.PlatformDirsABC.opinion>`. 

450 :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`. 

451 :returns: log path tied to the user 

452 """ 

453 return PlatformDirs( 

454 appname=appname, 

455 appauthor=appauthor, 

456 version=version, 

457 opinion=opinion, 

458 ensure_exists=ensure_exists, 

459 ).user_log_path 

460 

461 

462def user_documents_path() -> Path: 

463 """ 

464 :returns: documents path tied to the user 

465 """ 

466 return PlatformDirs().user_documents_path 

467 

468 

469def user_runtime_path( 

470 appname: str | None = None, 

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

472 version: str | None = None, 

473 opinion: bool = True, 

474 ensure_exists: bool = False, 

475) -> Path: 

476 """ 

477 :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 

478 :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`. 

479 :param version: See `version <platformdirs.api.PlatformDirsABC.version>`. 

480 :param opinion: See `opinion <platformdirs.api.PlatformDirsABC.opinion>`. 

481 :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`. 

482 :returns: runtime path tied to the user 

483 """ 

484 return PlatformDirs( 

485 appname=appname, 

486 appauthor=appauthor, 

487 version=version, 

488 opinion=opinion, 

489 ensure_exists=ensure_exists, 

490 ).user_runtime_path 

491 

492 

493__all__ = [ 

494 "__version__", 

495 "__version_info__", 

496 "PlatformDirs", 

497 "AppDirs", 

498 "PlatformDirsABC", 

499 "user_data_dir", 

500 "user_config_dir", 

501 "user_cache_dir", 

502 "user_state_dir", 

503 "user_log_dir", 

504 "user_documents_dir", 

505 "user_runtime_dir", 

506 "site_data_dir", 

507 "site_config_dir", 

508 "site_cache_dir", 

509 "user_data_path", 

510 "user_config_path", 

511 "user_cache_path", 

512 "user_state_path", 

513 "user_log_path", 

514 "user_documents_path", 

515 "user_runtime_path", 

516 "site_data_path", 

517 "site_config_path", 

518 "site_cache_path", 

519]