1""" 2Utilities for determining application-specific dirs. See <https://github.com/platformdirs/platformdirs> for details and 3usage. 4""" 5import importlib 6import os 7import sys 8from pathlib import Path 9from typing import TYPE_CHECKING, Optional, Type, Union 10 11if TYPE_CHECKING: 12 from typing_extensions import Literal # pragma: no cover 13 14from .api import PlatformDirsABC 15from .version import __version__, __version_info__ 16 17 18def _set_platform_dir_class() -> Type[PlatformDirsABC]: 19 if os.getenv("ANDROID_DATA") == "/data" and os.getenv("ANDROID_ROOT") == "/system": 20 module, name = "platformdirs.android", "Android" 21 elif sys.platform == "win32": 22 module, name = "platformdirs.windows", "Windows" 23 elif sys.platform == "darwin": 24 module, name = "platformdirs.macos", "MacOS" 25 else: 26 module, name = "platformdirs.unix", "Unix" 27 result: Type[PlatformDirsABC] = getattr(importlib.import_module(module), name) 28 return result 29 30 31PlatformDirs = _set_platform_dir_class() #: Currently active platform 32AppDirs = PlatformDirs #: Backwards compatibility with appdirs 33 34 35def user_data_dir( 36 appname: Optional[str] = None, 37 appauthor: Union[str, None, "Literal[False]"] = None, 38 version: Optional[str] = None, 39 roaming: bool = False, 40) -> str: 41 """ 42 :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 43 :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`. 44 :param version: See `version <platformdirs.api.PlatformDirsABC.version>`. 45 :param roaming: See `roaming <platformdirs.api.PlatformDirsABC.version>`. 46 :returns: data directory tied to the user 47 """ 48 return PlatformDirs(appname=appname, appauthor=appauthor, version=version, roaming=roaming).user_data_dir 49 50 51def site_data_dir( 52 appname: Optional[str] = None, 53 appauthor: Union[str, None, "Literal[False]"] = None, 54 version: Optional[str] = None, 55 multipath: bool = False, 56) -> str: 57 """ 58 :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 59 :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`. 60 :param version: See `version <platformdirs.api.PlatformDirsABC.version>`. 61 :param multipath: See `roaming <platformdirs.api.PlatformDirsABC.multipath>`. 62 :returns: data directory shared by users 63 """ 64 return PlatformDirs(appname=appname, appauthor=appauthor, version=version, multipath=multipath).site_data_dir 65 66 67def user_config_dir( 68 appname: Optional[str] = None, 69 appauthor: Union[str, None, "Literal[False]"] = None, 70 version: Optional[str] = None, 71 roaming: bool = False, 72) -> str: 73 """ 74 :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 75 :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`. 76 :param version: See `version <platformdirs.api.PlatformDirsABC.version>`. 77 :param roaming: See `roaming <platformdirs.api.PlatformDirsABC.version>`. 78 :returns: config directory tied to the user 79 """ 80 return PlatformDirs(appname=appname, appauthor=appauthor, version=version, roaming=roaming).user_config_dir 81 82 83def site_config_dir( 84 appname: Optional[str] = None, 85 appauthor: Union[str, None, "Literal[False]"] = None, 86 version: Optional[str] = None, 87 multipath: bool = False, 88) -> str: 89 """ 90 :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 91 :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`. 92 :param version: See `version <platformdirs.api.PlatformDirsABC.version>`. 93 :param multipath: See `roaming <platformdirs.api.PlatformDirsABC.multipath>`. 94 :returns: config directory shared by the users 95 """ 96 return PlatformDirs(appname=appname, appauthor=appauthor, version=version, multipath=multipath).site_config_dir 97 98 99def user_cache_dir( 100 appname: Optional[str] = None, 101 appauthor: Union[str, None, "Literal[False]"] = None, 102 version: Optional[str] = None, 103 opinion: bool = True, 104) -> str: 105 """ 106 :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 107 :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`. 108 :param version: See `version <platformdirs.api.PlatformDirsABC.version>`. 109 :param opinion: See `roaming <platformdirs.api.PlatformDirsABC.opinion>`. 110 :returns: cache directory tied to the user 111 """ 112 return PlatformDirs(appname=appname, appauthor=appauthor, version=version, opinion=opinion).user_cache_dir 113 114 115def user_state_dir( 116 appname: Optional[str] = None, 117 appauthor: Union[str, None, "Literal[False]"] = None, 118 version: Optional[str] = None, 119 roaming: bool = False, 120) -> str: 121 """ 122 :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 123 :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`. 124 :param version: See `version <platformdirs.api.PlatformDirsABC.version>`. 125 :param roaming: See `roaming <platformdirs.api.PlatformDirsABC.version>`. 126 :returns: state directory tied to the user 127 """ 128 return PlatformDirs(appname=appname, appauthor=appauthor, version=version, roaming=roaming).user_state_dir 129 130 131def user_log_dir( 132 appname: Optional[str] = None, 133 appauthor: Union[str, None, "Literal[False]"] = None, 134 version: Optional[str] = None, 135 opinion: bool = True, 136) -> str: 137 """ 138 :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 139 :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`. 140 :param version: See `version <platformdirs.api.PlatformDirsABC.version>`. 141 :param opinion: See `roaming <platformdirs.api.PlatformDirsABC.opinion>`. 142 :returns: log directory tied to the user 143 """ 144 return PlatformDirs(appname=appname, appauthor=appauthor, version=version, opinion=opinion).user_log_dir 145 146 147def user_documents_dir() -> str: 148 """ 149 :returns: documents directory tied to the user 150 """ 151 return PlatformDirs().user_documents_dir 152 153 154def user_runtime_dir( 155 appname: Optional[str] = None, 156 appauthor: Union[str, None, "Literal[False]"] = None, 157 version: Optional[str] = None, 158 opinion: bool = True, 159) -> str: 160 """ 161 :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 162 :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`. 163 :param version: See `version <platformdirs.api.PlatformDirsABC.version>`. 164 :param opinion: See `opinion <platformdirs.api.PlatformDirsABC.opinion>`. 165 :returns: runtime directory tied to the user 166 """ 167 return PlatformDirs(appname=appname, appauthor=appauthor, version=version, opinion=opinion).user_runtime_dir 168 169 170def user_data_path( 171 appname: Optional[str] = None, 172 appauthor: Union[str, None, "Literal[False]"] = None, 173 version: Optional[str] = None, 174 roaming: bool = False, 175) -> Path: 176 """ 177 :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 178 :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`. 179 :param version: See `version <platformdirs.api.PlatformDirsABC.version>`. 180 :param roaming: See `roaming <platformdirs.api.PlatformDirsABC.version>`. 181 :returns: data path tied to the user 182 """ 183 return PlatformDirs(appname=appname, appauthor=appauthor, version=version, roaming=roaming).user_data_path 184 185 186def site_data_path( 187 appname: Optional[str] = None, 188 appauthor: Union[str, None, "Literal[False]"] = None, 189 version: Optional[str] = None, 190 multipath: bool = False, 191) -> Path: 192 """ 193 :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 194 :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`. 195 :param version: See `version <platformdirs.api.PlatformDirsABC.version>`. 196 :param multipath: See `multipath <platformdirs.api.PlatformDirsABC.multipath>`. 197 :returns: data path shared by users 198 """ 199 return PlatformDirs(appname=appname, appauthor=appauthor, version=version, multipath=multipath).site_data_path 200 201 202def user_config_path( 203 appname: Optional[str] = None, 204 appauthor: Union[str, None, "Literal[False]"] = None, 205 version: Optional[str] = None, 206 roaming: bool = False, 207) -> Path: 208 """ 209 :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 210 :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`. 211 :param version: See `version <platformdirs.api.PlatformDirsABC.version>`. 212 :param roaming: See `roaming <platformdirs.api.PlatformDirsABC.version>`. 213 :returns: config path tied to the user 214 """ 215 return PlatformDirs(appname=appname, appauthor=appauthor, version=version, roaming=roaming).user_config_path 216 217 218def site_config_path( 219 appname: Optional[str] = None, 220 appauthor: Union[str, None, "Literal[False]"] = None, 221 version: Optional[str] = None, 222 multipath: bool = False, 223) -> Path: 224 """ 225 :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 226 :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`. 227 :param version: See `version <platformdirs.api.PlatformDirsABC.version>`. 228 :param multipath: See `roaming <platformdirs.api.PlatformDirsABC.multipath>`. 229 :returns: config path shared by the users 230 """ 231 return PlatformDirs(appname=appname, appauthor=appauthor, version=version, multipath=multipath).site_config_path 232 233 234def user_cache_path( 235 appname: Optional[str] = None, 236 appauthor: Union[str, None, "Literal[False]"] = None, 237 version: Optional[str] = None, 238 opinion: bool = True, 239) -> Path: 240 """ 241 :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 242 :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`. 243 :param version: See `version <platformdirs.api.PlatformDirsABC.version>`. 244 :param opinion: See `roaming <platformdirs.api.PlatformDirsABC.opinion>`. 245 :returns: cache path tied to the user 246 """ 247 return PlatformDirs(appname=appname, appauthor=appauthor, version=version, opinion=opinion).user_cache_path 248 249 250def user_state_path( 251 appname: Optional[str] = None, 252 appauthor: Union[str, None, "Literal[False]"] = None, 253 version: Optional[str] = None, 254 roaming: bool = False, 255) -> Path: 256 """ 257 :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 258 :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`. 259 :param version: See `version <platformdirs.api.PlatformDirsABC.version>`. 260 :param roaming: See `roaming <platformdirs.api.PlatformDirsABC.version>`. 261 :returns: state path tied to the user 262 """ 263 return PlatformDirs(appname=appname, appauthor=appauthor, version=version, roaming=roaming).user_state_path 264 265 266def user_log_path( 267 appname: Optional[str] = None, 268 appauthor: Union[str, None, "Literal[False]"] = None, 269 version: Optional[str] = None, 270 opinion: bool = True, 271) -> Path: 272 """ 273 :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 274 :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`. 275 :param version: See `version <platformdirs.api.PlatformDirsABC.version>`. 276 :param opinion: See `roaming <platformdirs.api.PlatformDirsABC.opinion>`. 277 :returns: log path tied to the user 278 """ 279 return PlatformDirs(appname=appname, appauthor=appauthor, version=version, opinion=opinion).user_log_path 280 281 282def user_documents_path() -> Path: 283 """ 284 :returns: documents path tied to the user 285 """ 286 return PlatformDirs().user_documents_path 287 288 289def user_runtime_path( 290 appname: Optional[str] = None, 291 appauthor: Union[str, None, "Literal[False]"] = None, 292 version: Optional[str] = None, 293 opinion: bool = True, 294) -> Path: 295 """ 296 :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`. 297 :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`. 298 :param version: See `version <platformdirs.api.PlatformDirsABC.version>`. 299 :param opinion: See `opinion <platformdirs.api.PlatformDirsABC.opinion>`. 300 :returns: runtime path tied to the user 301 """ 302 return PlatformDirs(appname=appname, appauthor=appauthor, version=version, opinion=opinion).user_runtime_path 303 304 305__all__ = [ 306 "__version__", 307 "__version_info__", 308 "PlatformDirs", 309 "AppDirs", 310 "PlatformDirsABC", 311 "user_data_dir", 312 "user_config_dir", 313 "user_cache_dir", 314 "user_state_dir", 315 "user_log_dir", 316 "user_documents_dir", 317 "user_runtime_dir", 318 "site_data_dir", 319 "site_config_dir", 320 "user_data_path", 321 "user_config_path", 322 "user_cache_path", 323 "user_state_path", 324 "user_log_path", 325 "user_documents_path", 326 "user_runtime_path", 327 "site_data_path", 328 "site_config_path", 329] 330