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

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 """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 """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 """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 """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 """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 """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 """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 """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 """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) # ruff:ignore[os-path-expanduser] 

84 return super().user_documents_dir 

85 

86 @property 

87 def user_downloads_dir(self) -> str: 

88 """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) # ruff:ignore[os-path-expanduser] 

91 return super().user_downloads_dir 

92 

93 @property 

94 def user_pictures_dir(self) -> str: 

95 """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) # ruff:ignore[os-path-expanduser] 

98 return super().user_pictures_dir 

99 

100 @property 

101 def user_videos_dir(self) -> str: 

102 """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) # ruff:ignore[os-path-expanduser] 

105 return super().user_videos_dir 

106 

107 @property 

108 def user_music_dir(self) -> str: 

109 """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) # ruff:ignore[os-path-expanduser] 

112 return super().user_music_dir 

113 

114 @property 

115 def user_desktop_dir(self) -> str: 

116 """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) # ruff:ignore[os-path-expanduser] 

119 return super().user_desktop_dir 

120 

121 @property 

122 def user_projects_dir(self) -> str: 

123 """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) # ruff:ignore[os-path-expanduser] # API returns str, not Path 

126 return super().user_projects_dir 

127 

128 @property 

129 def user_publicshare_dir(self) -> str: 

130 """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) # ruff:ignore[os-path-expanduser] # API returns str, not Path 

133 return super().user_publicshare_dir 

134 

135 @property 

136 def user_templates_dir(self) -> str: 

137 """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) # ruff:ignore[os-path-expanduser] # API returns str, not Path 

140 return super().user_templates_dir 

141 

142 @property 

143 def user_fonts_dir(self) -> str: 

144 """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" # ruff:ignore[os-path-expanduser] # API returns str, not Path 

147 return super().user_fonts_dir 

148 

149 @property 

150 def user_applications_dir(self) -> str: 

151 """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") # ruff:ignore[os-path-expanduser, os-path-join] 

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()] # ruff:ignore[os-path-join] 

160 return super()._site_applications_dirs 

161 

162 @property 

163 def site_applications_dir(self) -> str: 

164 """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]