README.rst
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
