[config.git] / djavu-asus / elpy / rpc-venv / lib / python3.11 / site-packages / platformdirs / unix.py

"""Unix."""
from __future__ import annotations

import os
import sys
from configparser import ConfigParser
from pathlib import Path

from .api import PlatformDirsABC

if sys.platform == "win32":

    def getuid() -> int:
        msg = "should only be used on Unix"
        raise RuntimeError(msg)

else:
    from os import getuid


class Unix(PlatformDirsABC):
    """
    On Unix/Linux, we follow the
    `XDG Basedir Spec <https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html>`_. The spec allows
    overriding directories with environment variables. The examples show are the default values, alongside the name of
    the environment variable that overrides them. Makes use of the
    `appname <platformdirs.api.PlatformDirsABC.appname>`,
    `version <platformdirs.api.PlatformDirsABC.version>`,
    `multipath <platformdirs.api.PlatformDirsABC.multipath>`,
    `opinion <platformdirs.api.PlatformDirsABC.opinion>`,
    `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
    """

    @property
    def user_data_dir(self) -> str:
        """
        :return: data directory tied to the user, e.g. ``~/.local/share/$appname/$version`` or
         ``$XDG_DATA_HOME/$appname/$version``
        """
        path = os.environ.get("XDG_DATA_HOME", "")
        if not path.strip():
            path = os.path.expanduser("~/.local/share")  # noqa: PTH111
        return self._append_app_name_and_version(path)

    @property
    def site_data_dir(self) -> str:
        """
        :return: data directories shared by users (if `multipath <platformdirs.api.PlatformDirsABC.multipath>` is
         enabled and ``XDG_DATA_DIR`` is set and a multi path the response is also a multi path separated by the OS
         path separator), e.g. ``/usr/local/share/$appname/$version`` or ``/usr/share/$appname/$version``
        """
        # XDG default for $XDG_DATA_DIRS; only first, if multipath is False
        path = os.environ.get("XDG_DATA_DIRS", "")
        if not path.strip():
            path = f"/usr/local/share{os.pathsep}/usr/share"
        return self._with_multi_path(path)

    def _with_multi_path(self, path: str) -> str:
        path_list = path.split(os.pathsep)
        if not self.multipath:
            path_list = path_list[0:1]
        path_list = [self._append_app_name_and_version(os.path.expanduser(p)) for p in path_list]  # noqa: PTH111
        return os.pathsep.join(path_list)

    @property
    def user_config_dir(self) -> str:
        """
        :return: config directory tied to the user, e.g. ``~/.config/$appname/$version`` or
         ``$XDG_CONFIG_HOME/$appname/$version``
        """
        path = os.environ.get("XDG_CONFIG_HOME", "")
        if not path.strip():
            path = os.path.expanduser("~/.config")  # noqa: PTH111
        return self._append_app_name_and_version(path)

    @property
    def site_config_dir(self) -> str:
        """
        :return: config directories shared by users (if `multipath <platformdirs.api.PlatformDirsABC.multipath>`
         is enabled and ``XDG_DATA_DIR`` is set and a multi path the response is also a multi path separated by the OS
         path separator), e.g. ``/etc/xdg/$appname/$version``
        """
        # XDG default for $XDG_CONFIG_DIRS only first, if multipath is False
        path = os.environ.get("XDG_CONFIG_DIRS", "")
        if not path.strip():
            path = "/etc/xdg"
        return self._with_multi_path(path)

    @property
    def user_cache_dir(self) -> str:
        """
        :return: cache directory tied to the user, e.g. ``~/.cache/$appname/$version`` or
         ``~/$XDG_CACHE_HOME/$appname/$version``
        """
        path = os.environ.get("XDG_CACHE_HOME", "")
        if not path.strip():
            path = os.path.expanduser("~/.cache")  # noqa: PTH111
        return self._append_app_name_and_version(path)

    @property
    def site_cache_dir(self) -> str:
        """:return: cache directory shared by users, e.g. ``/var/tmp/$appname/$version``"""
        return self._append_app_name_and_version("/var/tmp")  # noqa: S108

    @property
    def user_state_dir(self) -> str:
        """
        :return: state directory tied to the user, e.g. ``~/.local/state/$appname/$version`` or
         ``$XDG_STATE_HOME/$appname/$version``
        """
        path = os.environ.get("XDG_STATE_HOME", "")
        if not path.strip():
            path = os.path.expanduser("~/.local/state")  # noqa: PTH111
        return self._append_app_name_and_version(path)

    @property
    def user_log_dir(self) -> str:
        """:return: log directory tied to the user, same as `user_state_dir` if not opinionated else ``log`` in it"""
        path = self.user_state_dir
        if self.opinion:
            path = os.path.join(path, "log")  # noqa: PTH118
            self._optionally_create_directory(path)
        return path

    @property
    def user_documents_dir(self) -> str:
        """:return: documents directory tied to the user, e.g. ``~/Documents``"""
        return _get_user_media_dir("XDG_DOCUMENTS_DIR", "~/Documents")

    @property
    def user_downloads_dir(self) -> str:
        """:return: downloads directory tied to the user, e.g. ``~/Downloads``"""
        return _get_user_media_dir("XDG_DOWNLOAD_DIR", "~/Downloads")

    @property
    def user_pictures_dir(self) -> str:
        """:return: pictures directory tied to the user, e.g. ``~/Pictures``"""
        return _get_user_media_dir("XDG_PICTURES_DIR", "~/Pictures")

    @property
    def user_videos_dir(self) -> str:
        """:return: videos directory tied to the user, e.g. ``~/Videos``"""
        return _get_user_media_dir("XDG_VIDEOS_DIR", "~/Videos")

    @property
    def user_music_dir(self) -> str:
        """:return: music directory tied to the user, e.g. ``~/Music``"""
        return _get_user_media_dir("XDG_MUSIC_DIR", "~/Music")

    @property
    def user_desktop_dir(self) -> str:
        """:return: desktop directory tied to the user, e.g. ``~/Desktop``"""
        return _get_user_media_dir("XDG_DESKTOP_DIR", "~/Desktop")

    @property
    def user_runtime_dir(self) -> str:
        """
        :return: runtime directory tied to the user, e.g. ``/run/user/$(id -u)/$appname/$version`` or
         ``$XDG_RUNTIME_DIR/$appname/$version``.

         For FreeBSD/OpenBSD/NetBSD, it would return ``/var/run/user/$(id -u)/$appname/$version`` if
         exists, otherwise ``/tmp/runtime-$(id -u)/$appname/$version``, if``$XDG_RUNTIME_DIR``
         is not set.
        """
        path = os.environ.get("XDG_RUNTIME_DIR", "")
        if not path.strip():
            if sys.platform.startswith(("freebsd", "openbsd", "netbsd")):
                path = f"/var/run/user/{getuid()}"
                if not Path(path).exists():
                    path = f"/tmp/runtime-{getuid()}"  # noqa: S108
            else:
                path = f"/run/user/{getuid()}"
        return self._append_app_name_and_version(path)

    @property
    def site_runtime_dir(self) -> str:
        """
        :return: runtime directory shared by users, e.g. ``/run/$appname/$version`` or \
        ``$XDG_RUNTIME_DIR/$appname/$version``.

        Note that this behaves almost exactly like `user_runtime_dir` if ``$XDG_RUNTIME_DIR`` is set, but will
        fall back to paths associated to the root user instead of a regular logged-in user if it's not set.

        If you wish to ensure that a logged-in root user path is returned e.g. ``/run/user/0``, use `user_runtime_dir`
        instead.

        For FreeBSD/OpenBSD/NetBSD, it would return ``/var/run/$appname/$version`` if ``$XDG_RUNTIME_DIR`` is not set.
        """
        path = os.environ.get("XDG_RUNTIME_DIR", "")
        if not path.strip():
            if sys.platform.startswith(("freebsd", "openbsd", "netbsd")):
                path = "/var/run"
            else:
                path = "/run"
        return self._append_app_name_and_version(path)

    @property
    def site_data_path(self) -> Path:
        """:return: data path shared by users. Only return first item, even if ``multipath`` is set to ``True``"""
        return self._first_item_as_path_if_multipath(self.site_data_dir)

    @property
    def site_config_path(self) -> Path:
        """:return: config path shared by the users. Only return first item, even if ``multipath`` is set to ``True``"""
        return self._first_item_as_path_if_multipath(self.site_config_dir)

    @property
    def site_cache_path(self) -> Path:
        """:return: cache path shared by users. Only return first item, even if ``multipath`` is set to ``True``"""
        return self._first_item_as_path_if_multipath(self.site_cache_dir)

    def _first_item_as_path_if_multipath(self, directory: str) -> Path:
        if self.multipath:
            # If multipath is True, the first path is returned.
            directory = directory.split(os.pathsep)[0]
        return Path(directory)


