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