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 

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 platformdirs.windows import Windows as _Result 

28elif sys.platform == "darwin": 

29 from platformdirs.macos import MacOS as _Result 

30elif sys.platform == "ios": 

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

32else: 

33 from 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 platformdirs.android import _android_folder # ruff:ignore[import-outside-top-level] 

45 

46 if _android_folder() is not None: 

47 from 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(*, ensure_exists: bool = False) -> str: 

333 """:param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`. 

334 

335 :returns: documents directory tied to the user 

336 

337 """ 

338 return PlatformDirs(ensure_exists=ensure_exists).user_documents_dir 

339 

340 

341def user_downloads_dir(*, ensure_exists: bool = False) -> str: 

342 """:param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`. 

343 

344 :returns: downloads directory tied to the user 

345 

346 """ 

347 return PlatformDirs(ensure_exists=ensure_exists).user_downloads_dir 

348 

349 

350def user_pictures_dir(*, ensure_exists: bool = False) -> str: 

351 """:param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`. 

352 

353 :returns: pictures directory tied to the user 

354 

355 """ 

356 return PlatformDirs(ensure_exists=ensure_exists).user_pictures_dir 

357 

358 

359def user_videos_dir(*, ensure_exists: bool = False) -> str: 

360 """:param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`. 

361 

362 :returns: videos directory tied to the user 

363 

364 """ 

365 return PlatformDirs(ensure_exists=ensure_exists).user_videos_dir 

366 

367 

368def user_music_dir(*, ensure_exists: bool = False) -> str: 

369 """:param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`. 

370 

371 :returns: music directory tied to the user 

372 

373 """ 

374 return PlatformDirs(ensure_exists=ensure_exists).user_music_dir 

375 

376 

377def user_desktop_dir(*, ensure_exists: bool = False) -> str: 

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

379 

380 :returns: desktop directory tied to the user 

381 

382 """ 

383 return PlatformDirs(ensure_exists=ensure_exists).user_desktop_dir 

384 

385 

386def user_projects_dir(*, ensure_exists: bool = False) -> str: 

387 """:param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`. 

388 

389 :returns: projects directory tied to the user 

390 

391 """ 

392 return PlatformDirs(ensure_exists=ensure_exists).user_projects_dir 

393 

394 

395def user_publicshare_dir(*, ensure_exists: bool = False) -> str: 

396 """:param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`. 

397 

398 :returns: public share directory tied to the user 

399 

