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

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 

8PYTEST_DONT_REWRITE: Applications may import platformdirs before starting pytest. 

9 

10""" 

11 

12from __future__ import annotations 

13 

14import os 

15import sys 

16from typing import TYPE_CHECKING 

17 

18from .api import PlatformDirsABC, RuntimeDirWarning 

19from .version import __version__ 

20from .version import __version_tuple__ as __version_info__ 

21 

22if TYPE_CHECKING: 

23 from pathlib import Path 

24 from typing import Literal 

25 

26if sys.platform == "win32": 

27 from pip._vendor.platformdirs.windows import Windows as _Result 

28elif sys.platform == "darwin": 

29 from pip._vendor.platformdirs.macos import MacOS as _Result 

30elif sys.platform == "ios": 

31 from pip._vendor.platformdirs.ios import IOS as _Result # ruff:ignore[constant-imported-as-non-constant] # a class, PEP 8 acronym 

32else: 

33 from pip._vendor.platformdirs.unix import Unix as _Result 

34 

35 

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

37 # Every Android build of CPython has sys.getandroidapilevel, even in a process started with a cleared environment. 

38 if hasattr(sys, "getandroidapilevel") or ( 

39 os.getenv("ANDROID_DATA") == "/data" and os.getenv("ANDROID_ROOT") == "/system" 

40 ): 

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

42 return _Result 

43 

44 from pip._vendor.platformdirs.android import _android_folder # ruff:ignore[import-outside-top-level] 

45 

46 if _android_folder() is not None: 

47 from pip._vendor.platformdirs.android import Android # ruff:ignore[import-outside-top-level] 

48 

49 return Android # return to avoid redefinition of a result 

50 

51 return _Result 

52 

53 

54if TYPE_CHECKING: 

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

56 PlatformDirs = _Result 

57else: 

58 PlatformDirs = _set_platform_dir_class() #: Currently active platform 

59AppDirs = PlatformDirs #: Backwards compatibility with appdirs 

60 

61 

62def user_data_dir( # ruff:ignore[too-many-arguments, too-many-positional-arguments] 

63 appname: str | None = None, 

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

65 version: str | None = None, 

66 roaming: bool = False, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

67 ensure_exists: bool = False, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

68 use_site_for_root: bool = False, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

69) -> str: 

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

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

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

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

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

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

76 

77 :returns: data directory tied to the user 

78 

79 """ 

80 return PlatformDirs( 

81 appname=appname, 

82 appauthor=appauthor, 

83 version=version, 

84 roaming=roaming, 

85 ensure_exists=ensure_exists, 

86 use_site_for_root=use_site_for_root, 

87 ).user_data_dir 

88 

89 

90def site_data_dir( 

91 appname: str | None = None, 

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

93 version: str | None = None, 

94 multipath: bool = False, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

95 ensure_exists: bool = False, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

96) -> str: 

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

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

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

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

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

102 

103 :returns: data directory shared by users 

104 

105 """ 

106 return PlatformDirs( 

107 appname=appname, 

108 appauthor=appauthor, 

109 version=version, 

110 multipath=multipath, 

111 ensure_exists=ensure_exists, 

112 ).site_data_dir 

113 

114 

115def user_config_dir( # ruff:ignore[too-many-arguments, too-many-positional-arguments] 

116 appname: str | None = None, 

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

118 version: str | None = None, 

119 roaming: bool = False, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

120 ensure_exists: bool = False, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

121 use_site_for_root: bool = False, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

122) -> str: 

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

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

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

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

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

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

129 

130 :returns: config directory tied to the user 

131 

132 """ 

133 return PlatformDirs( 

134 appname=appname, 

135 appauthor=appauthor, 

136 version=version, 

137 roaming=roaming, 

138 ensure_exists=ensure_exists, 

139 use_site_for_root=use_site_for_root, 

140 ).user_config_dir 

141 

142 

143def site_config_dir( 

144 appname: str | None = None, 

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

146 version: str | None = None, 

147 multipath: bool = False, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

148 ensure_exists: bool = False, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

149) -> str: 

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

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

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

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

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

155 

156 :returns: config directory shared by users 

157 

158 """ 

159 return PlatformDirs( 

160 appname=appname, 

161 appauthor=appauthor, 

162 version=version, 

163 multipath=multipath, 

164 ensure_exists=ensure_exists, 

165 ).site_config_dir 

166 

167 

168def user_cache_dir( # ruff:ignore[too-many-arguments, too-many-positional-arguments] 

169 appname: str | None = None, 

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

171 version: str | None = None, 

172 opinion: bool = True, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

173 ensure_exists: bool = False, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

174 use_site_for_root: bool = False, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

175) -> str: 

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

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

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

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

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

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

182 

183 :returns: cache directory tied to the user 

184 

185 """ 

