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