Source code for platformdirs

"""
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

if sys.platform == "win32":
    from platformdirs.windows import Windows as _Result
elif sys.platform == "darwin":
    from platformdirs.macos import MacOS as _Result
else:
    from platformdirs.unix import Unix as _Result


def _set_platform_dir_class() -> type[PlatformDirsABC]:
    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


if TYPE_CHECKING:
    # Work around mypy issue: https://github.com/python/mypy/issues/10962
    PlatformDirs = _Result
else:
    PlatformDirs = _set_platform_dir_class()  #: Currently active platform
AppDirs = PlatformDirs  #: Backwards compatibility with appdirs


[docs] 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
[docs] 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
[docs] 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
[docs] 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
[docs] 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
[docs] 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
[docs] 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
[docs] 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
[docs] def user_documents_dir() -> str: """:returns: documents directory tied to the user""" return PlatformDirs().user_documents_dir
[docs] def user_downloads_dir() -> str: """:returns: downloads directory tied to the user""" return PlatformDirs().user_downloads_dir
[docs] def user_pictures_dir() -> str: """:returns: pictures directory tied to the user""" return PlatformDirs().user_pictures_dir
[docs] def user_videos_dir() -> str: """:returns: videos directory tied to the user""" return PlatformDirs().user_videos_dir
[docs] 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
[docs] 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
[docs] 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
[docs] 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
[docs] 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
[docs] 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
[docs] 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
[docs] 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
[docs] 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
[docs] 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
[docs] def user_documents_path() -> Path: """:returns: documents a path tied to the user""" return PlatformDirs().user_documents_path
[docs] def user_downloads_path() -> Path: """:returns: downloads path tied to the user""" return PlatformDirs().user_downloads_path
[docs] def user_pictures_path() -> Path: """:returns: pictures path tied to the user""" return PlatformDirs().user_pictures_path
[docs] def user_videos_path() -> Path: """:returns: videos path tied to the user""" return PlatformDirs().user_videos_path
[docs] 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
[docs] 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", ]