400 """ 

401 return PlatformDirs(ensure_exists=ensure_exists).user_publicshare_dir 

402 

403 

404def user_templates_dir(*, ensure_exists: bool = False) -> str: 

405 """:param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`. 

406 

407 :returns: templates directory tied to the user 

408 

409 """ 

410 return PlatformDirs(ensure_exists=ensure_exists).user_templates_dir 

411 

412 

413def user_fonts_dir() -> str: 

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

415 return PlatformDirs().user_fonts_dir 

416 

417 

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

419 appname: str | None = None, 

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

421 version: str | None = None, 

422 *, 

423 roaming: bool = False, 

424 ensure_exists: bool = False, 

425 use_site_for_root: bool = False, 

426) -> str: 

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

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

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

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

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

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

433 

434 :returns: preference directory tied to the user 

435 

436 """ 

437 return PlatformDirs( 

438 appname=appname, 

439 appauthor=appauthor, 

440 version=version, 

441 roaming=roaming, 

442 ensure_exists=ensure_exists, 

443 use_site_for_root=use_site_for_root, 

444 ).user_preference_dir 

445 

446 

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

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

449 

450 :returns: bin directory tied to the user 

451 

452 """ 

453 return PlatformDirs(use_site_for_root=use_site_for_root).user_bin_dir 

454 

455 

456def site_bin_dir() -> str: 

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

458 return PlatformDirs().site_bin_dir 

459 

460 

461def user_applications_dir( 

462 appname: str | None = None, 

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

464 version: str | None = None, 

465 *, 

466 ensure_exists: bool = False, 

467 use_site_for_root: bool = False, 

468) -> str: 

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

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

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

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

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

474 

475 :returns: applications directory tied to the user 

476 

477 """ 

478 return PlatformDirs( 

479 appname=appname, 

480 appauthor=appauthor, 

481 version=version, 

482 ensure_exists=ensure_exists, 

483 use_site_for_root=use_site_for_root, 

484 ).user_applications_dir 

485 

486 

487def site_applications_dir( 

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

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

490 *, 

491 appname: str | None = None, 

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

493 version: str | None = None, 

494) -> str: 

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

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

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

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

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

500 

501 :returns: applications directory shared by users 

502 

503 """ 

504 return PlatformDirs( 

505 appname=appname, 

506 appauthor=appauthor, 

507 version=version, 

508 multipath=multipath, 

509 ensure_exists=ensure_exists, 

510 ).site_applications_dir 

511 

512 

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

514 appname: str | None = None, 

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

516 version: str | None = None, 

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

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

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

520) -> str: 

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

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

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

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

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

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

527 

528 :returns: runtime directory tied to the user 

529 

530 """ 

531 return PlatformDirs( 

532 appname=appname, 

533 appauthor=appauthor, 

534 version=version, 

535 opinion=opinion, 

536 ensure_exists=ensure_exists, 

537 use_site_for_root=use_site_for_root, 

538 ).user_runtime_dir 

539 

540 

541def site_runtime_dir( 

542 appname: str | None = None, 

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

544 version: str | None = None, 

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

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

547) -> str: 

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

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

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

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

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

553 

554 :returns: runtime directory shared by users 

555 

556 """ 

557 return PlatformDirs( 

558 appname=appname, 

559 appauthor=appauthor, 

560 version=version, 

561 opinion=opinion, 

562 ensure_exists=ensure_exists, 

563 ).site_runtime_dir 

564 

565 

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

567 appname: str | None = None, 

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

569 version: str | None = None, 

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

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

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

573) -> Path: 

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

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

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

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

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

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

580 

581 :returns: data path tied to the user 

582 

583 """ 

584 return PlatformDirs( 

585 appname=appname, 

586 appauthor=appauthor, 

587 version=version, 

588 roaming=roaming, 

589 ensure_exists=ensure_exists, 

590 use_site_for_root=use_site_for_root, 

591 ).user_data_path 

592 

593 

594def site_data_path( 

595 appname: str | None = None, 

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

597 version: str | None = None, 

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

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

600) -> Path: 

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

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

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

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

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

606 

607 :returns: data path shared by users 

608 

609 """ 

610 return PlatformDirs( 

611 appname=appname, 

612 appauthor=appauthor, 

613 version=version, 

614 multipath=multipath, 

615 ensure_exists=ensure_exists, 

616 ).site_data_path 

617 

618 

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

620 appname: str | None = None, 

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

622 version: str | None = None, 

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

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

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

626) -> Path: 

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

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

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

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

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

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

633 

634 :returns: config path tied to the user 

635 

636 """ 

637 return PlatformDirs( 

638 appname=appname, 

639 appauthor=appauthor, 

640 version=version, 

641 roaming=roaming, 

642 ensure_exists=ensure_exists, 

643 use_site_for_root=use_site_for_root, 

644 ).user_config_path 

645 

646 

647def site_config_path( 

648 appname: str | None = None, 

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

650 version: str | None = None, 

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

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

653) -> Path: 

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

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

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

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

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

659 

660 :returns: config path shared by users 

661 

662 """ 

663 return PlatformDirs( 

664 appname=appname, 

665 appauthor=appauthor, 

666 version=version, 

667 multipath=multipath, 

668 ensure_exists=ensure_exists, 

669 ).site_config_path 

670 

671 

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

673 appname: str | None = None, 

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

675 version: str | None = None, 

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

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

678 *, 

679 multipath: bool = False, 

680) -> Path: 

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

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

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

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

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

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

687 

688 :returns: cache path shared by users 

689 

690 """ 

691 return PlatformDirs( 

692 appname=appname, 

693 appauthor=appauthor, 

694 version=version, 

695 multipath=multipath, 

696 opinion=opinion, 

697 ensure_exists=ensure_exists, 

698 ).site_cache_path 

699 

700 

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

702 appname: str | None = None, 

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

704 version: str | None = None, 

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

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

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

708) -> Path: 

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

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

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

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

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

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

715 

716 :returns: cache path tied to the user 

717 

718 """ 

719 return PlatformDirs( 

720 appname=appname, 

721 appauthor=appauthor, 

722 version=version, 

723 opinion=opinion, 

724 ensure_exists=ensure_exists, 

725 use_site_for_root=use_site_for_root, 

726 ).user_cache_path 

727 

728 

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

730 appname: str | None = None, 

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

732 version: str | None = None, 

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

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

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

736) -> Path: 

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

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

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

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

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

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

743 

744 :returns: state path tied to the user 

745 

746 """ 

747 return PlatformDirs( 

748 appname=appname, 

749 appauthor=appauthor, 

750 version=version, 

751 roaming=roaming, 

752 ensure_exists=ensure_exists, 

753 use_site_for_root=use_site_for_root, 

754 ).user_state_path 

755 

756 

757def site_state_path( 

758 appname: str | None = None, 

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

760 version: str | None = None, 

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

762) -> Path: 

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

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

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

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

767 

768 :returns: state path shared by users 

769 

770 """ 

771 return PlatformDirs( 

772 appname=appname, 

773 appauthor=appauthor, 

774 version=version, 

775 ensure_exists=ensure_exists, 

776 ).site_state_path 

777 

778 

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

780 appname: str | None = None, 

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

782 version: str | None = None, 

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

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

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

786 *, 

787 roaming: bool = False, 

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 :param use_site_for_root: See `use_site_for_root <platformdirs.api.PlatformDirsABC.use_site_for_root>`. 

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

796 

797 :returns: log path tied to the user 

798 

799 """ 

800 return PlatformDirs( 

801 appname=appname, 

802 appauthor=appauthor, 

803 version=version, 

804 roaming=roaming, 

805 opinion=opinion, 

806 ensure_exists=ensure_exists, 

807 use_site_for_root=use_site_for_root, 

808 ).user_log_path 

809 

810 

811def site_log_path( 

812 appname: str | None = None, 

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

814 version: str | None = None, 

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

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

817) -> Path: 

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

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

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

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

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

823 

824 :returns: log path shared by users 

825 

826 """ 

827 return PlatformDirs( 

828 appname=appname, 

829 appauthor=appauthor, 

830 version=version, 

831 opinion=opinion, 

832 ensure_exists=ensure_exists, 

833 ).site_log_path 

834 

835 

836def user_documents_path(*, ensure_exists: bool = False) -> Path: 

837 """:param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`. 

