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

"""Windows."""
from __future__ import annotations

import ctypes
import os
import sys
from functools import lru_cache
from typing import TYPE_CHECKING

from .api import PlatformDirsABC

if TYPE_CHECKING:
    from collections.abc import Callable


class Windows(PlatformDirsABC):
    """
    `MSDN on where to store app data files
    <http://support.microsoft.com/default.aspx?scid=kb;en-us;310294#XSLTH3194121123120121120120>`_.
    Makes use of the
    `appname <platformdirs.api.PlatformDirsABC.appname>`,
    `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`,
    `version <platformdirs.api.PlatformDirsABC.version>`,
    `roaming <platformdirs.api.PlatformDirsABC.roaming>`,
    `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.
         ``%USERPROFILE%\\AppData\\Local\\$appauthor\\$appname`` (not roaming) or
         ``%USERPROFILE%\\AppData\\Roaming\\$appauthor\\$appname`` (roaming)
        """
        const = "CSIDL_APPDATA" if self.roaming else "CSIDL_LOCAL_APPDATA"
        path = os.path.normpath(get_win_folder(const))
        return self._append_parts(path)

    def _append_parts(self, path: str, *, opinion_value: str | None = None) -> str:
        params = []
        if self.appname:
            if self.appauthor is not False:
                author = self.appauthor or self.appname
                params.append(author)
            params.append(self.appname)
            if opinion_value is not None and self.opinion:
                params.append(opinion_value)
            if self.version:
                params.append(self.version)
        path = os.path.join(path, *params)  # noqa: PTH118
        self._optionally_create_directory(path)
        return path

    @property
    def site_data_dir(self) -> str:
        """:return: data directory shared by users, e.g. ``C:\\ProgramData\\$appauthor\\$appname``"""
        path = os.path.normpath(get_win_folder("CSIDL_COMMON_APPDATA"))
        return self._append_parts(path)

    @property
    def user_config_dir(self) -> str:
        """:return: config directory tied to the user, same as `user_data_dir`"""
        return self.user_data_dir

    @property
    def site_config_dir(self) -> str:
        """:return: config directory shared by the users, same as `site_data_dir`"""
        return self.site_data_dir

    @property
    def user_cache_dir(self) -> str:
        """
        :return: cache directory tied to the user (if opinionated with ``Cache`` folder within ``$appname``) e.g.
         ``%USERPROFILE%\\AppData\\Local\\$appauthor\\$appname\\Cache\\$version``
        """
        path = os.path.normpath(get_win_folder("CSIDL_LOCAL_APPDATA"))
        return self._append_parts(path, opinion_value="Cache")

    @property
    def site_cache_dir(self) -> str:
        """:return: cache directory shared by users, e.g. ``C:\\ProgramData\\$appauthor\\$appname\\Cache\\$version``"""
        path = os.path.normpath(get_win_folder("CSIDL_COMMON_APPDATA"))
        return self._append_parts(path, opinion_value="Cache")

    @property
    def user_state_dir(self) -> str:
        """:return: state directory tied to the user, same as `user_data_dir`"""
        return self.user_data_dir

    @property
    def user_log_dir(self) -> str:
        """:return: log directory tied to the user, same as `user_data_dir` if not opinionated else ``Logs`` in it"""
        path = self.user_data_dir
        if self.opinion:
            path = os.path.join(path, "Logs")  # 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. ``%USERPROFILE%\\Documents``"""
        return os.path.normpath(get_win_folder("CSIDL_PERSONAL"))

    @property
    def user_downloads_dir(self) -> str:
        """:return: downloads directory tied to the user e.g. ``%USERPROFILE%\\Downloads``"""
        return os.path.normpath(get_win_folder("CSIDL_DOWNLOADS"))

    @property
    def user_pictures_dir(self) -> str:
        """:return: pictures directory tied to the user e.g. ``%USERPROFILE%\\Pictures``"""
        return os.path.normpath(get_win_folder("CSIDL_MYPICTURES"))

    @property
    def user_videos_dir(self) -> str:
        """:return: videos directory tied to the user e.g. ``%USERPROFILE%\\Videos``"""
        return os.path.normpath(get_win_folder("CSIDL_MYVIDEO"))

    @property
    def user_music_dir(self) -> str:
        """:return: music directory tied to the user e.g. ``%USERPROFILE%\\Music``"""
        return os.path.normpath(get_win_folder("CSIDL_MYMUSIC"))

    @property
    def user_desktop_dir(self) -> str:
        """:return: desktop directory tied to the user, e.g. ``%USERPROFILE%\\Desktop``"""
        return os.path.normpath(get_win_folder("CSIDL_DESKTOPDIRECTORY"))

    @property
    def user_runtime_dir(self) -> str:
        """
        :return: runtime directory tied to the user, e.g.
         ``%USERPROFILE%\\AppData\\Local\\Temp\\$appauthor\\$appname``
        """
        path = os.path.normpath(os.path.join(get_win_folder("CSIDL_LOCAL_APPDATA"), "Temp"))  # noqa: PTH118
        return self._append_parts(path)

    @property
    def site_runtime_dir(self) -> str:
        """:return: runtime directory shared by users, same as `user_runtime_dir`"""
        return self.user_runtime_dir


