platformdirs: introduce site_runtime_dir (#212)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

src/platformdirs/__init__.py

@@ -293,6 +293,30 @@ def user_runtime_dir(
     ).user_runtime_dir
 
 
+def site_runtime_dir(
+    appname: str | None = None,
+    appauthor: str | None | Literal[False] = None,
+    version: str | None = None,
+    opinion: bool = True,  # noqa: FBT001, FBT002
+    ensure_exists: bool = False,  # noqa: FBT001, FBT002
+) -> 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>`.
+    :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
+    :returns: runtime directory shared by users
+    """
+    return PlatformDirs(
+        appname=appname,
+        appauthor=appauthor,
+        version=version,
+        opinion=opinion,
+        ensure_exists=ensure_exists,
+    ).site_runtime_dir
+
+
 def user_data_path(
     appname: str | None = None,
     appauthor: str | None | Literal[False] = None,
@@ -539,6 +563,30 @@ def user_runtime_path(
     ).user_runtime_path
 
 
+def site_runtime_path(
+    appname: str | None = None,
+    appauthor: str | None | Literal[False] = None,
+    version: str | None = None,
+    opinion: bool = True,  # noqa: FBT001, FBT002
+    ensure_exists: bool = False,  # noqa: FBT001, FBT002
+) -> 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>`.
+    :param ensure_exists: See `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
+    :returns: runtime path shared by users
+    """
+    return PlatformDirs(
+        appname=appname,
+        appauthor=appauthor,
+        version=version,
+        opinion=opinion,
+        ensure_exists=ensure_exists,
+    ).site_runtime_path
+
+
 __all__ = [
     "__version__",
     "__version_info__",
@@ -560,6 +608,7 @@ def user_runtime_path(
     "site_data_dir",
     "site_config_dir",
     "site_cache_dir",
+    "site_runtime_dir",
     "user_data_path",
     "user_config_path",
     "user_cache_path",
@@ -575,4 +624,5 @@ def user_runtime_path(
     "site_data_path",
     "site_config_path",
     "site_cache_path",
+    "site_runtime_path",
 ]

src/platformdirs/__main__.py

@@ -18,6 +18,7 @@
     "site_data_dir",
     "site_config_dir",
     "site_cache_dir",
+    "site_runtime_dir",
 )
 
 

src/platformdirs/android.py

@@ -108,6 +108,11 @@ def user_runtime_dir(self) -> str:
             path = os.path.join(path, "tmp")  # noqa: PTH118
         return path
 
+    @property
+    def site_runtime_dir(self) -> str:
+        """:return: runtime directory shared by users, same as `user_runtime_dir`"""
+        return self.user_runtime_dir
+
 
 @lru_cache(maxsize=1)
 def _android_folder() -> str | None:

src/platformdirs/api.py

@@ -157,6 +157,11 @@ def user_desktop_dir(self) -> str:
     def user_runtime_dir(self) -> str:
         """:return: runtime directory tied to the user"""
 
+    @property
+    @abstractmethod
+    def site_runtime_dir(self) -> str:
+        """:return: runtime directory shared by users"""
+
     @property
     def user_data_path(self) -> Path:
         """:return: data path tied to the user"""
@@ -231,3 +236,8 @@ def user_desktop_path(self) -> Path:
     def user_runtime_path(self) -> Path:
         """:return: runtime path tied to the user"""
         return Path(self.user_runtime_dir)
+
+    @property
+    def site_runtime_path(self) -> Path:
+        """:return: runtime path shared by users"""
+        return Path(self.site_runtime_dir)

src/platformdirs/macos.py

@@ -90,6 +90,11 @@ def user_runtime_dir(self) -> str:
         """:return: runtime directory tied to the user, e.g. ``~/Library/Caches/TemporaryItems/$appname/$version``"""
         return self._append_app_name_and_version(os.path.expanduser("~/Library/Caches/TemporaryItems"))  # noqa: PTH111
 
+    @property
+    def site_runtime_dir(self) -> str:
+        """:return: runtime directory shared by users, same as `user_runtime_dir`"""
+        return self.user_runtime_dir
+
 
 __all__ = [
     "MacOS",

src/platformdirs/unix.py

@@ -172,6 +172,28 @@ def user_runtime_dir(self) -> str:
                 path = f"/run/user/{getuid()}"
         return self._append_app_name_and_version(path)
 
+    @property
+    def site_runtime_dir(self) -> str:
+        """
+        :return: runtime directory shared by users, e.g. ``/run/$appname/$version`` or
+        ``$XDG_RUNTIME_DIR/$appname/$version``.
+
+        Note that this behaves almost exactly like `user_runtime_dir` if ``$XDG_RUNTIME_DIR`` is set, but will
+        fallback to paths associated to the root user instead of a regular logged-in user if it's not set.
+
+        If you wish to ensure that a logged-in root user path is returned e.g. ``/run/user/0``, use `user_runtime_dir`
+        instead.
+
+        For FreeBSD/OpenBSD/NetBSD, it would return ``/var/run/$appname/$version`` if ``$XDG_RUNTIME_DIR`` is not set.
+        """
+        path = os.environ.get("XDG_RUNTIME_DIR", "")
+        if not path.strip():
+            if sys.platform.startswith(("freebsd", "openbsd", "netbsd")):
+                path = "/var/run"
+            else:
+                path = "/run"
+        return self._append_app_name_and_version(path)
+
     @property
     def site_data_path(self) -> Path:
         """:return: data path shared by users. Only return first item, even if ``multipath`` is set to ``True``"""

src/platformdirs/windows.py

@@ -136,6 +136,11 @@ def user_runtime_dir(self) -> str:
         path = os.path.normpath(os.path.join(get_win_folder("CSIDL_LOCAL_APPDATA"), "Temp"))  # noqa: PTH118
         return self._append_parts(path)
 
+    @property
+    def site_runtime_dir(self) -> str:
+        """:return: runtime directory shared by users, same as `user_runtime_dir`"""
+        return self.user_runtime_dir
+
 
 def get_win_folder_from_env_vars(csidl_name: str) -> str:
     """Get folder from environment variables."""

tests/conftest.py

@@ -22,6 +22,7 @@
     "site_data_dir",
     "site_config_dir",
     "site_cache_dir",
+    "site_runtime_dir",
 )
 
 

tests/test_android.py

@@ -60,6 +60,7 @@ def test_android(mocker: MockerFixture, params: dict[str, Any], func: str) -> No
         "user_music_dir": "/storage/emulated/0/Music",
         "user_desktop_dir": "/storage/emulated/0/Desktop",
         "user_runtime_dir": f"/data/data/com.example/cache{suffix}{'' if not params.get('opinion', True) else val}",
+        "site_runtime_dir": f"/data/data/com.example/cache{suffix}{'' if not params.get('opinion', True) else val}",
     }
     expected = expected_map[func]
 

tests/test_macos.py

@@ -40,6 +40,7 @@ def test_macos(params: dict[str, Any], func: str) -> None:
         "user_music_dir": f"{home}/Music",
         "user_desktop_dir": f"{home}/Desktop",
         "user_runtime_dir": f"{home}/Library/Caches/TemporaryItems{suffix}",
+        "site_runtime_dir": f"{home}/Library/Caches/TemporaryItems{suffix}",
     }
     expected = expected_map[func]
 

tests/test_unix.py

@@ -98,6 +98,7 @@ def _func_to_path(func: str) -> XDGVariable | None:
         "user_state_dir": XDGVariable("XDG_STATE_HOME", "~/.local/state"),
         "user_log_dir": XDGVariable("XDG_STATE_HOME", "~/.local/state"),
         "user_runtime_dir": XDGVariable("XDG_RUNTIME_DIR", "/run/user/1234"),
+        "site_runtime_dir": XDGVariable("XDG_RUNTIME_DIR", "/run"),
     }
     return mapping.get(func)
 
@@ -151,6 +152,8 @@ def test_platform_on_bsd(monkeypatch: pytest.MonkeyPatch, mocker: MockerFixture,
     monkeypatch.delenv("XDG_RUNTIME_DIR", raising=False)
     mocker.patch("sys.platform", platform)
 
+    assert Unix().site_runtime_dir == "/var/run"
+
     mocker.patch("pathlib.Path.exists", return_value=True)
     assert Unix().user_runtime_dir == "/var/run/user/1234"