Skip to content

fix: accept multipath in the site cache functions - #544

Open
darrenhuai wants to merge 3 commits into
tox-dev:mainfrom
darrenhuai:fix-site-cache-multipath-v2
Open

fix: accept multipath in the site cache functions#544
darrenhuai wants to merge 3 commits into
tox-dev:mainfrom
darrenhuai:fix-site-cache-multipath-v2

Conversation

@darrenhuai

Copy link
Copy Markdown
Contributor

multipath changes four site directories: site_data_dir and site_config_dir on Unix and macOS, site_applications_dir on both, and site_cache_dir on macOS when the interpreter comes from Homebrew. The module-level functions expose the argument for the first three, but site_cache_dir() and site_cache_path() take no multipath at all, so passing it is a TypeError and the Homebrew cache prefix is unreachable from the function API:

>>> platformdirs.site_cache_dir("SuperApp", multipath=True)
TypeError: site_cache_dir() got an unexpected keyword argument 'multipath'
>>> platformdirs.PlatformDirs("SuperApp", multipath=True).site_cache_dir
'/opt/homebrew/var/cache/SuperApp:/Library/Caches/SuperApp'

docs/explanation.rst already documents the behaviour those functions cannot produce ("site_data_dir and site_cache_dir include the Homebrew prefix as an additional path when multipath=True").

Adding it keyword-only keeps opinion and ensure_exists where they are for positional callers, and matches how the applications functions took their new options in #534/#535.

On site_cache_path it is a no-op, since the path variants return the first entry either way. I kept it for the same reason site_data_path and site_config_path carry it — test_function_interface_is_in_sync requires the dir and path signatures to match.

The new test parametrizes over the whole multipath family rather than just the cache case, so the next site directory that grows a multipath variant has to be reachable from its function too. Also corrected the multipath docstring in api.py, which still claimed only site_data_dir and site_config_dir were affected.

Impact is narrow, and worth stating plainly: it only bites a macOS user on Homebrew Python who wants both cache roots and is using the function API rather than PlatformDirs. It is an API-completeness gap, not a crash anyone has reported.

Verified locally on Windows: full suite 1249 passed / 94 skipped, ruff check src tests, ruff format --check, ty check --error-on-warning . all clean, and the guard test fails both when the change is reverted and when the signature is kept but the argument is not forwarded. I did not build the docs (no sphinx in my venv); the docstring edit is a plain literal.

Four site directories change with multipath: site_data_dir and
site_config_dir on Unix and macOS, site_applications_dir on both, and
site_cache_dir on macOS when the interpreter comes from Homebrew. The
module-level functions expose the argument for the first three, but
site_cache_dir() and site_cache_path() take no multipath at all, so
passing it is a TypeError and the Homebrew cache prefix is unreachable
from the function API. explanation.rst already documents the behaviour
those functions cannot produce.

Adding it keyword-only keeps opinion and ensure_exists where they are for
positional callers, and matches how the applications functions took their
new options.

On site_cache_path it is a no-op, since the path variants return the first
entry either way. Kept for the same reason site_data_path and
site_config_path carry it: test_function_interface_is_in_sync requires the
dir and path signatures to match.

The new test parametrizes over the whole multipath family rather than just
the cache case, so the next site directory that grows a multipath variant
has to be reachable from its function too. Also corrects the multipath
docstring in api.py, which still claimed only site_data_dir and
site_config_dir were affected.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant