A small Python module for determining appropriate platform-specific dirs, e.g. a "user data dir".
Project description
the problem
What directory should your app use for storing user data? If running on Mac OS X, you should use:
~/Library/Application Support/<AppName>
If on Windows (at least English Win XP) that should be:
C:\Documents and Settings\<User>\Application Data\Local Settings\<AppAuthor>\<AppName>
or possibly:
C:\Documents and Settings\<User>\Application Data\<AppAuthor>\<AppName>
for roaming profiles but that is another story.
On Linux (and other Unices) the dir, according to the XDG spec (and subject to some interpretation), is:
~/.config/<appname> # note AppName was lowercased
appdirs to the rescue
This kind of thing is what the appdirs module is for. appdirs will help you choose an appropriate:
user data dir (user_data_dir)
user cache dir (user_cache_dir)
site data dir (site_data_dir)
user log dir (user_log_dir)
and also:
is a single module so other Python packages can include their own private copy
is slightly opinionated on the directory names used. Look for “OPINION” in documentation and code for when an opinion is being applied.
some example output
On Mac OS X:
>>> from appdirs import * >>> appname = "SuperApp" >>> appauthor = "Acme" >>> user_data_dir(appname, appauthor) '/Users/trentm/Library/Application Support/SuperApp' >>> site_data_dir(appname, appauthor) '/Library/Application Support/SuperApp' >>> user_cache_dir(appname, appauthor) '/Users/trentm/Library/Caches/SuperApp' >>> user_log_dir(appname, appauthor) '/Users/trentm/Library/Logs/SuperApp'
On Windows 7:
>>> from appdirs 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_cache_dir(appname, appauthor) 'C:\\Users\\trentm\\AppData\\Local\\Acme\\SuperApp\\Cache' >>> user_log_dir(appname, appauthor) 'C:\\Users\\trentm\\AppData\\Local\\Acme\\SuperApp\\Logs'
On Linux:
>>> from appdirs import * >>> appname = "SuperApp" >>> appauthor = "Acme" >>> user_data_dir(appname, appauthor) '/home/trentm/.config/superapp >>> site_data_dir(appname, appauthor) '/etc/xdg/superapp' >>> user_cache_dir(appname, appauthor) '/home/trentm/.cache/superapp' >>> user_log_dir(appname, appauthor) '/home/trentm/.cache/superapp/log'
AppDirs for convenience
>>> from appdirs import AppDirs >>> dirs = AppDirs("SuperApp", "Acme") >>> dirs.user_data_dir '/Users/trentm/Library/Application Support/SuperApp' >>> dirs.site_data_dir '/Library/Application Support/SuperApp' >>> dirs.user_cache_dir '/Users/trentm/Library/Caches/SuperApp' >>> dirs.user_log_dir '/Users/trentm/Library/Logs/SuperApp'
Per-version isolation
If you have multiple versions of your app in use that you want to be able to run side-by-side, then you may want version-isolation for these dirs:
>>> from appdirs import AppDirs >>> dirs = AppDirs("SuperApp", "Acme", version="1.0") >>> dirs.user_data_dir '/Users/trentm/Library/Application Support/SuperApp/1.0' >>> dirs.site_data_dir '/Library/Application Support/SuperApp/1.0' >>> dirs.user_cache_dir '/Users/trentm/Library/Caches/SuperApp/1.0' >>> dirs.user_log_dir '/Users/trentm/Library/Logs/SuperApp/1.0'
appdirs Changelog
appdirs 1.2.0
[Unix] Put user_log_dir under the cache dir on Unix. Seems to be more typical.
[issue 9] Make unicode work on py3k.
appdirs 1.1.0
[issue 4] Add AppDirs.user_log_dir.
[Unix, issue 2, issue 7] appdirs now conforms to XDG base directory spec.
[Mac, issue 5] Fix site_data_dir() on Mac.
[Mac] Drop use of ‘Carbon’ module in favour of hardcoded paths; supports Python3 now.
[Windows] Append “Cache” to user_cache_dir on Windows by default. Use opinion=False option to disable this.
Add appdirs.AppDirs convenience class. Usage:
>>> dirs = AppDirs("SuperApp", "Acme", version="1.0") >>> dirs.user_data_dir '/Users/trentm/Library/Application Support/SuperApp/1.0'
[Windows] Cherry-pick Komodo’s change to downgrade paths to the Windows short paths if there are high bit chars.
[Linux] Change default user_cache_dir() on Linux to be singular, e.g. “~/.superapp/cache”.
[Windows] Add roaming option to user_data_dir() (for use on Windows only) and change the default user_data_dir behaviour to use a non-roaming profile dir (CSIDL_LOCAL_APPDATA instead of CSIDL_APPDATA). Why? Because a large roaming profile can cause login speed issues. The “only syncs on logout” behaviour can cause surprises in appdata info.
appdirs 1.0.1 (never released)
Started this changelog 27 July 2010. Before that this module originated in the Komodo product as applib.py and then as applib/location.py (used by PyPM in ActivePython). This is basically a fork of applib.py 1.0.1 and applib/location.py 1.0.1.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.