Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/platformdirs/api.py: 66%

1"""Base API.""" 

2 

3from __future__ import annotations 

4 

5import os 

6from abc import ABC, abstractmethod 

7from pathlib import Path 

8from typing import TYPE_CHECKING 

9 

10if TYPE_CHECKING: 

11 from typing import Iterator, Literal 

12 

13 

14class PlatformDirsABC(ABC): # noqa: PLR0904 

15 """Abstract base class for platform directories.""" 

16 

17 def __init__( # noqa: PLR0913, PLR0917 

18 self, 

19 appname: str | None = None, 

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

21 version: str | None = None, 

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

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

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

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

26 ) -> None: 

27 """ 

28 Create a new platform directory. 

29 

30 :param appname: See `appname`. 

31 :param appauthor: See `appauthor`. 

32 :param version: See `version`. 

33 :param roaming: See `roaming`. 

34 :param multipath: See `multipath`. 

35 :param opinion: See `opinion`. 

36 :param ensure_exists: See `ensure_exists`. 

37 

38 """ 

39 self.appname = appname #: The name of application. 

40 self.appauthor = appauthor 

41 """ 

42 The name of the app author or distributing body for this application. 

43 

44 Typically, it is the owning company name. Defaults to `appname`. You may pass ``False`` to disable it. 

45 

46 """ 

47 self.version = version 

48 """ 

49 An optional version path element to append to the path. 

50 

51 You might want to use this if you want multiple versions of your app to be able to run independently. If used, 

52 this would typically be ``<major>.<minor>``. 

53 

54 """ 

55 self.roaming = roaming 

56 """ 

57 Whether to use the roaming appdata directory on Windows. 

58 

59 That means that for users on a Windows network setup for roaming profiles, this user data will be synced on 

60 login (see 

61 `here <https://technet.microsoft.com/en-us/library/cc766489(WS.10).aspx>`_). 

62 

63 """ 

64 self.multipath = multipath 

65 """ 

66 An optional parameter which indicates that the entire list of data dirs should be returned. 

67 

68 By default, the first item would only be returned. 

69 

70 """ 

71 self.opinion = opinion #: A flag to indicating to use opinionated values. 

72 self.ensure_exists = ensure_exists 

73 """ 

74 Optionally create the directory (and any missing parents) upon access if it does not exist. 

75 

76 By default, no directories are created. 

77 

78 """ 

79 

80 def _append_app_name_and_version(self, *base: str) -> str: 

81 params = list(base[1:]) 

82 if self.appname: 

83 params.append(self.appname) 

84 if self.version: 

85 params.append(self.version) 

86 path = os.path.join(base[0], *params) # noqa: PTH118 

87 self._optionally_create_directory(path) 

88 return path 

89 

90 def _optionally_create_directory(self, path: str) -> None: 

91 if self.ensure_exists: 

92 Path(path).mkdir(parents=True, exist_ok=True) 

93 

94 @property 

95 @abstractmethod 

96 def user_data_dir(self) -> str: 

97 """:return: data directory tied to the user""" 

98 

99 @property 

100 @abstractmethod 

101 def site_data_dir(self) -> str: 

102 """:return: data directory shared by users""" 

103 

104 @property 

105 @abstractmethod 

106 def user_config_dir(self) -> str: 

107 """:return: config directory tied to the user""" 

108 

109 @property 

110 @abstractmethod 

111 def site_config_dir(self) -> str: 

112 """:return: config directory shared by the users""" 

113 

114 @property 

115 @abstractmethod 

116 def user_cache_dir(self) -> str: 

117 """:return: cache directory tied to the user""" 

118 

119 @property 

120 @abstractmethod 

121 def site_cache_dir(self) -> str: 

122 """:return: cache directory shared by users""" 

123 

124 @property 

125 @abstractmethod 

126 def user_state_dir(self) -> str: 

127 """:return: state directory tied to the user""" 

128 

129 @property 

130 @abstractmethod 

131 def user_log_dir(self) -> str: 

132 """:return: log directory tied to the user""" 

133 

134 @property 

135 @abstractmethod 

136 def user_documents_dir(self) -> str: 

137 """:return: documents directory tied to the user""" 

138 

139 @property 

140 @abstractmethod 

141 def user_downloads_dir(self) -> str: 

142 """:return: downloads directory tied to the user""" 

143 

144 @property 

145 @abstractmethod 

146 def user_pictures_dir(self) -> str: 

147 """:return: pictures directory tied to the user""" 

148 

149 @property 

150 @abstractmethod 

151 def user_videos_dir(self) -> str: 

152 """:return: videos directory tied to the user""" 

153 

154 @property 

155 @abstractmethod 

156 def user_music_dir(self) -> str: 

157 """:return: music directory tied to the user""" 

158 

159 @property 

160 @abstractmethod 

161 def user_desktop_dir(self) -> str: 

162 """:return: desktop directory tied to the user""" 

163 

164 @property 

165 @abstractmethod 

166 def user_runtime_dir(self) -> str: 

167 """:return: runtime directory tied to the user""" 

168 

169 @property 

170 @abstractmethod 

171 def site_runtime_dir(self) -> str: 

172 """:return: runtime directory shared by users""" 

173 

174 @property 

175 def user_data_path(self) -> Path: 

176 """:return: data path tied to the user""" 

177 return Path(self.user_data_dir) 

178 

179 @property 

180 def site_data_path(self) -> Path: 

181 """:return: data path shared by users""" 

182 return Path(self.site_data_dir) 

183 

184 @property 

185 def user_config_path(self) -> Path: 

186 """:return: config path tied to the user""" 

187 return Path(self.user_config_dir) 

188 

189 @property 

190 def site_config_path(self) -> Path: 

191 """:return: config path shared by the users""" 

192 return Path(self.site_config_dir) 

193 

194 @property 

195 def user_cache_path(self) -> Path: 

196 """:return: cache path tied to the user""" 

197 return Path(self.user_cache_dir) 

198 

199 @property 

200 def site_cache_path(self) -> Path: 

201 """:return: cache path shared by users""" 

202 return Path(self.site_cache_dir) 

203 

204 @property 

205 def user_state_path(self) -> Path: 

206 """:return: state path tied to the user""" 

207 return Path(self.user_state_dir) 

208 

209 @property 

210 def user_log_path(self) -> Path: 

211 """:return: log path tied to the user""" 

212 return Path(self.user_log_dir) 

213 

214 @property 

215 def user_documents_path(self) -> Path: 

216 """:return: documents a path tied to the user""" 

217 return Path(self.user_documents_dir) 

218 

219 @property 

220 def user_downloads_path(self) -> Path: 

221 """:return: downloads path tied to the user""" 

222 return Path(self.user_downloads_dir) 

223 

224 @property 

225 def user_pictures_path(self) -> Path: 

226 """:return: pictures path tied to the user""" 

227 return Path(self.user_pictures_dir) 

228 

229 @property 

230 def user_videos_path(self) -> Path: 

231 """:return: videos path tied to the user""" 

232 return Path(self.user_videos_dir) 

233 

234 @property 

235 def user_music_path(self) -> Path: 

236 """:return: music path tied to the user""" 

237 return Path(self.user_music_dir) 

238 

239 @property 

240 def user_desktop_path(self) -> Path: 

241 """:return: desktop path tied to the user""" 

242 return Path(self.user_desktop_dir) 

243 

244 @property 

245 def user_runtime_path(self) -> Path: 

246 """:return: runtime path tied to the user""" 

247 return Path(self.user_runtime_dir) 

248 

249 @property 

250 def site_runtime_path(self) -> Path: 

251 """:return: runtime path shared by users""" 

252 return Path(self.site_runtime_dir) 

253 

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

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

256 yield self.user_config_dir 

257 yield self.site_config_dir 

258 

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

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

261 yield self.user_data_dir 

262 yield self.site_data_dir 

263 

264 def iter_cache_dirs(self) -> Iterator[str]: 

265 """:yield: all user and site cache directories.""" 

266 yield self.user_cache_dir 

267 yield self.site_cache_dir 

268 

269 def iter_runtime_dirs(self) -> Iterator[str]: 

270 """:yield: all user and site runtime directories.""" 

271 yield self.user_runtime_dir 

272 yield self.site_runtime_dir 

273 

274 def iter_config_paths(self) -> Iterator[Path]: 

275 """:yield: all user and site configuration paths.""" 

276 for path in self.iter_config_dirs(): 

277 yield Path(path) 

278 

279 def iter_data_paths(self) -> Iterator[Path]: 

280 """:yield: all user and site data paths.""" 

281 for path in self.iter_data_dirs(): 

282 yield Path(path) 

283 

284 def iter_cache_paths(self) -> Iterator[Path]: 

285 """:yield: all user and site cache paths.""" 

286 for path in self.iter_cache_dirs(): 

287 yield Path(path) 

288 

289 def iter_runtime_paths(self) -> Iterator[Path]: 

290 """:yield: all user and site runtime paths.""" 

291 for path in self.iter_runtime_dirs(): 

292 yield Path(path)