From 3fa075bbe51dd4b0773eb64649ca4994a3b347fe Mon Sep 17 00:00:00 2001 From: Ruslan Kuprieiev Date: Fri, 3 Mar 2023 17:59:15 +0200 Subject: [PATCH] platformdirs: introduce site_cache_dir (#145) --- docs/api.rst | 6 ++++++ src/platformdirs/__init__.py | 34 ++++++++++++++++++++++++++++++++++ src/platformdirs/__main__.py | 1 + src/platformdirs/android.py | 5 +++++ src/platformdirs/api.py | 10 ++++++++++ src/platformdirs/macos.py | 5 +++++ src/platformdirs/unix.py | 12 ++++++++++++ src/platformdirs/windows.py | 6 ++++++ tests/conftest.py | 1 + tests/test_android.py | 1 + tests/test_macos.py | 1 + 11 files changed, 82 insertions(+) diff --git a/docs/api.rst b/docs/api.rst index 44ab1530..60e76b36 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -65,6 +65,12 @@ Shared config directory .. autofunction:: platformdirs.site_config_dir .. autofunction:: platformdirs.site_config_path +Shared cache directory +---------------------- + +.. autofunction:: platformdirs.site_cache_dir +.. autofunction:: platformdirs.site_cache_path + Platforms ~~~~~~~~~ diff --git a/src/platformdirs/__init__.py b/src/platformdirs/__init__.py index d4bd1448..68cc860c 100644 --- a/src/platformdirs/__init__.py +++ b/src/platformdirs/__init__.py @@ -124,6 +124,22 @@ def user_cache_dir( return PlatformDirs(appname=appname, appauthor=appauthor, version=version, opinion=opinion).user_cache_dir +def site_cache_dir( + appname: str | None = None, + appauthor: str | None | Literal[False] = None, + version: str | None = None, + opinion: bool = True, +) -> str: + """ + :param appname: See `appname `. + :param appauthor: See `appauthor `. + :param version: See `version `. + :param opinion: See `opinion `. + :returns: cache directory tied to the user + """ + return PlatformDirs(appname=appname, appauthor=appauthor, version=version, opinion=opinion).site_cache_dir + + def user_state_dir( appname: str | None = None, appauthor: str | None | Literal[False] = None, @@ -243,6 +259,22 @@ def site_config_path( return PlatformDirs(appname=appname, appauthor=appauthor, version=version, multipath=multipath).site_config_path +def site_cache_path( + appname: str | None = None, + appauthor: str | None | Literal[False] = None, + version: str | None = None, + opinion: bool = True, +) -> Path: + """ + :param appname: See `appname `. + :param appauthor: See `appauthor `. + :param version: See `version `. + :param opinion: See `opinion `. + :returns: cache directory tied to the user + """ + return PlatformDirs(appname=appname, appauthor=appauthor, version=version, opinion=opinion).site_cache_path + + def user_cache_path( appname: str | None = None, appauthor: str | None | Literal[False] = None, @@ -329,6 +361,7 @@ def user_runtime_path( "user_runtime_dir", "site_data_dir", "site_config_dir", + "site_cache_dir", "user_data_path", "user_config_path", "user_cache_path", @@ -338,4 +371,5 @@ def user_runtime_path( "user_runtime_path", "site_data_path", "site_config_path", + "site_cache_path", ] diff --git a/src/platformdirs/__main__.py b/src/platformdirs/__main__.py index 0fc1edd5..b740787b 100644 --- a/src/platformdirs/__main__.py +++ b/src/platformdirs/__main__.py @@ -12,6 +12,7 @@ "user_runtime_dir", "site_data_dir", "site_config_dir", + "site_cache_dir", ) diff --git a/src/platformdirs/android.py b/src/platformdirs/android.py index eda80935..567582fd 100644 --- a/src/platformdirs/android.py +++ b/src/platformdirs/android.py @@ -43,6 +43,11 @@ def user_cache_dir(self) -> str: """:return: cache directory tied to the user, e.g. e.g. ``/data/user///cache/``""" return self._append_app_name_and_version(cast(str, _android_folder()), "cache") + @property + def site_cache_dir(self) -> str: + """:return: cache directory shared by users, same as `user_cache_dir`""" + return self.user_cache_dir + @property def user_state_dir(self) -> str: """:return: state directory tied to the user, same as `user_data_dir`""" diff --git a/src/platformdirs/api.py b/src/platformdirs/api.py index 6f6e2c2c..49173904 100644 --- a/src/platformdirs/api.py +++ b/src/platformdirs/api.py @@ -90,6 +90,11 @@ def site_config_dir(self) -> str: def user_cache_dir(self) -> str: """:return: cache directory tied to the user""" + @property + @abstractmethod + def site_cache_dir(self) -> str: + """:return: cache directory shared by users""" + @property @abstractmethod def user_state_dir(self) -> str: @@ -135,6 +140,11 @@ def user_cache_path(self) -> Path: """:return: cache path tied to the user""" return Path(self.user_cache_dir) + @property + def site_cache_path(self) -> Path: + """:return: cache path shared by users""" + return Path(self.site_cache_dir) + @property def user_state_path(self) -> Path: """:return: state path tied to the user""" diff --git a/src/platformdirs/macos.py b/src/platformdirs/macos.py index 49c554ca..99ac145a 100644 --- a/src/platformdirs/macos.py +++ b/src/platformdirs/macos.py @@ -38,6 +38,11 @@ def user_cache_dir(self) -> str: """:return: cache directory tied to the user, e.g. ``~/Library/Caches/$appname/$version``""" return self._append_app_name_and_version(os.path.expanduser("~/Library/Caches")) + @property + def site_cache_dir(self) -> str: + """:return: cache directory shared by users, e.g. ``/Library/Caches/$appname/$version``""" + return self._append_app_name_and_version("/Library/Caches") + @property def user_state_dir(self) -> str: """:return: state directory tied to the user, same as `user_data_dir`""" diff --git a/src/platformdirs/unix.py b/src/platformdirs/unix.py index 9aca5a03..b7b02f99 100644 --- a/src/platformdirs/unix.py +++ b/src/platformdirs/unix.py @@ -93,6 +93,13 @@ def user_cache_dir(self) -> str: path = os.path.expanduser("~/.cache") return self._append_app_name_and_version(path) + @property + def site_cache_dir(self) -> str: + """ + :return: cache directory shared by users, e.g. ``/var/cache/$appname/$version`` + """ + return self._append_app_name_and_version("/var/cache") + @property def user_state_dir(self) -> str: """ @@ -148,6 +155,11 @@ 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 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 self._first_item_as_path_if_multipath(self.site_cache_dir) + def _first_item_as_path_if_multipath(self, directory: str) -> Path: if self.multipath: # If multipath is True, the first path is returned. diff --git a/src/platformdirs/windows.py b/src/platformdirs/windows.py index d5c27b34..fec17fbb 100644 --- a/src/platformdirs/windows.py +++ b/src/platformdirs/windows.py @@ -68,6 +68,12 @@ def user_cache_dir(self) -> str: path = os.path.normpath(get_win_folder("CSIDL_LOCAL_APPDATA")) return self._append_parts(path, opinion_value="Cache") + @property + def site_cache_dir(self) -> str: + """:return: cache directory shared by users, e.g. ``C:\\ProgramData\\$appauthor\\$appname\\Cache\\$version``""" + path = os.path.normpath(get_win_folder("CSIDL_COMMON_APPDATA")) + return self._append_parts(path, opinion_value="Cache") + @property def user_state_dir(self) -> str: """:return: state directory tied to the user, same as `user_data_dir`""" diff --git a/tests/conftest.py b/tests/conftest.py index 34f808f9..f205c7cc 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -15,6 +15,7 @@ "user_runtime_dir", "site_data_dir", "site_config_dir", + "site_cache_dir", ) diff --git a/tests/test_android.py b/tests/test_android.py index 51dd09b3..6e1d7fc3 100644 --- a/tests/test_android.py +++ b/tests/test_android.py @@ -48,6 +48,7 @@ def test_android(mocker: MockerFixture, params: dict[str, Any], func: str) -> No "user_config_dir": f"/data/data/com.example/shared_prefs{suffix}", "site_config_dir": f"/data/data/com.example/shared_prefs{suffix}", "user_cache_dir": f"/data/data/com.example/cache{suffix}", + "site_cache_dir": f"/data/data/com.example/cache{suffix}", "user_state_dir": f"/data/data/com.example/files{suffix}", "user_log_dir": f"/data/data/com.example/cache{suffix}{'' if params.get('opinion', True) is False else '/log'}", "user_documents_dir": "/storage/emulated/0/Documents", diff --git a/tests/test_macos.py b/tests/test_macos.py index 228838b6..f17fc4a9 100644 --- a/tests/test_macos.py +++ b/tests/test_macos.py @@ -29,6 +29,7 @@ def test_macos(params: dict[str, Any], func: str) -> None: "user_config_dir": f"{home}/Library/Application Support{suffix}", "site_config_dir": f"/Library/Application Support{suffix}", "user_cache_dir": f"{home}/Library/Caches{suffix}", + "site_cache_dir": f"/Library/Caches{suffix}", "user_state_dir": f"{home}/Library/Application Support{suffix}", "user_log_dir": f"{home}/Library/Logs{suffix}", "user_documents_dir": f"{home}/Documents",