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

1"""Utilities for determining application-specific dirs. 

2 

3Provides convenience functions (e.g. :func:`user_data_dir`, :func:`user_config_path`), a :data:`PlatformDirs` class that 

4auto-detects the current platform, and the :class:`~platformdirs.api.PlatformDirsABC` base class. 

5 

6See <https://github.com/platformdirs/platformdirs> for details and usage. 

7 

8""" 

9 

10from __future__ import annotations 

11 

12import os 

13import sys 

14from typing import TYPE_CHECKING 

15 

16from .api import PlatformDirsABC 

17from .version import __version__ 

18from .version import __version_tuple__ as __version_info__ 

19 

20if TYPE_CHECKING: 

21 from pathlib import Path 

22 from typing import Literal 

23 

24if sys.platform == "win32": 

25 from platformdirs.windows import Windows as _Result 

26elif sys.platform == "darwin": 

27 from platformdirs.macos import MacOS as _Result 

28else: 

29 from platformdirs.unix import Unix as _Result 

30 

31 

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

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

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

35 return _Result 

36 

37 from platformdirs.android import _android_folder # noqa: PLC0415 

38 

39 if _android_folder() is not None: 

40 from platformdirs.android import Android # noqa: PLC0415 

41 

42 return Android # return to avoid redefinition of a result 

43 

44 return _Result 

45 

46 

47if TYPE_CHECKING: 

48 # Work around mypy issue: https://github.com/python/mypy/issues/10962 

49 PlatformDirs = _Result 

50else: 

51 PlatformDirs = _set_platform_dir_class() #: Currently active platform 

52AppDirs = PlatformDirs #: Backwards compatibility with appdirs 

53 

54 

55def user_data_dir( # noqa: PLR0913, PLR0917 

56 appname: str | None = None, 

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

58 version: str | None = None, 

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

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

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

62) -> str: 

63 """:param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 

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

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

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

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

68 :param use_site_for_root: See `use_site_for_root <platformdirs.api.PlatformDirsABC.use_site_for_root>`. 

69 

70 :returns: data directory tied to the user 

71 

72 """ 

73 return PlatformDirs( 

74 appname=appname, 

75 appauthor=appauthor, 

76 version=version, 

77 roaming=roaming, 

78 ensure_exists=ensure_exists, 

79 use_site_for_root=use_site_for_root, 

80 ).user_data_dir 

81 

82 

83def site_data_dir( 

84 appname: str | None = None, 

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

86 version: str | None = None, 

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

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

89) -> str: 

90 """:param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 

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

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

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

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

95 

96 :returns: data directory shared by users 

97 

98 """ 

99 return PlatformDirs( 

100 appname=appname, 

101 appauthor=appauthor, 

102 version=version, 

103 multipath=multipath, 

104 ensure_exists=ensure_exists, 

105 ).site_data_dir 

106 

107 

108def user_config_dir( # noqa: PLR0913, PLR0917 

109 appname: str | None = None, 

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

111 version: str | None = None, 

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

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

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

115) -> str: 

116 """:param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 

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

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

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

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

121 :param use_site_for_root: See `use_site_for_root <platformdirs.api.PlatformDirsABC.use_site_for_root>`. 

122 

123 :returns: config directory tied to the user 

124 

125 """ 

126 return PlatformDirs( 

127 appname=appname, 

128 appauthor=appauthor, 

129 version=version, 

130 roaming=roaming, 

131 ensure_exists=ensure_exists, 

132 use_site_for_root=use_site_for_root, 

133 ).user_config_dir 

134 

135 

136def site_config_dir( 

137 appname: str | None = None, 

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

139 version: str | None = None, 

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

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

142) -> str: 

143 """:param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 

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

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

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

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

148 

149 :returns: config directory shared by users 

150 

151 """ 

152 return PlatformDirs( 

153 appname=appname, 

154 appauthor=appauthor, 

155 version=version, 

156 multipath=multipath, 

157 ensure_exists=ensure_exists, 

158 ).site_config_dir 

