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

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

2 

3from __future__ import annotations 

4 

5import os 

6 

7from .api import PlatformDirsABC 

8 

9 

10class XDGMixin(PlatformDirsABC): 

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

12 

13 @property 

14 def user_data_dir(self) -> str: 

15 """:returns: data directory tied to the user, from ``$XDG_DATA_HOME`` if set, else platform default""" 

16 if path := os.environ.get("XDG_DATA_HOME", "").strip(): 

17 return self._append_app_name_and_version(path) 

18 return super().user_data_dir 

19 

20 @property 

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

22 if xdg_dirs := os.environ.get("XDG_DATA_DIRS", "").strip(): 

23 return [self._append_app_name_and_version(p) for p in xdg_dirs.split(os.pathsep) if p.strip()] 

24 return super()._site_data_dirs 

25 

26 @property 

27 def site_data_dir(self) -> str: 

28 """:returns: data directories shared by users, from ``$XDG_DATA_DIRS`` if set, else platform default""" 

29 dirs = self._site_data_dirs 

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

31 

32 @property 

33 def user_config_dir(self) -> str: 

34 """:returns: config directory tied to the user, from ``$XDG_CONFIG_HOME`` if set, else platform default""" 

35 if path := os.environ.get("XDG_CONFIG_HOME", "").strip(): 

36 return self._append_app_name_and_version(path) 

37 return super().user_config_dir 

38 

39 @property 

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

41 if xdg_dirs := os.environ.get("XDG_CONFIG_DIRS", "").strip(): 

42 return [self._append_app_name_and_version(p) for p in xdg_dirs.split(os.pathsep) if p.strip()] 

43 return super()._site_config_dirs 

44 

45 @property 

46 def site_config_dir(self) -> str: 

47 """:returns: config directories shared by users, from ``$XDG_CONFIG_DIRS`` if set, else platform default""" 

48 dirs = self._site_config_dirs 

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

50 

51 @property 

52 def user_cache_dir(self) -> str: 

53 """:returns: cache directory tied to the user, from ``$XDG_CACHE_HOME`` if set, else platform default""" 

54 if path := os.environ.get("XDG_CACHE_HOME", "").strip(): 

55 return self._append_app_name_and_version(path) 

56 return super().user_cache_dir 

57 

58 @property 

59 def user_state_dir(self) -> str: 

60 """:returns: state directory tied to the user, from ``$XDG_STATE_HOME`` if set, else platform default""" 

61 if path := os.environ.get("XDG_STATE_HOME", "").strip(): 

62 return self._append_app_name_and_version(path) 

63 return super().user_state_dir 

64 

65 @property 

66 def user_runtime_dir(self) -> str: 

67 """:returns: runtime directory tied to the user, from ``$XDG_RUNTIME_DIR`` if set, else platform default""" 

68 if path := os.environ.get("XDG_RUNTIME_DIR", "").strip(): 

69 return self._append_app_name_and_version(path) 

70 return super().user_runtime_dir 

71 

72 @property 

73 def site_runtime_dir(self) -> str: 

74 """:returns: runtime directory shared by users, from ``$XDG_RUNTIME_DIR`` if set, else platform default""" 

75 if path := os.environ.get("XDG_RUNTIME_DIR", "").strip(): 

76 return self._append_app_name_and_version(path) 

77 return super().site_runtime_dir 

78 

79 @property 

80 def user_documents_dir(self) -> str: 

81 """:returns: documents directory tied to the user, from ``$XDG_DOCUMENTS_DIR`` if set, else platform default""" 

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

83 return os.path.expanduser(path) # noqa: PTH111 

84 return super().user_documents_dir 

85 

86 @property 

87 def user_downloads_dir(self) -> str: 

88 """:returns: downloads directory tied to the user, from ``$XDG_DOWNLOAD_DIR`` if set, else platform default""" 

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

90 return os.path.expanduser(path) # noqa: PTH111 

91 return super().user_downloads_dir 

92 

93 @property 

94 def user_pictures_dir(self) -> str: 

95 """:returns: pictures directory tied to the user, from ``$XDG_PICTURES_DIR`` if set, else platform default""" 

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

97 return os.path.expanduser(path) # noqa: PTH111 

98 return super().user_pictures_dir 

99 

100 @property 

101 def user_videos_dir(self) -> str: 

102 """:returns: videos directory tied to the user, from ``$XDG_VIDEOS_DIR`` if set, else platform default""" 

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

104 return os.path.expanduser(path) # noqa: PTH111 

105 return super().user_videos_dir 

106 

107 @property 

108 def user_music_dir(self) -> str: 

109 """:returns: music directory tied to the user, from ``$XDG_MUSIC_DIR`` if set, else platform default""" 

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

111 return os.path.expanduser(path) # noqa: PTH111 

112 return super().user_music_dir 

113 

114 @property 

115 def user_desktop_dir(self) -> str: 

116 """:returns: desktop directory tied to the user, from ``$XDG_DESKTOP_DIR`` if set, else platform default""" 

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

118 return os.path.expanduser(path) # noqa: PTH111 

119 return super().user_desktop_dir 

120 

121 @property 

122 def user_projects_dir(self) -> str: 

123 """:returns: projects directory tied to the user, from ``$XDG_PROJECTS_DIR`` if set, else platform default""" 

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

125 return os.path.expanduser(path) # noqa: PTH111 # API returns str, not Path 

126 return super().user_projects_dir 

127 

128 @property 

129 def user_publicshare_dir(self) -> str: 

130 """:returns: public share directory tied to the user, from ``$XDG_PUBLICSHARE_DIR`` if set, else platform default""" 

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

132 return os.path.expanduser(path) # noqa: PTH111 # API returns str, not Path 

133 return super().user_publicshare_dir 

134 

135 @property 

136 def user_templates_dir(self) -> str: 

137 """:returns: templates directory tied to the user, from ``$XDG_TEMPLATES_DIR`` if set, else platform default""" 

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

139 return os.path.expanduser(path) # noqa: PTH111 # API returns str, not Path 

140 return super().user_templates_dir 

141 

142 @property 

143 def user_fonts_dir(self) -> str: 

144 """:returns: fonts directory tied to the user, from ``$XDG_DATA_HOME/fonts`` if set, else platform default""" 

145 if path := os.environ.get("XDG_DATA_HOME", "").strip(): 

146 return f"{os.path.expanduser(path)}/fonts" # noqa: PTH111 # API returns str, not Path 

147 return super().user_fonts_dir 

148 

149 @property 

150 def user_applications_dir(self) -> str: 

151 """:returns: applications directory tied to the user, from ``$XDG_DATA_HOME`` if set, else platform default""" 

152 if path := os.environ.get("XDG_DATA_HOME", "").strip(): 

153 return os.path.join(os.path.expanduser(path), "applications") # noqa: PTH111, PTH118 

154 return super().user_applications_dir 

155 

156 @property 

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

158 if xdg_dirs := os.environ.get("XDG_DATA_DIRS", "").strip(): 

159 return [os.path.join(p, "applications") for p in xdg_dirs.split(os.pathsep) if p.strip()] # noqa: PTH118 

160 return super()._site_applications_dirs 

161 

162 @property 

163 def site_applications_dir(self) -> str: 

164 """:returns: applications directories shared by users, from ``$XDG_DATA_DIRS`` if set, else platform default""" 

165 dirs = self._site_applications_dirs 

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

167 

168 

169__all__ = [ 

170 "XDGMixin", 

171]