838 

839 :returns: documents path tied to the user 

840 

841 """ 

842 return PlatformDirs(ensure_exists=ensure_exists).user_documents_path 

843 

844 

845def user_downloads_path(*, ensure_exists: bool = False) -> Path: 

846 """:param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`. 

847 

848 :returns: downloads path tied to the user 

849 

850 """ 

851 return PlatformDirs(ensure_exists=ensure_exists).user_downloads_path 

852 

853 

854def user_pictures_path(*, ensure_exists: bool = False) -> Path: 

855 """:param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`. 

856 

857 :returns: pictures path tied to the user 

858 

859 """ 

860 return PlatformDirs(ensure_exists=ensure_exists).user_pictures_path 

861 

862 

863def user_videos_path(*, ensure_exists: bool = False) -> Path: 

864 """:param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`. 

865 

866 :returns: videos path tied to the user 

867 

868 """ 

869 return PlatformDirs(ensure_exists=ensure_exists).user_videos_path 

870 

871 

872def user_music_path(*, ensure_exists: bool = False) -> Path: 

873 """:param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`. 

874 

875 :returns: music path tied to the user 

876 

877 """ 

878 return PlatformDirs(ensure_exists=ensure_exists).user_music_path 

879 

880 

881def user_desktop_path(*, ensure_exists: bool = False) -> Path: 

882 """:param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`. 

883 

884 :returns: desktop path tied to the user 

885 

886 """ 

887 return PlatformDirs(ensure_exists=ensure_exists).user_desktop_path 

888 

889 

890def user_projects_path(*, ensure_exists: bool = False) -> Path: 

891 """:param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`. 

892 

893 :returns: projects path tied to the user 

894 

895 """ 

896 return PlatformDirs(ensure_exists=ensure_exists).user_projects_path 

897 

898 

899def user_publicshare_path(*, ensure_exists: bool = False) -> Path: 

900 """:param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`. 

901 

902 :returns: public share path tied to the user 

903 

904 """ 

905 return PlatformDirs(ensure_exists=ensure_exists).user_publicshare_path 

906 

907 

908def user_templates_path(*, ensure_exists: bool = False) -> Path: 

909 """:param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`. 

910 

911 :returns: templates path tied to the user 

912 

913 """ 

914 return PlatformDirs(ensure_exists=ensure_exists).user_templates_path 

915 

916 

917def user_fonts_path() -> Path: 

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

919 return PlatformDirs().user_fonts_path 

920 

921 

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

923 appname: str | None = None, 

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

925 version: str | None = None, 

926 *, 

927 roaming: bool = False, 

928 ensure_exists: bool = False, 

929 use_site_for_root: bool = False, 

930) -> Path: 

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

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

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

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

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

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

937 

938 :returns: preference path tied to the user 

939 

940 """ 

941 return PlatformDirs( 

942 appname=appname, 

943 appauthor=appauthor, 

944 version=version, 

945 roaming=roaming, 

946 ensure_exists=ensure_exists, 

947 use_site_for_root=use_site_for_root, 

948 ).user_preference_path 

949 

950 

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

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

953 

954 :returns: bin path tied to the user 

955 

956 """ 

957 return PlatformDirs(use_site_for_root=use_site_for_root).user_bin_path 

958 

959 

960def site_bin_path() -> Path: 

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

962 return PlatformDirs().site_bin_path 

963 

964 

965def user_applications_path( 

966 appname: str | None = None, 

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

968 version: str | None = None,