aboutsummaryrefslogtreecommitdiff
path: root/.venv/lib/python3.12/site-packages/setuptools/_vendor/platformdirs
diff options
context:
space:
mode:
authorS. Solomon Darnell2025-03-28 21:52:21 -0500
committerS. Solomon Darnell2025-03-28 21:52:21 -0500
commit4a52a71956a8d46fcb7294ac71734504bb09bcc2 (patch)
treeee3dc5af3b6313e921cd920906356f5d4febc4ed /.venv/lib/python3.12/site-packages/setuptools/_vendor/platformdirs
parentcc961e04ba734dd72309fb548a2f97d67d578813 (diff)
downloadgn-ai-master.tar.gz
two version of R2R are hereHEADmaster
Diffstat (limited to '.venv/lib/python3.12/site-packages/setuptools/_vendor/platformdirs')
-rw-r--r--.venv/lib/python3.12/site-packages/setuptools/_vendor/platformdirs/__init__.py627
-rw-r--r--.venv/lib/python3.12/site-packages/setuptools/_vendor/platformdirs/__main__.py55
-rw-r--r--.venv/lib/python3.12/site-packages/setuptools/_vendor/platformdirs/android.py249
-rw-r--r--.venv/lib/python3.12/site-packages/setuptools/_vendor/platformdirs/api.py292
-rw-r--r--.venv/lib/python3.12/site-packages/setuptools/_vendor/platformdirs/macos.py130
-rw-r--r--.venv/lib/python3.12/site-packages/setuptools/_vendor/platformdirs/py.typed0
-rw-r--r--.venv/lib/python3.12/site-packages/setuptools/_vendor/platformdirs/unix.py275
-rw-r--r--.venv/lib/python3.12/site-packages/setuptools/_vendor/platformdirs/version.py16
-rw-r--r--.venv/lib/python3.12/site-packages/setuptools/_vendor/platformdirs/windows.py272
9 files changed, 1916 insertions, 0 deletions
diff --git a/.venv/lib/python3.12/site-packages/setuptools/_vendor/platformdirs/__init__.py b/.venv/lib/python3.12/site-packages/setuptools/_vendor/platformdirs/__init__.py
new file mode 100644
index 00000000..3f7d9490
--- /dev/null
+++ b/.venv/lib/python3.12/site-packages/setuptools/_vendor/platformdirs/__init__.py
@@ -0,0 +1,627 @@
+"""
+Utilities for determining application-specific dirs.
+
+See <https://github.com/platformdirs/platformdirs> for details and usage.
+
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import TYPE_CHECKING
+
+from .api import PlatformDirsABC
+from .version import __version__
+from .version import __version_tuple__ as __version_info__
+
+if TYPE_CHECKING:
+ from pathlib import Path
+ from typing import Literal
+
+
+def _set_platform_dir_class() -> type[PlatformDirsABC]:
+ if sys.platform == "win32":
+ from platformdirs.windows import Windows as Result # noqa: PLC0415
+ elif sys.platform == "darwin":
+ from platformdirs.macos import MacOS as Result # noqa: PLC0415
+ else:
+ from platformdirs.unix import Unix as Result # noqa: PLC0415
+
+ if os.getenv("ANDROID_DATA") == "/data" and os.getenv("ANDROID_ROOT") == "/system":
+ if os.getenv("SHELL") or os.getenv("PREFIX"):
+ return Result
+
+ from platformdirs.android import _android_folder # noqa: PLC0415
+
+ if _android_folder() is not None:
+ from platformdirs.android import Android # noqa: PLC0415
+
+ return Android # return to avoid redefinition of a result
+
+ return Result
+
+
+PlatformDirs = _set_platform_dir_class() #: Currently active platform
+AppDirs = PlatformDirs #: Backwards compatibility with appdirs
+
+
+def user_data_dir(
+ appname: str | None = None,
+ appauthor: str | None | Literal[False] = None,
+ version: str | None = None,
+ roaming: bool = False, # noqa: FBT001, FBT002
+ ensure_exists: bool = False, # noqa: FBT001, FBT002
+) -> str:
+ """
+ :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
+ :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
+ :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
+ :param roaming: See `roaming <platformdirs.api.PlatformDirsABC.roaming>`.
+ :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
+ :returns: data directory tied to the user
+ """
+ return PlatformDirs(
+ appname=appname,
+ appauthor=appauthor,
+ version=version,
+ roaming=roaming,
+ ensure_exists=ensure_exists,
+ ).user_data_dir
+
+
+def site_data_dir(
+ appname: str | None = None,
+ appauthor: str | None | Literal[False] = None,
+ version: str | None = None,
+ multipath: bool = False, # noqa: FBT001, FBT002
+ ensure_exists: bool = False, # noqa: FBT001, FBT002
+) -> str:
+ """
+ :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
+ :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
+ :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
+ :param multipath: See `roaming <platformdirs.api.PlatformDirsABC.multipath>`.
+ :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
+ :returns: data directory shared by users
+ """
+ return PlatformDirs(
+ appname=appname,
+ appauthor=appauthor,
+ version=version,
+ multipath=multipath,
+ ensure_exists=ensure_exists,
+ ).site_data_dir
+
+
+def user_config_dir(
+ appname: str | None = None,
+ appauthor: str | None | Literal[False] = None,
+ version: str | None = None,
+ roaming: bool = False, # noqa: FBT001, FBT002
+ ensure_exists: bool = False, # noqa: FBT001, FBT002
+) -> str:
+ """
+ :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
+ :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
+ :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
+ :param roaming: See `roaming <platformdirs.api.PlatformDirsABC.roaming>`.
+ :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
+ :returns: config directory tied to the user
+ """
+ return PlatformDirs(
+ appname=appname,
+ appauthor=appauthor,
+ version=version,
+ roaming=roaming,
+ ensure_exists=ensure_exists,
+ ).user_config_dir
+
+
+def site_config_dir(
+ appname: str | None = None,
+ appauthor: str | None | Literal[False] = None,
+ version: str | None = None,
+ multipath: bool = False, # noqa: FBT001, FBT002
+ ensure_exists: bool = False, # noqa: FBT001, FBT002
+) -> str:
+ """
+ :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
+ :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
+ :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
+ :param multipath: See `roaming <platformdirs.api.PlatformDirsABC.multipath>`.
+ :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
+ :returns: config directory shared by the users
+ """
+ return PlatformDirs(
+ appname=appname,
+ appauthor=appauthor,
+ version=version,
+ multipath=multipath,
+ ensure_exists=ensure_exists,
+ ).site_config_dir
+
+
+def user_cache_dir(
+ appname: str | None = None,
+ appauthor: str | None | Literal[False] = None,
+ version: str | None = None,
+ opinion: bool = True, # noqa: FBT001, FBT002
+ ensure_exists: bool = False, # noqa: FBT001, FBT002
+) -> str:
+ """
+ :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
+ :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
+ :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
+ :param opinion: See `roaming <platformdirs.api.PlatformDirsABC.opinion>`.
+ :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
+ :returns: cache directory tied to the user
+ """
+ return PlatformDirs(
+ appname=appname,
+ appauthor=appauthor,
+ version=version,
+ opinion=opinion,
+ ensure_exists=ensure_exists,
+ ).user_cache_dir
+
+
+def site_cache_dir(
+ appname: str | None = None,
+ appauthor: str | None | Literal[False] = None,
+ version: str | None = None,
+ opinion: bool = True, # noqa: FBT001, FBT002
+ ensure_exists: bool = False, # noqa: FBT001, FBT002
+) -> str:
+ """
+ :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
+ :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
+ :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
+ :param opinion: See `opinion <platformdirs.api.PlatformDirsABC.opinion>`.
+ :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
+ :returns: cache directory tied to the user
+ """
+ return PlatformDirs(
+ appname=appname,
+ appauthor=appauthor,
+ version=version,
+ opinion=opinion,
+ ensure_exists=ensure_exists,
+ ).site_cache_dir
+
+
+def user_state_dir(
+ appname: str | None = None,
+ appauthor: str | None | Literal[False] = None,
+ version: str | None = None,
+ roaming: bool = False, # noqa: FBT001, FBT002
+ ensure_exists: bool = False, # noqa: FBT001, FBT002
+) -> str:
+ """
+ :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
+ :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
+ :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
+ :param roaming: See `roaming <platformdirs.api.PlatformDirsABC.roaming>`.
+ :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
+ :returns: state directory tied to the user
+ """
+ return PlatformDirs(
+ appname=appname,
+ appauthor=appauthor,
+ version=version,
+ roaming=roaming,
+ ensure_exists=ensure_exists,
+ ).user_state_dir
+
+
+def user_log_dir(
+ appname: str | None = None,
+ appauthor: str | None | Literal[False] = None,
+ version: str | None = None,
+ opinion: bool = True, # noqa: FBT001, FBT002
+ ensure_exists: bool = False, # noqa: FBT001, FBT002
+) -> str:
+ """
+ :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
+ :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
+ :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
+ :param opinion: See `roaming <platformdirs.api.PlatformDirsABC.opinion>`.
+ :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
+ :returns: log directory tied to the user
+ """
+ return PlatformDirs(
+ appname=appname,
+ appauthor=appauthor,
+ version=version,
+ opinion=opinion,
+ ensure_exists=ensure_exists,
+ ).user_log_dir
+
+
+def user_documents_dir() -> str:
+ """:returns: documents directory tied to the user"""
+ return PlatformDirs().user_documents_dir
+
+
+def user_downloads_dir() -> str:
+ """:returns: downloads directory tied to the user"""
+ return PlatformDirs().user_downloads_dir
+
+
+def user_pictures_dir() -> str:
+ """:returns: pictures directory tied to the user"""
+ return PlatformDirs().user_pictures_dir
+
+
+def user_videos_dir() -> str:
+ """:returns: videos directory tied to the user"""
+ return PlatformDirs().user_videos_dir
+
+
+def user_music_dir() -> str:
+ """:returns: music directory tied to the user"""
+ return PlatformDirs().user_music_dir
+
+
+def user_desktop_dir() -> str:
+ """:returns: desktop directory tied to the user"""
+ return PlatformDirs().user_desktop_dir
+
+
+def user_runtime_dir(
+ appname: str | None = None,
+ appauthor: str | None | Literal[False] = None,
+ version: str | None = None,
+ opinion: bool = True, # noqa: FBT001, FBT002
+ ensure_exists: bool = False, # noqa: FBT001, FBT002
+) -> str:
+ """
+ :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
+ :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
+ :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
+ :param opinion: See `opinion <platformdirs.api.PlatformDirsABC.opinion>`.
+ :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
+ :returns: runtime directory tied to the user
+ """
+ return PlatformDirs(
+ appname=appname,
+ appauthor=appauthor,
+ version=version,
+ opinion=opinion,
+ ensure_exists=ensure_exists,
+ ).user_runtime_dir
+
+
+def site_runtime_dir(
+ appname: str | None = None,
+ appauthor: str | None | Literal[False] = None,
+ version: str | None = None,
+ opinion: bool = True, # noqa: FBT001, FBT002
+ ensure_exists: bool = False, # noqa: FBT001, FBT002
+) -> str:
+ """
+ :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
+ :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
+ :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
+ :param opinion: See `opinion <platformdirs.api.PlatformDirsABC.opinion>`.
+ :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
+ :returns: runtime directory shared by users
+ """
+ return PlatformDirs(
+ appname=appname,
+ appauthor=appauthor,
+ version=version,
+ opinion=opinion,
+ ensure_exists=ensure_exists,
+ ).site_runtime_dir
+
+
+def user_data_path(
+ appname: str | None = None,
+ appauthor: str | None | Literal[False] = None,
+ version: str | None = None,
+ roaming: bool = False, # noqa: FBT001, FBT002
+ ensure_exists: bool = False, # noqa: FBT001, FBT002
+) -> Path:
+ """
+ :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
+ :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
+ :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
+ :param roaming: See `roaming <platformdirs.api.PlatformDirsABC.roaming>`.
+ :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
+ :returns: data path tied to the user
+ """
+ return PlatformDirs(
+ appname=appname,
+ appauthor=appauthor,
+ version=version,
+ roaming=roaming,
+ ensure_exists=ensure_exists,
+ ).user_data_path
+
+
+def site_data_path(
+ appname: str | None = None,
+ appauthor: str | None | Literal[False] = None,
+ version: str | None = None,
+ multipath: bool = False, # noqa: FBT001, FBT002
+ ensure_exists: bool = False, # noqa: FBT001, FBT002
+) -> Path:
+ """
+ :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
+ :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
+ :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
+ :param multipath: See `multipath <platformdirs.api.PlatformDirsABC.multipath>`.
+ :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
+ :returns: data path shared by users
+ """
+ return PlatformDirs(
+ appname=appname,
+ appauthor=appauthor,
+ version=version,
+ multipath=multipath,
+ ensure_exists=ensure_exists,
+ ).site_data_path
+
+
+def user_config_path(
+ appname: str | None = None,
+ appauthor: str | None | Literal[False] = None,
+ version: str | None = None,
+ roaming: bool = False, # noqa: FBT001, FBT002
+ ensure_exists: bool = False, # noqa: FBT001, FBT002
+) -> Path:
+ """
+ :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
+ :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
+ :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
+ :param roaming: See `roaming <platformdirs.api.PlatformDirsABC.roaming>`.
+ :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
+ :returns: config path tied to the user
+ """
+ return PlatformDirs(
+ appname=appname,
+ appauthor=appauthor,
+ version=version,
+ roaming=roaming,
+ ensure_exists=ensure_exists,
+ ).user_config_path
+
+
+def site_config_path(
+ appname: str | None = None,
+ appauthor: str | None | Literal[False] = None,
+ version: str | None = None,
+ multipath: bool = False, # noqa: FBT001, FBT002
+ ensure_exists: bool = False, # noqa: FBT001, FBT002
+) -> Path:
+ """
+ :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
+ :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
+ :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
+ :param multipath: See `roaming <platformdirs.api.PlatformDirsABC.multipath>`.
+ :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
+ :returns: config path shared by the users
+ """
+ return PlatformDirs(
+ appname=appname,
+ appauthor=appauthor,
+ version=version,
+ multipath=multipath,
+ ensure_exists=ensure_exists,
+ ).site_config_path
+
+
+def site_cache_path(
+ appname: str | None = None,
+ appauthor: str | None | Literal[False] = None,
+ version: str | None = None,
+ opinion: bool = True, # noqa: FBT001, FBT002
+ ensure_exists: bool = False, # noqa: FBT001, FBT002
+) -> Path:
+ """
+ :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
+ :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
+ :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
+ :param opinion: See `opinion <platformdirs.api.PlatformDirsABC.opinion>`.
+ :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
+ :returns: cache directory tied to the user
+ """
+ return PlatformDirs(
+ appname=appname,
+ appauthor=appauthor,
+ version=version,
+ opinion=opinion,
+ ensure_exists=ensure_exists,
+ ).site_cache_path
+
+
+def user_cache_path(
+ appname: str | None = None,
+ appauthor: str | None | Literal[False] = None,
+ version: str | None = None,
+ opinion: bool = True, # noqa: FBT001, FBT002
+ ensure_exists: bool = False, # noqa: FBT001, FBT002
+) -> Path:
+ """
+ :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
+ :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
+ :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
+ :param opinion: See `roaming <platformdirs.api.PlatformDirsABC.opinion>`.
+ :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
+ :returns: cache path tied to the user
+ """
+ return PlatformDirs(
+ appname=appname,
+ appauthor=appauthor,
+ version=version,
+ opinion=opinion,
+ ensure_exists=ensure_exists,
+ ).user_cache_path
+
+
+def user_state_path(
+ appname: str | None = None,
+ appauthor: str | None | Literal[False] = None,
+ version: str | None = None,
+ roaming: bool = False, # noqa: FBT001, FBT002
+ ensure_exists: bool = False, # noqa: FBT001, FBT002
+) -> Path:
+ """
+ :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
+ :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
+ :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
+ :param roaming: See `roaming <platformdirs.api.PlatformDirsABC.roaming>`.
+ :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
+ :returns: state path tied to the user
+ """
+ return PlatformDirs(
+ appname=appname,
+ appauthor=appauthor,
+ version=version,
+ roaming=roaming,
+ ensure_exists=ensure_exists,
+ ).user_state_path
+
+
+def user_log_path(
+ appname: str | None = None,
+ appauthor: str | None | Literal[False] = None,
+ version: str | None = None,
+ opinion: bool = True, # noqa: FBT001, FBT002
+ ensure_exists: bool = False, # noqa: FBT001, FBT002
+) -> Path:
+ """
+ :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
+ :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
+ :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
+ :param opinion: See `roaming <platformdirs.api.PlatformDirsABC.opinion>`.
+ :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
+ :returns: log path tied to the user
+ """
+ return PlatformDirs(
+ appname=appname,
+ appauthor=appauthor,
+ version=version,
+ opinion=opinion,
+ ensure_exists=ensure_exists,
+ ).user_log_path
+
+
+def user_documents_path() -> Path:
+ """:returns: documents a path tied to the user"""
+ return PlatformDirs().user_documents_path
+
+
+def user_downloads_path() -> Path:
+ """:returns: downloads path tied to the user"""
+ return PlatformDirs().user_downloads_path
+
+
+def user_pictures_path() -> Path:
+ """:returns: pictures path tied to the user"""
+ return PlatformDirs().user_pictures_path
+
+
+def user_videos_path() -> Path:
+ """:returns: videos path tied to the user"""
+ return PlatformDirs().user_videos_path
+
+
+def user_music_path() -> Path:
+ """:returns: music path tied to the user"""
+ return PlatformDirs().user_music_path
+
+
+def user_desktop_path() -> Path:
+ """:returns: desktop path tied to the user"""
+ return PlatformDirs().user_desktop_path
+
+
+def user_runtime_path(
+ appname: str | None = None,
+ appauthor: str | None | Literal[False] = None,
+ version: str | None = None,
+ opinion: bool = True, # noqa: FBT001, FBT002
+ ensure_exists: bool = False, # noqa: FBT001, FBT002
+) -> Path:
+ """
+ :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
+ :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
+ :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
+ :param opinion: See `opinion <platformdirs.api.PlatformDirsABC.opinion>`.
+ :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
+ :returns: runtime path tied to the user
+ """
+ return PlatformDirs(
+ appname=appname,
+ appauthor=appauthor,
+ version=version,
+ opinion=opinion,
+ ensure_exists=ensure_exists,
+ ).user_runtime_path
+
+
+def site_runtime_path(
+ appname: str | None = None,
+ appauthor: str | None | Literal[False] = None,
+ version: str | None = None,
+ opinion: bool = True, # noqa: FBT001, FBT002
+ ensure_exists: bool = False, # noqa: FBT001, FBT002
+) -> Path:
+ """
+ :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
+ :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
+ :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
+ :param opinion: See `opinion <platformdirs.api.PlatformDirsABC.opinion>`.
+ :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
+ :returns: runtime path shared by users
+ """
+ return PlatformDirs(
+ appname=appname,
+ appauthor=appauthor,
+ version=version,
+ opinion=opinion,
+ ensure_exists=ensure_exists,
+ ).site_runtime_path
+
+
+__all__ = [
+ "AppDirs",
+ "PlatformDirs",
+ "PlatformDirsABC",
+ "__version__",
+ "__version_info__",
+ "site_cache_dir",
+ "site_cache_path",
+ "site_config_dir",
+ "site_config_path",
+ "site_data_dir",
+ "site_data_path",
+ "site_runtime_dir",
+ "site_runtime_path",
+ "user_cache_dir",
+ "user_cache_path",
+ "user_config_dir",
+ "user_config_path",
+ "user_data_dir",
+ "user_data_path",
+ "user_desktop_dir",
+ "user_desktop_path",
+ "user_documents_dir",
+ "user_documents_path",
+ "user_downloads_dir",
+ "user_downloads_path",
+ "user_log_dir",
+ "user_log_path",
+ "user_music_dir",
+ "user_music_path",
+ "user_pictures_dir",
+ "user_pictures_path",
+ "user_runtime_dir",
+ "user_runtime_path",
+ "user_state_dir",
+ "user_state_path",
+ "user_videos_dir",
+ "user_videos_path",
+]
diff --git a/.venv/lib/python3.12/site-packages/setuptools/_vendor/platformdirs/__main__.py b/.venv/lib/python3.12/site-packages/setuptools/_vendor/platformdirs/__main__.py
new file mode 100644
index 00000000..922c5213
--- /dev/null
+++ b/.venv/lib/python3.12/site-packages/setuptools/_vendor/platformdirs/__main__.py
@@ -0,0 +1,55 @@
+"""Main entry point."""
+
+from __future__ import annotations
+
+from platformdirs import PlatformDirs, __version__
+
+PROPS = (
+ "user_data_dir",
+ "user_config_dir",
+ "user_cache_dir",
+ "user_state_dir",
+ "user_log_dir",
+ "user_documents_dir",
+ "user_downloads_dir",
+ "user_pictures_dir",
+ "user_videos_dir",
+ "user_music_dir",
+ "user_runtime_dir",
+ "site_data_dir",
+ "site_config_dir",
+ "site_cache_dir",
+ "site_runtime_dir",
+)
+
+
+def main() -> None:
+ """Run the main entry point."""
+ app_name = "MyApp"
+ app_author = "MyCompany"
+
+ print(f"-- platformdirs {__version__} --") # noqa: T201
+
+ print("-- app dirs (with optional 'version')") # noqa: T201
+ dirs = PlatformDirs(app_name, app_author, version="1.0")
+ for prop in PROPS:
+ print(f"{prop}: {getattr(dirs, prop)}") # noqa: T201
+
+ print("\n-- app dirs (without optional 'version')") # noqa: T201
+ dirs = PlatformDirs(app_name, app_author)
+ for prop in PROPS:
+ print(f"{prop}: {getattr(dirs, prop)}") # noqa: T201
+
+ print("\n-- app dirs (without optional 'appauthor')") # noqa: T201
+ dirs = PlatformDirs(app_name)
+ for prop in PROPS:
+ print(f"{prop}: {getattr(dirs, prop)}") # noqa: T201
+
+ print("\n-- app dirs (with disabled 'appauthor')") # noqa: T201
+ dirs = PlatformDirs(app_name, appauthor=False)
+ for prop in PROPS:
+ print(f"{prop}: {getattr(dirs, prop)}") # noqa: T201
+
+
+if __name__ == "__main__":
+ main()
diff --git a/.venv/lib/python3.12/site-packages/setuptools/_vendor/platformdirs/android.py b/.venv/lib/python3.12/site-packages/setuptools/_vendor/platformdirs/android.py
new file mode 100644
index 00000000..afd3141c
--- /dev/null
+++ b/.venv/lib/python3.12/site-packages/setuptools/_vendor/platformdirs/android.py
@@ -0,0 +1,249 @@
+"""Android."""
+
+from __future__ import annotations
+
+import os
+import re
+import sys
+from functools import lru_cache
+from typing import TYPE_CHECKING, cast
+
+from .api import PlatformDirsABC
+
+
+class Android(PlatformDirsABC):
+ """
+ Follows the guidance `from here <https://android.stackexchange.com/a/216132>`_.
+
+ Makes use of the `appname <platformdirs.api.PlatformDirsABC.appname>`, `version
+ <platformdirs.api.PlatformDirsABC.version>`, `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
+
+ """
+
+ @property
+ def user_data_dir(self) -> str:
+ """:return: data directory tied to the user, e.g. ``/data/user/<userid>/<packagename>/files/<AppName>``"""
+ return self._append_app_name_and_version(cast(str, _android_folder()), "files")
+
+ @property
+ def site_data_dir(self) -> str:
+ """:return: data directory shared by users, same as `user_data_dir`"""
+ return self.user_data_dir
+
+ @property
+ def user_config_dir(self) -> str:
+ """
+ :return: config directory tied to the user, e.g. \
+ ``/data/user/<userid>/<packagename>/shared_prefs/<AppName>``
+ """
+ return self._append_app_name_and_version(cast(str, _android_folder()), "shared_prefs")
+
+ @property
+ def site_config_dir(self) -> str:
+ """:return: config directory shared by the users, same as `user_config_dir`"""
+ return self.user_config_dir
+
+ @property
+ def user_cache_dir(self) -> str:
+ """:return: cache directory tied to the user, e.g.,``/data/user/<userid>/<packagename>/cache/<AppName>``"""
+ return self._append_app_name_and_version(cast(str, _android_folder()), "cache")
+
+ @property
+ def site_cache_dir(self) -> str:
+ """:return: cache directory shared by users, same as `user_cache_dir`"""
+ return self.user_cache_dir
+
+ @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_cache_dir` if not opinionated else ``log`` in it,
+ e.g. ``/data/user/<userid>/<packagename>/cache/<AppName>/log``
+ """
+ path = self.user_cache_dir
+ if self.opinion:
+ path = os.path.join(path, "log") # noqa: PTH118
+ return path
+
+ @property
+ def user_documents_dir(self) -> str:
+ """:return: documents directory tied to the user e.g. ``/storage/emulated/0/Documents``"""
+ return _android_documents_folder()
+
+ @property
+ def user_downloads_dir(self) -> str:
+ """:return: downloads directory tied to the user e.g. ``/storage/emulated/0/Downloads``"""
+ return _android_downloads_folder()
+
+ @property
+ def user_pictures_dir(self) -> str:
+ """:return: pictures directory tied to the user e.g. ``/storage/emulated/0/Pictures``"""
+ return _android_pictures_folder()
+
+ @property
+ def user_videos_dir(self) -> str:
+ """:return: videos directory tied to the user e.g. ``/storage/emulated/0/DCIM/Camera``"""
+ return _android_videos_folder()
+
+ @property
+ def user_music_dir(self) -> str:
+ """:return: music directory tied to the user e.g. ``/storage/emulated/0/Music``"""
+ return _android_music_folder()
+
+ @property
+ def user_desktop_dir(self) -> str:
+ """:return: desktop directory tied to the user e.g. ``/storage/emulated/0/Desktop``"""
+ return "/storage/emulated/0/Desktop"
+
+ @property
+ def user_runtime_dir(self) -> str:
+ """
+ :return: runtime directory tied to the user, same as `user_cache_dir` if not opinionated else ``tmp`` in it,
+ e.g. ``/data/user/<userid>/<packagename>/cache/<AppName>/tmp``
+ """
+ path = self.user_cache_dir
+ if self.opinion:
+ path = os.path.join(path, "tmp") # noqa: PTH118
+ return path
+
+ @property
+ def site_runtime_dir(self) -> str:
+ """:return: runtime directory shared by users, same as `user_runtime_dir`"""
+ return self.user_runtime_dir
+
+
+@lru_cache(maxsize=1)
+def _android_folder() -> str | None: # noqa: C901, PLR0912
+ """:return: base folder for the Android OS or None if it cannot be found"""
+ result: str | None = None
+ # type checker isn't happy with our "import android", just don't do this when type checking see
+ # https://stackoverflow.com/a/61394121
+ if not TYPE_CHECKING:
+ try:
+ # First try to get a path to android app using python4android (if available)...
+ from android import mActivity # noqa: PLC0415
+
+ context = cast("android.content.Context", mActivity.getApplicationContext()) # noqa: F821
+ result = context.getFilesDir().getParentFile().getAbsolutePath()
+ except Exception: # noqa: BLE001
+ result = None
+ if result is None:
+ try:
+ # ...and fall back to using plain pyjnius, if python4android isn't available or doesn't deliver any useful
+ # result...
+ from jnius import autoclass # noqa: PLC0415
+
+ context = autoclass("android.content.Context")
+ result = context.getFilesDir().getParentFile().getAbsolutePath()
+ except Exception: # noqa: BLE001
+ result = None
+ if result is None:
+ # and if that fails, too, find an android folder looking at path on the sys.path
+ # warning: only works for apps installed under /data, not adopted storage etc.
+ pattern = re.compile(r"/data/(data|user/\d+)/(.+)/files")
+ for path in sys.path:
+ if pattern.match(path):
+ result = path.split("/files")[0]
+ break
+ else:
+ result = None
+ if result is None:
+ # one last try: find an android folder looking at path on the sys.path taking adopted storage paths into
+ # account
+ pattern = re.compile(r"/mnt/expand/[a-fA-F0-9-]{36}/(data|user/\d+)/(.+)/files")
+ for path in sys.path:
+ if pattern.match(path):
+ result = path.split("/files")[0]
+ break
+ else:
+ result = None
+ return result
+
+
+@lru_cache(maxsize=1)
+def _android_documents_folder() -> str:
+ """:return: documents folder for the Android OS"""
+ # Get directories with pyjnius
+ try:
+ from jnius import autoclass # noqa: PLC0415
+
+ context = autoclass("android.content.Context")
+ environment = autoclass("android.os.Environment")
+ documents_dir: str = context.getExternalFilesDir(environment.DIRECTORY_DOCUMENTS).getAbsolutePath()
+ except Exception: # noqa: BLE001
+ documents_dir = "/storage/emulated/0/Documents"
+
+ return documents_dir
+
+
+@lru_cache(maxsize=1)
+def _android_downloads_folder() -> str:
+ """:return: downloads folder for the Android OS"""
+ # Get directories with pyjnius
+ try:
+ from jnius import autoclass # noqa: PLC0415
+
+ context = autoclass("android.content.Context")
+ environment = autoclass("android.os.Environment")
+ downloads_dir: str = context.getExternalFilesDir(environment.DIRECTORY_DOWNLOADS).getAbsolutePath()
+ except Exception: # noqa: BLE001
+ downloads_dir = "/storage/emulated/0/Downloads"
+
+ return downloads_dir
+
+
+@lru_cache(maxsize=1)
+def _android_pictures_folder() -> str:
+ """:return: pictures folder for the Android OS"""
+ # Get directories with pyjnius
+ try:
+ from jnius import autoclass # noqa: PLC0415
+
+ context = autoclass("android.content.Context")
+ environment = autoclass("android.os.Environment")
+ pictures_dir: str = context.getExternalFilesDir(environment.DIRECTORY_PICTURES).getAbsolutePath()
+ except Exception: # noqa: BLE001
+ pictures_dir = "/storage/emulated/0/Pictures"
+
+ return pictures_dir
+
+
+@lru_cache(maxsize=1)
+def _android_videos_folder() -> str:
+ """:return: videos folder for the Android OS"""
+ # Get directories with pyjnius
+ try:
+ from jnius import autoclass # noqa: PLC0415
+
+ context = autoclass("android.content.Context")
+ environment = autoclass("android.os.Environment")
+ videos_dir: str = context.getExternalFilesDir(environment.DIRECTORY_DCIM).getAbsolutePath()
+ except Exception: # noqa: BLE001
+ videos_dir = "/storage/emulated/0/DCIM/Camera"
+
+ return videos_dir
+
+
+@lru_cache(maxsize=1)
+def _android_music_folder() -> str:
+ """:return: music folder for the Android OS"""
+ # Get directories with pyjnius
+ try:
+ from jnius import autoclass # noqa: PLC0415
+
+ context = autoclass("android.content.Context")
+ environment = autoclass("android.os.Environment")
+ music_dir: str = context.getExternalFilesDir(environment.DIRECTORY_MUSIC).getAbsolutePath()
+ except Exception: # noqa: BLE001
+ music_dir = "/storage/emulated/0/Music"
+
+ return music_dir
+
+
+__all__ = [
+ "Android",
+]
diff --git a/.venv/lib/python3.12/site-packages/setuptools/_vendor/platformdirs/api.py b/.venv/lib/python3.12/site-packages/setuptools/_vendor/platformdirs/api.py
new file mode 100644
index 00000000..c50caa64
--- /dev/null
+++ b/.venv/lib/python3.12/site-packages/setuptools/_vendor/platformdirs/api.py
@@ -0,0 +1,292 @@
+"""Base API."""
+
+from __future__ import annotations
+
+import os
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+ from typing import Iterator, Literal
+
+
+class PlatformDirsABC(ABC): # noqa: PLR0904
+ """Abstract base class for platform directories."""
+
+ def __init__( # noqa: PLR0913, PLR0917
+ self,
+ appname: str | None = None,
+ appauthor: str | None | Literal[False] = None,
+ version: str | None = None,
+ roaming: bool = False, # noqa: FBT001, FBT002
+ multipath: bool = False, # noqa: FBT001, FBT002
+ opinion: bool = True, # noqa: FBT001, FBT002
+ ensure_exists: bool = False, # noqa: FBT001, FBT002
+ ) -> None:
+ """
+ Create a new platform directory.
+
+ :param appname: See `appname`.
+ :param appauthor: See `appauthor`.
+ :param version: See `version`.
+ :param roaming: See `roaming`.
+ :param multipath: See `multipath`.
+ :param opinion: See `opinion`.
+ :param ensure_exists: See `ensure_exists`.
+
+ """
+ self.appname = appname #: The name of application.
+ self.appauthor = appauthor
+ """
+ The name of the app author or distributing body for this application.
+
+ Typically, it is the owning company name. Defaults to `appname`. You may pass ``False`` to disable it.
+
+ """
+ self.version = version
+ """
+ An optional version path element to append to the path.
+
+ You might want to use this if you want multiple versions of your app to be able to run independently. If used,
+ this would typically be ``<major>.<minor>``.
+
+ """
+ self.roaming = roaming
+ """
+ Whether to use the roaming appdata directory on Windows.
+
+ That means that for users on a Windows network setup for roaming profiles, this user data will be synced on
+ login (see
+ `here <https://technet.microsoft.com/en-us/library/cc766489(WS.10).aspx>`_).
+
+ """
+ self.multipath = multipath
+ """
+ An optional parameter which indicates that the entire list of data dirs should be returned.
+
+ By default, the first item would only be returned.
+
+ """
+ self.opinion = opinion #: A flag to indicating to use opinionated values.
+ self.ensure_exists = ensure_exists
+ """
+ Optionally create the directory (and any missing parents) upon access if it does not exist.
+
+ By default, no directories are created.
+
+ """
+
+ def _append_app_name_and_version(self, *base: str) -> str:
+ params = list(base[1:])
+ if self.appname:
+ params.append(self.appname)
+ if self.version:
+ params.append(self.version)
+ path = os.path.join(base[0], *params) # noqa: PTH118
+ self._optionally_create_directory(path)
+ return path
+
+ def _optionally_create_directory(self, path: str) -> None:
+ if self.ensure_exists:
+ Path(path).mkdir(parents=True, exist_ok=True)
+
+ @property
+ @abstractmethod
+ def user_data_dir(self) -> str:
+ """:return: data directory tied to the user"""
+
+ @property
+ @abstractmethod
+ def site_data_dir(self) -> str:
+ """:return: data directory shared by users"""
+
+ @property
+ @abstractmethod
+ def user_config_dir(self) -> str:
+ """:return: config directory tied to the user"""
+
+ @property
+ @abstractmethod
+ def site_config_dir(self) -> str:
+ """:return: config directory shared by the users"""
+
+ @property
+ @abstractmethod
+ def user_cache_dir(self) -> str:
+ """:return: cache directory tied to the user"""
+
+ @property
+ @abstractmethod
+ def site_cache_dir(self) -> str:
+ """:return: cache directory shared by users"""
+
+ @property
+ @abstractmethod
+ def user_state_dir(self) -> str:
+ """:return: state directory tied to the user"""
+
+ @property
+ @abstractmethod
+ def user_log_dir(self) -> str:
+ """:return: log directory tied to the user"""
+
+ @property
+ @abstractmethod
+ def user_documents_dir(self) -> str:
+ """:return: documents directory tied to the user"""
+
+ @property
+ @abstractmethod
+ def user_downloads_dir(self) -> str:
+ """:return: downloads directory tied to the user"""
+
+ @property
+ @abstractmethod
+ def user_pictures_dir(self) -> str:
+ """:return: pictures directory tied to the user"""
+
+ @property
+ @abstractmethod
+ def user_videos_dir(self) -> str:
+ """:return: videos directory tied to the user"""
+
+ @property
+ @abstractmethod
+ def user_music_dir(self) -> str:
+ """:return: music directory tied to the user"""
+
+ @property
+ @abstractmethod
+ def user_desktop_dir(self) -> str:
+ """:return: desktop directory tied to the user"""
+
+ @property
+ @abstractmethod
+ def user_runtime_dir(self) -> str:
+ """:return: runtime directory tied to the user"""
+
+ @property
+ @abstractmethod
+ def site_runtime_dir(self) -> str:
+ """:return: runtime directory shared by users"""
+
+ @property
+ def user_data_path(self) -> Path:
+ """:return: data path tied to the user"""
+ return Path(self.user_data_dir)
+
+ @property
+ def site_data_path(self) -> Path:
+ """:return: data path shared by users"""
+ return Path(self.site_data_dir)
+
+ @property
+ def user_config_path(self) -> Path:
+ """:return: config path tied to the user"""
+ return Path(self.user_config_dir)
+
+ @property
+ def site_config_path(self) -> Path:
+ """:return: config path shared by the users"""
+ return Path(self.site_config_dir)
+
+ @property
+ def user_cache_path(self) -> Path:
+ """:return: cache path tied to the user"""
+ return Path(self.user_cache_dir)
+
+ @property
+ def site_cache_path(self) -> Path:
+ """:return: cache path shared by users"""
+ return Path(self.site_cache_dir)
+
+ @property
+ def user_state_path(self) -> Path:
+ """:return: state path tied to the user"""
+ return Path(self.user_state_dir)
+
+ @property
+ def user_log_path(self) -> Path:
+ """:return: log path tied to the user"""
+ return Path(self.user_log_dir)
+
+ @property
+ def user_documents_path(self) -> Path:
+ """:return: documents a path tied to the user"""
+ return Path(self.user_documents_dir)
+
+ @property
+ def user_downloads_path(self) -> Path:
+ """:return: downloads path tied to the user"""
+ return Path(self.user_downloads_dir)
+
+ @property
+ def user_pictures_path(self) -> Path:
+ """:return: pictures path tied to the user"""
+ return Path(self.user_pictures_dir)
+
+ @property
+ def user_videos_path(self) -> Path:
+ """:return: videos path tied to the user"""
+ return Path(self.user_videos_dir)
+
+ @property
+ def user_music_path(self) -> Path:
+ """:return: music path tied to the user"""
+ return Path(self.user_music_dir)
+
+ @property
+ def user_desktop_path(self) -> Path:
+ """:return: desktop path tied to the user"""
+ return Path(self.user_desktop_dir)
+
+ @property
+ def user_runtime_path(self) -> Path:
+ """:return: runtime path tied to the user"""
+ return Path(self.user_runtime_dir)
+
+ @property
+ def site_runtime_path(self) -> Path:
+ """:return: runtime path shared by users"""
+ return Path(self.site_runtime_dir)
+
+ def iter_config_dirs(self) -> Iterator[str]:
+ """:yield: all user and site configuration directories."""
+ yield self.user_config_dir
+ yield self.site_config_dir
+
+ def iter_data_dirs(self) -> Iterator[str]:
+ """:yield: all user and site data directories."""
+ yield self.user_data_dir
+ yield self.site_data_dir
+
+ def iter_cache_dirs(self) -> Iterator[str]:
+ """:yield: all user and site cache directories."""
+ yield self.user_cache_dir
+ yield self.site_cache_dir
+
+ def iter_runtime_dirs(self) -> Iterator[str]:
+ """:yield: all user and site runtime directories."""
+ yield self.user_runtime_dir
+ yield self.site_runtime_dir
+
+ def iter_config_paths(self) -> Iterator[Path]:
+ """:yield: all user and site configuration paths."""
+ for path in self.iter_config_dirs():
+ yield Path(path)
+
+ def iter_data_paths(self) -> Iterator[Path]:
+ """:yield: all user and site data paths."""
+ for path in self.iter_data_dirs():
+ yield Path(path)
+
+ def iter_cache_paths(self) -> Iterator[Path]:
+ """:yield: all user and site cache paths."""
+ for path in self.iter_cache_dirs():
+ yield Path(path)
+
+ def iter_runtime_paths(self) -> Iterator[Path]:
+ """:yield: all user and site runtime paths."""
+ for path in self.iter_runtime_dirs():
+ yield Path(path)
diff --git a/.venv/lib/python3.12/site-packages/setuptools/_vendor/platformdirs/macos.py b/.venv/lib/python3.12/site-packages/setuptools/_vendor/platformdirs/macos.py
new file mode 100644
index 00000000..eb1ba5df
--- /dev/null
+++ b/.venv/lib/python3.12/site-packages/setuptools/_vendor/platformdirs/macos.py
@@ -0,0 +1,130 @@
+"""macOS."""
+
+from __future__ import annotations
+
+import os.path
+import sys
+
+from .api import PlatformDirsABC
+
+
+class MacOS(PlatformDirsABC):
+ """
+ Platform directories for the macOS operating system.
+
+ Follows the guidance from
+ `Apple documentation <https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/MacOSXDirectories/MacOSXDirectories.html>`_.
+ Makes use of the `appname <platformdirs.api.PlatformDirsABC.appname>`,
+ `version <platformdirs.api.PlatformDirsABC.version>`,
+ `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
+
+ """
+
+ @property
+ def user_data_dir(self) -> str:
+ """:return: data directory tied to the user, e.g. ``~/Library/Application Support/$appname/$version``"""
+ return self._append_app_name_and_version(os.path.expanduser("~/Library/Application Support")) # noqa: PTH111
+
+ @property
+ def site_data_dir(self) -> str:
+ """
+ :return: data directory shared by users, e.g. ``/Library/Application Support/$appname/$version``.
+ If we're using a Python binary managed by `Homebrew <https://brew.sh>`_, the directory
+ will be under the Homebrew prefix, e.g. ``/opt/homebrew/share/$appname/$version``.
+ If `multipath <platformdirs.api.PlatformDirsABC.multipath>` is enabled, and we're in Homebrew,
+ the response is a multi-path string separated by ":", e.g.
+ ``/opt/homebrew/share/$appname/$version:/Library/Application Support/$appname/$version``
+ """
+ is_homebrew = sys.prefix.startswith("/opt/homebrew")
+ path_list = [self._append_app_name_and_version("/opt/homebrew/share")] if is_homebrew else []
+ path_list.append(self._append_app_name_and_version("/Library/Application Support"))
+ if self.multipath:
+ return os.pathsep.join(path_list)
+ return path_list[0]
+
+ @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, e.g. ``~/Library/Caches/$appname/$version``"""
+ return self._append_app_name_and_version(os.path.expanduser("~/Library/Caches")) # noqa: PTH111
+
+ @property
+ def site_cache_dir(self) -> str:
+ """
+ :return: cache directory shared by users, e.g. ``/Library/Caches/$appname/$version``.
+ If we're using a Python binary managed by `Homebrew <https://brew.sh>`_, the directory
+ will be under the Homebrew prefix, e.g. ``/opt/homebrew/var/cache/$appname/$version``.
+ If `multipath <platformdirs.api.PlatformDirsABC.multipath>` is enabled, and we're in Homebrew,
+ the response is a multi-path string separated by ":", e.g.
+ ``/opt/homebrew/var/cache/$appname/$version:/Library/Caches/$appname/$version``
+ """
+ is_homebrew = sys.prefix.startswith("/opt/homebrew")
+ path_list = [self._append_app_name_and_version("/opt/homebrew/var/cache")] if is_homebrew else []
+ path_list.append(self._append_app_name_and_version("/Library/Caches"))
+ if self.multipath:
+ return os.pathsep.join(path_list)
+ return path_list[0]
+
+ @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, e.g. ``~/Library/Logs/$appname/$version``"""
+ return self._append_app_name_and_version(os.path.expanduser("~/Library/Logs")) # noqa: PTH111
+
+ @property
+ def user_documents_dir(self) -> str:
+ """:return: documents directory tied to the user, e.g. ``~/Documents``"""
+ return os.path.expanduser("~/Documents") # noqa: PTH111
+
+ @property
+ def user_downloads_dir(self) -> str:
+ """:return: downloads directory tied to the user, e.g. ``~/Downloads``"""
+ return os.path.expanduser("~/Downloads") # noqa: PTH111
+
+ @property
+ def user_pictures_dir(self) -> str:
+ """:return: pictures directory tied to the user, e.g. ``~/Pictures``"""
+ return os.path.expanduser("~/Pictures") # noqa: PTH111
+
+ @property
+ def user_videos_dir(self) -> str:
+ """:return: videos directory tied to the user, e.g. ``~/Movies``"""
+ return os.path.expanduser("~/Movies") # noqa: PTH111
+
+ @property
+ def user_music_dir(self) -> str:
+ """:return: music directory tied to the user, e.g. ``~/Music``"""
+ return os.path.expanduser("~/Music") # noqa: PTH111
+
+ @property
+ def user_desktop_dir(self) -> str:
+ """:return: desktop directory tied to the user, e.g. ``~/Desktop``"""
+ return os.path.expanduser("~/Desktop") # noqa: PTH111
+
+ @property
+ def user_runtime_dir(self) -> str:
+ """:return: runtime directory tied to the user, e.g. ``~/Library/Caches/TemporaryItems/$appname/$version``"""
+ return self._append_app_name_and_version(os.path.expanduser("~/Library/Caches/TemporaryItems")) # noqa: PTH111
+
+ @property
+ def site_runtime_dir(self) -> str:
+ """:return: runtime directory shared by users, same as `user_runtime_dir`"""
+ return self.user_runtime_dir
+
+
+__all__ = [
+ "MacOS",
+]
diff --git a/.venv/lib/python3.12/site-packages/setuptools/_vendor/platformdirs/py.typed b/.venv/lib/python3.12/site-packages/setuptools/_vendor/platformdirs/py.typed
new file mode 100644
index 00000000..e69de29b
--- /dev/null
+++ b/.venv/lib/python3.12/site-packages/setuptools/_vendor/platformdirs/py.typed
diff --git a/.venv/lib/python3.12/site-packages/setuptools/_vendor/platformdirs/unix.py b/.venv/lib/python3.12/site-packages/setuptools/_vendor/platformdirs/unix.py
new file mode 100644
index 00000000..9500ade6
--- /dev/null
+++ b/.venv/lib/python3.12/site-packages/setuptools/_vendor/platformdirs/unix.py
@@ -0,0 +1,275 @@
+"""Unix."""
+
+from __future__ import annotations
+
+import os
+import sys
+from configparser import ConfigParser
+from pathlib import Path
+from typing import Iterator, NoReturn
+
+from .api import PlatformDirsABC
+
+if sys.platform == "win32":
+
+ def getuid() -> NoReturn:
+ msg = "should only be used on Unix"
+ raise RuntimeError(msg)
+
+else:
+ from os import getuid
+
+
+class Unix(PlatformDirsABC): # noqa: PLR0904
+ """
+ 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 shown 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_dirs(self) -> list[str]:
+ path = os.environ.get("XDG_DATA_DIRS", "")
+ if not path.strip():
+ path = f"/usr/local/share{os.pathsep}/usr/share"
+ return [self._append_app_name_and_version(p) for p in path.split(os.pathsep)]
+
+ @property
+ def site_data_dir(self) -> str:
+ """
+ :return: data directories shared by users (if `multipath <platformdirs.api.PlatformDirsABC.multipath>` is
+ enabled and ``XDG_DATA_DIRS`` 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
+ dirs = self._site_data_dirs
+ if not self.multipath:
+ return dirs[0]
+ return os.pathsep.join(dirs)
+
+ @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_dirs(self) -> list[str]:
+ path = os.environ.get("XDG_CONFIG_DIRS", "")
+ if not path.strip():
+ path = "/etc/xdg"
+ return [self._append_app_name_and_version(p) for p in path.split(os.pathsep)]
+
+ @property
+ def site_config_dir(self) -> str:
+ """
+ :return: config directories shared by users (if `multipath <platformdirs.api.PlatformDirsABC.multipath>`
+ is enabled and ``XDG_CONFIG_DIRS`` 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
+ dirs = self._site_config_dirs
+ if not self.multipath:
+ return dirs[0]
+ return os.pathsep.join(dirs)
+
+ @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/cache/$appname/$version``"""
+ return self._append_app_name_and_version("/var/cache")
+
+ @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 the 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, returns the 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 the 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 iter_config_dirs(self) -> Iterator[str]:
+ """:yield: all user and site configuration directories."""
+ yield self.user_config_dir
+ yield from self._site_config_dirs
+
+ def iter_data_dirs(self) -> Iterator[str]:
+ """:yield: all user and site data directories."""
+ yield self.user_data_dir
+ yield from self._site_data_dirs
+
+
+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",
+]
diff --git a/.venv/lib/python3.12/site-packages/setuptools/_vendor/platformdirs/version.py b/.venv/lib/python3.12/site-packages/setuptools/_vendor/platformdirs/version.py
new file mode 100644
index 00000000..6483ddce
--- /dev/null
+++ b/.venv/lib/python3.12/site-packages/setuptools/_vendor/platformdirs/version.py
@@ -0,0 +1,16 @@
+# file generated by setuptools_scm
+# don't change, don't track in version control
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+ from typing import Tuple, Union
+ VERSION_TUPLE = Tuple[Union[int, str], ...]
+else:
+ VERSION_TUPLE = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+
+__version__ = version = '4.2.2'
+__version_tuple__ = version_tuple = (4, 2, 2)
diff --git a/.venv/lib/python3.12/site-packages/setuptools/_vendor/platformdirs/windows.py b/.venv/lib/python3.12/site-packages/setuptools/_vendor/platformdirs/windows.py
new file mode 100644
index 00000000..d7bc9609
--- /dev/null
+++ b/.venv/lib/python3.12/site-packages/setuptools/_vendor/platformdirs/windows.py
@@ -0,0 +1,272 @@
+"""Windows."""
+
+from __future__ import annotations
+
+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 <https://learn.microsoft.com/en-us/windows/win32/shell/knownfolderid>`_.
+
+ 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 a 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 # noqa: PLC0415
+
+ 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
+
+ import ctypes # noqa: PLC0415
+
+ 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]:
+ try:
+ import ctypes # noqa: PLC0415
+ except ImportError:
+ pass
+ else:
+ if hasattr(ctypes, "windll"):
+ return get_win_folder_via_ctypes
+ try:
+ import winreg # noqa: PLC0415, 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",
+]