159 

160 

161def user_cache_dir( # noqa: PLR0913, PLR0917 

162 appname: str | None = None, 

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

164 version: str | None = None, 

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

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

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

168) -> str: 

169 """:param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 

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

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

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

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

174 :param use_site_for_root: See `use_site_for_root <platformdirs.api.PlatformDirsABC.use_site_for_root>`. 

175 

176 :returns: cache directory tied to the user 

177 

178 """ 

179 return PlatformDirs( 

180 appname=appname, 

181 appauthor=appauthor, 

182 version=version, 

183 opinion=opinion, 

184 ensure_exists=ensure_exists, 

185 use_site_for_root=use_site_for_root, 

186 ).user_cache_dir 

187 

188 

189def site_cache_dir( 

190 appname: str | None = None, 

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

192 version: str | None = None, 

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

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

195) -> str: 

196 """:param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 

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

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

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

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

201 

202 :returns: cache directory shared by users 

203 

204 """ 

205 return PlatformDirs( 

206 appname=appname, 

207 appauthor=appauthor, 

208 version=version, 

209 opinion=opinion, 

210 ensure_exists=ensure_exists, 

211 ).site_cache_dir 

212 

213 

214def user_state_dir( # noqa: PLR0913, PLR0917 

215 appname: str | None = None, 

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

217 version: str | None = None, 

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

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

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

221) -> str: 

222 """:param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 

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

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

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

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

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

228 

229 :returns: state directory tied to the user 

230 

231 """ 

232 return PlatformDirs( 

233 appname=appname, 

234 appauthor=appauthor, 

235 version=version, 

236 roaming=roaming, 

237 ensure_exists=ensure_exists, 

238 use_site_for_root=use_site_for_root, 

239 ).user_state_dir 

240 

241 

242def site_state_dir( 

243 appname: str | None = None, 

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

245 version: str | None = None, 

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

247) -> str: 

248 """:param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 

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

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

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

252 

253 :returns: state directory shared by users 

254 

255 """ 

256 return PlatformDirs( 

257 appname=appname, 

258 appauthor=appauthor, 

259 version=version, 

260 ensure_exists=ensure_exists, 

261 ).site_state_dir 

262 

263 

264def user_log_dir( # noqa: PLR0913, PLR0917 

265 appname: str | None = None, 

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

267 version: str | None = None, 

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

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

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

271) -> str: 

272 """:param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 

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

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

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

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

277 :param use_site_for_root: See `use_site_for_root <platformdirs.api.PlatformDirsABC.use_site_for_root>`. 

278 

279 :returns: log directory tied to the user 

280 

281 """ 

282 return PlatformDirs( 

283 appname=appname, 

284 appauthor=appauthor, 

285 version=version, 

286 opinion=opinion, 

287 ensure_exists=ensure_exists, 

288 use_site_for_root=use_site_for_root, 

289 ).user_log_dir 

290 

291 

292def site_log_dir( 

293 appname: str | None = None, 

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

295 version: str | None = None, 

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

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

298) -> str: 

299 """:param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 

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

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

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

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

304 

305 :returns: log directory shared by users 

306 

307 """ 

308 return PlatformDirs( 

309 appname=appname, 

310 appauthor=appauthor, 

311 version=version, 

312 opinion=opinion, 

313 ensure_exists=ensure_exists, 

314 ).site_log_dir 

315 

316 

317def user_documents_dir() -> str: 

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

319 return PlatformDirs().user_documents_dir 

320 

321 

322def user_downloads_dir() -> str: 

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

324 return PlatformDirs().user_downloads_dir 

325 

326 

327def user_pictures_dir() -> str: 

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

329 return PlatformDirs().user_pictures_dir 

330 

331 

332def user_videos_dir() -> str: 

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

334 return PlatformDirs().user_videos_dir 

335 

336 

337def user_music_dir() -> str: 

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

339 return PlatformDirs().user_music_dir 

340 

341 

