1.. image:: https://secure.travis-ci.org/ActiveState/appdirs.png 2 :target: http://travis-ci.org/ActiveState/appdirs 3 4the problem 5=========== 6 7What directory should your app use for storing user data? If running on Mac OS X, you 8should use:: 9 10 ~/Library/Application Support/<AppName> 11 12If on Windows (at least English Win XP) that should be:: 13 14 C:\Documents and Settings\<User>\Application Data\Local Settings\<AppAuthor>\<AppName> 15 16or possibly:: 17 18 C:\Documents and Settings\<User>\Application Data\<AppAuthor>\<AppName> 19 20for `roaming profiles <http://bit.ly/9yl3b6>`_ but that is another story. 21 22On Linux (and other Unices) the dir, according to the `XDG 23spec <http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html>`_, is:: 24 25 ~/.local/share/<AppName> 26 27 28``appdirs`` to the rescue 29========================= 30 31This kind of thing is what the ``appdirs`` module is for. ``appdirs`` will 32help you choose an appropriate: 33 34- user data dir (``user_data_dir``) 35- user config dir (``user_config_dir``) 36- user cache dir (``user_cache_dir``) 37- site data dir (``site_data_dir``) 38- site config dir (``site_config_dir``) 39- user log dir (``user_log_dir``) 40 41and also: 42 43- is a single module so other Python packages can include their own private copy 44- is slightly opinionated on the directory names used. Look for "OPINION" in 45 documentation and code for when an opinion is being applied. 46 47 48some example output 49=================== 50 51On Mac OS X:: 52 53 >>> from appdirs import * 54 >>> appname = "SuperApp" 55 >>> appauthor = "Acme" 56 >>> user_data_dir(appname, appauthor) 57 '/Users/trentm/Library/Application Support/SuperApp' 58 >>> site_data_dir(appname, appauthor) 59 '/Library/Application Support/SuperApp' 60 >>> user_cache_dir(appname, appauthor) 61 '/Users/trentm/Library/Caches/SuperApp' 62 >>> user_log_dir(appname, appauthor) 63 '/Users/trentm/Library/Logs/SuperApp' 64 65On Windows 7:: 66 67 >>> from appdirs import * 68 >>> appname = "SuperApp" 69 >>> appauthor = "Acme" 70 >>> user_data_dir(appname, appauthor) 71 'C:\\Users\\trentm\\AppData\\Local\\Acme\\SuperApp' 72 >>> user_data_dir(appname, appauthor, roaming=True) 73 'C:\\Users\\trentm\\AppData\\Roaming\\Acme\\SuperApp' 74 >>> user_cache_dir(appname, appauthor) 75 'C:\\Users\\trentm\\AppData\\Local\\Acme\\SuperApp\\Cache' 76 >>> user_log_dir(appname, appauthor) 77 'C:\\Users\\trentm\\AppData\\Local\\Acme\\SuperApp\\Logs' 78 79On Linux:: 80 81 >>> from appdirs import * 82 >>> appname = "SuperApp" 83 >>> appauthor = "Acme" 84 >>> user_data_dir(appname, appauthor) 85 '/home/trentm/.local/share/SuperApp 86 >>> site_data_dir(appname, appauthor) 87 '/usr/local/share/SuperApp' 88 >>> site_data_dir(appname, appauthor, multipath=True) 89 '/usr/local/share/SuperApp:/usr/share/SuperApp' 90 >>> user_cache_dir(appname, appauthor) 91 '/home/trentm/.cache/SuperApp' 92 >>> user_log_dir(appname, appauthor) 93 '/home/trentm/.cache/SuperApp/log' 94 >>> user_config_dir(appname) 95 '/home/trentm/.config/SuperApp' 96 >>> site_config_dir(appname) 97 '/etc/xdg/SuperApp' 98 >>> os.environ['XDG_CONFIG_DIRS'] = '/etc:/usr/local/etc' 99 >>> site_config_dir(appname, multipath=True) 100 '/etc/SuperApp:/usr/local/etc/SuperApp' 101 102 103``AppDirs`` for convenience 104=========================== 105 106:: 107 108 >>> from appdirs import AppDirs 109 >>> dirs = AppDirs("SuperApp", "Acme") 110 >>> dirs.user_data_dir 111 '/Users/trentm/Library/Application Support/SuperApp' 112 >>> dirs.site_data_dir 113 '/Library/Application Support/SuperApp' 114 >>> dirs.user_cache_dir 115 '/Users/trentm/Library/Caches/SuperApp' 116 >>> dirs.user_log_dir 117 '/Users/trentm/Library/Logs/SuperApp' 118 119 120 121Per-version isolation 122===================== 123 124If you have multiple versions of your app in use that you want to be 125able to run side-by-side, then you may want version-isolation for these 126dirs:: 127 128 >>> from appdirs import AppDirs 129 >>> dirs = AppDirs("SuperApp", "Acme", version="1.0") 130 >>> dirs.user_data_dir 131 '/Users/trentm/Library/Application Support/SuperApp/1.0' 132 >>> dirs.site_data_dir 133 '/Library/Application Support/SuperApp/1.0' 134 >>> dirs.user_cache_dir 135 '/Users/trentm/Library/Caches/SuperApp/1.0' 136 >>> dirs.user_log_dir 137 '/Users/trentm/Library/Logs/SuperApp/1.0' 138 139