def get_win_folder_from_env_vars(csidl_name: str) -> str:
    """Get folder from environment variables."""
    result = get_win_folder_if_csidl_name_not_env_var(csidl_name)
    if result is not None:
        return result

    env_var_name = {
        "CSIDL_APPDATA": "APPDATA",
        "CSIDL_COMMON_APPDATA": "ALLUSERSPROFILE",
        "CSIDL_LOCAL_APPDATA": "LOCALAPPDATA",
    }.get(csidl_name)
    if env_var_name is None:
        msg = f"Unknown CSIDL name: {csidl_name}"
        raise ValueError(msg)
    result = os.environ.get(env_var_name)
    if result is None:
        msg = f"Unset environment variable: {env_var_name}"
        raise ValueError(msg)
    return result


def get_win_folder_if_csidl_name_not_env_var(csidl_name: str) -> str | None:
    """Get folder for a CSIDL name that does not exist as an environment variable."""
    if csidl_name == "CSIDL_PERSONAL":
        return os.path.join(os.path.normpath(os.environ["USERPROFILE"]), "Documents")  # noqa: PTH118

    if csidl_name == "CSIDL_DOWNLOADS":
        return os.path.join(os.path.normpath(os.environ["USERPROFILE"]), "Downloads")  # noqa: PTH118

    if csidl_name == "CSIDL_MYPICTURES":
        return os.path.join(os.path.normpath(os.environ["USERPROFILE"]), "Pictures")  # noqa: PTH118

    if csidl_name == "CSIDL_MYVIDEO":
        return os.path.join(os.path.normpath(os.environ["USERPROFILE"]), "Videos")  # noqa: PTH118

    if csidl_name == "CSIDL_MYMUSIC":
        return os.path.join(os.path.normpath(os.environ["USERPROFILE"]), "Music")  # noqa: PTH118
    return None


def get_win_folder_from_registry(csidl_name: str) -> str:
    """
    Get folder from the registry.

    This is a fallback technique at best. I'm not sure if using the registry for these guarantees us the correct answer
    for all CSIDL_* names.
    """
    shell_folder_name = {
        "CSIDL_APPDATA": "AppData",
        "CSIDL_COMMON_APPDATA": "Common AppData",
        "CSIDL_LOCAL_APPDATA": "Local AppData",
        "CSIDL_PERSONAL": "Personal",
        "CSIDL_DOWNLOADS": "{374DE290-123F-4565-9164-39C4925E467B}",
        "CSIDL_MYPICTURES": "My Pictures",
        "CSIDL_MYVIDEO": "My Video",
        "CSIDL_MYMUSIC": "My Music",
    }.get(csidl_name)
    if shell_folder_name is None:
        msg = f"Unknown CSIDL name: {csidl_name}"
        raise ValueError(msg)
    if sys.platform != "win32":  # only needed for mypy type checker to know that this code runs only on Windows
        raise NotImplementedError
    import winreg

    key = winreg.OpenKey(winreg.HKEY_CURRENT_USER, r"Software\Microsoft\Windows\CurrentVersion\Explorer\Shell Folders")
    directory, _ = winreg.QueryValueEx(key, shell_folder_name)
    return str(directory)