186 return PlatformDirs( 

187 appname=appname, 

188 appauthor=appauthor, 

189 version=version, 

190 opinion=opinion, 

191 ensure_exists=ensure_exists, 

192 use_site_for_root=use_site_for_root, 

193 ).user_cache_dir 

194 

195 

196def site_cache_dir( # ruff:ignore[too-many-arguments] 

197 appname: str | None = None, 

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

199 version: str | None = None, 

200 opinion: bool = True, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

201 ensure_exists: bool = False, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

202 *, 

203 multipath: bool = False, 

204) -> str: 

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

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

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

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

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

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

211 

212 :returns: cache directory shared by users 

213 

214 """ 

215 return PlatformDirs( 

216 appname=appname, 

217 appauthor=appauthor, 

218 version=version, 

219 multipath=multipath, 

220 opinion=opinion, 

221 ensure_exists=ensure_exists, 

222 ).site_cache_dir 

223 

224 

225def user_state_dir( # ruff:ignore[too-many-arguments, too-many-positional-arguments] 

226 appname: str | None = None, 

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

228 version: str | None = None, 

229 roaming: bool = False, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

230 ensure_exists: bool = False, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

231 use_site_for_root: bool = False, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

232) -> str: 

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

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

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

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

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

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

239 

240 :returns: state directory tied to the user 

241 

242 """ 

243 return PlatformDirs( 

244 appname=appname, 

245 appauthor=appauthor, 

246 version=version, 

247 roaming=roaming, 

248 ensure_exists=ensure_exists, 

249 use_site_for_root=use_site_for_root, 

250 ).user_state_dir 

251 

252 

253def site_state_dir( 

254 appname: str | None = None, 

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

256 version: str | None = None, 

257 ensure_exists: bool = False, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

258) -> str: 

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

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

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

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

263 

264 :returns: state directory shared by users 

265 

266 """ 

267 return PlatformDirs( 

268 appname=appname, 

269 appauthor=appauthor, 

270 version=version, 

271 ensure_exists=ensure_exists, 

272 ).site_state_dir 

273 

274 

275def user_log_dir( # ruff:ignore[too-many-arguments, too-many-positional-arguments] 

276 appname: str | None = None, 

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

278 version: str | None = None, 

279 opinion: bool = True, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

280 ensure_exists: bool = False, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

281 use_site_for_root: bool = False, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

282 *, 

283 roaming: bool = False, 

284) -> str: 

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

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

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

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

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

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

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

292 

293 :returns: log directory tied to the user 

294 

295 """ 

296 return PlatformDirs( 

297 appname=appname, 

298 appauthor=appauthor, 

299 version=version, 

300 roaming=roaming, 

301 opinion=opinion, 

302 ensure_exists=ensure_exists, 

303 use_site_for_root=use_site_for_root, 

304 ).user_log_dir 

305 

306 

307def site_log_dir( 

308 appname: str | None = None, 

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

310 version: str | None = None, 

311 opinion: bool = True, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

312 ensure_exists: bool = False, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

313) -> str: 

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

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

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

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

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

319 

320 :returns: log directory shared by users 

321 

322 """ 

323 return PlatformDirs( 

324 appname=appname, 

325 appauthor=appauthor, 

326 version=version, 

327 opinion=opinion, 

328 ensure_exists=ensure_exists, 

329 ).site_log_dir 

330 

331 

332def user_documents_dir() -> str: 

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

334 return PlatformDirs().user_documents_dir 

335 

336 

337def user_downloads_dir() -> str: 

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

339 return PlatformDirs().user_downloads_dir 

340 

341 

342def user_pictures_dir() -> str: 

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

344 return PlatformDirs().user_pictures_dir 

345 

346 

347def user_videos_dir() -> str: 

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

349 return PlatformDirs().user_videos_dir 

350 

351 

352def user_music_dir() -> str: 

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

354 return PlatformDirs().user_music_dir 

355 

356 

357def user_desktop_dir() -> str: 

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

359 return PlatformDirs().user_desktop_dir 

360 

361 

362def user_projects_dir() -> str: 

363 """:returns: projects directory tied to the user""" 

364 return PlatformDirs().user_projects_dir 

365 

366 

367def user_publicshare_dir() -> str: 

368 """:returns: public share directory tied to the user""" 

369 return PlatformDirs().user_publicshare_dir 

370 

371 

372def user_templates_dir() -> str: 

373 """:returns: templates directory tied to the user""" 

374 return PlatformDirs().user_templates_dir 

375 

376 

377def user_fonts_dir() -> str: 

378 """:returns: fonts directory tied to the user""" 

379 return PlatformDirs().user_fonts_dir 

380 

381 

382def user_preference_dir( # ruff:ignore[too-many-arguments] 

383 appname: str | None = None, 

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

385 version: str | None = None, 

386 *, 

387 roaming: bool = False, 

388 ensure_exists: bool = False, 

389 use_site_for_root: bool = False, 

390) -> str: 

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

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

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

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

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

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

397 

398 :returns: preference directory tied to the user 

399 

400 """ 

