✨ feat: add user_publicshare_dir, user_templates_dir, user_fonts_dir, user_preference_dir#491
Merged
Conversation
… user_preference_dir Cross-ecosystem research (Rust dirs/directories, Java directories-jvm, Go adrg/xdg) shows these four directories are consistently supported elsewhere but absent from platformdirs. Two come directly from the xdg-user-dirs spec (XDG_PUBLICSHARE_DIR, XDG_TEMPLATES_DIR), one is derived from XDG_DATA_HOME (fonts), and one exposes the macOS-specific ~/Library/Preferences split that Rust and Java both model explicitly. publicshare and templates follow the existing media-dir pattern: unix.py reads user-dirs.dirs via _get_user_media_dir, XDGMixin overrides via the env var. fonts has no dedicated env var so XDGMixin derives it from XDG_DATA_HOME/fonts instead. preference aliases user_config_dir on all platforms except macOS, where ~/Library/Preferences is a genuinely separate location from ~/Library/Application Support. macOS has no standard templates directory; ~/Templates is returned as a pragmatic fallback (consistent with Go's approach) to preserve the str return contract. Windows fonts uses %LOCALAPPDATA%\Microsoft\Windows\Fonts, the real per-user writable location added in Windows 10.
Add explanation, per-platform tables, and API references for user_publicshare_dir, user_templates_dir, user_fonts_dir, and user_preference_dir. Also add the missing "User media directories" section to explanation.rst covering the full set of non-app-scoped dirs, with upstream spec links (XDG user-dirs, Apple File System Guide, Windows KNOWNFOLDERID). Notable callouts: macOS has no native templates dir (~/Templates fallback), Windows publicshare is machine-wide C:\Users\Public, fonts on Windows uses the Win10+ per-user location, and preference_dir is only distinct from config_dir on macOS.
gaborbernat
added
documentation
… lists over list-table
Add the missing user-facing/media dirs branch (documents, downloads, pictures, videos, music, fonts, templates, projects, desktop, publicshare) and the macOS preference dir node. Color coding: blue = app dirs, green = user media dirs, purple = macOS-only preference, amber = decision nodes.
for more information, see https://pre-commit.ci
gaborbernat
changed the title
gaborbernat
changed the title
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
1 participant
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.
Cross-ecosystem research (Rust
dirs/directories, Javadirectories-jvm, Goadrg/xdg) shows four directories consistently supported elsewhere but absent from platformdirs: public share, templates, fonts, and preference. Two come directly from the XDG user-dirs spec (XDG_PUBLICSHARE_DIR,XDG_TEMPLATES_DIR), one is derived fromXDG_DATA_HOME(fonts), and one exposes the macOS-specific~/Library/Preferencessplit that Rust and Java both model explicitly.user_publicshare_diranduser_templates_dirfollow the existing media-dir pattern:unix.pyreadsuser-dirs.dirsvia_get_user_media_dirandXDGMixinoverrides via the env var.user_fonts_dirhas no dedicated env var — it is derived from$XDG_DATA_HOME/fonts, soXDGMixinwatchesXDG_DATA_HOMEinstead.user_preference_diraliasesuser_config_diron Linux, Windows, and Android; on macOS it returns~/Library/Preferences/AppName, a genuinely separate location from~/Library/Application Support.Three platform-specific decisions: macOS returns
~/Templatesas a pragmatic fallback foruser_templates_dir(Rust/Java returnNone, but thestrreturn type requires a path); Windowsuser_publicshare_dirreturnsC:\Users\Public(%PUBLIC%) — a machine-wide folder, not per-user, matching Rust/Java convention; Windowsuser_fonts_diruses%LOCALAPPDATA%\Microsoft\Windows\Fonts, the real per-user writable font location added in Windows 10.Documentation:
explanation.rstgains a prose introduction and a complete colored flowchart covering all directory types (app dirs and user media dirs);platforms.rsthas per-platform tables for all four new properties with upstream spec links;api.rstadds autofunction entries; README updated with the full directory type listing; docs toctree reorganised with Diátaxis-style captions.