codekingpro/portable-devtools

1"""Base API."""2 3from __future__ import annotations4 5import os6from abc import ABC, abstractmethod7from pathlib import Path8from typing import TYPE_CHECKING9 10if TYPE_CHECKING:11    from typing import Iterator, Literal12 13 14class PlatformDirsABC(ABC):  # noqa: PLR090415    """Abstract base class for platform directories."""16 17    def __init__(  # noqa: PLR0913, PLR091718        self,19        appname: str | None = None,20        appauthor: str | None | Literal[False] = None,21        version: str | None = None,22        roaming: bool = False,  # noqa: FBT001, FBT00223        multipath: bool = False,  # noqa: FBT001, FBT00224        opinion: bool = True,  # noqa: FBT001, FBT00225        ensure_exists: bool = False,  # noqa: FBT001, FBT00226    ) -> None:27        """28        Create a new platform directory.29 30        :param appname: See `appname`.31        :param appauthor: See `appauthor`.32        :param version: See `version`.33        :param roaming: See `roaming`.34        :param multipath: See `multipath`.35        :param opinion: See `opinion`.36        :param ensure_exists: See `ensure_exists`.37 38        """39        self.appname = appname  #: The name of application.40        self.appauthor = appauthor41        """42        The name of the app author or distributing body for this application.43 44        Typically, it is the owning company name. Defaults to `appname`. You may pass ``False`` to disable it.45 46        """47        self.version = version48        """49        An optional version path element to append to the path.50 51        You might want to use this if you want multiple versions of your app to be able to run independently. If used,52        this would typically be ``<major>.<minor>``.53 54        """55        self.roaming = roaming56        """57        Whether to use the roaming appdata directory on Windows.58 59        That means that for users on a Windows network setup for roaming profiles, this user data will be synced on60        login (see61        `here <https://technet.microsoft.com/en-us/library/cc766489(WS.10).aspx>`_).62 63        """64        self.multipath = multipath65        """66        An optional parameter which indicates that the entire list of data dirs should be returned.67 68        By default, the first item would only be returned.69 70        """71        self.opinion = opinion  #: A flag to indicating to use opinionated values.72        self.ensure_exists = ensure_exists73        """74        Optionally create the directory (and any missing parents) upon access if it does not exist.75 76        By default, no directories are created.77 78        """79 80    def _append_app_name_and_version(self, *base: str) -> str:81        params = list(base[1:])82        if self.appname:83            params.append(self.appname)84            if self.version:85                params.append(self.version)86        path = os.path.join(base[0], *params)  # noqa: PTH11887        self._optionally_create_directory(path)88        return path89 90    def _optionally_create_directory(self, path: str) -> None:91        if self.ensure_exists:92            Path(path).mkdir(parents=True, exist_ok=True)93 94    @property95    @abstractmethod96    def user_data_dir(self) -> str:97        """:return: data directory tied to the user"""98 99    @property100    @abstractmethod101    def site_data_dir(self) -> str:102        """:return: data directory shared by users"""103 104    @property105    @abstractmethod106    def user_config_dir(self) -> str:107        """:return: config directory tied to the user"""108 109    @property110    @abstractmethod111    def site_config_dir(self) -> str:112        """:return: config directory shared by the users"""113 114    @property115    @abstractmethod116    def user_cache_dir(self) -> str:117        """:return: cache directory tied to the user"""118 119    @property120    @abstractmethod121    def site_cache_dir(self) -> str:122        """:return: cache directory shared by users"""123 124    @property125    @abstractmethod126    def user_state_dir(self) -> str:127        """:return: state directory tied to the user"""128 129    @property130    @abstractmethod131    def user_log_dir(self) -> str:132        """:return: log directory tied to the user"""133 134    @property135    @abstractmethod136    def user_documents_dir(self) -> str:137        """:return: documents directory tied to the user"""138 139    @property140    @abstractmethod141    def user_downloads_dir(self) -> str:142        """:return: downloads directory tied to the user"""143 144    @property145    @abstractmethod146    def user_pictures_dir(self) -> str:147        """:return: pictures directory tied to the user"""148 149    @property150    @abstractmethod151    def user_videos_dir(self) -> str:152        """:return: videos directory tied to the user"""153 154    @property155    @abstractmethod156    def user_music_dir(self) -> str:157        """:return: music directory tied to the user"""158 159    @property160    @abstractmethod161    def user_desktop_dir(self) -> str:162        """:return: desktop directory tied to the user"""163 164    @property165    @abstractmethod166    def user_runtime_dir(self) -> str:167        """:return: runtime directory tied to the user"""168 169    @property170    @abstractmethod171    def site_runtime_dir(self) -> str:172        """:return: runtime directory shared by users"""173 174    @property175    def user_data_path(self) -> Path:176        """:return: data path tied to the user"""177        return Path(self.user_data_dir)178 179    @property180    def site_data_path(self) -> Path:181        """:return: data path shared by users"""182        return Path(self.site_data_dir)183 184    @property185    def user_config_path(self) -> Path:186        """:return: config path tied to the user"""187        return Path(self.user_config_dir)188 189    @property190    def site_config_path(self) -> Path:191        """:return: config path shared by the users"""192        return Path(self.site_config_dir)193 194    @property195    def user_cache_path(self) -> Path:196        """:return: cache path tied to the user"""197        return Path(self.user_cache_dir)198 199    @property200    def site_cache_path(self) -> Path:201        """:return: cache path shared by users"""202        return Path(self.site_cache_dir)203 204    @property205    def user_state_path(self) -> Path:206        """:return: state path tied to the user"""207        return Path(self.user_state_dir)208 209    @property210    def user_log_path(self) -> Path:211        """:return: log path tied to the user"""212        return Path(self.user_log_dir)213 214    @property215    def user_documents_path(self) -> Path:216        """:return: documents a path tied to the user"""217        return Path(self.user_documents_dir)218 219    @property220    def user_downloads_path(self) -> Path:221        """:return: downloads path tied to the user"""222        return Path(self.user_downloads_dir)223 224    @property225    def user_pictures_path(self) -> Path:226        """:return: pictures path tied to the user"""227        return Path(self.user_pictures_dir)228 229    @property230    def user_videos_path(self) -> Path:231        """:return: videos path tied to the user"""232        return Path(self.user_videos_dir)233 234    @property235    def user_music_path(self) -> Path:236        """:return: music path tied to the user"""237        return Path(self.user_music_dir)238 239    @property240    def user_desktop_path(self) -> Path:241        """:return: desktop path tied to the user"""242        return Path(self.user_desktop_dir)243 244    @property245    def user_runtime_path(self) -> Path:246        """:return: runtime path tied to the user"""247        return Path(self.user_runtime_dir)248 249    @property250    def site_runtime_path(self) -> Path:251        """:return: runtime path shared by users"""252        return Path(self.site_runtime_dir)253 254    def iter_config_dirs(self) -> Iterator[str]:255        """:yield: all user and site configuration directories."""256        yield self.user_config_dir257        yield self.site_config_dir258 259    def iter_data_dirs(self) -> Iterator[str]:260        """:yield: all user and site data directories."""261        yield self.user_data_dir262        yield self.site_data_dir263 264    def iter_cache_dirs(self) -> Iterator[str]:265        """:yield: all user and site cache directories."""266        yield self.user_cache_dir267        yield self.site_cache_dir268 269    def iter_runtime_dirs(self) -> Iterator[str]:270        """:yield: all user and site runtime directories."""271        yield self.user_runtime_dir272        yield self.site_runtime_dir273 274    def iter_config_paths(self) -> Iterator[Path]:275        """:yield: all user and site configuration paths."""276        for path in self.iter_config_dirs():277            yield Path(path)278 279    def iter_data_paths(self) -> Iterator[Path]:280        """:yield: all user and site data paths."""281        for path in self.iter_data_dirs():282            yield Path(path)283 284    def iter_cache_paths(self) -> Iterator[Path]:285        """:yield: all user and site cache paths."""286        for path in self.iter_cache_dirs():287            yield Path(path)288 289    def iter_runtime_paths(self) -> Iterator[Path]:290        """:yield: all user and site runtime paths."""291        for path in self.iter_runtime_dirs():292            yield Path(path)293