fix: don't crash when an XDG dirs variable holds only separators - #523
Merged
gaborbernat merged 6 commits intoAug 13, 2026
Merged
Conversation
…ators
site_data_dir, site_config_dir and site_applications_dir raised IndexError on
both Unix and macOS when $XDG_DATA_DIRS or $XDG_CONFIG_DIRS was set to
something that is non-empty but contains no actual paths, ":" being the
simplest case. The lookup split on os.pathsep and dropped blank entries, which
left an empty list, and the caller then indexed [0] on it.
A whitespace-only value already fell back to the platform defaults, because the
outer .strip() made it falsy. A value of ":" took the other branch and crashed
instead, which is an odd place to draw the line.
The awkward part is how easily a shell composes one by accident:
export XDG_DATA_DIRS="$SOME_UNSET:$ALSO_UNSET"
That yields ":" and the caller gets "list index out of range" from inside the
library rather than anything pointing at the environment.
Pulled the split into _xdg_dir_list() so the three call sites share it, and
made the emptiness check happen after filtering rather than before. Blank,
whitespace-only and separators-only values now all mean the same thing: treat
the variable as unset.
user_desktop_dir was the only one of the 27 public *_dir properties missing from the PROPS tuple in tests/conftest.py, and from the copy in __main__.py that test_props_same_as_test compares against. That tuple feeds the func and func_path fixtures, so leaving it out quietly excluded desktop from every test parametrised on them - test_windows, test_macos, test_android, test_unix's XDG cases, the appdirs comparison, and test_no_ctypes among them. test_no_ctypes is the one that stings. tox-dev#519 was user_desktop_dir raising ValueError on Windows whenever ctypes was unavailable, which is exactly what that test exists to catch; it just never saw the property. Adding it here would have caught that bug before release. Nothing fails once it's included, so there's no second bug hiding behind this - it only closes the hole. python -m platformdirs also prints the desktop directory now, which it should have been doing all along.
The new _xdg_dir_list helper kept entries verbatim after splitting, while main stripped the ends of the whole value first, so a padded XDG_DATA_DIRS such as ' /opt/share ' produced ' /opt/share /foo'. Stripping each entry restores the old behavior for padded values and also cleans whitespace inside multi-entry values that main kept. The padded case joins the test_xdg_variable family, which reads its expectations from the canonical defaults table and runs with multipath enabled, so the join branch that used to yield an empty string for all-separator values is pinned as well.
The all-separators test added a sixth verbatim copy of the Xcode framework sys.prefix setup that keeps tests off the Homebrew heuristic; a shared fixture gives the prefix a single home so a heuristic change no longer needs six coordinated edits. Drop the standalone Windows user_desktop_dir test: its comment claimed the shared PROPS fixture skips the property, which stopped being true once user_desktop_dir joined PROPS, and expected_map already carries the identical assertion.
One fragment bundled the XDG separators fix with the unrelated python -m platformdirs listing fix; towncrier renders counter-suffixed fragments as separate bullets, giving each fix its own entry.
gaborbernat
approved these changes
Aug 13, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Two things, the second found while writing tests for the first.
site_*_dircrashes when an XDG dirs variable holds no pathssite_data_dir,site_config_dirandsite_applications_dirraiseIndexErroron Unix and macOS when$XDG_DATA_DIRSor$XDG_CONFIG_DIRSis set to something non-empty that contains no actual paths:The lookup splits on
os.pathsepand drops blank entries, which leaves an empty list, and then the caller doesdirs[0].What makes it look unintended rather than merely undefined is that a whitespace-only value already falls back to the platform defaults — the outer
.strip()makes it falsy, so it takes thesuper()branch.":"is just as empty in every sense that matters but takes the other branch and crashes.It's easy to produce one by accident from a shell:
That's
":", and the caller getslist index out of rangefrom inside platformdirs with nothing pointing at the environment as the cause.I pulled the split into
_xdg_dir_list()so the three call sites share it, and moved the emptiness check to after filtering instead of before. Unset, empty, whitespace-only and separators-only now all mean the same thing.user_desktop_dirwas missing from the shared test property listWhile adding cases for the above I noticed
user_desktop_diris the only one of the 27 public*_dirproperties absent from thePROPStuple intests/conftest.py, and from the copy in__main__.pythattest_props_same_as_testchecks it against.That tuple backs the
funcandfunc_pathfixtures, so the omission quietly kept desktop out of every test parametrised on them —test_windows,test_macos,test_android, the XDG cases intest_unix, the appdirs comparison, andtest_no_ctypes.test_no_ctypesis the awkward one. #519 wasuser_desktop_dirraisingValueErroron Windows builds withoutctypes, which is the exact failure that test exists to catch — it just never ran against that property. Including it would have caught the bug before 4.11.0 went out.Nothing fails once it's added, so there's no second bug behind it; it only closes the gap.
python -m platformdirsprints the desktop directory now too.Happy to split these into separate PRs if you'd rather keep them apart.