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

1"""Base API.""" 

2from __future__ import annotations 

3 

4import os 

5from abc import ABC, abstractmethod 

6from pathlib import Path 

7from typing import TYPE_CHECKING 

8 

9if TYPE_CHECKING: 

10 from typing import Literal 

11 

12 

13class PlatformDirsABC(ABC): 

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

15 

16 def __init__( # noqa: PLR0913 

17 self, 

18 appname: str | None = None, 

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

20 version: str | None = None, 

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

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

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

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

25 ) -> None: 

26 """ 

27 Create a new platform directory. 

28 

29 :param appname: See `appname`. 

30 :param appauthor: See `appauthor`. 

31 :param version: See `version`. 

32 :param roaming: See `roaming`. 

33 :param multipath: See `multipath`. 

34 :param opinion: See `opinion`. 

35 :param ensure_exists: See `ensure_exists`. 

36 """ 

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

38 self.appauthor = appauthor 

39 """ 

40 The name of the app author or distributing body for this application. Typically, it is the owning company name. 

41 Defaults to `appname`. You may pass ``False`` to disable it. 

42 """ 

43 self.version = version 

44 """ 

45 An optional version path element to append to the path. You might want to use this if you want multiple versions 

46 of your app to be able to run independently. If used, this would typically be ``<major>.<minor>``. 

47 """ 

48 self.roaming = roaming 

49 """ 

50 Whether to use the roaming appdata directory on Windows. That means that for users on a Windows network setup 

51 for roaming profiles, this user data will be synced on login (see 

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

53 """ 

54 self.multipath = multipath 

55 """ 

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

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

58 """ 

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

60 self.ensure_exists = ensure_exists 

61 """ 

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

63 By default, no directories are created. 

64 """ 

65 

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

67 params = list(base[1:]) 

68 if self.appname: 

69 params.append(self.appname) 

70 if self.version: 

71 params.append(self.version) 

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

73 self._optionally_create_directory(path) 

74 return path 

75 

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

77 if self.ensure_exists: 

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

79 

80 @property 

81 @abstractmethod 

82 def user_data_dir(self) -> str: 

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

84 

85 @property 

86 @abstractmethod 

87 def site_data_dir(self) -> str: 

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

89 

90 @property 

91 @abstractmethod 

92 def user_config_dir(self) -> str: 

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

94 

95 @property 

96 @abstractmethod 

97 def site_config_dir(self) -> str: 

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

99 

100 @property 

101 @abstractmethod 

102 def user_cache_dir(self) -> str: 

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

104 

105 @property 

106 @abstractmethod 

107 def site_cache_dir(self) -> str: 

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

109 

110 @property 

111 @abstractmethod 

112 def user_state_dir(self) -> str: 

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

114 

115 @property 

116 @abstractmethod 

117 def user_log_dir(self) -> str: 

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

119 

120 @property 

121 @abstractmethod 

122 def user_documents_dir(self) -> str: 

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

124 

125 @property 

126 @abstractmethod 

127 def user_downloads_dir(self) -> str: 

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

129 

130 @property 

131 @abstractmethod 

132 def user_pictures_dir(self) -> str: 

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

134 

135 @property 

136 @abstractmethod 

137 def user_videos_dir(self) -> str: 

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

139 

140 @property 

141 @abstractmethod 

142 def user_music_dir(self) -> str: 

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

144 

145 @property 

146 @abstractmethod 

147 def user_desktop_dir(self) -> str: 

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

149 

150 @property 

151 @abstractmethod 

152 def user_runtime_dir(self) -> str: 

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

154 

155 @property 

156 @abstractmethod 

157 def site_runtime_dir(self) -> str: 

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

159 

160 @property 

161 def user_data_path(self) -> Path: 

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

163 return Path(self.user_data_dir) 

164 

165 @property 

166 def site_data_path(self) -> Path: 

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

168 return Path(self.site_data_dir) 

169 

170 @property 

171 def user_config_path(self) -> Path: 

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

173 return Path(self.user_config_dir) 

174 

175 @property 

176 def site_config_path(self) -> Path: 

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

178 return Path(self.site_config_dir) 

179 

180 @property 

181 def user_cache_path(self) -> Path: 

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

183 return Path(self.user_cache_dir) 

184 

185 @property 

186 def site_cache_path(self) -> Path: 

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

188 return Path(self.site_cache_dir) 

189 

190 @property 

191 def user_state_path(self) -> Path: 

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

193 return Path(self.user_state_dir) 

194 

195 @property 

196 def user_log_path(self) -> Path: 

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

198 return Path(self.user_log_dir) 

199 

200 @property 

201 def user_documents_path(self) -> Path: 

202 """:return: documents path tied to the user""" 

203 return Path(self.user_documents_dir) 

204 

205 @property 

206 def user_downloads_path(self) -> Path: 

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

208 return Path(self.user_downloads_dir) 

209 

210 @property 

211 def user_pictures_path(self) -> Path: 

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

213 return Path(self.user_pictures_dir) 

214 

215 @property 

216 def user_videos_path(self) -> Path: 

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

218 return Path(self.user_videos_dir) 

219 

220 @property 

221 def user_music_path(self) -> Path: 

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

223 return Path(self.user_music_dir) 

224 

225 @property 

226 def user_desktop_path(self) -> Path: 

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

228 return Path(self.user_desktop_dir) 

229 

230 @property 

231 def user_runtime_path(self) -> Path: 

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

233 return Path(self.user_runtime_dir) 

234 

235 @property 

236 def site_runtime_path(self) -> Path: 

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

238 return Path(self.site_runtime_dir)