fix: retain Homebrew site directories inside virtual environments (#543)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Bernát Gábor <gaborjbernat@gmail.com>

Author: 3 people

docs/changelog/543.bugfix.rst

@@ -0,0 +1,2 @@
+Use the base Python installation to locate Homebrew site directories on macOS, preserving shared data, config, cache and
+state paths inside virtual environments.

docs/platforms.rst

@@ -569,6 +569,9 @@ On all other platforms, this aliases ``user_config_dir``.
 
 These are system-wide (and, generally, read-only) directories.
 
+On macOS, the Homebrew base Python installation determines shared data, config, cache and state locations. Activating a
+virtual environment preserves those locations.
+
 ``site_data_dir``
 =================
 

src/platformdirs/macos.py

@@ -29,8 +29,8 @@ def _base_user_app_support_dir(self) -> str:
         return self._append_app_name_and_version(os.path.expanduser("~/Library/Application Support"))  # ruff:ignore[os-path-expanduser]
 
     def _base_site_dirs(self) -> list[str]:
-        is_homebrew = "/opt/python" in sys.prefix
-        homebrew_prefix = sys.prefix.split("/opt/python")[0] if is_homebrew else ""
+        is_homebrew = "/opt/python" in sys.base_prefix
+        homebrew_prefix = sys.base_prefix.split("/opt/python")[0] if is_homebrew else ""
         path_list = [self._append_app_name_and_version(f"{homebrew_prefix}/share")] if is_homebrew else []
         path_list.append(self._append_app_name_and_version("/Library/Application Support"))
         return path_list
@@ -70,8 +70,8 @@ def user_cache_dir(self) -> str:
 
     @property
     def _site_cache_dirs(self) -> list[str]:
-        is_homebrew = "/opt/python" in sys.prefix
-        homebrew_prefix = sys.prefix.split("/opt/python")[0] if is_homebrew else ""
+        is_homebrew = "/opt/python" in sys.base_prefix
+        homebrew_prefix = sys.base_prefix.split("/opt/python")[0] if is_homebrew else ""
         path_list = [self._append_app_name_and_version(f"{homebrew_prefix}/var/cache")] if is_homebrew else []
         path_list.append(self._append_app_name_and_version("/Library/Caches"))
         return path_list

tests/test_comp_with_appdirs.py

@@ -49,7 +49,9 @@ def test_has_all_properties() -> None:
         "app_name_author_version",
     ],
 )
-def test_compatibility(params: dict[str, Any], func: str) -> None:
+def test_compatibility(params: dict[str, Any], func: str, monkeypatch: pytest.MonkeyPatch) -> None:
+    # Compare system defaults here; appdirs has no Homebrew-specific locations.
+    monkeypatch.setattr(sys, "base_prefix", "/usr")
     # Only test functions that are part of appdirs
     if getattr(appdirs, func, None) is None:
         pytest.skip(f"`{func}` does not exist in `appdirs`")

tests/test_macos.py

@@ -3,7 +3,7 @@
 import os
 import sys
 from pathlib import Path
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, Final
 
 import pytest
 
@@ -50,15 +50,15 @@ def home() -> str:
 
 @pytest.fixture
 def _homebrew_py_prefix(mocker: MockerFixture) -> None:
-    mocker.patch("sys.prefix", "/opt/homebrew/opt/python@3.13/Frameworks/Python.framework/Versions/3.13")
+    mocker.patch("sys.base_prefix", "/opt/homebrew/opt/python@3.13/Frameworks/Python.framework/Versions/3.13")
 
 
 @pytest.fixture
 def _builtin_py_prefix(mocker: MockerFixture) -> None:
-    """Keep ``sys.prefix`` off the ``/opt/python`` Homebrew heuristic so directories use the system defaults."""
+    """Keep ``sys.base_prefix`` off the ``/opt/python`` Homebrew heuristic so directories use the system defaults."""
     py_version = sys.version_info
     mocker.patch(
-        "sys.prefix",
+        "sys.base_prefix",
         "/Applications/Xcode.app/Contents/Developer/Library/Frameworks/Python3.framework"
         f"/Versions/{py_version.major}.{py_version.minor}",
     )
@@ -153,7 +153,7 @@ def test_macos_homebrew(
         },
     ]
     for prefix in test_data:
-        mocker.patch("sys.prefix", prefix["sys_prefix"])
+        mocker.patch("sys.base_prefix", prefix["sys_prefix"])
 
         result = getattr(MacOS(multipath=multipath, **params), site_func)
 
@@ -484,3 +484,60 @@ def test_macos_iter_runtime_dirs_no_duplicate(home: str) -> None:
     # site_runtime_dir is defined as user_runtime_dir.
     expected = os.path.join(f"{home}/Library/Caches/TemporaryItems", "foo")  # ruff:ignore[os-path-join]
     assert list(MacOS(appname="foo").iter_runtime_dirs()) == [expected]
+
+
+@pytest.mark.usefixtures("_clear_xdg_env")
+@pytest.mark.parametrize(
+    "homebrew_prefix",
+    [
+        pytest.param("/opt/homebrew", id="apple-silicon"),
+        pytest.param("/usr/local", id="intel"),
+        pytest.param("/custom/brew", id="custom-prefix"),
+    ],
+)
+@pytest.mark.parametrize("multipath", [pytest.param(True, id="multipath"), pytest.param(False, id="singlepath")])
+@pytest.mark.parametrize(
+    "prop",
+    [
+        "site_data_dir",
+        "site_config_dir",
+        "site_cache_dir",
+        "site_state_dir",
+        "site_data_path",
+        "site_config_path",
+        "site_cache_path",
+        "site_state_path",
+    ],
+)
+def test_homebrew_virtual_environment(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path, homebrew_prefix: str, prop: str, multipath: bool
+) -> None:
+    monkeypatch.setattr(sys, "prefix", str(tmp_path / ".venv"))
+    monkeypatch.setattr(
+        sys, "base_prefix", f"{homebrew_prefix}/opt/python@3.13/Frameworks/Python.framework/Versions/3.13"
+    )
+    suffix: Final = "var/cache" if "cache" in prop else "share"
+    expected: str | Path = f"{homebrew_prefix}/{suffix}{os.sep}Example{os.sep}1.0"
+    if prop.endswith("_path"):
+        expected = Path(expected)
+    elif multipath and prop != "site_state_dir":
+        fallback: Final = "Caches" if "cache" in prop else "Application Support"
+        expected += f":/Library/{fallback}{os.sep}Example{os.sep}1.0"
+    assert getattr(MacOS(appname="Example", version="1.0", multipath=multipath), prop) == expected
+
+
+@pytest.mark.usefixtures("_clear_xdg_env", "_builtin_py_prefix")
+@pytest.mark.parametrize(
+    ("prop", "expected"),
+    [
+        pytest.param("site_data_dir", "/Library/Application Support", id="data"),
+        pytest.param("site_config_dir", "/Library/Application Support", id="config"),
+        pytest.param("site_cache_dir", "/Library/Caches", id="cache"),
+        pytest.param("site_state_dir", "/Library/Application Support", id="state"),
+    ],
+)
+def test_non_homebrew_base_ignores_virtual_environment_name(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path, prop: str, expected: str
+) -> None:
+    monkeypatch.setattr(sys, "prefix", (tmp_path / "opt/python/.venv").as_posix())
+    assert getattr(MacOS(), prop) == expected