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

1"""XDG environment variable mixin for Unix and macOS.""" 

2 

3from __future__ import annotations 

4 

5import os 

6import posixpath 

7from typing import Final 

8 

9from .api import PlatformDirsABC 

10 

11 

12class XDGMixin(PlatformDirsABC): 

13 """Mixin that checks XDG environment variables, falling back to platform-specific defaults via ``super()``.""" 

14 

15 @property 

16 def user_data_dir(self) -> str: 

17 """Data directory tied to the user, from ``$XDG_DATA_HOME`` if set, else platform default.""" 

18 if path := _xdg_dir("XDG_DATA_HOME"): 

19 return self._append_app_name_and_version(path) 

20 return super().user_data_dir 

21 

22 @property 

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

24 if xdg_dirs := _xdg_dir_list("XDG_DATA_DIRS"): 

25 return [self._append_app_name_and_version(p) for p in xdg_dirs] 

26 return super()._site_data_dirs 

27 

28 @property 

29 def site_data_dir(self) -> str: 

30 """Data directories shared by users, from ``$XDG_DATA_DIRS`` if set, else platform default.""" 

31 dirs = self._site_data_dirs 

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

33 

34 @property 

35 def user_config_dir(self) -> str: 

36 """Config directory tied to the user, from ``$XDG_CONFIG_HOME`` if set, else platform default.""" 

37 if path := _xdg_dir("XDG_CONFIG_HOME"): 

38 return self._append_app_name_and_version(path) 

39 return super().user_config_dir 

40 

41 @property 

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

43 if xdg_dirs := _xdg_dir_list("XDG_CONFIG_DIRS"): 

44 return [self._append_app_name_and_version(p) for p in xdg_dirs] 

45 return super()._site_config_dirs 

46 

47 @property 

48 def site_config_dir(self) -> str: 

49 """Config directories shared by users, from ``$XDG_CONFIG_DIRS`` if set, else platform default.""" 

50 dirs = self._site_config_dirs 

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

52 

53 @property 

54 def user_cache_dir(self) -> str: 

55 """Cache directory tied to the user, from ``$XDG_CACHE_HOME`` if set, else platform default.""" 

56 if path := _xdg_dir("XDG_CACHE_HOME"): 

57 return self._append_app_name_and_version(path) 

58 return super().user_cache_dir 

59 

60 @property 

61 def user_state_dir(self) -> str: 

62 """State directory tied to the user, from ``$XDG_STATE_HOME`` if set, else platform default.""" 

63 if path := _xdg_dir("XDG_STATE_HOME"): 

64 return self._append_app_name_and_version(path) 

65 return super().user_state_dir 

66 

67 @property 

68 def user_runtime_dir(self) -> str: 

69 """Runtime directory tied to the user, from ``$XDG_RUNTIME_DIR`` if set, else platform default.""" 

70 if path := _xdg_dir("XDG_RUNTIME_DIR"): 

71 return self._append_app_name_and_version(path) 

72 return super().user_runtime_dir 

73 

74 @property 

75 def site_runtime_dir(self) -> str: 

76 """Runtime directory shared by users, from ``$XDG_RUNTIME_DIR`` if set, else platform default.""" 

77 if path := _xdg_dir("XDG_RUNTIME_DIR"): 

78 return self._append_app_name_and_version(path) 

79 return super().site_runtime_dir 

80 

81 @property 

82 def user_documents_dir(self) -> str: 

83 """Documents directory tied to the user, from ``$XDG_DOCUMENTS_DIR`` if set, else platform default.""" 

84 if path := os.environ.get("XDG_DOCUMENTS_DIR", "").strip(): 

85 return os.path.expanduser(path) # ruff:ignore[os-path-expanduser] 

86 return super().user_documents_dir 

87 

88 @property 

89 def user_downloads_dir(self) -> str: 

90 """Downloads directory tied to the user, from ``$XDG_DOWNLOAD_DIR`` if set, else platform default.""" 

91 if path := os.environ.get("XDG_DOWNLOAD_DIR", "").strip(): 

92 return os.path.expanduser(path) # ruff:ignore[os-path-expanduser] 

93 return super().user_downloads_dir 

94 

95 @property 

96 def user_pictures_dir(self) -> str: 

97 """Pictures directory tied to the user, from ``$XDG_PICTURES_DIR`` if set, else platform default.""" 

98 if path := os.environ.get("XDG_PICTURES_DIR", "").strip(): 