401 return PlatformDirs( 

402 appname=appname, 

403 appauthor=appauthor, 

404 version=version, 

405 roaming=roaming, 

406 ensure_exists=ensure_exists, 

407 use_site_for_root=use_site_for_root, 

408 ).user_preference_dir 

409 

410 

411def user_bin_dir(*, use_site_for_root: bool = False) -> str: 

412 """:param use_site_for_root: See `use_site_for_root <platformdirs.api.PlatformDirsABC.use_site_for_root>`. 

413 

414 :returns: bin directory tied to the user 

415 

416 """ 

417 return PlatformDirs(use_site_for_root=use_site_for_root).user_bin_dir 

418 

419 

420def site_bin_dir() -> str: 

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

422 return PlatformDirs().site_bin_dir 

423 

424 

425def user_applications_dir( 

426 appname: str | None = None, 

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

428 version: str | None = None, 

429 *, 

430 ensure_exists: bool = False, 

431 use_site_for_root: bool = False, 

432) -> str: 

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

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

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

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

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

438 

439 :returns: applications directory tied to the user 

440 

441 """ 

442 return PlatformDirs( 

443 appname=appname, 

444 appauthor=appauthor, 

445 version=version, 

446 ensure_exists=ensure_exists, 

447 use_site_for_root=use_site_for_root, 

448 ).user_applications_dir 

449 

450 

451def site_applications_dir( 

452 multipath: bool = False, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

453 ensure_exists: bool = False, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

454 *, 

455 appname: str | None = None, 

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

457 version: str | None = None, 

458) -> str: 

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

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

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

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

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

464 

465 :returns: applications directory shared by users 

466 

467 """ 

468 return PlatformDirs( 

469 appname=appname, 

470 appauthor=appauthor, 

471 version=version, 

472 multipath=multipath, 

473 ensure_exists=ensure_exists, 

474 ).site_applications_dir 

475 

476 

477def user_runtime_dir( # ruff:ignore[too-many-arguments, too-many-positional-arguments] 

478 appname: str | None = None, 

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

480 version: str | None = None, 

481 opinion: bool = True, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

482 ensure_exists: bool = False, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

483 use_site_for_root: bool = False, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

484) -> str: 

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

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

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

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

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

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

491 

492 :returns: runtime directory tied to the user 

493 

494 """ 

495 return PlatformDirs( 

496 appname=appname, 

497 appauthor=appauthor, 

498 version=version, 

499 opinion=opinion, 

500 ensure_exists=ensure_exists, 

501 use_site_for_root=use_site_for_root, 

502 ).user_runtime_dir 

503 

504 

505def site_runtime_dir( 

506 appname: str | None = None, 

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

508 version: str | None = None, 

509 opinion: bool = True, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

510 ensure_exists: bool = False, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

511) -> str: 

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

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

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

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

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

517 

518 :returns: runtime directory shared by users 

519 

520 """ 

521 return PlatformDirs( 

522 appname=appname, 

523 appauthor=appauthor, 

524 version=version, 

525 opinion=opinion, 

526 ensure_exists=ensure_exists, 

527 ).site_runtime_dir 

528 

529 

530def user_data_path( # ruff:ignore[too-many-arguments, too-many-positional-arguments] 

531 appname: str | None = None, 

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

533 version: str | None = None, 

534 roaming: bool = False, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

535 ensure_exists: bool = False, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

536 use_site_for_root: bool = False, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

537) -> Path: 

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

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

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

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

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

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

544 

545 :returns: data path tied to the user 

546 

547 """ 

548 return PlatformDirs( 

549 appname=appname, 

550 appauthor=appauthor, 

551 version=version, 

552 roaming=roaming, 

553 ensure_exists=ensure_exists, 

554 use_site_for_root=use_site_for_root, 

555 ).user_data_path 

556 

557 

558def site_data_path( 

559 appname: str | None = None, 

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

561 version: str | None = None, 

562 multipath: bool = False, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

563 ensure_exists: bool = False, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

564) -> Path: 

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

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

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

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

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

570 

571 :returns: data path shared by users 

572 

573 """ 

