Platformdirs - README

问题

https://static.pepy.tech/badge/platformdirs/month

在编写桌面应用程序时，存储用户数据和配置的正确位置因平台而异。即使是单个平台的应用程序，找出正确的位置也可能存在许多细微差别。

例如，如果在 macOS 上运行，您应该使用：

~/Library/Application Support/<AppName>

如果在 Windows 上（至少是英语版 Windows），则应该是：

C:\Users\<User>\Application Data\Local Settings\<AppAuthor>\<AppName>

或者可能是：

C:\Users\<User>\Application Data\<AppAuthor>\<AppName>

用于漫游配置文件，但这又是另一个故事。

根据 XDG Basedir 规范，在 Linux（和其他 Unix 系统）上，它应该是：

~/.local/share/<AppName>

`platformdirs` 来拯救

这正是 platformdirs 包的用途。platformdirs 将帮助您选择一个合适的：

用户数据目录 (user_data_dir)
用户配置目录 (user_config_dir)
用户缓存目录 (user_cache_dir)
站点数据目录 (site_data_dir)
站点配置目录 (site_config_dir)
用户日志目录 (user_log_dir)
用户文档目录 (user_documents_dir)
用户下载目录 (user_downloads_dir)
用户图片目录 (user_pictures_dir)
用户视频目录 (user_videos_dir)
用户音乐目录 (user_music_dir)
用户桌面目录 (user_desktop_dir)
用户运行时目录 (user_runtime_dir)

还可以：

对使用的目录名称有些建议。在文档和代码中查找“Opinion”以了解何时应用了建议。

示例输出

在 macOS 上：

>>> from platformdirs import *
>>> appname = "SuperApp"
>>> appauthor = "Acme"
>>> user_data_dir(appname, appauthor)
'/Users/trentm/Library/Application Support/SuperApp'
>>> user_config_dir(appname, appauthor)
'/Users/trentm/Library/Application Support/SuperApp'
>>> user_cache_dir(appname, appauthor)
'/Users/trentm/Library/Caches/SuperApp'
>>> site_data_dir(appname, appauthor)
'/Library/Application Support/SuperApp'
>>> site_config_dir(appname, appauthor)
'/Library/Application Support/SuperApp'
>>> user_log_dir(appname, appauthor)
'/Users/trentm/Library/Logs/SuperApp'
>>> user_documents_dir()
'/Users/trentm/Documents'
>>> user_downloads_dir()
'/Users/trentm/Downloads'
>>> user_pictures_dir()
'/Users/trentm/Pictures'
>>> user_videos_dir()
'/Users/trentm/Movies'
>>> user_music_dir()
'/Users/trentm/Music'
>>> user_desktop_dir()
'/Users/trentm/Desktop'
>>> user_runtime_dir(appname, appauthor)
'/Users/trentm/Library/Caches/TemporaryItems/SuperApp'

在 Windows 上：

>>> from platformdirs import *
>>> appname = "SuperApp"
>>> appauthor = "Acme"
>>> user_data_dir(appname, appauthor)
'C:\\Users\\trentm\\AppData\\Local\\Acme\\SuperApp'
>>> user_data_dir(appname, appauthor, roaming=True)
'C:\\Users\\trentm\\AppData\\Roaming\\Acme\\SuperApp'
>>> user_config_dir(appname, appauthor)
'C:\\Users\\trentm\\AppData\\Local\\Acme\\SuperApp'
>>> user_cache_dir(appname, appauthor)
'C:\\Users\\trentm\\AppData\\Local\\Acme\\SuperApp\\Cache'
>>> site_data_dir(appname, appauthor)
'C:\\ProgramData\\Acme\\SuperApp'
>>> site_config_dir(appname, appauthor)
'C:\\ProgramData\\Acme\\SuperApp'
>>> user_log_dir(appname, appauthor)
'C:\\Users\\trentm\\AppData\\Local\\Acme\\SuperApp\\Logs'
>>> user_documents_dir()
'C:\\Users\\trentm\\Documents'
>>> user_downloads_dir()
'C:\\Users\\trentm\\Downloads'
>>> user_pictures_dir()
'C:\\Users\\trentm\\Pictures'
>>> user_videos_dir()
'C:\\Users\\trentm\\Videos'
>>> user_music_dir()
'C:\\Users\\trentm\\Music'
>>> user_desktop_dir()
'C:\\Users\\trentm\\Desktop'
>>> user_runtime_dir(appname, appauthor)
'C:\\Users\\trentm\\AppData\\Local\\Temp\\Acme\\SuperApp'

在 Linux 上：

>>> from platformdirs import *
>>> appname = "SuperApp"
>>> appauthor = "Acme"
>>> user_data_dir(appname, appauthor)
'/home/trentm/.local/share/SuperApp'
>>> user_config_dir(appname)
'/home/trentm/.config/SuperApp'
>>> user_cache_dir(appname, appauthor)
'/home/trentm/.cache/SuperApp'
>>> site_data_dir(appname, appauthor)
'/usr/local/share/SuperApp'
>>> site_data_dir(appname, appauthor, multipath=True)
'/usr/local/share/SuperApp:/usr/share/SuperApp'
>>> site_config_dir(appname)
'/etc/xdg/SuperApp'
>>> os.environ["XDG_CONFIG_DIRS"] = "/etc:/usr/local/etc"
>>> site_config_dir(appname, multipath=True)
'/etc/SuperApp:/usr/local/etc/SuperApp'
>>> user_log_dir(appname, appauthor)
'/home/trentm/.local/state/SuperApp/log'
>>> user_documents_dir()
'/home/trentm/Documents'
>>> user_downloads_dir()
'/home/trentm/Downloads'
>>> user_pictures_dir()
'/home/trentm/Pictures'
>>> user_videos_dir()
'/home/trentm/Videos'
>>> user_music_dir()
'/home/trentm/Music'
>>> user_desktop_dir()
'/home/trentm/Desktop'
>>> user_runtime_dir(appname, appauthor)
'/run/user/{os.getuid()}/SuperApp'

