codekingpro/portable-devtools

1"""2Utilities for determining application-specific dirs.3 4See <https://github.com/platformdirs/platformdirs> for details and usage.5 6"""7 8from __future__ import annotations9 10import os11import sys12from typing import TYPE_CHECKING13 14from .api import PlatformDirsABC15from .version import __version__16from .version import __version_tuple__ as __version_info__17 18if TYPE_CHECKING:19    from pathlib import Path20    from typing import Literal21 22 23def _set_platform_dir_class() -> type[PlatformDirsABC]:24    if sys.platform == "win32":25        from platformdirs.windows import Windows as Result  # noqa: PLC041526    elif sys.platform == "darwin":27        from platformdirs.macos import MacOS as Result  # noqa: PLC041528    else:29        from platformdirs.unix import Unix as Result  # noqa: PLC041530 31    if os.getenv("ANDROID_DATA") == "/data" and os.getenv("ANDROID_ROOT") == "/system":32        if os.getenv("SHELL") or os.getenv("PREFIX"):33            return Result34 35        from platformdirs.android import _android_folder  # noqa: PLC041536 37        if _android_folder() is not None:38            from platformdirs.android import Android  # noqa: PLC041539 40            return Android  # return to avoid redefinition of a result41 42    return Result43 44 45PlatformDirs = _set_platform_dir_class()  #: Currently active platform46AppDirs = PlatformDirs  #: Backwards compatibility with appdirs47 48 49def user_data_dir(50    appname: str | None = None,51    appauthor: str | None | Literal[False] = None,52    version: str | None = None,53    roaming: bool = False,  # noqa: FBT001, FBT00254    ensure_exists: bool = False,  # noqa: FBT001, FBT00255) -> str:56    """57    :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.58    :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.59    :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.60    :param roaming: See `roaming <platformdirs.api.PlatformDirsABC.roaming>`.61    :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.62    :returns: data directory tied to the user63    """64    return PlatformDirs(65        appname=appname,66        appauthor=appauthor,67        version=version,68        roaming=roaming,69        ensure_exists=ensure_exists,70    ).user_data_dir71 72 73def site_data_dir(74    appname: str | None = None,75    appauthor: str | None | Literal[False] = None,76    version: str | None = None,77    multipath: bool = False,  # noqa: FBT001, FBT00278    ensure_exists: bool = False,  # noqa: FBT001, FBT00279) -> str:80    """81    :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.82    :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.83    :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.84    :param multipath: See `roaming <platformdirs.api.PlatformDirsABC.multipath>`.85    :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.86    :returns: data directory shared by users87    """88    return PlatformDirs(89        appname=appname,90        appauthor=appauthor,91        version=version,92        multipath=multipath,93        ensure_exists=ensure_exists,94    ).site_data_dir95 96 97def user_config_dir(98    appname: str | None = None,99    appauthor: str | None | Literal[False] = None,100    version: str | None = None,101    roaming: bool = False,  # noqa: FBT001, FBT002102    ensure_exists: bool = False,  # noqa: FBT001, FBT002103) -> str:104    """105    :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.106    :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.107    :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.108    :param roaming: See `roaming <platformdirs.api.PlatformDirsABC.roaming>`.109    :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.110    :returns: config directory tied to the user111    """112    return PlatformDirs(113        appname=appname,114        appauthor=appauthor,115        version=version,116        roaming=roaming,117        ensure_exists=ensure_exists,118    ).user_config_dir119 120 121def site_config_dir(122    appname: str | None = None,123    appauthor: str | None | Literal[False] = None,124    version: str | None = None,125    multipath: bool = False,  # noqa: FBT001, FBT002126    ensure_exists: bool = False,  # noqa: FBT001, FBT002127) -> str:128    """129    :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.130    :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.131    :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.132    :param multipath: See `roaming <platformdirs.api.PlatformDirsABC.multipath>`.133    :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.134    :returns: config directory shared by the users135    """136    return PlatformDirs(137        appname=appname,138        appauthor=appauthor,139        version=version,140        multipath=multipath,141        ensure_exists=ensure_exists,142    ).site_config_dir143 144 145def user_cache_dir(146    appname: str | None = None,147    appauthor: str | None | Literal[False] = None,148    version: str | None = None,149    opinion: bool = True,  # noqa: FBT001, FBT002150    ensure_exists: bool = False,  # noqa: FBT001, FBT002151) -> str:152    """153    :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.154    :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.155    :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.156    :param opinion: See `roaming <platformdirs.api.PlatformDirsABC.opinion>`.157    :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.158    :returns: cache directory tied to the user159    """160    return PlatformDirs(161        appname=appname,162        appauthor=appauthor,163        version=version,164        opinion=opinion,165        ensure_exists=ensure_exists,166    ).user_cache_dir167 168 169def site_cache_dir(170    appname: str | None = None,171    appauthor: str | None | Literal[False] = None,172    version: str | None = None,173    opinion: bool = True,  # noqa: FBT001, FBT002174    ensure_exists: bool = False,  # noqa: FBT001, FBT002175) -> str:176    """177    :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.178    :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.179    :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.180    :param opinion: See `opinion <platformdirs.api.PlatformDirsABC.opinion>`.181    :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.182    :returns: cache directory tied to the user183    """184    return PlatformDirs(185        appname=appname,186        appauthor=appauthor,187        version=version,188        opinion=opinion,189        ensure_exists=ensure_exists,190    ).site_cache_dir191 192 193def user_state_dir(194    appname: str | None = None,195    appauthor: str | None | Literal[False] = None,196    version: str | None = None,197    roaming: bool = False,  # noqa: FBT001, FBT002198    ensure_exists: bool = False,  # noqa: FBT001, FBT002199) -> str:200    """201    :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.202    :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.203    :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.204    :param roaming: See `roaming <platformdirs.api.PlatformDirsABC.roaming>`.205    :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.206    :returns: state directory tied to the user207    """208    return PlatformDirs(209        appname=appname,210        appauthor=appauthor,211        version=version,212        roaming=roaming,213        ensure_exists=ensure_exists,214    ).user_state_dir215 216 217def user_log_dir(218    appname: str | None = None,219    appauthor: str | None | Literal[False] = None,220    version: str | None = None,221    opinion: bool = True,  # noqa: FBT001, FBT002222    ensure_exists: bool = False,  # noqa: FBT001, FBT002223) -> str:224    """225    :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.226    :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.227    :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.228    :param opinion: See `roaming <platformdirs.api.PlatformDirsABC.opinion>`.229    :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.230    :returns: log directory tied to the user231    """232    return PlatformDirs(233        appname=appname,234        appauthor=appauthor,235        version=version,236        opinion=opinion,237        ensure_exists=ensure_exists,238    ).user_log_dir239 240 241def user_documents_dir() -> str:242    """:returns: documents directory tied to the user"""243    return PlatformDirs().user_documents_dir244 245 246def user_downloads_dir() -> str:247    """:returns: downloads directory tied to the user"""248    return PlatformDirs().user_downloads_dir249 250 251def user_pictures_dir() -> str:252    """:returns: pictures directory tied to the user"""253    return PlatformDirs().user_pictures_dir254 255 256def user_videos_dir() -> str:257    """:returns: videos directory tied to the user"""258    return PlatformDirs().user_videos_dir259 260 261def user_music_dir() -> str:262    """:returns: music directory tied to the user"""263    return PlatformDirs().user_music_dir264 265 266def user_desktop_dir() -> str:267    """:returns: desktop directory tied to the user"""268    return PlatformDirs().user_desktop_dir269 270 271def user_runtime_dir(272    appname: str | None = None,273    appauthor: str | None | Literal[False] = None,274    version: str | None = None,275    opinion: bool = True,  # noqa: FBT001, FBT002276    ensure_exists: bool = False,  # noqa: FBT001, FBT002277) -> str:278    """279    :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.280    :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.281    :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.282    :param opinion: See `opinion <platformdirs.api.PlatformDirsABC.opinion>`.283    :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.284    :returns: runtime directory tied to the user285    """286    return PlatformDirs(287        appname=appname,288        appauthor=appauthor,289        version=version,290        opinion=opinion,291        ensure_exists=ensure_exists,292    ).user_runtime_dir293 294 295def site_runtime_dir(296    appname: str | None = None,297    appauthor: str | None | Literal[False] = None,298    version: str | None = None,299    opinion: bool = True,  # noqa: FBT001, FBT002300    ensure_exists: bool = False,  # noqa: FBT001, FBT002301) -> str:302    """303    :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.304    :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.305    :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.306    :param opinion: See `opinion <platformdirs.api.PlatformDirsABC.opinion>`.307    :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.308    :returns: runtime directory shared by users309    """310    return PlatformDirs(311        appname=appname,312        appauthor=appauthor,313        version=version,314        opinion=opinion,315        ensure_exists=ensure_exists,316    ).site_runtime_dir317 318 319def user_data_path(320    appname: str | None = None,321    appauthor: str | None | Literal[False] = None,322    version: str | None = None,323    roaming: bool = False,  # noqa: FBT001, FBT002324    ensure_exists: bool = False,  # noqa: FBT001, FBT002325) -> Path:326    """327    :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.328    :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.329    :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.330    :param roaming: See `roaming <platformdirs.api.PlatformDirsABC.roaming>`.331    :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.332    :returns: data path tied to the user333    """334    return PlatformDirs(335        appname=appname,336        appauthor=appauthor,337        version=version,338        roaming=roaming,339        ensure_exists=ensure_exists,340    ).user_data_path341 342 343def site_data_path(344    appname: str | None = None,345    appauthor: str | None | Literal[False] = None,346    version: str | None = None,347    multipath: bool = False,  # noqa: FBT001, FBT002348    ensure_exists: bool = False,  # noqa: FBT001, FBT002349) -> Path:350    """351    :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.352    :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.353    :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.354    :param multipath: See `multipath <platformdirs.api.PlatformDirsABC.multipath>`.355    :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.356    :returns: data path shared by users357    """358    return PlatformDirs(359        appname=appname,360        appauthor=appauthor,361        version=version,362        multipath=multipath,363        ensure_exists=ensure_exists,364    ).site_data_path365 366 367def user_config_path(368    appname: str | None = None,369    appauthor: str | None | Literal[False] = None,370    version: str | None = None,371    roaming: bool = False,  # noqa: FBT001, FBT002372    ensure_exists: bool = False,  # noqa: FBT001, FBT002373) -> Path:374    """375    :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.376    :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.377    :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.378    :param roaming: See `roaming <platformdirs.api.PlatformDirsABC.roaming>`.379    :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.380    :returns: config path tied to the user381    """382    return PlatformDirs(383        appname=appname,384        appauthor=appauthor,385        version=version,386        roaming=roaming,387        ensure_exists=ensure_exists,388    ).user_config_path389 390 391def site_config_path(392    appname: str | None = None,393    appauthor: str | None | Literal[False] = None,394    version: str | None = None,395    multipath: bool = False,  # noqa: FBT001, FBT002396    ensure_exists: bool = False,  # noqa: FBT001, FBT002397) -> Path:398    """399    :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.400    :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.401    :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.402    :param multipath: See `roaming <platformdirs.api.PlatformDirsABC.multipath>`.403    :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.404    :returns: config path shared by the users405    """406    return PlatformDirs(407        appname=appname,408        appauthor=appauthor,409        version=version,410        multipath=multipath,411        ensure_exists=ensure_exists,412    ).site_config_path413 414 415def site_cache_path(416    appname: str | None = None,417    appauthor: str | None | Literal[False] = None,418    version: str | None = None,419    opinion: bool = True,  # noqa: FBT001, FBT002420    ensure_exists: bool = False,  # noqa: FBT001, FBT002421) -> Path:422    """423    :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.424    :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.425    :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.426    :param opinion: See `opinion <platformdirs.api.PlatformDirsABC.opinion>`.427    :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.428    :returns: cache directory tied to the user429    """430    return PlatformDirs(431        appname=appname,432        appauthor=appauthor,433        version=version,434        opinion=opinion,435        ensure_exists=ensure_exists,436    ).site_cache_path437 438 439def user_cache_path(440    appname: str | None = None,441    appauthor: str | None | Literal[False] = None,442    version: str | None = None,443    opinion: bool = True,  # noqa: FBT001, FBT002444    ensure_exists: bool = False,  # noqa: FBT001, FBT002445) -> Path:446    """447    :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.448    :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.449    :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.450    :param opinion: See `roaming <platformdirs.api.PlatformDirsABC.opinion>`.451    :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.452    :returns: cache path tied to the user453    """454    return PlatformDirs(455        appname=appname,456        appauthor=appauthor,457        version=version,458        opinion=opinion,459        ensure_exists=ensure_exists,460    ).user_cache_path461 462 463def user_state_path(464    appname: str | None = None,465    appauthor: str | None | Literal[False] = None,466    version: str | None = None,467    roaming: bool = False,  # noqa: FBT001, FBT002468    ensure_exists: bool = False,  # noqa: FBT001, FBT002469) -> Path:470    """471    :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.472    :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.473    :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.474    :param roaming: See `roaming <platformdirs.api.PlatformDirsABC.roaming>`.475    :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.476    :returns: state path tied to the user477    """478    return PlatformDirs(479        appname=appname,480        appauthor=appauthor,481        version=version,482        roaming=roaming,483        ensure_exists=ensure_exists,484    ).user_state_path485 486 487def user_log_path(488    appname: str | None = None,489    appauthor: str | None | Literal[False] = None,490    version: str | None = None,491    opinion: bool = True,  # noqa: FBT001, FBT002492    ensure_exists: bool = False,  # noqa: FBT001, FBT002493) -> Path:494    """495    :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.496    :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.497    :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.498    :param opinion: See `roaming <platformdirs.api.PlatformDirsABC.opinion>`.499    :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.500    :returns: log path tied to the user501    """502    return PlatformDirs(503        appname=appname,504        appauthor=appauthor,505        version=version,506        opinion=opinion,507        ensure_exists=ensure_exists,508    ).user_log_path509 510 511def user_documents_path() -> Path:512    """:returns: documents a path tied to the user"""513    return PlatformDirs().user_documents_path514 515 516def user_downloads_path() -> Path:517    """:returns: downloads path tied to the user"""518    return PlatformDirs().user_downloads_path519 520 521def user_pictures_path() -> Path:522    """:returns: pictures path tied to the user"""523    return PlatformDirs().user_pictures_path524 525 526def user_videos_path() -> Path:527    """:returns: videos path tied to the user"""528    return PlatformDirs().user_videos_path529 530 531def user_music_path() -> Path:532    """:returns: music path tied to the user"""533    return PlatformDirs().user_music_path534 535 536def user_desktop_path() -> Path:537    """:returns: desktop path tied to the user"""538    return PlatformDirs().user_desktop_path539 540 541def user_runtime_path(542    appname: str | None = None,543    appauthor: str | None | Literal[False] = None,544    version: str | None = None,545    opinion: bool = True,  # noqa: FBT001, FBT002546    ensure_exists: bool = False,  # noqa: FBT001, FBT002547) -> Path:548    """549    :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.550    :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.551    :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.552    :param opinion: See `opinion <platformdirs.api.PlatformDirsABC.opinion>`.553    :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.554    :returns: runtime path tied to the user555    """556    return PlatformDirs(557        appname=appname,558        appauthor=appauthor,559        version=version,560        opinion=opinion,561        ensure_exists=ensure_exists,562    ).user_runtime_path563 564 565def site_runtime_path(566    appname: str | None = None,567    appauthor: str | None | Literal[False] = None,568    version: str | None = None,569    opinion: bool = True,  # noqa: FBT001, FBT002570    ensure_exists: bool = False,  # noqa: FBT001, FBT002571) -> Path:572    """573    :param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.574    :param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.575    :param version: See `version <platformdirs.api.PlatformDirsABC.version>`.576    :param opinion: See `opinion <platformdirs.api.PlatformDirsABC.opinion>`.577    :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.578    :returns: runtime path shared by users579    """580    return PlatformDirs(581        appname=appname,582        appauthor=appauthor,583        version=version,584        opinion=opinion,585        ensure_exists=ensure_exists,586    ).site_runtime_path587 588 589__all__ = [590    "AppDirs",591    "PlatformDirs",592    "PlatformDirsABC",593    "__version__",594    "__version_info__",595    "site_cache_dir",596    "site_cache_path",597    "site_config_dir",598    "site_config_path",599    "site_data_dir",600    "site_data_path",601    "site_runtime_dir",602    "site_runtime_path",603    "user_cache_dir",604    "user_cache_path",605    "user_config_dir",606    "user_config_path",607    "user_data_dir",608    "user_data_path",609    "user_desktop_dir",610    "user_desktop_path",611    "user_documents_dir",612    "user_documents_path",613    "user_downloads_dir",614    "user_downloads_path",615    "user_log_dir",616    "user_log_path",617    "user_music_dir",618    "user_music_path",619    "user_pictures_dir",620    "user_pictures_path",621    "user_runtime_dir",622    "user_runtime_path",623    "user_state_dir",624    "user_state_path",625    "user_videos_dir",626    "user_videos_path",627]628