1Metadata-Version: 1.2
2Name: appdirs
3Version: 1.4.4
4Summary: A small Python module for determining appropriate platform-specific dirs, e.g. a "user data dir".
5Home-page: http://github.com/ActiveState/appdirs
6Author: Trent Mick
7Author-email: trentm@gmail.com
8Maintainer: Jeff Rouse
9Maintainer-email: jr@its.to
10License: MIT
11Description:
12        .. image:: https://secure.travis-ci.org/ActiveState/appdirs.png
13            :target: http://travis-ci.org/ActiveState/appdirs
14
15        the problem
16        ===========
17
18        What directory should your app use for storing user data? If running on Mac OS X, you
19        should use::
20
21            ~/Library/Application Support/<AppName>
22
23        If on Windows (at least English Win XP) that should be::
24
25            C:\Documents and Settings\<User>\Application Data\Local Settings\<AppAuthor>\<AppName>
26
27        or possibly::
28
29            C:\Documents and Settings\<User>\Application Data\<AppAuthor>\<AppName>
30
31        for `roaming profiles <http://bit.ly/9yl3b6>`_ but that is another story.
32
33        On Linux (and other Unices) the dir, according to the `XDG
34        spec <http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html>`_, is::
35
36            ~/.local/share/<AppName>
37
38
39        ``appdirs`` to the rescue
40        =========================
41
42        This kind of thing is what the ``appdirs`` module is for. ``appdirs`` will
43        help you choose an appropriate:
44
45        - user data dir (``user_data_dir``)
46        - user config dir (``user_config_dir``)
47        - user cache dir (``user_cache_dir``)
48        - site data dir (``site_data_dir``)
49        - site config dir (``site_config_dir``)
50        - user log dir (``user_log_dir``)
51
52        and also:
53
54        - is a single module so other Python packages can include their own private copy
55        - is slightly opinionated on the directory names used. Look for "OPINION" in
56          documentation and code for when an opinion is being applied.
57
58
59        some example output
60        ===================
61
62        On Mac OS X::
63
64            >>> from appdirs import *
65            >>> appname = "SuperApp"
66            >>> appauthor = "Acme"
67            >>> user_data_dir(appname, appauthor)
68            '/Users/trentm/Library/Application Support/SuperApp'
69            >>> site_data_dir(appname, appauthor)
70            '/Library/Application Support/SuperApp'
71            >>> user_cache_dir(appname, appauthor)
72            '/Users/trentm/Library/Caches/SuperApp'
73            >>> user_log_dir(appname, appauthor)
74            '/Users/trentm/Library/Logs/SuperApp'
75
76        On Windows 7::
77
78            >>> from appdirs import *
79            >>> appname = "SuperApp"
80            >>> appauthor = "Acme"
81            >>> user_data_dir(appname, appauthor)
82            'C:\\Users\\trentm\\AppData\\Local\\Acme\\SuperApp'
83            >>> user_data_dir(appname, appauthor, roaming=True)
84            'C:\\Users\\trentm\\AppData\\Roaming\\Acme\\SuperApp'
85            >>> user_cache_dir(appname, appauthor)
86            'C:\\Users\\trentm\\AppData\\Local\\Acme\\SuperApp\\Cache'
87            >>> user_log_dir(appname, appauthor)
88            'C:\\Users\\trentm\\AppData\\Local\\Acme\\SuperApp\\Logs'
89
90        On Linux::
91
92            >>> from appdirs import *
93            >>> appname = "SuperApp"
94            >>> appauthor = "Acme"
95            >>> user_data_dir(appname, appauthor)
96            '/home/trentm/.local/share/SuperApp
97            >>> site_data_dir(appname, appauthor)
98            '/usr/local/share/SuperApp'
99            >>> site_data_dir(appname, appauthor, multipath=True)
100            '/usr/local/share/SuperApp:/usr/share/SuperApp'
101            >>> user_cache_dir(appname, appauthor)
102            '/home/trentm/.cache/SuperApp'
103            >>> user_log_dir(appname, appauthor)
104            '/home/trentm/.cache/SuperApp/log'
105            >>> user_config_dir(appname)
106            '/home/trentm/.config/SuperApp'
107            >>> site_config_dir(appname)
108            '/etc/xdg/SuperApp'
109            >>> os.environ['XDG_CONFIG_DIRS'] = '/etc:/usr/local/etc'
110            >>> site_config_dir(appname, multipath=True)
111            '/etc/SuperApp:/usr/local/etc/SuperApp'
112
113
114        ``AppDirs`` for convenience
115        ===========================
116
117        ::
118
119            >>> from appdirs import AppDirs
120            >>> dirs = AppDirs("SuperApp", "Acme")
121            >>> dirs.user_data_dir
122            '/Users/trentm/Library/Application Support/SuperApp'
123            >>> dirs.site_data_dir
124            '/Library/Application Support/SuperApp'
125            >>> dirs.user_cache_dir
126            '/Users/trentm/Library/Caches/SuperApp'
127            >>> dirs.user_log_dir
128            '/Users/trentm/Library/Logs/SuperApp'
129
130
131
132        Per-version isolation
133        =====================
134
135        If you have multiple versions of your app in use that you want to be
136        able to run side-by-side, then you may want version-isolation for these
137        dirs::
138
139            >>> from appdirs import AppDirs
140            >>> dirs = AppDirs("SuperApp", "Acme", version="1.0")
141            >>> dirs.user_data_dir
142            '/Users/trentm/Library/Application Support/SuperApp/1.0'
143            >>> dirs.site_data_dir
144            '/Library/Application Support/SuperApp/1.0'
145            >>> dirs.user_cache_dir
146            '/Users/trentm/Library/Caches/SuperApp/1.0'
147            >>> dirs.user_log_dir
148            '/Users/trentm/Library/Logs/SuperApp/1.0'
149
150
151
152        appdirs Changelog
153        =================
154
155        appdirs 1.4.4
156        -------------
157        - [PR #92] Don't import appdirs from setup.py
158
159        Project officially classified as Stable which is important
160        for inclusion in other distros such as ActivePython.
161
162        First of several incremental releases to catch up on maintenance.
163
164        appdirs 1.4.3
165        -------------
166        - [PR #76] Python 3.6 invalid escape sequence deprecation fixes
167        - Fix for Python 3.6 support
168
169        appdirs 1.4.2
170        -------------
171        - [PR #84] Allow installing without setuptools
172        - [PR #86] Fix string delimiters in setup.py description
173        - Add Python 3.6 support
174
175        appdirs 1.4.1
176        -------------
177        - [issue #38] Fix _winreg import on Windows Py3
178        - [issue #55] Make appname optional
179
180        appdirs 1.4.0
181        -------------
182        - [PR #42] AppAuthor is now optional on Windows
183        - [issue 41] Support Jython on Windows, Mac, and Unix-like platforms. Windows
184          support requires `JNA <https://github.com/twall/jna>`_.
185        - [PR #44] Fix incorrect behaviour of the site_config_dir method
186
187        appdirs 1.3.0
188        -------------
189        - [Unix, issue 16] Conform to XDG standard, instead of breaking it for
190          everybody
191        - [Unix] Removes gratuitous case mangling of the case, since \*nix-es are
192          usually case sensitive, so mangling is not wise
193        - [Unix] Fixes the utterly wrong behaviour in ``site_data_dir``, return result
194          based on XDG_DATA_DIRS and make room for respecting the standard which
195          specifies XDG_DATA_DIRS is a multiple-value variable
196        - [Issue 6] Add ``*_config_dir`` which are distinct on nix-es, according to
197          XDG specs; on Windows and Mac return the corresponding ``*_data_dir``
198
199        appdirs 1.2.0
200        -------------
201
202        - [Unix] Put ``user_log_dir`` under the *cache* dir on Unix. Seems to be more
203          typical.
204        - [issue 9] Make ``unicode`` work on py3k.
205
206        appdirs 1.1.0
207        -------------
208
209        - [issue 4] Add ``AppDirs.user_log_dir``.
210        - [Unix, issue 2, issue 7] appdirs now conforms to `XDG base directory spec
211          <http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html>`_.
212        - [Mac, issue 5] Fix ``site_data_dir()`` on Mac.
213        - [Mac] Drop use of 'Carbon' module in favour of hardcoded paths; supports
214          Python3 now.
215        - [Windows] Append "Cache" to ``user_cache_dir`` on Windows by default. Use
216          ``opinion=False`` option to disable this.
217        - Add ``appdirs.AppDirs`` convenience class. Usage:
218
219                >>> dirs = AppDirs("SuperApp", "Acme", version="1.0")
220                >>> dirs.user_data_dir
221                '/Users/trentm/Library/Application Support/SuperApp/1.0'
222
223        - [Windows] Cherry-pick Komodo's change to downgrade paths to the Windows short
224          paths if there are high bit chars.
225        - [Linux] Change default ``user_cache_dir()`` on Linux to be singular, e.g.
226          "~/.superapp/cache".
227        - [Windows] Add ``roaming`` option to ``user_data_dir()`` (for use on Windows only)
228          and change the default ``user_data_dir`` behaviour to use a *non*-roaming
229          profile dir (``CSIDL_LOCAL_APPDATA`` instead of ``CSIDL_APPDATA``). Why? Because
230          a large roaming profile can cause login speed issues. The "only syncs on
231          logout" behaviour can cause surprises in appdata info.
232
233
234        appdirs 1.0.1 (never released)
235        ------------------------------
236
237        Started this changelog 27 July 2010. Before that this module originated in the
238        `Komodo <http://www.activestate.com/komodo>`_ product as ``applib.py`` and then
239        as `applib/location.py
240        <http://github.com/ActiveState/applib/blob/master/applib/location.py>`_ (used by
241        `PyPM <http://code.activestate.com/pypm/>`_ in `ActivePython
242        <http://www.activestate.com/activepython>`_). This is basically a fork of
243        applib.py 1.0.1 and applib/location.py 1.0.1.
244
245
246Keywords: application directory log cache user
247Platform: UNKNOWN
248Classifier: Development Status :: 5 - Production/Stable
249Classifier: Intended Audience :: Developers
250Classifier: License :: OSI Approved :: MIT License
251Classifier: Operating System :: OS Independent
252Classifier: Programming Language :: Python :: 2
253Classifier: Programming Language :: Python :: 2.7
254Classifier: Programming Language :: Python :: 3
255Classifier: Programming Language :: Python :: 3.4
256Classifier: Programming Language :: Python :: 3.5
257Classifier: Programming Language :: Python :: 3.6
258Classifier: Programming Language :: Python :: 3.7
259Classifier: Programming Language :: Python :: 3.8
260Classifier: Programming Language :: Python :: Implementation :: PyPy
261Classifier: Programming Language :: Python :: Implementation :: CPython
262Classifier: Topic :: Software Development :: Libraries :: Python Modules
263