def _get_user_media_dir(env_var: str, fallback_tilde_path: str) -> str:
    media_dir = _get_user_dirs_folder(env_var)
    if media_dir is None:
        media_dir = os.environ.get(env_var, "").strip()
        if not media_dir:
            media_dir = os.path.expanduser(fallback_tilde_path)  # noqa: PTH111

    return media_dir


def _get_user_dirs_folder(key: str) -> str | None:
    """Return directory from user-dirs.dirs config file. See https://freedesktop.org/wiki/Software/xdg-user-dirs/."""
    user_dirs_config_path = Path(Unix().user_config_dir) / "user-dirs.dirs"
    if user_dirs_config_path.exists():
        parser = ConfigParser()

        with user_dirs_config_path.open() as stream:
            # Add fake section header, so ConfigParser doesn't complain
            parser.read_string(f"[top]\n{stream.read()}")

        if key not in parser["top"]:
            return None

        path = parser["top"][key].strip('"')
        # Handle relative home paths
        return path.replace("$HOME", os.path.expanduser("~"))  # noqa: PTH111

    return None


__all__ = [
    "Unix",
]
Commit	Line	Data
53e6db90 DC	1	"""Unix."""
	2	from __future__ import annotations
	3
	4	import os
	5	import sys
	6	from configparser import ConfigParser
	7	from pathlib import Path
	8
	9	from .api import PlatformDirsABC
	10
	11	if sys.platform == "win32":
	12
	13	def getuid() -> int:
	14	msg = "should only be used on Unix"
	15	raise RuntimeError(msg)
	16
	17	else:
	18	from os import getuid
	19
	20
	21	class Unix(PlatformDirsABC):
	22	"""
	23	On Unix/Linux, we follow the
	24	`XDG Basedir Spec <https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html>`_. The spec allows
	25	overriding directories with environment variables. The examples show are the default values, alongside the name of
	26	the environment variable that overrides them. Makes use of the
	27	`appname <platformdirs.api.PlatformDirsABC.appname>`,
	28	`version <platformdirs.api.PlatformDirsABC.version>`,
	29	`multipath <platformdirs.api.PlatformDirsABC.multipath>`,
	30	`opinion <platformdirs.api.PlatformDirsABC.opinion>`,
	31	`ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
	32	"""
	33
	34	@property
	35	def user_data_dir(self) -> str:
	36	"""
	37	:return: data directory tied to the user, e.g. ``~/.local/share/$appname/$version`` or
	38	``$XDG_DATA_HOME/$appname/$version``
	39	"""
	40	path = os.environ.get("XDG_DATA_HOME", "")
	41	if not path.strip():
	42	path = os.path.expanduser("~/.local/share") # noqa: PTH111
	43	return self._append_app_name_and_version(path)
	44
	45	@property
	46	def site_data_dir(self) -> str:
	47	"""
	48	:return: data directories shared by users (if `multipath <platformdirs.api.PlatformDirsABC.multipath>` is
	49	enabled and ``XDG_DATA_DIR`` is set and a multi path the response is also a multi path separated by the OS
	50	path separator), e.g. ``/usr/local/share/$appname/$version`` or ``/usr/share/$appname/$version``
	51	"""
	52	# XDG default for $XDG_DATA_DIRS; only first, if multipath is False
	53	path = os.environ.get("XDG_DATA_DIRS", "")
	54	if not path.strip():
	55	path = f"/usr/local/share{os.pathsep}/usr/share"
	56	return self._with_multi_path(path)
	57
	58	def _with_multi_path(self, path: str) -> str:
	59	path_list = path.split(os.pathsep)
	60	if not self.multipath:
	61	path_list = path_list[0:1]
	62	path_list = [self._append_app_name_and_version(os.path.expanduser(p)) for p in path_list] # noqa: PTH111
	63	return os.pathsep.join(path_list)
	64