574 return PlatformDirs( 

575 appname=appname, 

576 appauthor=appauthor, 

577 version=version, 

578 multipath=multipath, 

579 ensure_exists=ensure_exists, 

580 ).site_data_path 

581 

582 

583def user_config_path( # ruff:ignore[too-many-arguments, too-many-positional-arguments] 

584 appname: str | None = None, 

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

586 version: str | None = None, 

587 roaming: bool = False, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

588 ensure_exists: bool = False, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

589 use_site_for_root: bool = False, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

590) -> Path: 

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

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

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

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

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

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

597 

598 :returns: config path tied to the user 

599 

600 """ 

601 return PlatformDirs( 

602 appname=appname, 

603 appauthor=appauthor, 

604 version=version, 

605 roaming=roaming, 

606 ensure_exists=ensure_exists, 

607 use_site_for_root=use_site_for_root, 

608 ).user_config_path 

609 

610 

611def site_config_path( 

612 appname: str | None = None, 

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

614 version: str | None = None, 

615 multipath: bool = False, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

616 ensure_exists: bool = False, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

617) -> Path: 

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

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

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

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

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

623 

624 :returns: config path shared by users 

625 

626 """ 

627 return PlatformDirs( 

628 appname=appname, 

629 appauthor=appauthor, 

630 version=version, 

631 multipath=multipath, 

632 ensure_exists=ensure_exists, 

633 ).site_config_path 

634 

635 

636def site_cache_path( # ruff:ignore[too-many-arguments] 

637 appname: str | None = None, 

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

639 version: str | None = None, 

640 opinion: bool = True, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

641 ensure_exists: bool = False, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

642 *, 

643 multipath: bool = False, 

644) -> Path: 

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

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

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

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

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

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

651 

652 :returns: cache path shared by users 

653 

654 """ 

655 return PlatformDirs( 

656 appname=appname, 

657 appauthor=appauthor, 

658 version=version, 

659 multipath=multipath, 

660 opinion=opinion, 

661 ensure_exists=ensure_exists, 

662 ).site_cache_path 

663 

664 

665def user_cache_path( # ruff:ignore[too-many-arguments, too-many-positional-arguments] 

666 appname: str | None = None, 

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

668 version: str | None = None, 

669 opinion: bool = True, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

670 ensure_exists: bool = False, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

671 use_site_for_root: bool = False, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

672) -> Path: 

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

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

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

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

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

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

679 

680 :returns: cache path tied to the user 

681 

682 """ 

683 return PlatformDirs( 

684 appname=appname, 

685 appauthor=appauthor, 

686 version=version, 

687 opinion=opinion, 

688 ensure_exists=ensure_exists, 

689 use_site_for_root=use_site_for_root, 

690 ).user_cache_path 

691 

692 

693def user_state_path( # ruff:ignore[too-many-arguments, too-many-positional-arguments] 

694 appname: str | None = None, 

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

696 version: str | None = None, 

697 roaming: bool = False, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

698 ensure_exists: bool = False, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

699 use_site_for_root: bool = False, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

700) -> Path: 

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

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

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

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

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

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

707 

708 :returns: state path tied to the user 

709 

710 """ 

711 return PlatformDirs( 

712 appname=appname, 

713 appauthor=appauthor, 

714 version=version, 

715 roaming=roaming, 

716 ensure_exists=ensure_exists, 

717 use_site_for_root=use_site_for_root, 

718 ).user_state_path 

719 

720 

721def site_state_path( 

722 appname: str | None = None, 

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

724 version: str | None = None, 

725 ensure_exists: bool = False, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

726) -> Path: 

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

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

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

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

731 

732 :returns: state path shared by users 

733 

734 """ 

735 return PlatformDirs( 

736 appname=appname, 

737 appauthor=appauthor, 

738 version=version, 

739 ensure_exists=ensure_exists, 

740 ).site_state_path 

741 

742 

743def user_log_path( # ruff:ignore[too-many-arguments, too-many-positional-arguments] 

744 appname: str | None = None, 

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

746 version: str | None = None, 

747 opinion: bool = True, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

748 ensure_exists: bool = False, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

749 use_site_for_root: bool = False, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

750 *, 

751 roaming: bool = False, 

752) -> Path: 

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

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

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

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

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

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

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

760 

761 :returns: log path tied to the user 

762 