def get_win_folder_via_ctypes(csidl_name: str) -> str:
    """Get folder with ctypes."""
    # There is no 'CSIDL_DOWNLOADS'.
    # Use 'CSIDL_PROFILE' (40) and append the default folder 'Downloads' instead.
    # https://learn.microsoft.com/en-us/windows/win32/shell/knownfolderid

    csidl_const = {
        "CSIDL_APPDATA": 26,
        "CSIDL_COMMON_APPDATA": 35,
        "CSIDL_LOCAL_APPDATA": 28,
        "CSIDL_PERSONAL": 5,
        "CSIDL_MYPICTURES": 39,
        "CSIDL_MYVIDEO": 14,
        "CSIDL_MYMUSIC": 13,
        "CSIDL_DOWNLOADS": 40,
        "CSIDL_DESKTOPDIRECTORY": 16,
    }.get(csidl_name)
    if csidl_const is None:
        msg = f"Unknown CSIDL name: {csidl_name}"
        raise ValueError(msg)

    buf = ctypes.create_unicode_buffer(1024)
    windll = getattr(ctypes, "windll")  # noqa: B009 # using getattr to avoid false positive with mypy type checker
    windll.shell32.SHGetFolderPathW(None, csidl_const, None, 0, buf)

    # Downgrade to short path name if it has high-bit chars.
    if any(ord(c) > 255 for c in buf):  # noqa: PLR2004
        buf2 = ctypes.create_unicode_buffer(1024)
        if windll.kernel32.GetShortPathNameW(buf.value, buf2, 1024):
            buf = buf2

    if csidl_name == "CSIDL_DOWNLOADS":
        return os.path.join(buf.value, "Downloads")  # noqa: PTH118

    return buf.value


def _pick_get_win_folder() -> Callable[[str], str]:
    if hasattr(ctypes, "windll"):
        return get_win_folder_via_ctypes
    try:
        import winreg  # noqa: F401
    except ImportError:
        return get_win_folder_from_env_vars
    else:
        return get_win_folder_from_registry


get_win_folder = lru_cache(maxsize=None)(_pick_get_win_folder())

__all__ = [
    "Windows",
]
Commit	Line	Data
53e6db90 DC	1	"""Windows."""
	2	from __future__ import annotations
	3
	4	import ctypes
	5	import os
	6	import sys
	7	from functools import lru_cache
	8	from typing import TYPE_CHECKING
	9
	10	from .api import PlatformDirsABC
	11
	12	if TYPE_CHECKING:
	13	from collections.abc import Callable
	14
	15
	16	class Windows(PlatformDirsABC):
	17	"""
	18	`MSDN on where to store app data files
	19	<http://support.microsoft.com/default.aspx?scid=kb;en-us;310294#XSLTH3194121123120121120120>`_.
	20	Makes use of the
	21	`appname <platformdirs.api.PlatformDirsABC.appname>`,
	22	`appauthor <platformdirs.api.PlatformDirsABC.appauthor>`,
	23	`version <platformdirs.api.PlatformDirsABC.version>`,
	24	`roaming <platformdirs.api.PlatformDirsABC.roaming>`,
	25	`opinion <platformdirs.api.PlatformDirsABC.opinion>`,
	26	`ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
	27	"""
	28
	29	@property
	30	def user_data_dir(self) -> str:
	31	"""
	32	:return: data directory tied to the user, e.g.
	33	``%USERPROFILE%\\AppData\\Local\\$appauthor\\$appname`` (not roaming) or
	34	``%USERPROFILE%\\AppData\\Roaming\\$appauthor\\$appname`` (roaming)
	35	"""
	36	const = "CSIDL_APPDATA" if self.roaming else "CSIDL_LOCAL_APPDATA"
	37	path = os.path.normpath(get_win_folder(const))
	38	return self._append_parts(path)
	39
	40	def _append_parts(self, path: str, *, opinion_value: str \| None = None) -> str:
	41	params = []
	42	if self.appname:
	43	if self.appauthor is not False:
	44	author = self.appauthor or self.appname
	45	params.append(author)
	46	params.append(self.appname)
	47	if opinion_value is not None and self.opinion:
	48	params.append(opinion_value)
	49	if self.version:
	50	params.append(self.version)
	51	path = os.path.join(path, *params) # noqa: PTH118
	52	self._optionally_create_directory(path)
	53	return path
	54
	55	@property
	56	def site_data_dir(self) -> str:
	57	""":return: data directory shared by users, e.g. ``C:\\ProgramData\\$appauthor\\$appname``"""
	58	path = os.path.normpath(get_win_folder("CSIDL_COMMON_APPDATA"))
	59	return self._append_parts(path)
	60
	61	@property
	62	def user_config_dir(self) -> str:
	63	""":return: config directory tied to the user, same as `user_data_dir`"""
	64	return self.user_data_dir