342def user_desktop_dir() -> str: 

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

344 return PlatformDirs().user_desktop_dir 

345 

346 

347def user_bin_dir() -> str: 

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

349 return PlatformDirs().user_bin_dir 

350 

351 

352def site_bin_dir() -> str: 

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

354 return PlatformDirs().site_bin_dir 

355 

356 

357def user_applications_dir() -> str: 

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

359 return PlatformDirs().user_applications_dir 

360 

361 

362def site_applications_dir( 

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

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

365) -> str: 

366 """:param multipath: See `multipath <platformdirs.api.PlatformDirsABC.multipath>`. 

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

368 

369 :returns: applications directory shared by users 

370 

371 """ 

372 return PlatformDirs( 

373 multipath=multipath, 

374 ensure_exists=ensure_exists, 

375 ).site_applications_dir 

376 

377 

378def user_runtime_dir( # noqa: PLR0913, PLR0917 

379 appname: str | None = None, 

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

381 version: str | None = None, 

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

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

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

385) -> str: 

386 """:param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 

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

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

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

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

391 :param use_site_for_root: See `use_site_for_root <platformdirs.api.PlatformDirsABC.use_site_for_root>`. 

392 

393 :returns: runtime directory tied to the user 

394 

395 """ 

396 return PlatformDirs( 

397 appname=appname, 

398 appauthor=appauthor, 

399 version=version, 

400 opinion=opinion, 

401 ensure_exists=ensure_exists, 

402 use_site_for_root=use_site_for_root, 

403 ).user_runtime_dir 

404 

405 

406def site_runtime_dir( 

407 appname: str | None = None, 

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

409 version: str | None = None, 

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

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

412) -> str: 

413 """:param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 

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

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

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

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

418 

419 :returns: runtime directory shared by users 

420 

421 """ 

422 return PlatformDirs( 

423 appname=appname, 

424 appauthor=appauthor, 

425 version=version, 

426 opinion=opinion, 

427 ensure_exists=ensure_exists, 

428 ).site_runtime_dir 

429 

430 

431def user_data_path( # noqa: PLR0913, PLR0917 

432 appname: str | None = None, 

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

434 version: str | None = None, 

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

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

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

438) -> Path: 

439 """:param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 

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

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

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

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

444 :param use_site_for_root: See `use_site_for_root <platformdirs.api.PlatformDirsABC.use_site_for_root>`. 

445 

446 :returns: data path tied to the user 

447 

448 """ 

449 return PlatformDirs( 

450 appname=appname, 

451 appauthor=appauthor, 

452 version=version, 

453 roaming=roaming, 

454 ensure_exists=ensure_exists, 

455 use_site_for_root=use_site_for_root, 

456 ).user_data_path 

457 

458 

459def site_data_path( 

460 appname: str | None = None, 

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

462 version: str | None = None, 

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

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

465) -> Path: 

466 """:param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 

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

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

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

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

471 

472 :returns: data path shared by users 

473 

474 """ 

475 return PlatformDirs( 

476 appname=appname, 

477 appauthor=appauthor, 

478 version=version, 

479 multipath=multipath, 

480 ensure_exists=ensure_exists, 

481 ).site_data_path 

482 

483 

484def user_config_path( # noqa: PLR0913, PLR0917 

485 appname: str | None = None, 

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

487 version: str | None = None, 

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

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

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

491) -> Path: 

492 """:param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 

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

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

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

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

497 :param use_site_for_root: See `use_site_for_root <platformdirs.api.PlatformDirsABC.use_site_for_root>`. 

498 

499 :returns: config path tied to the user 

500 

501 """ 

502 return PlatformDirs( 

503 appname=appname, 

504 appauthor=appauthor, 

505 version=version, 

506 roaming=roaming, 

507 ensure_exists=ensure_exists, 

508 use_site_for_root=use_site_for_root, 

509 ).user_config_path 

510 

511 

512def site_config_path( 

513 appname: str | None = None, 

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

515 version: str | None = None, 

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

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

518) -> Path: 

