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

1"""Unix.""" 

2 

3from __future__ import annotations 

4 

5import os 

6import sys 

7from configparser import ConfigParser 

8from functools import cached_property 

9from pathlib import Path 

10from tempfile import gettempdir 

11from typing import TYPE_CHECKING, NoReturn 

12 

13from ._xdg import XDGMixin 

14from .api import PlatformDirsABC 

15 

16if TYPE_CHECKING: 

17 from collections.abc import Iterator 

18 

19if sys.platform == "win32": 

20 

21 def getuid() -> NoReturn: 

22 msg = "should only be used on Unix" 

23 raise RuntimeError(msg) 

24 

25else: 

26 from os import getuid 

27 

28 

29class _UnixDefaults(PlatformDirsABC): # noqa: PLR0904 

30 """Default directories for Unix/Linux without XDG environment variable overrides. 

31 

32 The XDG env var handling is in :class:`~platformdirs._xdg.XDGMixin`. 

33 

34 """ 

35 

36 @cached_property 

37 def _use_site(self) -> bool: 

38 return self.use_site_for_root and getuid() == 0 

39 

40 @property 

41 def user_data_dir(self) -> str: 

42 """:returns: data directory tied to the user, e.g. ``~/.local/share/$appname/$version`` or ``$XDG_DATA_HOME/$appname/$version``""" 

43 return self._append_app_name_and_version(os.path.expanduser("~/.local/share")) # noqa: PTH111 

44 

45 @property 

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

47 return [self._append_app_name_and_version("/usr/local/share"), self._append_app_name_and_version("/usr/share")] 

48 

49 @property 

50 def user_config_dir(self) -> str: 

51 """:returns: config directory tied to the user, e.g. ``~/.config/$appname/$version`` or ``$XDG_CONFIG_HOME/$appname/$version``""" 

52 return self._append_app_name_and_version(os.path.expanduser("~/.config")) # noqa: PTH111 

53 

54 @property 

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

56 return [self._append_app_name_and_version("/etc/xdg")] 

57 

58 @property 

59 def user_cache_dir(self) -> str: 

60 """:returns: cache directory tied to the user, e.g. ``~/.cache/$appname/$version`` or ``$XDG_CACHE_HOME/$appname/$version``""" 

61 return self._append_app_name_and_version(os.path.expanduser("~/.cache")) # noqa: PTH111 

62 

63 @property 

64 def site_cache_dir(self) -> str: 

65 """:returns: cache directory shared by users, e.g. ``/var/cache/$appname/$version``""" 

66 return self._append_app_name_and_version("/var/cache") 

67 

68 @property 

69 def user_state_dir(self) -> str: 

70 """:returns: state directory tied to the user, e.g. ``~/.local/state/$appname/$version`` or ``$XDG_STATE_HOME/$appname/$version``""" 

71 return self._append_app_name_and_version(os.path.expanduser("~/.local/state")) # noqa: PTH111 

72 

73 @property 

74 def site_state_dir(self) -> str: 

75 """:returns: state directory shared by users, e.g. ``/var/lib/$appname/$version``""" 

76 return self._append_app_name_and_version("/var/lib") 

77 

78 @property 

79 def user_log_dir(self) -> str: 

80 """:returns: log directory tied to the user, same as `user_state_dir` if not opinionated else ``log`` in it""" 

81 path = self.user_state_dir 

82 if self.opinion: 

83 path = os.path.join(path, "log") # noqa: PTH118 

84 self._optionally_create_directory(path) 

85 return path 

86 

87 @property 

88 def site_log_dir(self) -> str: 

89 """:returns: log directory shared by users, e.g. ``/var/log/$appname/$version`` 

90 

91 Unlike `user_log_dir`, ``opinion`` has no effect since ``/var/log`` is inherently a log directory. 

92 

93 """ 

94 return self._append_app_name_and_version("/var/log") 

95 

96 @property 

97 def user_documents_dir(self) -> str: 

98 """:returns: documents directory tied to the user, e.g. ``~/Documents``""" 

99 return _get_user_media_dir("XDG_DOCUMENTS_DIR", "~/Documents") 

100 

101 @property 

102 def user_downloads_dir(self) -> str: 

103 """:returns: downloads directory tied to the user, e.g. ``~/Downloads``""" 

104 return _get_user_media_dir("XDG_DOWNLOAD_DIR", "~/Downloads") 

105 

106 @property 

107 def user_pictures_dir(self) -> str: 

