pip._vendor.platformdirs.windows Namespace Reference

Data Structures
class	Windows

Functions
str	get_win_folder_from_env_vars (str csidl_name)
str|None	get_win_folder_if_csidl_name_not_env_var (str csidl_name)
str	get_win_folder_from_registry (str csidl_name)
str	get_win_folder_via_ctypes (str csidl_name)
Callable[[str], str]	_pick_get_win_folder ()

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

Detailed Description

Windows.

Function Documentation

_pick_get_win_folder()

Callable[[str], str] _pick_get_win_folder ( )

protected

Definition at line 240 of file windows.py.

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
 
 

References i.

get_win_folder_from_env_vars()

str get_win_folder_from_env_vars

(

str

csidl_name

)

Get folder from environment variables.

Definition at line 135 of file windows.py.

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
 
 

References pip._vendor.platformdirs.windows.get_win_folder_if_csidl_name_not_env_var(), and i.

Here is the call graph for this function:

get_win_folder_from_registry()

str get_win_folder_from_registry

(

str

csidl_name

)

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.

Definition at line 175 of file windows.py.

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)
 
 

References i.

get_win_folder_if_csidl_name_not_env_var()

str | None get_win_folder_if_csidl_name_not_env_var

(

str

csidl_name

)

Get folder for a CSIDL name that does not exist as an environment variable.

Definition at line 156 of file windows.py.

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
 
 

References i.

Referenced by pip._vendor.platformdirs.windows.get_win_folder_from_env_vars().

Here is the caller graph for this function:

get_win_folder_via_ctypes()

str get_win_folder_via_ctypes

(

str

csidl_name

)

Get folder with ctypes.

Definition at line 204 of file windows.py.

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,
    }.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 highbit 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
 
 

References i.

Variable Documentation

get_win_folder

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

Definition at line 251 of file windows.py.

Referenced by Windows.site_cache_dir(), Windows.site_data_dir(), Windows.user_cache_dir(), Windows.user_data_dir(), Windows.user_documents_dir(), Windows.user_downloads_dir(), Windows.user_music_dir(), Windows.user_pictures_dir(), Windows.user_runtime_dir(), and Windows.user_videos_dir().