519 """:param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 

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

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

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

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

524 

525 :returns: config path shared by users 

526 

527 """ 

528 return PlatformDirs( 

529 appname=appname, 

530 appauthor=appauthor, 

531 version=version, 

532 multipath=multipath, 

533 ensure_exists=ensure_exists, 

534 ).site_config_path 

535 

536 

537def site_cache_path( 

538 appname: str | None = None, 

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

540 version: str | None = None, 

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

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

543) -> Path: 

544 """:param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 

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

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

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

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

549 

550 :returns: cache path shared by users 

551 

552 """ 

553 return PlatformDirs( 

554 appname=appname, 

555 appauthor=appauthor, 

556 version=version, 

557 opinion=opinion, 

558 ensure_exists=ensure_exists, 

559 ).site_cache_path 

560 

561 

562def user_cache_path( # noqa: PLR0913, PLR0917 

563 appname: str | None = None, 

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

565 version: str | None = None, 

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

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

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

569) -> Path: 

570 """:param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 

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

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

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

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

575 :param use_site_for_root: See `use_site_for_root <platformdirs.api.PlatformDirsABC.use_site_for_root>`. 

576 

577 :returns: cache path tied to the user 

578 

579 """ 

580 return PlatformDirs( 

581 appname=appname, 

582 appauthor=appauthor, 

583 version=version, 

584 opinion=opinion, 

585 ensure_exists=ensure_exists, 

586 use_site_for_root=use_site_for_root, 

587 ).user_cache_path 

588 

589 

590def user_state_path( # noqa: PLR0913, PLR0917 

591 appname: str | None = None, 

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

593 version: str | None = None, 

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

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

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

597) -> Path: 

598 """:param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 

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

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

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

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

603 :param use_site_for_root: See `use_site_for_root <platformdirs.api.PlatformDirsABC.use_site_for_root>`. 

604 

605 :returns: state path tied to the user 

606 

607 """ 

608 return PlatformDirs( 

609 appname=appname, 

610 appauthor=appauthor, 

611 version=version, 

612 roaming=roaming, 

613 ensure_exists=ensure_exists, 

614 use_site_for_root=use_site_for_root, 

615 ).user_state_path 

616 

617 

618def site_state_path( 

619 appname: str | None = None, 

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

621 version: str | None = None, 

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

623) -> Path: 

624 """:param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 

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

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

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

628 

629 :returns: state path shared by users 

630 

631 """ 

632 return PlatformDirs( 

633 appname=appname, 

634 appauthor=appauthor, 

635 version=version, 

636 ensure_exists=ensure_exists, 

637 ).site_state_path 

638 

639 

640def user_log_path( # noqa: PLR0913, PLR0917 

641 appname: str | None = None, 

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

643 version: str | None = None, 

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

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

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

647) -> Path: 

648 """:param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 

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

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

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

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

653 :param use_site_for_root: See `use_site_for_root <platformdirs.api.PlatformDirsABC.use_site_for_root>`. 

654 

655 :returns: log path tied to the user 

656 

657 """ 

658 return PlatformDirs( 

659 appname=appname, 

660 appauthor=appauthor, 

661 version=version, 

662 opinion=opinion, 

663 ensure_exists=ensure_exists, 

664 use_site_for_root=use_site_for_root, 

665 ).user_log_path 

666 

667 

668def site_log_path( 

669 appname: str | None = None, 

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

671 version: str | None = None, 

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

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

674) -> Path: 

675 """:param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 

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

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

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

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

680 

681 :returns: log path shared by users 

682 

683 """ 

684 return PlatformDirs( 

685 appname=appname, 

686 appauthor=appauthor, 

687 version=version, 

688 opinion=opinion, 

689 ensure_exists=ensure_exists, 

690 ).site_log_path 

691 

692 

693def user_documents_path() -> Path: 

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

695 return PlatformDirs().user_documents_path 

696 

697 

698def user_downloads_path() -> Path: 

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

