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

1from __future__ import annotations 

2 

3import os 

4import sys 

5from abc import ABC, abstractmethod 

6from pathlib import Path 

7 

8if sys.version_info >= (3, 8): # pragma: no branch 

9 from typing import Literal # pragma: no cover 

10 

11 

12class PlatformDirsABC(ABC): 

13 """ 

14 Abstract base class for platform directories. 

15 """ 

16 

17 def __init__( 

18 self, 

19 appname: str | None = None, 

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

21 version: str | None = None, 

22 roaming: bool = False, 

23 multipath: bool = False, 

24 opinion: bool = True, 

25 ensure_exists: bool = False, 

26 ): 

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 self.appname = appname #: The name of application. 

39 self.appauthor = appauthor 

40 """ 

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

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

43 """ 

44 self.version = version 

45 """ 

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

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

48 """ 

49 self.roaming = roaming 

50 """ 

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

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

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

54 """ 

55 self.multipath = multipath 

56 """ 

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

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

59 """ 

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

61 self.ensure_exists = ensure_exists 

62 """ 

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

64 By default, no directories are created. 

65 """ 

66 

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

68 params = list(base[1:]) 

69 if self.appname: 

70 params.append(self.appname) 

71 if self.version: 

72 params.append(self.version) 

73 path = os.path.join(base[0], *params) 

74 self._optionally_create_directory(path) 

75 return path 

76 

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

78 if self.ensure_exists: 

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

80 

81 @property 

82 @abstractmethod 

83 def user_data_dir(self) -> str: 

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

85 

86 @property 

87 @abstractmethod 

88 def site_data_dir(self) -> str: 

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

90 

91 @property 

92 @abstractmethod 

93 def user_config_dir(self) -> str: 

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

95 

96 @property 

97 @abstractmethod 

98 def site_config_dir(self) -> str: 

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

100 

101 @property 

102 @abstractmethod 

103 def user_cache_dir(self) -> str: 

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

105 

106 @property 

107 @abstractmethod 

108 def site_cache_dir(self) -> str: 

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

110 

111 @property 

112 @abstractmethod 

113 def user_state_dir(self) -> str: 

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

115 

116 @property 

117 @abstractmethod 

118 def user_log_dir(self) -> str: 

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

120 

121 @property 

122 @abstractmethod 

123 def user_documents_dir(self) -> str: 

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

125 

126 @property 

127 @abstractmethod 

128 def user_runtime_dir(self) -> str: 

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

130 

131 @property 

132 def user_data_path(self) -> Path: 

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

134 return Path(self.user_data_dir) 

135 

136 @property 

137 def site_data_path(self) -> Path: 

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

139 return Path(self.site_data_dir) 

140 

141 @property 

142 def user_config_path(self) -> Path: 

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

144 return Path(self.user_config_dir) 

145 

146 @property 

147 def site_config_path(self) -> Path: 

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

149 return Path(self.site_config_dir) 

150 

151 @property 

152 def user_cache_path(self) -> Path: 

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

154 return Path(self.user_cache_dir) 

155 

156 @property 

157 def site_cache_path(self) -> Path: 

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

159 return Path(self.site_cache_dir) 

160 

161 @property 

162 def user_state_path(self) -> Path: 

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

164 return Path(self.user_state_dir) 

165 

166 @property 

167 def user_log_path(self) -> Path: 

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

169 return Path(self.user_log_dir) 

170 

171 @property 

172 def user_documents_path(self) -> Path: 

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

174 return Path(self.user_documents_dir) 

175 

176 @property 

177 def user_runtime_path(self) -> Path: 

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

179 return Path(self.user_runtime_dir)