platformdirs: introduce site_cache_dir (#145)

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

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 <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>`.
+    :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 <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>`.
+    :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",
 ]

src/platformdirs/__main__.py

@@ -12,6 +12,7 @@
     "user_runtime_dir",
     "site_data_dir",
     "site_config_dir",
+    "site_cache_dir",
 )
 
 

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/<userid>/<packagename>/cache/<AppName>``"""
         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`"""

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

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

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.

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

tests/conftest.py

@@ -15,6 +15,7 @@
     "user_runtime_dir",
     "site_data_dir",
     "site_config_dir",
+    "site_cache_dir",
 )
 
 

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

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