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

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 import sys 

11 

12 if sys.version_info >= (3, 8): # pragma: no cover (py38+) 

13 from typing import Literal 

14 else: # pragma: no cover (py38+) 

15 from typing_extensions import Literal 

16 

17 

18class PlatformDirsABC(ABC): 

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

20 

21 def __init__( # noqa: PLR0913 

22 self, 

23 appname: str | None = None, 

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

25 version: str | None = None, 

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

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

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

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

30 ) -> None: 

31 """ 

32 Create a new platform directory. 

33 

34 :param appname: See `appname`. 

35 :param appauthor: See `appauthor`. 

36 :param version: See `version`. 

37 :param roaming: See `roaming`. 

38 :param multipath: See `multipath`. 

39 :param opinion: See `opinion`. 

40 :param ensure_exists: See `ensure_exists`. 

41 """ 

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

43 self.appauthor = appauthor 

44 """ 

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

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

47 """ 

48 self.version = version 

49 """ 

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

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

52 """ 

53 self.roaming = roaming 

54 """ 

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

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

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

58 """ 

59 self.multipath = multipath 

60 """ 

61 An optional parameter only applicable to Unix/Linux which indicates that the entire list of data dirs should be 

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

63 """ 

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

65 self.ensure_exists = ensure_exists 

66 """ 

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

68 By default, no directories are created. 

69 """ 

70 

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

72 params = list(base[1:]) 

73 if self.appname: 

74 params.append(self.appname) 

75 if self.version: 

76 params.append(self.version) 

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

78 self._optionally_create_directory(path) 

79 return path 

80 

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

82 if self.ensure_exists: 

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

84 

85 @property 

86 @abstractmethod 

87 def user_data_dir(self) -> str: 

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

89 

90 @property 

91 @abstractmethod 

92 def site_data_dir(self) -> str: 

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

94 

95 @property 

96 @abstractmethod 

97 def user_config_dir(self) -> str: 

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

99 

100 @property 

101 @abstractmethod 

102 def site_config_dir(self) -> str: 

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

104 

105 @property 

106 @abstractmethod 

107 def user_cache_dir(self) -> str: 

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

109 

110 @property 

111 @abstractmethod 

112 def site_cache_dir(self) -> str: 

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

114 

115 @property 

116 @abstractmethod 

117 def user_state_dir(self) -> str: 

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

119 

120 @property 

121 @abstractmethod 

122 def user_log_dir(self) -> str: 

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

124 

125 @property 

126 @abstractmethod 

127 def user_documents_dir(self) -> str: 

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

129 

130 @property 

131 @abstractmethod 

132 def user_downloads_dir(self) -> str: 

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

134 

135 @property 

136 @abstractmethod 

137 def user_pictures_dir(self) -> str: 

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

139 

140 @property 

141 @abstractmethod 

142 def user_videos_dir(self) -> str: 

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

144 

145 @property 

146 @abstractmethod 

147 def user_music_dir(self) -> str: 

148 """:return: music 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 def user_data_path(self) -> Path: 

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

158 return Path(self.user_data_dir) 

159 

160 @property 

161 def site_data_path(self) -> Path: 

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

163 return Path(self.site_data_dir) 

164 

165 @property 

166 def user_config_path(self) -> Path: 

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

168 return Path(self.user_config_dir) 

169 

170 @property 

171 def site_config_path(self) -> Path: 

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

173 return Path(self.site_config_dir) 

174 

175 @property 

176 def user_cache_path(self) -> Path: 

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

178 return Path(self.user_cache_dir) 

179 

180 @property 

181 def site_cache_path(self) -> Path: 

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

183 return Path(self.site_cache_dir) 

184 

185 @property 

186 def user_state_path(self) -> Path: 

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

188 return Path(self.user_state_dir) 

189 

190 @property 

191 def user_log_path(self) -> Path: 

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

193 return Path(self.user_log_dir) 

194 

195 @property 

196 def user_documents_path(self) -> Path: 

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

198 return Path(self.user_documents_dir) 

199 

200 @property 

201 def user_downloads_path(self) -> Path: 

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

203 return Path(self.user_downloads_dir) 

204 

205 @property 

206 def user_pictures_path(self) -> Path: 

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

208 return Path(self.user_pictures_dir) 

209 

210 @property 

211 def user_videos_path(self) -> Path: 

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

213 return Path(self.user_videos_dir) 

214 

215 @property 

216 def user_music_path(self) -> Path: 

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

218 return Path(self.user_music_dir) 

219 

220 @property 

221 def user_runtime_path(self) -> Path: 

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

223 return Path(self.user_runtime_dir)