在 Android 上：

>>> from platformdirs import *
>>> appname = "SuperApp"
>>> appauthor = "Acme"
>>> user_data_dir(appname, appauthor)
'/data/data/com.myApp/files/SuperApp'
>>> user_config_dir(appname)
'/data/data/com.myApp/shared_prefs/SuperApp'
>>> user_cache_dir(appname, appauthor)
'/data/data/com.myApp/cache/SuperApp'
>>> site_data_dir(appname, appauthor)
'/data/data/com.myApp/files/SuperApp'
>>> site_config_dir(appname)
'/data/data/com.myApp/shared_prefs/SuperApp'
>>> user_log_dir(appname, appauthor)
'/data/data/com.myApp/cache/SuperApp/log'
>>> user_documents_dir()
'/storage/emulated/0/Documents'
>>> user_downloads_dir()
'/storage/emulated/0/Downloads'
>>> user_pictures_dir()
'/storage/emulated/0/Pictures'
>>> user_videos_dir()
'/storage/emulated/0/DCIM/Camera'
>>> user_music_dir()
'/storage/emulated/0/Music'
>>> user_desktop_dir()
'/storage/emulated/0/Desktop'
>>> user_runtime_dir(appname, appauthor)
'/data/data/com.myApp/cache/SuperApp/tmp'

注意：某些 Android 应用，如 Termux 和 Pydroid，被用作 Shell。这些应用由最终用户用来模拟 Linux 环境。`SHELL` 环境变量是否存在用于 Platformdirs 来区分一般 Android 应用和用作 Shell 的 Android 应用。Shell Android 应用也支持 `XDG_*` 环境变量。

方便的 `PlatformDirs`

>>> from platformdirs import PlatformDirs
>>> dirs = PlatformDirs("SuperApp", "Acme")
>>> dirs.user_data_dir
'/Users/trentm/Library/Application Support/SuperApp'
>>> dirs.user_config_dir
'/Users/trentm/Library/Application Support/SuperApp'
>>> dirs.user_cache_dir
'/Users/trentm/Library/Caches/SuperApp'
>>> dirs.site_data_dir
'/Library/Application Support/SuperApp'
>>> dirs.site_config_dir
'/Library/Application Support/SuperApp'
>>> dirs.user_cache_dir
'/Users/trentm/Library/Caches/SuperApp'
>>> dirs.user_log_dir
'/Users/trentm/Library/Logs/SuperApp'
>>> dirs.user_documents_dir
'/Users/trentm/Documents'
>>> dirs.user_downloads_dir
'/Users/trentm/Downloads'
>>> dirs.user_pictures_dir
'/Users/trentm/Pictures'
>>> dirs.user_videos_dir
'/Users/trentm/Movies'
>>> dirs.user_music_dir
'/Users/trentm/Music'
>>> dirs.user_desktop_dir
'/Users/trentm/Desktop'
>>> dirs.user_runtime_dir
'/Users/trentm/Library/Caches/TemporaryItems/SuperApp'

按版本隔离

如果您有多个版本的应用程序需要并行运行，您可能希望对这些目录进行版本隔离：

>>> from platformdirs import PlatformDirs
>>> dirs = PlatformDirs("SuperApp", "Acme", version="1.0")
>>> dirs.user_data_dir
'/Users/trentm/Library/Application Support/SuperApp/1.0'
>>> dirs.user_config_dir
'/Users/trentm/Library/Application Support/SuperApp/1.0'
>>> dirs.user_cache_dir
'/Users/trentm/Library/Caches/SuperApp/1.0'
>>> dirs.site_data_dir
'/Library/Application Support/SuperApp/1.0'
>>> dirs.site_config_dir
'/Library/Application Support/SuperApp/1.0'
>>> dirs.user_log_dir
'/Users/trentm/Library/Logs/SuperApp/1.0'
>>> dirs.user_documents_dir
'/Users/trentm/Documents'
>>> dirs.user_downloads_dir
'/Users/trentm/Downloads'
>>> dirs.user_pictures_dir
'/Users/trentm/Pictures'
>>> dirs.user_videos_dir
'/Users/trentm/Movies'
>>> dirs.user_music_dir
'/Users/trentm/Music'
>>> dirs.user_desktop_dir
'/Users/trentm/Desktop'
>>> dirs.user_runtime_dir
'/Users/trentm/Library/Caches/TemporaryItems/SuperApp/1.0'

但请注意，对于配置文件，您需要手动处理配置文件迁移。

为何要分支？

此存储库是 ActiveState（appdirs 的创建者，该包的祖先）精彩工作的友好分支。

维护开源项目并非易事，尤其是在组织内部。Python 社区非常感谢 appdirs（特别是 Trent Mick 和 Jeff Rouse）创建了一个极其有用且简单的模块，这一点已由它多年来吸引的大量用户证明。

然而，鉴于长期存在的未解决问题和拉取请求数量众多，且没有明确的确保包维护能够持续或增长的途径，因此创建了这个分支。

非常欢迎贡献。

问题

platformdirs 来拯救

示例输出

方便的 `PlatformDirs`

按版本隔离

为何要分支？

`platformdirs` 来拯救