700 return PlatformDirs().user_downloads_path 

701 

702 

703def user_pictures_path() -> Path: 

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

705 return PlatformDirs().user_pictures_path 

706 

707 

708def user_videos_path() -> Path: 

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

710 return PlatformDirs().user_videos_path 

711 

712 

713def user_music_path() -> Path: 

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

715 return PlatformDirs().user_music_path 

716 

717 

718def user_desktop_path() -> Path: 

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

720 return PlatformDirs().user_desktop_path 

721 

722 

723def user_bin_path() -> Path: 

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

725 return PlatformDirs().user_bin_path 

726 

727 

728def site_bin_path() -> Path: 

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

730 return PlatformDirs().site_bin_path 

731 

732 

733def user_applications_path() -> Path: 

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

735 return PlatformDirs().user_applications_path 

736 

737 

738def site_applications_path( 

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

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

741) -> Path: 

742 """:param multipath: See `multipath <platformdirs.api.PlatformDirsABC.multipath>`. 

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

744 

745 :returns: applications path shared by users 

746 

747 """ 

748 return PlatformDirs( 

749 multipath=multipath, 

750 ensure_exists=ensure_exists, 

751 ).site_applications_path 

752 

753 

754def user_runtime_path( # noqa: PLR0913, PLR0917 

755 appname: str | None = None, 

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

757 version: str | None = None, 

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

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

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

761) -> Path: 

762 """:param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 

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

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

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

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

767 :param use_site_for_root: See `use_site_for_root <platformdirs.api.PlatformDirsABC.use_site_for_root>`. 

768 

769 :returns: runtime path tied to the user 

770 

771 """ 

772 return PlatformDirs( 

773 appname=appname, 

774 appauthor=appauthor, 

775 version=version, 

776 opinion=opinion, 

777 ensure_exists=ensure_exists, 

778 use_site_for_root=use_site_for_root, 

779 ).user_runtime_path 

780 

781 

782def site_runtime_path( 

783 appname: str | None = None, 

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

785 version: str | None = None, 

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

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

788) -> Path: 

789 """:param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 

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

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

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

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

794 

795 :returns: runtime path shared by users 

796 

797 """ 

798 return PlatformDirs( 

799 appname=appname, 

800 appauthor=appauthor, 

801 version=version, 

802 opinion=opinion, 

803 ensure_exists=ensure_exists, 

804 ).site_runtime_path 

805 

806 

807__all__ = [ 

808 "AppDirs", 

809 "PlatformDirs", 

810 "PlatformDirsABC", 

811 "__version__", 

812 "__version_info__", 

813 "site_applications_dir", 

814 "site_applications_path", 

815 "site_bin_dir", 

816 "site_bin_path", 

817 "site_cache_dir", 

818 "site_cache_path", 

819 "site_config_dir", 

820 "site_config_path", 

821 "site_data_dir", 

822 "site_data_path", 

823 "site_log_dir", 

824 "site_log_path", 

825 "site_runtime_dir", 

826 "site_runtime_path", 

827 "site_state_dir", 

828 "site_state_path", 

829 "user_applications_dir", 

830 "user_applications_path", 

831 "user_bin_dir", 

832 "user_bin_path", 

833 "user_cache_dir", 

834 "user_cache_path", 

835 "user_config_dir", 

836 "user_config_path", 

837 "user_data_dir", 

838 "user_data_path", 

839 "user_desktop_dir", 

840 "user_desktop_path", 

841 "user_documents_dir", 

842 "user_documents_path", 

843 "user_downloads_dir", 

844 "user_downloads_path", 

845 "user_log_dir", 

846 "user_log_path", 

847 "user_music_dir", 

848 "user_music_path", 

849 "user_pictures_dir", 

850 "user_pictures_path", 

851 "user_runtime_dir", 

852 "user_runtime_path", 

853 "user_state_dir", 

854 "user_state_path", 

855 "user_videos_dir", 

856 "user_videos_path", 

857]