763 """ 

764 return PlatformDirs( 

765 appname=appname, 

766 appauthor=appauthor, 

767 version=version, 

768 roaming=roaming, 

769 opinion=opinion, 

770 ensure_exists=ensure_exists, 

771 use_site_for_root=use_site_for_root, 

772 ).user_log_path 

773 

774 

775def site_log_path( 

776 appname: str | None = None, 

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

778 version: str | None = None, 

779 opinion: bool = True, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

780 ensure_exists: bool = False, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

781) -> Path: 

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

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

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

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

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

787 

788 :returns: log path shared by users 

789 

790 """ 

791 return PlatformDirs( 

792 appname=appname, 

793 appauthor=appauthor, 

794 version=version, 

795 opinion=opinion, 

796 ensure_exists=ensure_exists, 

797 ).site_log_path 

798 

799 

800def user_documents_path() -> Path: 

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

802 return PlatformDirs().user_documents_path 

803 

804 

805def user_downloads_path() -> Path: 

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

807 return PlatformDirs().user_downloads_path 

808 

809 

810def user_pictures_path() -> Path: 

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

812 return PlatformDirs().user_pictures_path 

813 

814 

815def user_videos_path() -> Path: 

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

817 return PlatformDirs().user_videos_path 

818 

819 

820def user_music_path() -> Path: 

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

822 return PlatformDirs().user_music_path 

823 

824 

825def user_desktop_path() -> Path: 

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

827 return PlatformDirs().user_desktop_path 

828 

829 

830def user_projects_path() -> Path: 

831 """:returns: projects path tied to the user""" 

832 return PlatformDirs().user_projects_path 

833 

834 

835def user_publicshare_path() -> Path: 

836 """:returns: public share path tied to the user""" 

837 return PlatformDirs().user_publicshare_path 

838 

839 

840def user_templates_path() -> Path: 

841 """:returns: templates path tied to the user""" 

842 return PlatformDirs().user_templates_path 

843 

844 

845def user_fonts_path() -> Path: 

846 """:returns: fonts path tied to the user""" 

847 return PlatformDirs().user_fonts_path 

848 

849 

850def user_preference_path( # ruff:ignore[too-many-arguments] 

851 appname: str | None = None, 

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

853 version: str | None = None, 

854 *, 

855 roaming: bool = False, 

856 ensure_exists: bool = False, 

857 use_site_for_root: bool = False, 

858) -> Path: 

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

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

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

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

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

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

865 

866 :returns: preference path tied to the user 

867 

868 """ 

869 return PlatformDirs( 

870 appname=appname, 

871 appauthor=appauthor, 

872 version=version, 

873 roaming=roaming, 

874 ensure_exists=ensure_exists, 

875 use_site_for_root=use_site_for_root, 

876 ).user_preference_path 

877 

878 

879def user_bin_path(*, use_site_for_root: bool = False) -> Path: 

880 """:param use_site_for_root: See `use_site_for_root <platformdirs.api.PlatformDirsABC.use_site_for_root>`. 

881 

882 :returns: bin path tied to the user 

883 

884 """ 

885 return PlatformDirs(use_site_for_root=use_site_for_root).user_bin_path 

886 

887 

888def site_bin_path() -> Path: 

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

890 return PlatformDirs().site_bin_path 

891 

892 

893def user_applications_path( 

894 appname: str | None = None, 

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

896 version: str | None = None, 

897 *, 

898 ensure_exists: bool = False, 

899 use_site_for_root: bool = False, 

900) -> Path: 

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

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

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

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

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

906 

907 :returns: applications path tied to the user 

908 

909 """ 

910 return PlatformDirs( 

911 appname=appname, 

912 appauthor=appauthor, 

913 version=version, 

914 ensure_exists=ensure_exists, 

915 use_site_for_root=use_site_for_root, 

916 ).user_applications_path 

917 

918 

919def site_applications_path( 

920 multipath: bool = False, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

921 ensure_exists: bool = False, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

922 *, 

923 appname: str | None = None, 

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

925 version: str | None = None, 

926) -> Path: 

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

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

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

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

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

932 

933 :returns: applications path shared by users 

934 

935 """ 

936 return PlatformDirs( 

937 appname=appname, 

938 appauthor=appauthor, 

939 version=version, 

940 multipath=multipath, 

941 ensure_exists=ensure_exists, 

942 ).site_applications_path 

943 

944 

945def user_runtime_path( # ruff:ignore[too-many-arguments, too-many-positional-arguments] 

946 appname: str | None = None, 

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

948 version: str | None = None, 

949 opinion: bool = True, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

950 ensure_exists: bool = False, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

951 use_site_for_root: bool = False, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] 

952) -> Path: 

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

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

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

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

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

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

959 

960 :returns: runtime path tied to the user 

961 

962 """ 

963 return PlatformDirs(