99 return os.path.expanduser(path) # ruff:ignore[os-path-expanduser] 

100 return super().user_pictures_dir 

101 

102 @property 

103 def user_videos_dir(self) -> str: 

104 """Videos directory tied to the user, from ``$XDG_VIDEOS_DIR`` if set, else platform default.""" 

105 if path := os.environ.get("XDG_VIDEOS_DIR", "").strip(): 

106 return os.path.expanduser(path) # ruff:ignore[os-path-expanduser] 

107 return super().user_videos_dir 

108 

109 @property 

110 def user_music_dir(self) -> str: 

111 """Music directory tied to the user, from ``$XDG_MUSIC_DIR`` if set, else platform default.""" 

112 if path := os.environ.get("XDG_MUSIC_DIR", "").strip(): 

113 return os.path.expanduser(path) # ruff:ignore[os-path-expanduser] 

114 return super().user_music_dir 

115 

116 @property 

117 def user_desktop_dir(self) -> str: 

118 """Desktop directory tied to the user, from ``$XDG_DESKTOP_DIR`` if set, else platform default.""" 

119 if path := os.environ.get("XDG_DESKTOP_DIR", "").strip(): 

120 return os.path.expanduser(path) # ruff:ignore[os-path-expanduser] 

121 return super().user_desktop_dir 

122 

123 @property 

124 def user_projects_dir(self) -> str: 

125 """Projects directory tied to the user, from ``$XDG_PROJECTS_DIR`` if set, else platform default.""" 

126 if path := os.environ.get("XDG_PROJECTS_DIR", "").strip(): 

127 return os.path.expanduser(path) # ruff:ignore[os-path-expanduser] # API returns str, not Path 

128 return super().user_projects_dir 

129 

130 @property 

131 def user_publicshare_dir(self) -> str: 

132 """Public share directory tied to the user, from ``$XDG_PUBLICSHARE_DIR`` if set, else platform default.""" 

133 if path := os.environ.get("XDG_PUBLICSHARE_DIR", "").strip(): 

134 return os.path.expanduser(path) # ruff:ignore[os-path-expanduser] # API returns str, not Path 

135 return super().user_publicshare_dir 

136 

137 @property 

138 def user_templates_dir(self) -> str: 

139 """Templates directory tied to the user, from ``$XDG_TEMPLATES_DIR`` if set, else platform default.""" 

140 if path := os.environ.get("XDG_TEMPLATES_DIR", "").strip(): 

141 return os.path.expanduser(path) # ruff:ignore[os-path-expanduser] # API returns str, not Path 

142 return super().user_templates_dir 

143 

144 @property 

145 def user_fonts_dir(self) -> str: 

146 """Fonts directory tied to the user, from ``$XDG_DATA_HOME/fonts`` if set, else platform default.""" 

147 if path := _xdg_dir("XDG_DATA_HOME"): 

148 return f"{os.path.expanduser(path)}/fonts" # ruff:ignore[os-path-expanduser] # API returns str, not Path 

149 return super().user_fonts_dir 

150 

151 @property 

152 def user_applications_dir(self) -> str: 

153 """Applications directory tied to the user, from ``$XDG_DATA_HOME`` if set, else platform default.""" 

154 if path := _xdg_dir("XDG_DATA_HOME"): 

155 return os.path.join(os.path.expanduser(path), "applications") # ruff:ignore[os-path-expanduser, os-path-join] 

156 return super().user_applications_dir 

157 

158 @property 

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

160 if xdg_dirs := _xdg_dir_list("XDG_DATA_DIRS"): 

161 return [os.path.join(p, "applications") for p in xdg_dirs] # ruff:ignore[os-path-join] 

162 return super()._site_applications_dirs 

163 

164 @property 

165 def site_applications_dir(self) -> str: 

166 """Applications directories shared by users, from ``$XDG_DATA_DIRS`` if set, else platform default.""" 

167 dirs = self._site_applications_dirs 

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

169 

170 

171def _xdg_dir(env_var: str) -> str | None: 

172 path: Final = os.environ.get(env_var, "").strip() 

173 return path if posixpath.isabs(path) else None 

174 

175 

176def _xdg_dir_list(env_var: str) -> list[str]: 

177 return [ 

178 stripped for path in os.environ.get(env_var, "").split(os.pathsep) if posixpath.isabs(stripped := path.strip()) 

179 ] 

180 

181 

182__all__ = [ 

183 "XDGMixin", 

184 "_xdg_dir", 

185]