Skip to content

fix: don't crash when an XDG dirs variable holds only separators - #523

Merged
gaborbernat merged 6 commits into
tox-dev:mainfrom
darrenhuai:fix/xdg-site-dirs-all-blank
Aug 13, 2026
Merged

fix: don't crash when an XDG dirs variable holds only separators#523
gaborbernat merged 6 commits into
tox-dev:mainfrom
darrenhuai:fix/xdg-site-dirs-all-blank

Conversation

@darrenhuai

Copy link
Copy Markdown
Contributor

Two things, the second found while writing tests for the first.

site_*_dir crashes when an XDG dirs variable holds no paths

site_data_dir, site_config_dir and site_applications_dir raise IndexError on Unix and macOS when $XDG_DATA_DIRS or $XDG_CONFIG_DIRS is set to something non-empty that contains no actual paths:

XDG_DATA_DIRS=':'    -> IndexError: list index out of range
XDG_DATA_DIRS='::'   -> IndexError: list index out of range
XDG_DATA_DIRS=' : '  -> IndexError: list index out of range

The lookup splits on os.pathsep and drops blank entries, which leaves an empty list, and then the caller does dirs[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 the super() 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:

export XDG_DATA_DIRS="$SOME_UNSET:$ALSO_UNSET"

That's ":", and the caller gets list index out of range from 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_dir was missing from the shared test property list

While adding cases for the above I noticed user_desktop_dir is the only one of the 27 public *_dir properties absent from the PROPS tuple in tests/conftest.py, and from the copy in __main__.py that test_props_same_as_test checks it against.

That tuple backs the func and func_path fixtures, so the omission quietly kept desktop out of every test parametrised on them — test_windows, test_macos, test_android, the XDG cases in test_unix, the appdirs comparison, and test_no_ctypes.

test_no_ctypes is the awkward one. #519 was user_desktop_dir raising ValueError on Windows builds without ctypes, 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 platformdirs prints the desktop directory now too.

Happy to split these into separate PRs if you'd rather keep them apart.

…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.
darrenhuai and others added 4 commits August 13, 2026 14:45
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
gaborbernat merged commit c8af984 into tox-dev:main Aug 13, 2026
36 checks passed
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.

2 participants