108 """:returns: pictures directory tied to the user, e.g. ``~/Pictures``""" 

109 return _get_user_media_dir("XDG_PICTURES_DIR", "~/Pictures") 

110 

111 @property 

112 def user_videos_dir(self) -> str: 

113 """:returns: videos directory tied to the user, e.g. ``~/Videos``""" 

114 return _get_user_media_dir("XDG_VIDEOS_DIR", "~/Videos") 

115 

116 @property 

117 def user_music_dir(self) -> str: 

118 """:returns: music directory tied to the user, e.g. ``~/Music``""" 

119 return _get_user_media_dir("XDG_MUSIC_DIR", "~/Music") 

120 

121 @property 

122 def user_desktop_dir(self) -> str: 

123 """:returns: desktop directory tied to the user, e.g. ``~/Desktop``""" 

124 return _get_user_media_dir("XDG_DESKTOP_DIR", "~/Desktop") 

125 

126 @property 

127 def user_bin_dir(self) -> str: 

128 """:returns: bin directory tied to the user, e.g. ``~/.local/bin``""" 

129 return os.path.expanduser("~/.local/bin") # noqa: PTH111 

130 

131 @property 

132 def site_bin_dir(self) -> str: 

133 """:returns: bin directory shared by users, e.g. ``/usr/local/bin``""" 

134 return "/usr/local/bin" 

135 

136 @property 

137 def user_applications_dir(self) -> str: 

138 """:returns: applications directory tied to the user, e.g. ``~/.local/share/applications``""" 

139 return os.path.join(os.path.expanduser("~/.local/share"), "applications") # noqa: PTH111, PTH118 

140 

141 @property 

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

143 return [os.path.join(p, "applications") for p in ["/usr/local/share", "/usr/share"]] # noqa: PTH118 

144 

145 @property 

146 def site_applications_dir(self) -> str: 

147 """:returns: applications directory shared by users, e.g. ``/usr/share/applications``""" 

148 dirs = self._site_applications_dirs 

149 return os.pathsep.join(dirs) if self.multipath else dirs[0] 

150 

151 @property 

152 def user_runtime_dir(self) -> str: 

153 """:returns: runtime directory tied to the user, e.g. ``$XDG_RUNTIME_DIR/$appname/$version``. 

154 

155 If ``$XDG_RUNTIME_DIR`` is unset, tries the platform default (``/tmp/run/user/$(id -u)`` on OpenBSD, ``/var/run/user/$(id -u)`` on FreeBSD/NetBSD, ``/run/user/$(id -u)`` otherwise). If the default is not writable, falls back to a temporary directory. 

156 

157 """ 

158 if sys.platform.startswith("openbsd"): 

159 path = f"/tmp/run/user/{getuid()}" # noqa: S108 

160 elif sys.platform.startswith(("freebsd", "netbsd")): 

161 path = f"/var/run/user/{getuid()}" 

162 else: 

163 path = f"/run/user/{getuid()}" 

164 if not os.access(path, os.W_OK): 

165 path = f"{gettempdir()}/runtime-{getuid()}" 

166 return self._append_app_name_and_version(path) 

167 

168 @property 

169 def site_runtime_dir(self) -> str: 

170 """:returns: runtime directory shared by users, e.g. ``/run/$appname/$version`` or ``$XDG_RUNTIME_DIR/$appname/$version``. 

171 

172 Note that this behaves almost exactly like `user_runtime_dir` if ``$XDG_RUNTIME_DIR`` is set, but will fall back to paths associated to the root user instead of a regular logged-in user if it's not set. 

173 

174 If you wish to ensure that a logged-in root user path is returned e.g. ``/run/user/0``, use `user_runtime_dir` instead. 

175 

176 For FreeBSD/OpenBSD/NetBSD, it would return ``/var/run/$appname/$version`` if ``$XDG_RUNTIME_DIR`` is not set. 

177 

178 """ 

179 if sys.platform.startswith(("freebsd", "openbsd", "netbsd")): 

180 path = "/var/run" 

181 else: 

182 path = "/run" 

183 return self._append_app_name_and_version(path) 

184 

185 @property 

186 def site_data_path(self) -> Path: 

187 """:returns: data path shared by users. Only return the first item, even if ``multipath`` is set to ``True``""" 

188 return self._first_item_as_path_if_multipath(self.site_data_dir) 

189 

190 @property 

191 def site_config_path(self) -> Path: 

192 """:returns: config path shared by users, returns the first item, even if ``multipath`` is set to ``True``""" 

193 return self._first_item_as_path_if_multipath(self.site_config_dir) 

194 

195 @property 

196 def site_cache_path(self) -> Path: 

197 """:returns: cache path shared by users. Only return the first item, even if ``multipath`` is set to ``True``""" 

198 return self._first_item_as_path_if_multipath(self.site_cache_dir) 

199 

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

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

202 yield self.user_config_dir 

203 yield from self._site_config_dirs 

204 

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

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

207 yield self.user_data_dir 

208 yield from self._site_data_dirs 

209 

210 

211class Unix(XDGMixin, _UnixDefaults): 

212 """On Unix/Linux, we follow the `XDG Basedir Spec <https://specifications.freedesktop.org/basedir/latest/>`_. 

213 

214 The spec allows overriding directories with environment variables. The examples shown are the default values, 

215 alongside the name of the environment variable that overrides them. Makes use of the `appname 

216 <platformdirs.api.PlatformDirsABC.appname>`, `version <platformdirs.api.PlatformDirsABC.version>`, `multipath 

217 <platformdirs.api.PlatformDirsABC.multipath>`, `opinion <platformdirs.api.PlatformDirsABC.opinion>`, `ensure_exists 

218 <platformdirs.api.PlatformDirsABC.ensure_exists>`. 

219 

220 """ 

221 

222 @property 

223 def user_data_dir(self) -> str: 

224 """:returns: data directory tied to the user, or site equivalent when root with ``use_site_for_root``""" 

225 return self.site_data_dir if self._use_site else super().user_data_dir 

226 

227 @property 

228 def user_config_dir(self) -> str: 

229 """:returns: config directory tied to the user, or site equivalent when root with ``use_site_for_root``""" 

230 return self.site_config_dir if self._use_site else super().user_config_dir 

231 

232 @property 

233 def user_cache_dir(self) -> str: 

234 """:returns: cache directory tied to the user, or site equivalent when root with ``use_site_for_root``""" 

235 return self.site_cache_dir if self._use_site else super().user_cache_dir 

236 

237 @property 

238 def user_state_dir(self) -> str: 

239 """:returns: state directory tied to the user, or site equivalent when root with ``use_site_for_root``""" 

240 return self.site_state_dir if self._use_site else super().user_state_dir 

241 

242 @property 

243 def user_log_dir(self) -> str: 

244 """:returns: log directory tied to the user, or site equivalent when root with ``use_site_for_root``""" 

245 return self.site_log_dir if self._use_site else super().user_log_dir 

246 

247 @property 

248 def user_applications_dir(self) -> str: 

249 """:returns: applications directory tied to the user, or site equivalent when root with ``use_site_for_root``""" 

250 return self.site_applications_dir if self._use_site else super().user_applications_dir 

251 

252 @property 

253 def user_runtime_dir(self) -> str: 

254 """:returns: runtime directory tied to the user, or site equivalent when root with ``use_site_for_root``""" 

255 return self.site_runtime_dir if self._use_site else super().user_runtime_dir 

256 

257 @property 

258 def user_bin_dir(self) -> str: 

259 """:returns: bin directory tied to the user, or site equivalent when root with ``use_site_for_root``""" 

260 return self.site_bin_dir if self._use_site else super().user_bin_dir 

261 

262 

263def _get_user_media_dir(env_var: str, fallback_tilde_path: str) -> str: 

264 if media_dir := _get_user_dirs_folder(env_var): 

265 return media_dir 

266 return os.path.expanduser(fallback_tilde_path) # noqa: PTH111 

267 

268 

269def _get_user_dirs_folder(key: str) -> str | None: 

270 """Return directory from user-dirs.dirs config file. 

271 

272 See https://freedesktop.org/wiki/Software/xdg-user-dirs/. 

273 

274 """ 

275 config_home = os.environ.get("XDG_CONFIG_HOME", "").strip() or os.path.expanduser("~/.config") # noqa: PTH111 

276 user_dirs_config_path = Path(config_home) / "user-dirs.dirs" 

277 if user_dirs_config_path.exists(): 

278 parser = ConfigParser() 

279 

280 with user_dirs_config_path.open() as stream: 

281 parser.read_string(f"[top]\n{stream.read()}") 

282 

283 if key not in parser["top"]: 

284 return None 

285 

286 path = parser["top"][key].strip('"') 

287 return path.replace("$HOME", os.path.expanduser("~")) # noqa: PTH111 

288 

289 return None 

290 

291 

292__all__ = [ 

293 "Unix", 

294]