65	@property
66	def user_config_dir(self) -> str:
67	"""
68	:return: config directory tied to the user, e.g. ``~/.config/$appname/$version`` or
69	``$XDG_CONFIG_HOME/$appname/$version``
70	"""
71	path = os.environ.get("XDG_CONFIG_HOME", "")
72	if not path.strip():
73	path = os.path.expanduser("~/.config") # noqa: PTH111
74	return self._append_app_name_and_version(path)
75
76	@property
77	def site_config_dir(self) -> str:
78	"""
79	:return: config directories shared by users (if `multipath <platformdirs.api.PlatformDirsABC.multipath>`
80	is enabled and ``XDG_DATA_DIR`` is set and a multi path the response is also a multi path separated by the OS
81	path separator), e.g. ``/etc/xdg/$appname/$version``
82	"""
83	# XDG default for $XDG_CONFIG_DIRS only first, if multipath is False
84	path = os.environ.get("XDG_CONFIG_DIRS", "")
85	if not path.strip():
86	path = "/etc/xdg"
87	return self._with_multi_path(path)
88
89	@property
90	def user_cache_dir(self) -> str:
91	"""
92	:return: cache directory tied to the user, e.g. ``~/.cache/$appname/$version`` or
93	``~/$XDG_CACHE_HOME/$appname/$version``
94	"""
95	path = os.environ.get("XDG_CACHE_HOME", "")
96	if not path.strip():
97	path = os.path.expanduser("~/.cache") # noqa: PTH111
98	return self._append_app_name_and_version(path)
99
100	@property
101	def site_cache_dir(self) -> str:
102	""":return: cache directory shared by users, e.g. ``/var/tmp/$appname/$version``"""
103	return self._append_app_name_and_version("/var/tmp") # noqa: S108
104
105	@property
106	def user_state_dir(self) -> str:
107	"""
108	:return: state directory tied to the user, e.g. ``~/.local/state/$appname/$version`` or
109	``$XDG_STATE_HOME/$appname/$version``
110	"""
111	path = os.environ.get("XDG_STATE_HOME", "")
112	if not path.strip():
113	path = os.path.expanduser("~/.local/state") # noqa: PTH111
114	return self._append_app_name_and_version(path)
115
116	@property
117	def user_log_dir(self) -> str:
118	""":return: log directory tied to the user, same as `user_state_dir` if not opinionated else ``log`` in it"""
119	path = self.user_state_dir
120	if self.opinion:
121	path = os.path.join(path, "log") # noqa: PTH118
122	self._optionally_create_directory(path)
123	return path
124
125	@property
126	def user_documents_dir(self) -> str:
127	""":return: documents directory tied to the user, e.g. ``~/Documents``"""
128	return _get_user_media_dir("XDG_DOCUMENTS_DIR", "~/Documents")
129
130	@property
131	def user_downloads_dir(self) -> str:
132	""":return: downloads directory tied to the user, e.g. ``~/Downloads``"""
133	return _get_user_media_dir("XDG_DOWNLOAD_DIR", "~/Downloads")
134
135	@property
136	def user_pictures_dir(self) -> str:
137	""":return: pictures directory tied to the user, e.g. ``~/Pictures``"""
138	return _get_user_media_dir("XDG_PICTURES_DIR", "~/Pictures")
139
140	@property
141	def user_videos_dir(self) -> str:
142	""":return: videos directory tied to the user, e.g. ``~/Videos``"""
143	return _get_user_media_dir("XDG_VIDEOS_DIR", "~/Videos")
144
145	@property
146	def user_music_dir(self) -> str:
147	""":return: music directory tied to the user, e.g. ``~/Music``"""
148	return _get_user_media_dir("XDG_MUSIC_DIR", "~/Music")
149
150	@property
151	def user_desktop_dir(self) -> str:
152	""":return: desktop directory tied to the user, e.g. ``~/Desktop``"""
153	return _get_user_media_dir("XDG_DESKTOP_DIR", "~/Desktop")
154
155	@property
156	def user_runtime_dir(self) -> str:
157	"""
158	:return: runtime directory tied to the user, e.g. ``/run/user/$(id -u)/$appname/$version`` or
159	``$XDG_RUNTIME_DIR/$appname/$version``.
160
161	For FreeBSD/OpenBSD/NetBSD, it would return ``/var/run/user/$(id -u)/$appname/$version`` if
162	exists, otherwise ``/tmp/runtime-$(id -u)/$appname/$version``, if``$XDG_RUNTIME_DIR``
163	is not set.
164	"""
165	path = os.environ.get("XDG_RUNTIME_DIR", "")
166	if not path.strip():
167	if sys.platform.startswith(("freebsd", "openbsd", "netbsd")):
168	path = f"/var/run/user/{getuid()}"
169	if not Path(path).exists():
170	path = f"/tmp/runtime-{getuid()}" # noqa: S108
171	else:
172	path = f"/run/user/{getuid()}"
173	return self._append_app_name_and_version(path)
174
175	@property
176	def site_runtime_dir(self) -> str:
177	"""
178	:return: runtime directory shared by users, e.g. ``/run/$appname/$version`` or \
179	``$XDG_RUNTIME_DIR/$appname/$version``.
180
181	Note that this behaves almost exactly like `user_runtime_dir` if ``$XDG_RUNTIME_DIR`` is set, but will
182	fall back to paths associated to the root user instead of a regular logged-in user if it's not set.
183
184	If you wish to ensure that a logged-in root user path is returned e.g. ``/run/user/0``, use `user_runtime_dir`
185	instead.
186
187	For FreeBSD/OpenBSD/NetBSD, it would return ``/var/run/$appname/$version`` if ``$XDG_RUNTIME_DIR`` is not set.
188	"""
189	path = os.environ.get("XDG_RUNTIME_DIR", "")
190	if not path.strip():
191	if sys.platform.startswith(("freebsd", "openbsd", "netbsd")):
192	path = "/var/run"
193	else:
194	path = "/run"
195	return self._append_app_name_and_version(path)
196
197	@property
198	def site_data_path(self) -> Path:
199	""":return: data path shared by users. Only return first item, even if ``multipath`` is set to ``True``"""
200	return self._first_item_as_path_if_multipath(self.site_data_dir)
201
202	@property
203	def site_config_path(self) -> Path:
204	""":return: config path shared by the users. Only return first item, even if ``multipath`` is set to ``True``"""
205	return self._first_item_as_path_if_multipath(self.site_config_dir)
206
207	@property
208	def site_cache_path(self) -> Path:
209	""":return: cache path shared by users. Only return first item, even if ``multipath`` is set to ``True``"""
210	return self._first_item_as_path_if_multipath(self.site_cache_dir)
211
212	def _first_item_as_path_if_multipath(self, directory: str) -> Path:
213	if self.multipath:
214	# If multipath is True, the first path is returned.
215	directory = directory.split(os.pathsep)[0]
216	return Path(directory)
217
218
219	def _get_user_media_dir(env_var: str, fallback_tilde_path: str) -> str:
220	media_dir = _get_user_dirs_folder(env_var)
221	if media_dir is None:
222	media_dir = os.environ.get(env_var, "").strip()
223	if not media_dir:
224	media_dir = os.path.expanduser(fallback_tilde_path) # noqa: PTH111
225
226	return media_dir
227
228
229	def _get_user_dirs_folder(key: str) -> str \| None:
230	"""Return directory from user-dirs.dirs config file. See https://freedesktop.org/wiki/Software/xdg-user-dirs/."""
231	user_dirs_config_path = Path(Unix().user_config_dir) / "user-dirs.dirs"
232	if user_dirs_config_path.exists():
233	parser = ConfigParser()
234
235	with user_dirs_config_path.open() as stream:
236	# Add fake section header, so ConfigParser doesn't complain
237	parser.read_string(f"[top]\n{stream.read()}")
238
239	if key not in parser["top"]:
240	return None
241
242	path = parser["top"][key].strip('"')
243	# Handle relative home paths
244	return path.replace("$HOME", os.path.expanduser("~")) # noqa: PTH111
245
246	return None
247
248
249	__all__ = [
250	"Unix",
251	]