65
66	@property
67	def site_config_dir(self) -> str:
68	""":return: config directory shared by the users, same as `site_data_dir`"""
69	return self.site_data_dir
70
71	@property
72	def user_cache_dir(self) -> str:
73	"""
74	:return: cache directory tied to the user (if opinionated with ``Cache`` folder within ``$appname``) e.g.
75	``%USERPROFILE%\\AppData\\Local\\$appauthor\\$appname\\Cache\\$version``
76	"""
77	path = os.path.normpath(get_win_folder("CSIDL_LOCAL_APPDATA"))
78	return self._append_parts(path, opinion_value="Cache")
79
80	@property
81	def site_cache_dir(self) -> str:
82	""":return: cache directory shared by users, e.g. ``C:\\ProgramData\\$appauthor\\$appname\\Cache\\$version``"""
83	path = os.path.normpath(get_win_folder("CSIDL_COMMON_APPDATA"))
84	return self._append_parts(path, opinion_value="Cache")
85
86	@property
87	def user_state_dir(self) -> str:
88	""":return: state directory tied to the user, same as `user_data_dir`"""
89	return self.user_data_dir
90
91	@property
92	def user_log_dir(self) -> str:
93	""":return: log directory tied to the user, same as `user_data_dir` if not opinionated else ``Logs`` in it"""
94	path = self.user_data_dir
95	if self.opinion:
96	path = os.path.join(path, "Logs") # noqa: PTH118
97	self._optionally_create_directory(path)
98	return path
99
100	@property
101	def user_documents_dir(self) -> str:
102	""":return: documents directory tied to the user e.g. ``%USERPROFILE%\\Documents``"""
103	return os.path.normpath(get_win_folder("CSIDL_PERSONAL"))
104
105	@property
106	def user_downloads_dir(self) -> str:
107	""":return: downloads directory tied to the user e.g. ``%USERPROFILE%\\Downloads``"""
108	return os.path.normpath(get_win_folder("CSIDL_DOWNLOADS"))
109
110	@property
111	def user_pictures_dir(self) -> str:
112	""":return: pictures directory tied to the user e.g. ``%USERPROFILE%\\Pictures``"""
113	return os.path.normpath(get_win_folder("CSIDL_MYPICTURES"))
114
115	@property
116	def user_videos_dir(self) -> str:
117	""":return: videos directory tied to the user e.g. ``%USERPROFILE%\\Videos``"""
118	return os.path.normpath(get_win_folder("CSIDL_MYVIDEO"))
119
120	@property
121	def user_music_dir(self) -> str:
122	""":return: music directory tied to the user e.g. ``%USERPROFILE%\\Music``"""
123	return os.path.normpath(get_win_folder("CSIDL_MYMUSIC"))
124
125	@property
126	def user_desktop_dir(self) -> str:
127	""":return: desktop directory tied to the user, e.g. ``%USERPROFILE%\\Desktop``"""
128	return os.path.normpath(get_win_folder("CSIDL_DESKTOPDIRECTORY"))
129
130	@property
131	def user_runtime_dir(self) -> str:
132	"""
133	:return: runtime directory tied to the user, e.g.
134	``%USERPROFILE%\\AppData\\Local\\Temp\\$appauthor\\$appname``
135	"""
136	path = os.path.normpath(os.path.join(get_win_folder("CSIDL_LOCAL_APPDATA"), "Temp")) # noqa: PTH118
137	return self._append_parts(path)
138
139	@property
140	def site_runtime_dir(self) -> str:
141	""":return: runtime directory shared by users, same as `user_runtime_dir`"""
142	return self.user_runtime_dir
143
144
145	def get_win_folder_from_env_vars(csidl_name: str) -> str:
146	"""Get folder from environment variables."""
147	result = get_win_folder_if_csidl_name_not_env_var(csidl_name)
148	if result is not None:
149	return result
150
151	env_var_name = {
152	"CSIDL_APPDATA": "APPDATA",
153	"CSIDL_COMMON_APPDATA": "ALLUSERSPROFILE",
154	"CSIDL_LOCAL_APPDATA": "LOCALAPPDATA",
155	}.get(csidl_name)
156	if env_var_name is None:
157	msg = f"Unknown CSIDL name: {csidl_name}"
158	raise ValueError(msg)
159	result = os.environ.get(env_var_name)
160	if result is None:
161	msg = f"Unset environment variable: {env_var_name}"
162	raise ValueError(msg)
163	return result
164
165
166	def get_win_folder_if_csidl_name_not_env_var(csidl_name: str) -> str \| None:
167	"""Get folder for a CSIDL name that does not exist as an environment variable."""
168	if csidl_name == "CSIDL_PERSONAL":
169	return os.path.join(os.path.normpath(os.environ["USERPROFILE"]), "Documents") # noqa: PTH118
170
171	if csidl_name == "CSIDL_DOWNLOADS":
172	return os.path.join(os.path.normpath(os.environ["USERPROFILE"]), "Downloads") # noqa: PTH118
173
174	if csidl_name == "CSIDL_MYPICTURES":
175	return os.path.join(os.path.normpath(os.environ["USERPROFILE"]), "Pictures") # noqa: PTH118
176
177	if csidl_name == "CSIDL_MYVIDEO":
178	return os.path.join(os.path.normpath(os.environ["USERPROFILE"]), "Videos") # noqa: PTH118
179
180	if csidl_name == "CSIDL_MYMUSIC":
181	return os.path.join(os.path.normpath(os.environ["USERPROFILE"]), "Music") # noqa: PTH118
182	return None
183
184
185	def get_win_folder_from_registry(csidl_name: str) -> str:
186	"""
187	Get folder from the registry.
188
189	This is a fallback technique at best. I'm not sure if using the registry for these guarantees us the correct answer
190	for all CSIDL_* names.
191	"""
192	shell_folder_name = {
193	"CSIDL_APPDATA": "AppData",
194	"CSIDL_COMMON_APPDATA": "Common AppData",
195	"CSIDL_LOCAL_APPDATA": "Local AppData",
196	"CSIDL_PERSONAL": "Personal",
197	"CSIDL_DOWNLOADS": "{374DE290-123F-4565-9164-39C4925E467B}",
198	"CSIDL_MYPICTURES": "My Pictures",
199	"CSIDL_MYVIDEO": "My Video",
200	"CSIDL_MYMUSIC": "My Music",
201	}.get(csidl_name)
202	if shell_folder_name is None:
203	msg = f"Unknown CSIDL name: {csidl_name}"
204	raise ValueError(msg)
205	if sys.platform != "win32": # only needed for mypy type checker to know that this code runs only on Windows
206	raise NotImplementedError
207	import winreg
208
209	key = winreg.OpenKey(winreg.HKEY_CURRENT_USER, r"Software\Microsoft\Windows\CurrentVersion\Explorer\Shell Folders")
210	directory, _ = winreg.QueryValueEx(key, shell_folder_name)
211	return str(directory)
212
213
214	def get_win_folder_via_ctypes(csidl_name: str) -> str:
215	"""Get folder with ctypes."""
216	# There is no 'CSIDL_DOWNLOADS'.
217	# Use 'CSIDL_PROFILE' (40) and append the default folder 'Downloads' instead.
218	# https://learn.microsoft.com/en-us/windows/win32/shell/knownfolderid
219
220	csidl_const = {
221	"CSIDL_APPDATA": 26,
222	"CSIDL_COMMON_APPDATA": 35,
223	"CSIDL_LOCAL_APPDATA": 28,
224	"CSIDL_PERSONAL": 5,
225	"CSIDL_MYPICTURES": 39,
226	"CSIDL_MYVIDEO": 14,
227	"CSIDL_MYMUSIC": 13,
228	"CSIDL_DOWNLOADS": 40,
229	"CSIDL_DESKTOPDIRECTORY": 16,
230	}.get(csidl_name)
231	if csidl_const is None:
232	msg = f"Unknown CSIDL name: {csidl_name}"
233	raise ValueError(msg)
234
235	buf = ctypes.create_unicode_buffer(1024)
236	windll = getattr(ctypes, "windll") # noqa: B009 # using getattr to avoid false positive with mypy type checker
237	windll.shell32.SHGetFolderPathW(None, csidl_const, None, 0, buf)
238
239	# Downgrade to short path name if it has high-bit chars.
240	if any(ord(c) > 255 for c in buf): # noqa: PLR2004
241	buf2 = ctypes.create_unicode_buffer(1024)
242	if windll.kernel32.GetShortPathNameW(buf.value, buf2, 1024):
243	buf = buf2
244
245	if csidl_name == "CSIDL_DOWNLOADS":
246	return os.path.join(buf.value, "Downloads") # noqa: PTH118
247
248	return buf.value
249
250
251	def _pick_get_win_folder() -> Callable[[str], str]:
252	if hasattr(ctypes, "windll"):
253	return get_win_folder_via_ctypes
254	try:
255	import winreg # noqa: F401
256	except ImportError:
257	return get_win_folder_from_env_vars
258	else:
259	return get_win_folder_from_registry
260
261
262	get_win_folder = lru_cache(maxsize=None)(_pick_get_win_folder())
263
264	__all__ = [
265	"Windows",
266	]