fix: accept multipath in the site cache functions

docs/changelog.rst

@@ -6,21 +6,21 @@
 
 .. towncrier release notes start
 
-********************
+*********************
  4.11.8 (2026-09-08)
-********************
+*********************
 
 - Make :func:`~platformdirs.user_data_path`, :func:`~platformdirs.user_config_path`,
-  :func:`~platformdirs.user_preference_path` and :func:`~platformdirs.user_applications_path` return the first site entry
-  when root is redirected by ``use_site_for_root`` under ``multipath``, matching their ``site_*_path`` twins. They passed
-  the whole joined list to :class:`~pathlib.Path`, giving one unusable path such as ``/xdg/a/foo:/xdg/b/foo`` - by
-  :user:`darrenhuai`. :pr:`538`
+  :func:`~platformdirs.user_preference_path` and :func:`~platformdirs.user_applications_path` return the first site
+  entry when root is redirected by ``use_site_for_root`` under ``multipath``, matching their ``site_*_path`` twins. They
+  passed the whole joined list to :class:`~pathlib.Path`, giving one unusable path such as ``/xdg/a/foo:/xdg/b/foo`` -
+  by :user:`darrenhuai`. :pr:`538`
 - Ignore relative paths in XDG Base Directory environment variables and use the existing platform fallback. Relative
   entries in ``$XDG_DATA_DIRS`` and ``$XDG_CONFIG_DIRS`` are skipped. :pr:`540`
 - Preserve literal percent signs in Unix ``user-dirs.dirs`` paths, including ``100% complete``, ``100%%`` and
   ``%(XDG_DESKTOP_DIR)s``. Continue to expand ``$HOME``. :pr:`542`
-- Use the base Python installation to locate Homebrew site directories on macOS, preserving shared data, config, cache and
-  state paths inside virtual environments. :pr:`543`
+- Use the base Python installation to locate Homebrew site directories on macOS, preserving shared data, config, cache
+  and state paths inside virtual environments. :pr:`543`
 
 *********************
  4.11.7 (2026-09-01)

docs/changelog/544.bugfix.rst

@@ -0,0 +1,3 @@
+Give :func:`~platformdirs.site_cache_dir` and :func:`~platformdirs.site_cache_path` the ``multipath`` argument. They
+took none, so the Homebrew cache prefix that :attr:`~platformdirs.macos.MacOS.site_cache_dir` returns under
+``multipath`` was unreachable from the function API - by :user:`darrenhuai`.

src/platformdirs/__init__.py

@@ -186,18 +186,21 @@ def user_cache_dir(  # ruff:ignore[too-many-arguments, too-many-positional-argum
     ).user_cache_dir
 
 
-def site_cache_dir(
+def site_cache_dir(  # ruff:ignore[too-many-arguments]
     appname: str | None = None,
     appauthor: str | Literal[False] | None = None,
     version: str | None = None,
     opinion: bool = True,  # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument]
     ensure_exists: bool = False,  # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument]
+    *,
+    multipath: bool = False,
 ) -> 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>`.
+    :param multipath: See `multipath <platformdirs.api.PlatformDirsABC.multipath>`.
 
     :returns: cache directory shared by users
 
@@ -206,6 +209,7 @@ def site_cache_dir(
         appname=appname,
         appauthor=appauthor,
         version=version,
+        multipath=multipath,
         opinion=opinion,
         ensure_exists=ensure_exists,
     ).site_cache_dir
@@ -618,18 +622,21 @@ def site_config_path(
     ).site_config_path
 
 
-def site_cache_path(
+def site_cache_path(  # ruff:ignore[too-many-arguments]
     appname: str | None = None,
     appauthor: str | Literal[False] | None = None,
     version: str | None = None,
     opinion: bool = True,  # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument]
     ensure_exists: bool = False,  # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument]
+    *,
+    multipath: bool = False,
 ) -> 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>`.
+    :param multipath: See `multipath <platformdirs.api.PlatformDirsABC.multipath>`.
 
     :returns: cache path shared by users
 
@@ -638,6 +645,7 @@ def site_cache_path(
         appname=appname,
         appauthor=appauthor,
         version=version,
+        multipath=multipath,
         opinion=opinion,
         ensure_exists=ensure_exists,
     ).site_cache_path

src/platformdirs/api.py

@@ -75,8 +75,8 @@ def __init__(  # ruff:ignore[too-many-arguments, too-many-positional-arguments]
         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. Only affects ``site_data_dir`` and ``site_config_dir`` on
-        Unix and macOS.
+        By default, the first item would only be returned. Only affects ``site_data_dir``, ``site_config_dir`` and
+        ``site_applications_dir`` on Unix and macOS, plus ``site_cache_dir`` on macOS under Homebrew.
 
         """
         self.opinion = opinion

tests/test_macos.py

@@ -7,6 +7,7 @@
 
 import pytest
 
+import platformdirs
 from platformdirs.macos import MacOS
 
 if TYPE_CHECKING:
@@ -180,6 +181,17 @@ def test_macos_homebrew(
         assert result == expected
 
 
+@pytest.mark.usefixtures("_clear_xdg_env", "_homebrew_py_prefix")
+@pytest.mark.parametrize("suffix", ["dir", "path"])
+@pytest.mark.parametrize("name", ["site_data", "site_config", "site_cache", "site_applications"])
+def test_multipath_reaches_the_module_function(mocker: MockerFixture, name: str, suffix: str) -> None:
+    # The module-level functions have to reach every site directory that multipath changes.
+    mocker.patch("platformdirs.PlatformDirs", MacOS)
+    function = getattr(platformdirs, f"{name}_{suffix}")
+    expected = getattr(MacOS(appname="foo", multipath=True), f"{name}_{suffix}")
+    assert function(appname="foo", multipath=True) == expected
+
+
 @pytest.mark.parametrize(
     ("env_var", "prop", "xdg_path"),
     [