diff --git a/lib/platformdirs/__init__.py b/lib/platformdirs/__init__.py index 75c8bff9..3f7d9490 100644 --- a/lib/platformdirs/__init__.py +++ b/lib/platformdirs/__init__.py @@ -1,6 +1,8 @@ """ -Utilities for determining application-specific dirs. See for details and -usage. +Utilities for determining application-specific dirs. + +See for details and usage. + """ from __future__ import annotations @@ -20,22 +22,22 @@ if TYPE_CHECKING: def _set_platform_dir_class() -> type[PlatformDirsABC]: if sys.platform == "win32": - from platformdirs.windows import Windows as Result + from platformdirs.windows import Windows as Result # noqa: PLC0415 elif sys.platform == "darwin": - from platformdirs.macos import MacOS as Result + from platformdirs.macos import MacOS as Result # noqa: PLC0415 else: - from platformdirs.unix import Unix as Result + 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 + from platformdirs.android import _android_folder # noqa: PLC0415 if _android_folder() is not None: - from platformdirs.android import Android + from platformdirs.android import Android # noqa: PLC0415 - return Android # return to avoid redefinition of result + return Android # return to avoid redefinition of a result return Result @@ -507,7 +509,7 @@ def user_log_path( def user_documents_path() -> Path: - """:returns: documents path tied to the user""" + """:returns: documents a path tied to the user""" return PlatformDirs().user_documents_path @@ -585,41 +587,41 @@ def site_runtime_path( __all__ = [ + "AppDirs", + "PlatformDirs", + "PlatformDirsABC", "__version__", "__version_info__", - "PlatformDirs", - "AppDirs", - "PlatformDirsABC", - "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_desktop_dir", - "user_runtime_dir", - "site_data_dir", - "site_config_dir", "site_cache_dir", - "site_runtime_dir", - "user_data_path", - "user_config_path", - "user_cache_path", - "user_state_path", - "user_log_path", - "user_documents_path", - "user_downloads_path", - "user_pictures_path", - "user_videos_path", - "user_music_path", - "user_desktop_path", - "user_runtime_path", - "site_data_path", - "site_config_path", "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/lib/platformdirs/__main__.py b/lib/platformdirs/__main__.py index 4bf27c9c..922c5213 100644 --- a/lib/platformdirs/__main__.py +++ b/lib/platformdirs/__main__.py @@ -24,7 +24,7 @@ PROPS = ( def main() -> None: - """Run main entry point.""" + """Run the main entry point.""" app_name = "MyApp" app_author = "MyCompany" diff --git a/lib/platformdirs/android.py b/lib/platformdirs/android.py index 4acdb638..fefafd32 100644 --- a/lib/platformdirs/android.py +++ b/lib/platformdirs/android.py @@ -13,10 +13,11 @@ from .api import PlatformDirsABC class Android(PlatformDirsABC): """ - Follows the guidance `from here `_. Makes use of the - `appname `, - `version `, - `ensure_exists `. + Follows the guidance `from here `_. + + Makes use of the `appname `, `version + `, `ensure_exists `. + """ @property @@ -44,7 +45,7 @@ class Android(PlatformDirsABC): @property def user_cache_dir(self) -> str: - """:return: cache directory tied to the user, e.g. e.g. ``/data/user///cache/``""" + """:return: cache directory tied to the user, e.g.,``/data/user///cache/``""" return self._append_app_name_and_version(cast(str, _android_folder()), "cache") @property @@ -119,13 +120,13 @@ class Android(PlatformDirsABC): def _android_folder() -> str | None: """:return: base folder for the Android OS or None if it cannot be found""" try: - # First try to get path to android app via pyjnius - from jnius import autoclass + # First try to get a path to android app via pyjnius + from jnius import autoclass # noqa: PLC0415 context = autoclass("android.content.Context") result: str | None = context.getFilesDir().getParentFile().getAbsolutePath() except Exception: # noqa: BLE001 - # if fails find an android folder looking path on the sys.path + # if fails find an android folder looking a path on the sys.path pattern = re.compile(r"/data/(data|user/\d+)/(.+)/files") for path in sys.path: if pattern.match(path): @@ -141,7 +142,7 @@ def _android_documents_folder() -> str: """:return: documents folder for the Android OS""" # Get directories with pyjnius try: - from jnius import autoclass + from jnius import autoclass # noqa: PLC0415 context = autoclass("android.content.Context") environment = autoclass("android.os.Environment") @@ -157,7 +158,7 @@ def _android_downloads_folder() -> str: """:return: downloads folder for the Android OS""" # Get directories with pyjnius try: - from jnius import autoclass + from jnius import autoclass # noqa: PLC0415 context = autoclass("android.content.Context") environment = autoclass("android.os.Environment") @@ -173,7 +174,7 @@ def _android_pictures_folder() -> str: """:return: pictures folder for the Android OS""" # Get directories with pyjnius try: - from jnius import autoclass + from jnius import autoclass # noqa: PLC0415 context = autoclass("android.content.Context") environment = autoclass("android.os.Environment") @@ -189,7 +190,7 @@ def _android_videos_folder() -> str: """:return: videos folder for the Android OS""" # Get directories with pyjnius try: - from jnius import autoclass + from jnius import autoclass # noqa: PLC0415 context = autoclass("android.content.Context") environment = autoclass("android.os.Environment") @@ -205,7 +206,7 @@ def _android_music_folder() -> str: """:return: music folder for the Android OS""" # Get directories with pyjnius try: - from jnius import autoclass + from jnius import autoclass # noqa: PLC0415 context = autoclass("android.content.Context") environment = autoclass("android.os.Environment") diff --git a/lib/platformdirs/api.py b/lib/platformdirs/api.py index 031a38a3..c50caa64 100644 --- a/lib/platformdirs/api.py +++ b/lib/platformdirs/api.py @@ -11,10 +11,10 @@ if TYPE_CHECKING: from typing import Iterator, Literal -class PlatformDirsABC(ABC): +class PlatformDirsABC(ABC): # noqa: PLR0904 """Abstract base class for platform directories.""" - def __init__( # noqa: PLR0913 + def __init__( # noqa: PLR0913, PLR0917 self, appname: str | None = None, appauthor: str | None | Literal[False] = None, @@ -34,34 +34,47 @@ class PlatformDirsABC(ABC): :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. + 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 ``.``. + 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 ``.``. + """ 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 `_). + 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 `_). + """ 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: @@ -200,7 +213,7 @@ class PlatformDirsABC(ABC): @property def user_documents_path(self) -> Path: - """:return: documents path tied to the user""" + """:return: documents a path tied to the user""" return Path(self.user_documents_dir) @property diff --git a/lib/platformdirs/macos.py b/lib/platformdirs/macos.py index b7b48808..eb1ba5df 100644 --- a/lib/platformdirs/macos.py +++ b/lib/platformdirs/macos.py @@ -10,11 +10,14 @@ from .api import PlatformDirsABC class MacOS(PlatformDirsABC): """ - Platform directories for the macOS operating system. Follows the guidance from `Apple documentation - `_. + Platform directories for the macOS operating system. + + Follows the guidance from + `Apple documentation `_. Makes use of the `appname `, `version `, `ensure_exists `. + """ @property @@ -28,7 +31,7 @@ class MacOS(PlatformDirsABC): :return: data directory shared by users, e.g. ``/Library/Application Support/$appname/$version``. If we're using a Python binary managed by `Homebrew `_, the directory will be under the Homebrew prefix, e.g. ``/opt/homebrew/share/$appname/$version``. - If `multipath ` is enabled and we're in Homebrew, + If `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`` """ @@ -60,7 +63,7 @@ class MacOS(PlatformDirsABC): :return: cache directory shared by users, e.g. ``/Library/Caches/$appname/$version``. If we're using a Python binary managed by `Homebrew `_, the directory will be under the Homebrew prefix, e.g. ``/opt/homebrew/var/cache/$appname/$version``. - If `multipath ` is enabled and we're in Homebrew, + If `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`` """ diff --git a/lib/platformdirs/unix.py b/lib/platformdirs/unix.py index ca4728e6..9500ade6 100644 --- a/lib/platformdirs/unix.py +++ b/lib/platformdirs/unix.py @@ -6,13 +6,13 @@ import os import sys from configparser import ConfigParser from pathlib import Path -from typing import Iterator +from typing import Iterator, NoReturn from .api import PlatformDirsABC if sys.platform == "win32": - def getuid() -> int: + def getuid() -> NoReturn: msg = "should only be used on Unix" raise RuntimeError(msg) @@ -20,17 +20,17 @@ else: from os import getuid -class Unix(PlatformDirsABC): +class Unix(PlatformDirsABC): # noqa: PLR0904 """ - On Unix/Linux, we follow the - `XDG Basedir Spec `_. The spec allows - overriding directories with environment variables. The examples show are the default values, alongside the name of - the environment variable that overrides them. Makes use of the - `appname `, - `version `, - `multipath `, - `opinion `, - `ensure_exists `. + On Unix/Linux, we follow the `XDG Basedir Spec `_. + + 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 + `, `version `, `multipath + `, `opinion `, `ensure_exists + `. + """ @property @@ -205,17 +205,17 @@ class Unix(PlatformDirsABC): @property def site_data_path(self) -> Path: - """:return: data path shared by users. Only return first item, even if ``multipath`` is set to ``True``""" + """: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. Only return first item, even if ``multipath`` is set to ``True``""" + """: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 first item, even if ``multipath`` is set to ``True``""" + """: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: @@ -246,7 +246,12 @@ def _get_user_media_dir(env_var: str, fallback_tilde_path: str) -> str: 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/.""" + """ + 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() diff --git a/lib/platformdirs/version.py b/lib/platformdirs/version.py index cc1e3456..c418cd0c 100644 --- a/lib/platformdirs/version.py +++ b/lib/platformdirs/version.py @@ -12,5 +12,5 @@ __version__: str __version_tuple__: VERSION_TUPLE version_tuple: VERSION_TUPLE -__version__ = version = '4.2.0' -__version_tuple__ = version_tuple = (4, 2, 0) +__version__ = version = '4.2.1' +__version_tuple__ = version_tuple = (4, 2, 1) diff --git a/lib/platformdirs/windows.py b/lib/platformdirs/windows.py index c62d0c8d..d7bc9609 100644 --- a/lib/platformdirs/windows.py +++ b/lib/platformdirs/windows.py @@ -2,7 +2,6 @@ from __future__ import annotations -import ctypes import os import sys from functools import lru_cache @@ -16,15 +15,13 @@ if TYPE_CHECKING: class Windows(PlatformDirsABC): """ - `MSDN on where to store app data files - `_. - Makes use of the - `appname `, - `appauthor `, - `version `, - `roaming `, - `opinion `, - `ensure_exists `. + `MSDN on where to store app data files `_. + + Makes use of the `appname `, `appauthor + `, `version `, `roaming + `, `opinion `, `ensure_exists + `. + """ @property @@ -165,7 +162,7 @@ def get_win_folder_from_env_vars(csidl_name: str) -> str: 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.""" + """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 @@ -189,6 +186,7 @@ def get_win_folder_from_registry(csidl_name: str) -> str: 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", @@ -205,7 +203,7 @@ def get_win_folder_from_registry(csidl_name: str) -> str: 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 + 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) @@ -218,6 +216,8 @@ def get_win_folder_via_ctypes(csidl_name: str) -> str: # 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, @@ -250,10 +250,15 @@ def get_win_folder_via_ctypes(csidl_name: str) -> str: def _pick_get_win_folder() -> Callable[[str], str]: - if hasattr(ctypes, "windll"): - return get_win_folder_via_ctypes try: - import winreg # noqa: F401 + 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: