appdirs-1.4.3/0000755000076500000240000000000013057460772012732 5ustar jrstaff00000000000000appdirs-1.4.3/appdirs.egg-info/0000755000076500000240000000000013057460772016066 5ustar jrstaff00000000000000appdirs-1.4.3/appdirs.egg-info/dependency_links.txt0000644000076500000240000000000113057460772022134 0ustar jrstaff00000000000000 appdirs-1.4.3/appdirs.egg-info/PKG-INFO0000644000076500000240000002453413057460772017173 0ustar jrstaff00000000000000Metadata-Version: 1.1 Name: appdirs Version: 1.4.3 Summary: A small Python module for determining appropriate platform-specific dirs, e.g. a "user data dir". Home-page: http://github.com/ActiveState/appdirs Author: Trent Mick; Sridhar Ratnakumar; Jeff Rouse Author-email: trentm@gmail.com; github@srid.name; jr@its.to License: MIT Description: .. image:: https://secure.travis-ci.org/ActiveState/appdirs.png :target: http://travis-ci.org/ActiveState/appdirs the problem =========== What directory should your app use for storing user data? If running on Mac OS X, you should use:: ~/Library/Application Support/ If on Windows (at least English Win XP) that should be:: C:\Documents and Settings\\Application Data\Local Settings\\ or possibly:: C:\Documents and Settings\\Application Data\\ for `roaming profiles `_ but that is another story. On Linux (and other Unices) the dir, according to the `XDG spec `_, is:: ~/.local/share/ ``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 config dir (``user_config_dir``) - user cache dir (``user_cache_dir``) - site data dir (``site_data_dir``) - site config dir (``site_config_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/.local/share/SuperApp >>> site_data_dir(appname, appauthor) '/usr/local/share/SuperApp' >>> site_data_dir(appname, appauthor, multipath=True) '/usr/local/share/SuperApp:/usr/share/SuperApp' >>> user_cache_dir(appname, appauthor) '/home/trentm/.cache/SuperApp' >>> user_log_dir(appname, appauthor) '/home/trentm/.cache/SuperApp/log' >>> user_config_dir(appname) '/home/trentm/.config/SuperApp' >>> site_config_dir(appname) '/etc/xdg/SuperApp' >>> os.environ['XDG_CONFIG_DIRS'] = '/etc:/usr/local/etc' >>> site_config_dir(appname, multipath=True) '/etc/SuperApp:/usr/local/etc/SuperApp' ``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.4.3 ------------- - [PR #76] Python 3.6 invalid escape sequence deprecation fixes - Fix for Python 3.6 support appdirs 1.4.2 ------------- - [PR #84] Allow installing without setuptools - [PR #86] Fix string delimiters in setup.py description - Add Python 3.6 support appdirs 1.4.1 ------------- - [issue #38] Fix _winreg import on Windows Py3 - [issue #55] Make appname optional appdirs 1.4.0 ------------- - [PR #42] AppAuthor is now optional on Windows - [issue 41] Support Jython on Windows, Mac, and Unix-like platforms. Windows support requires `JNA `_. - [PR #44] Fix incorrect behaviour of the site_config_dir method appdirs 1.3.0 ------------- - [Unix, issue 16] Conform to XDG standard, instead of breaking it for everybody - [Unix] Removes gratuitous case mangling of the case, since \*nix-es are usually case sensitive, so mangling is not wise - [Unix] Fixes the utterly wrong behaviour in ``site_data_dir``, return result based on XDG_DATA_DIRS and make room for respecting the standard which specifies XDG_DATA_DIRS is a multiple-value variable - [Issue 6] Add ``*_config_dir`` which are distinct on nix-es, according to XDG specs; on Windows and Mac return the corresponding ``*_data_dir`` 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. Keywords: application directory log cache user Platform: UNKNOWN Classifier: Development Status :: 4 - Beta Classifier: Intended Audience :: Developers Classifier: License :: OSI Approved :: MIT License Classifier: Operating System :: OS Independent Classifier: Programming Language :: Python :: 2 Classifier: Programming Language :: Python :: 2.6 Classifier: Programming Language :: Python :: 2.7 Classifier: Programming Language :: Python :: 3 Classifier: Programming Language :: Python :: 3.2 Classifier: Programming Language :: Python :: 3.3 Classifier: Programming Language :: Python :: 3.4 Classifier: Programming Language :: Python :: 3.5 Classifier: Programming Language :: Python :: 3.6 Classifier: Programming Language :: Python :: Implementation :: PyPy Classifier: Programming Language :: Python :: Implementation :: CPython Classifier: Topic :: Software Development :: Libraries :: Python Modules appdirs-1.4.3/appdirs.egg-info/SOURCES.txt0000644000076500000240000000035213057460772017752 0ustar jrstaff00000000000000CHANGES.rst LICENSE.txt MANIFEST.in README.rst appdirs.py setup.cfg setup.py appdirs.egg-info/PKG-INFO appdirs.egg-info/SOURCES.txt appdirs.egg-info/dependency_links.txt appdirs.egg-info/top_level.txt test/__init__.py test/test_api.pyappdirs-1.4.3/appdirs.egg-info/top_level.txt0000644000076500000240000000001013057460772020607 0ustar jrstaff00000000000000appdirs appdirs-1.4.3/appdirs.py0000644000076500000240000006017513057456407014757 0ustar jrstaff00000000000000#!/usr/bin/env python # -*- coding: utf-8 -*- # Copyright (c) 2005-2010 ActiveState Software Inc. # Copyright (c) 2013 Eddy Petrișor """Utilities for determining application-specific dirs. See for details and usage. """ # Dev Notes: # - MSDN on where to store app data files: # http://support.microsoft.com/default.aspx?scid=kb;en-us;310294#XSLTH3194121123120121120120 # - Mac OS X: http://developer.apple.com/documentation/MacOSX/Conceptual/BPFileSystem/index.html # - XDG spec for Un*x: http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html __version_info__ = (1, 4, 3) __version__ = '.'.join(map(str, __version_info__)) import sys import os PY3 = sys.version_info[0] == 3 if PY3: unicode = str if sys.platform.startswith('java'): import platform os_name = platform.java_ver()[3][0] if os_name.startswith('Windows'): # "Windows XP", "Windows 7", etc. system = 'win32' elif os_name.startswith('Mac'): # "Mac OS X", etc. system = 'darwin' else: # "Linux", "SunOS", "FreeBSD", etc. # Setting this to "linux2" is not ideal, but only Windows or Mac # are actually checked for and the rest of the module expects # *sys.platform* style strings. system = 'linux2' else: system = sys.platform def user_data_dir(appname=None, appauthor=None, version=None, roaming=False): r"""Return full path to the user-specific data dir for this application. "appname" is the name of application. If None, just the system directory is returned. "appauthor" (only used on Windows) is the name of the appauthor or distributing body for this application. Typically it is the owning company name. This falls back to appname. You may pass False to disable it. "version" is an optional version path element to append to the path. You might want to use this if you want multiple versions of your app to be able to run independently. If used, this would typically be ".". Only applied when appname is present. "roaming" (boolean, default False) can be set True to use the Windows roaming appdata directory. That means that for users on a Windows network setup for roaming profiles, this user data will be sync'd on login. See for a discussion of issues. Typical user data directories are: Mac OS X: ~/Library/Application Support/ Unix: ~/.local/share/ # or in $XDG_DATA_HOME, if defined Win XP (not roaming): C:\Documents and Settings\\Application Data\\ Win XP (roaming): C:\Documents and Settings\\Local Settings\Application Data\\ Win 7 (not roaming): C:\Users\\AppData\Local\\ Win 7 (roaming): C:\Users\\AppData\Roaming\\ For Unix, we follow the XDG spec and support $XDG_DATA_HOME. That means, by default "~/.local/share/". """ if system == "win32": if appauthor is None: appauthor = appname const = roaming and "CSIDL_APPDATA" or "CSIDL_LOCAL_APPDATA" path = os.path.normpath(_get_win_folder(const)) if appname: if appauthor is not False: path = os.path.join(path, appauthor, appname) else: path = os.path.join(path, appname) elif system == 'darwin': path = os.path.expanduser('~/Library/Application Support/') if appname: path = os.path.join(path, appname) else: path = os.getenv('XDG_DATA_HOME', os.path.expanduser("~/.local/share")) if appname: path = os.path.join(path, appname) if appname and version: path = os.path.join(path, version) return path def site_data_dir(appname=None, appauthor=None, version=None, multipath=False): r"""Return full path to the user-shared data dir for this application. "appname" is the name of application. If None, just the system directory is returned. "appauthor" (only used on Windows) is the name of the appauthor or distributing body for this application. Typically it is the owning company name. This falls back to appname. You may pass False to disable it. "version" is an optional version path element to append to the path. You might want to use this if you want multiple versions of your app to be able to run independently. If used, this would typically be ".". Only applied when appname is present. "multipath" is an optional parameter only applicable to *nix which indicates that the entire list of data dirs should be returned. By default, the first item from XDG_DATA_DIRS is returned, or '/usr/local/share/', if XDG_DATA_DIRS is not set Typical site data directories are: Mac OS X: /Library/Application Support/ Unix: /usr/local/share/ or /usr/share/ Win XP: C:\Documents and Settings\All Users\Application Data\\ Vista: (Fail! "C:\ProgramData" is a hidden *system* directory on Vista.) Win 7: C:\ProgramData\\ # Hidden, but writeable on Win 7. For Unix, this is using the $XDG_DATA_DIRS[0] default. WARNING: Do not use this on Windows. See the Vista-Fail note above for why. """ if system == "win32": if appauthor is None: appauthor = appname path = os.path.normpath(_get_win_folder("CSIDL_COMMON_APPDATA")) if appname: if appauthor is not False: path = os.path.join(path, appauthor, appname) else: path = os.path.join(path, appname) elif system == 'darwin': path = os.path.expanduser('/Library/Application Support') if appname: path = os.path.join(path, appname) else: # XDG default for $XDG_DATA_DIRS # only first, if multipath is False path = os.getenv('XDG_DATA_DIRS', os.pathsep.join(['/usr/local/share', '/usr/share'])) pathlist = [os.path.expanduser(x.rstrip(os.sep)) for x in path.split(os.pathsep)] if appname: if version: appname = os.path.join(appname, version) pathlist = [os.sep.join([x, appname]) for x in pathlist] if multipath: path = os.pathsep.join(pathlist) else: path = pathlist[0] return path if appname and version: path = os.path.join(path, version) return path def user_config_dir(appname=None, appauthor=None, version=None, roaming=False): r"""Return full path to the user-specific config dir for this application. "appname" is the name of application. If None, just the system directory is returned. "appauthor" (only used on Windows) is the name of the appauthor or distributing body for this application. Typically it is the owning company name. This falls back to appname. You may pass False to disable it. "version" is an optional version path element to append to the path. You might want to use this if you want multiple versions of your app to be able to run independently. If used, this would typically be ".". Only applied when appname is present. "roaming" (boolean, default False) can be set True to use the Windows roaming appdata directory. That means that for users on a Windows network setup for roaming profiles, this user data will be sync'd on login. See for a discussion of issues. Typical user config directories are: Mac OS X: same as user_data_dir Unix: ~/.config/ # or in $XDG_CONFIG_HOME, if defined Win *: same as user_data_dir For Unix, we follow the XDG spec and support $XDG_CONFIG_HOME. That means, by default "~/.config/". """ if system in ["win32", "darwin"]: path = user_data_dir(appname, appauthor, None, roaming) else: path = os.getenv('XDG_CONFIG_HOME', os.path.expanduser("~/.config")) if appname: path = os.path.join(path, appname) if appname and version: path = os.path.join(path, version) return path def site_config_dir(appname=None, appauthor=None, version=None, multipath=False): r"""Return full path to the user-shared data dir for this application. "appname" is the name of application. If None, just the system directory is returned. "appauthor" (only used on Windows) is the name of the appauthor or distributing body for this application. Typically it is the owning company name. This falls back to appname. You may pass False to disable it. "version" is an optional version path element to append to the path. You might want to use this if you want multiple versions of your app to be able to run independently. If used, this would typically be ".". Only applied when appname is present. "multipath" is an optional parameter only applicable to *nix which indicates that the entire list of config dirs should be returned. By default, the first item from XDG_CONFIG_DIRS is returned, or '/etc/xdg/', if XDG_CONFIG_DIRS is not set Typical site config directories are: Mac OS X: same as site_data_dir Unix: /etc/xdg/ or $XDG_CONFIG_DIRS[i]/ for each value in $XDG_CONFIG_DIRS Win *: same as site_data_dir Vista: (Fail! "C:\ProgramData" is a hidden *system* directory on Vista.) For Unix, this is using the $XDG_CONFIG_DIRS[0] default, if multipath=False WARNING: Do not use this on Windows. See the Vista-Fail note above for why. """ if system in ["win32", "darwin"]: path = site_data_dir(appname, appauthor) if appname and version: path = os.path.join(path, version) else: # XDG default for $XDG_CONFIG_DIRS # only first, if multipath is False path = os.getenv('XDG_CONFIG_DIRS', '/etc/xdg') pathlist = [os.path.expanduser(x.rstrip(os.sep)) for x in path.split(os.pathsep)] if appname: if version: appname = os.path.join(appname, version) pathlist = [os.sep.join([x, appname]) for x in pathlist] if multipath: path = os.pathsep.join(pathlist) else: path = pathlist[0] return path def user_cache_dir(appname=None, appauthor=None, version=None, opinion=True): r"""Return full path to the user-specific cache dir for this application. "appname" is the name of application. If None, just the system directory is returned. "appauthor" (only used on Windows) is the name of the appauthor or distributing body for this application. Typically it is the owning company name. This falls back to appname. You may pass False to disable it. "version" is an optional version path element to append to the path. You might want to use this if you want multiple versions of your app to be able to run independently. If used, this would typically be ".". Only applied when appname is present. "opinion" (boolean) can be False to disable the appending of "Cache" to the base app data dir for Windows. See discussion below. Typical user cache directories are: Mac OS X: ~/Library/Caches/ Unix: ~/.cache/ (XDG default) Win XP: C:\Documents and Settings\\Local Settings\Application Data\\\Cache Vista: C:\Users\\AppData\Local\\\Cache On Windows the only suggestion in the MSDN docs is that local settings go in the `CSIDL_LOCAL_APPDATA` directory. This is identical to the non-roaming app data dir (the default returned by `user_data_dir` above). Apps typically put cache data somewhere *under* the given dir here. Some examples: ...\Mozilla\Firefox\Profiles\\Cache ...\Acme\SuperApp\Cache\1.0 OPINION: This function appends "Cache" to the `CSIDL_LOCAL_APPDATA` value. This can be disabled with the `opinion=False` option. """ if system == "win32": if appauthor is None: appauthor = appname path = os.path.normpath(_get_win_folder("CSIDL_LOCAL_APPDATA")) if appname: if appauthor is not False: path = os.path.join(path, appauthor, appname) else: path = os.path.join(path, appname) if opinion: path = os.path.join(path, "Cache") elif system == 'darwin': path = os.path.expanduser('~/Library/Caches') if appname: path = os.path.join(path, appname) else: path = os.getenv('XDG_CACHE_HOME', os.path.expanduser('~/.cache')) if appname: path = os.path.join(path, appname) if appname and version: path = os.path.join(path, version) return path def user_state_dir(appname=None, appauthor=None, version=None, roaming=False): r"""Return full path to the user-specific state dir for this application. "appname" is the name of application. If None, just the system directory is returned. "appauthor" (only used on Windows) is the name of the appauthor or distributing body for this application. Typically it is the owning company name. This falls back to appname. You may pass False to disable it. "version" is an optional version path element to append to the path. You might want to use this if you want multiple versions of your app to be able to run independently. If used, this would typically be ".". Only applied when appname is present. "roaming" (boolean, default False) can be set True to use the Windows roaming appdata directory. That means that for users on a Windows network setup for roaming profiles, this user data will be sync'd on login. See for a discussion of issues. Typical user state directories are: Mac OS X: same as user_data_dir Unix: ~/.local/state/ # or in $XDG_STATE_HOME, if defined Win *: same as user_data_dir For Unix, we follow this Debian proposal to extend the XDG spec and support $XDG_STATE_HOME. That means, by default "~/.local/state/". """ if system in ["win32", "darwin"]: path = user_data_dir(appname, appauthor, None, roaming) else: path = os.getenv('XDG_STATE_HOME', os.path.expanduser("~/.local/state")) if appname: path = os.path.join(path, appname) if appname and version: path = os.path.join(path, version) return path def user_log_dir(appname=None, appauthor=None, version=None, opinion=True): r"""Return full path to the user-specific log dir for this application. "appname" is the name of application. If None, just the system directory is returned. "appauthor" (only used on Windows) is the name of the appauthor or distributing body for this application. Typically it is the owning company name. This falls back to appname. You may pass False to disable it. "version" is an optional version path element to append to the path. You might want to use this if you want multiple versions of your app to be able to run independently. If used, this would typically be ".". Only applied when appname is present. "opinion" (boolean) can be False to disable the appending of "Logs" to the base app data dir for Windows, and "log" to the base cache dir for Unix. See discussion below. Typical user log directories are: Mac OS X: ~/Library/Logs/ Unix: ~/.cache//log # or under $XDG_CACHE_HOME if defined Win XP: C:\Documents and Settings\\Local Settings\Application Data\\\Logs Vista: C:\Users\\AppData\Local\\\Logs On Windows the only suggestion in the MSDN docs is that local settings go in the `CSIDL_LOCAL_APPDATA` directory. (Note: I'm interested in examples of what some windows apps use for a logs dir.) OPINION: This function appends "Logs" to the `CSIDL_LOCAL_APPDATA` value for Windows and appends "log" to the user cache dir for Unix. This can be disabled with the `opinion=False` option. """ if system == "darwin": path = os.path.join( os.path.expanduser('~/Library/Logs'), appname) elif system == "win32": path = user_data_dir(appname, appauthor, version) version = False if opinion: path = os.path.join(path, "Logs") else: path = user_cache_dir(appname, appauthor, version) version = False if opinion: path = os.path.join(path, "log") if appname and version: path = os.path.join(path, version) return path class AppDirs(object): """Convenience wrapper for getting application dirs.""" def __init__(self, appname=None, appauthor=None, version=None, roaming=False, multipath=False): self.appname = appname self.appauthor = appauthor self.version = version self.roaming = roaming self.multipath = multipath @property def user_data_dir(self): return user_data_dir(self.appname, self.appauthor, version=self.version, roaming=self.roaming) @property def site_data_dir(self): return site_data_dir(self.appname, self.appauthor, version=self.version, multipath=self.multipath) @property def user_config_dir(self): return user_config_dir(self.appname, self.appauthor, version=self.version, roaming=self.roaming) @property def site_config_dir(self): return site_config_dir(self.appname, self.appauthor, version=self.version, multipath=self.multipath) @property def user_cache_dir(self): return user_cache_dir(self.appname, self.appauthor, version=self.version) @property def user_state_dir(self): return user_state_dir(self.appname, self.appauthor, version=self.version) @property def user_log_dir(self): return user_log_dir(self.appname, self.appauthor, version=self.version) #---- internal support stuff def _get_win_folder_from_registry(csidl_name): """This is a fallback technique at best. I'm not sure if using the registry for this guarantees us the correct answer for all CSIDL_* names. """ if PY3: import winreg as _winreg else: import _winreg shell_folder_name = { "CSIDL_APPDATA": "AppData", "CSIDL_COMMON_APPDATA": "Common AppData", "CSIDL_LOCAL_APPDATA": "Local AppData", }[csidl_name] key = _winreg.OpenKey( _winreg.HKEY_CURRENT_USER, r"Software\Microsoft\Windows\CurrentVersion\Explorer\Shell Folders" ) dir, type = _winreg.QueryValueEx(key, shell_folder_name) return dir def _get_win_folder_with_pywin32(csidl_name): from win32com.shell import shellcon, shell dir = shell.SHGetFolderPath(0, getattr(shellcon, csidl_name), 0, 0) # Try to make this a unicode path because SHGetFolderPath does # not return unicode strings when there is unicode data in the # path. try: dir = unicode(dir) # Downgrade to short path name if have highbit chars. See # . has_high_char = False for c in dir: if ord(c) > 255: has_high_char = True break if has_high_char: try: import win32api dir = win32api.GetShortPathName(dir) except ImportError: pass except UnicodeError: pass return dir def _get_win_folder_with_ctypes(csidl_name): import ctypes csidl_const = { "CSIDL_APPDATA": 26, "CSIDL_COMMON_APPDATA": 35, "CSIDL_LOCAL_APPDATA": 28, }[csidl_name] buf = ctypes.create_unicode_buffer(1024) ctypes.windll.shell32.SHGetFolderPathW(None, csidl_const, None, 0, buf) # Downgrade to short path name if have highbit chars. See # . has_high_char = False for c in buf: if ord(c) > 255: has_high_char = True break if has_high_char: buf2 = ctypes.create_unicode_buffer(1024) if ctypes.windll.kernel32.GetShortPathNameW(buf.value, buf2, 1024): buf = buf2 return buf.value def _get_win_folder_with_jna(csidl_name): import array from com.sun import jna from com.sun.jna.platform import win32 buf_size = win32.WinDef.MAX_PATH * 2 buf = array.zeros('c', buf_size) shell = win32.Shell32.INSTANCE shell.SHGetFolderPath(None, getattr(win32.ShlObj, csidl_name), None, win32.ShlObj.SHGFP_TYPE_CURRENT, buf) dir = jna.Native.toString(buf.tostring()).rstrip("\0") # Downgrade to short path name if have highbit chars. See # . has_high_char = False for c in dir: if ord(c) > 255: has_high_char = True break if has_high_char: buf = array.zeros('c', buf_size) kernel = win32.Kernel32.INSTANCE if kernel.GetShortPathName(dir, buf, buf_size): dir = jna.Native.toString(buf.tostring()).rstrip("\0") return dir if system == "win32": try: import win32com.shell _get_win_folder = _get_win_folder_with_pywin32 except ImportError: try: from ctypes import windll _get_win_folder = _get_win_folder_with_ctypes except ImportError: try: import com.sun.jna _get_win_folder = _get_win_folder_with_jna except ImportError: _get_win_folder = _get_win_folder_from_registry #---- self test code if __name__ == "__main__": appname = "MyApp" appauthor = "MyCompany" props = ("user_data_dir", "user_config_dir", "user_cache_dir", "user_state_dir", "user_log_dir", "site_data_dir", "site_config_dir") print("-- app dirs %s --" % __version__) print("-- app dirs (with optional 'version')") dirs = AppDirs(appname, appauthor, version="1.0") for prop in props: print("%s: %s" % (prop, getattr(dirs, prop))) print("\n-- app dirs (without optional 'version')") dirs = AppDirs(appname, appauthor) for prop in props: print("%s: %s" % (prop, getattr(dirs, prop))) print("\n-- app dirs (without optional 'appauthor')") dirs = AppDirs(appname) for prop in props: print("%s: %s" % (prop, getattr(dirs, prop))) print("\n-- app dirs (with disabled 'appauthor')") dirs = AppDirs(appname, appauthor=False) for prop in props: print("%s: %s" % (prop, getattr(dirs, prop))) appdirs-1.4.3/CHANGES.rst0000644000076500000240000000627213057456407014543 0ustar jrstaff00000000000000appdirs Changelog ================= appdirs 1.4.3 ------------- - [PR #76] Python 3.6 invalid escape sequence deprecation fixes - Fix for Python 3.6 support appdirs 1.4.2 ------------- - [PR #84] Allow installing without setuptools - [PR #86] Fix string delimiters in setup.py description - Add Python 3.6 support appdirs 1.4.1 ------------- - [issue #38] Fix _winreg import on Windows Py3 - [issue #55] Make appname optional appdirs 1.4.0 ------------- - [PR #42] AppAuthor is now optional on Windows - [issue 41] Support Jython on Windows, Mac, and Unix-like platforms. Windows support requires `JNA `_. - [PR #44] Fix incorrect behaviour of the site_config_dir method appdirs 1.3.0 ------------- - [Unix, issue 16] Conform to XDG standard, instead of breaking it for everybody - [Unix] Removes gratuitous case mangling of the case, since \*nix-es are usually case sensitive, so mangling is not wise - [Unix] Fixes the utterly wrong behaviour in ``site_data_dir``, return result based on XDG_DATA_DIRS and make room for respecting the standard which specifies XDG_DATA_DIRS is a multiple-value variable - [Issue 6] Add ``*_config_dir`` which are distinct on nix-es, according to XDG specs; on Windows and Mac return the corresponding ``*_data_dir`` 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. appdirs-1.4.3/LICENSE.txt0000644000076500000240000000211113044552622014540 0ustar jrstaff00000000000000# This is the MIT license Copyright (c) 2010 ActiveState Software Inc. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. appdirs-1.4.3/MANIFEST.in0000644000076500000240000000013213044552622014454 0ustar jrstaff00000000000000include README.rst include CHANGES.rst include LICENSE.txt include *.py include test/*.py appdirs-1.4.3/PKG-INFO0000644000076500000240000002453413057460772014037 0ustar jrstaff00000000000000Metadata-Version: 1.1 Name: appdirs Version: 1.4.3 Summary: A small Python module for determining appropriate platform-specific dirs, e.g. a "user data dir". Home-page: http://github.com/ActiveState/appdirs Author: Trent Mick; Sridhar Ratnakumar; Jeff Rouse Author-email: trentm@gmail.com; github@srid.name; jr@its.to License: MIT Description: .. image:: https://secure.travis-ci.org/ActiveState/appdirs.png :target: http://travis-ci.org/ActiveState/appdirs the problem =========== What directory should your app use for storing user data? If running on Mac OS X, you should use:: ~/Library/Application Support/ If on Windows (at least English Win XP) that should be:: C:\Documents and Settings\\Application Data\Local Settings\\ or possibly:: C:\Documents and Settings\\Application Data\\ for `roaming profiles `_ but that is another story. On Linux (and other Unices) the dir, according to the `XDG spec `_, is:: ~/.local/share/ ``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 config dir (``user_config_dir``) - user cache dir (``user_cache_dir``) - site data dir (``site_data_dir``) - site config dir (``site_config_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/.local/share/SuperApp >>> site_data_dir(appname, appauthor) '/usr/local/share/SuperApp' >>> site_data_dir(appname, appauthor, multipath=True) '/usr/local/share/SuperApp:/usr/share/SuperApp' >>> user_cache_dir(appname, appauthor) '/home/trentm/.cache/SuperApp' >>> user_log_dir(appname, appauthor) '/home/trentm/.cache/SuperApp/log' >>> user_config_dir(appname) '/home/trentm/.config/SuperApp' >>> site_config_dir(appname) '/etc/xdg/SuperApp' >>> os.environ['XDG_CONFIG_DIRS'] = '/etc:/usr/local/etc' >>> site_config_dir(appname, multipath=True) '/etc/SuperApp:/usr/local/etc/SuperApp' ``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.4.3 ------------- - [PR #76] Python 3.6 invalid escape sequence deprecation fixes - Fix for Python 3.6 support appdirs 1.4.2 ------------- - [PR #84] Allow installing without setuptools - [PR #86] Fix string delimiters in setup.py description - Add Python 3.6 support appdirs 1.4.1 ------------- - [issue #38] Fix _winreg import on Windows Py3 - [issue #55] Make appname optional appdirs 1.4.0 ------------- - [PR #42] AppAuthor is now optional on Windows - [issue 41] Support Jython on Windows, Mac, and Unix-like platforms. Windows support requires `JNA `_. - [PR #44] Fix incorrect behaviour of the site_config_dir method appdirs 1.3.0 ------------- - [Unix, issue 16] Conform to XDG standard, instead of breaking it for everybody - [Unix] Removes gratuitous case mangling of the case, since \*nix-es are usually case sensitive, so mangling is not wise - [Unix] Fixes the utterly wrong behaviour in ``site_data_dir``, return result based on XDG_DATA_DIRS and make room for respecting the standard which specifies XDG_DATA_DIRS is a multiple-value variable - [Issue 6] Add ``*_config_dir`` which are distinct on nix-es, according to XDG specs; on Windows and Mac return the corresponding ``*_data_dir`` 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. Keywords: application directory log cache user Platform: UNKNOWN Classifier: Development Status :: 4 - Beta Classifier: Intended Audience :: Developers Classifier: License :: OSI Approved :: MIT License Classifier: Operating System :: OS Independent Classifier: Programming Language :: Python :: 2 Classifier: Programming Language :: Python :: 2.6 Classifier: Programming Language :: Python :: 2.7 Classifier: Programming Language :: Python :: 3 Classifier: Programming Language :: Python :: 3.2 Classifier: Programming Language :: Python :: 3.3 Classifier: Programming Language :: Python :: 3.4 Classifier: Programming Language :: Python :: 3.5 Classifier: Programming Language :: Python :: 3.6 Classifier: Programming Language :: Python :: Implementation :: PyPy Classifier: Programming Language :: Python :: Implementation :: CPython Classifier: Topic :: Software Development :: Libraries :: Python Modules appdirs-1.4.3/README.rst0000644000076500000240000001026013044552622014410 0ustar jrstaff00000000000000.. image:: https://secure.travis-ci.org/ActiveState/appdirs.png :target: http://travis-ci.org/ActiveState/appdirs the problem =========== What directory should your app use for storing user data? If running on Mac OS X, you should use:: ~/Library/Application Support/ If on Windows (at least English Win XP) that should be:: C:\Documents and Settings\\Application Data\Local Settings\\ or possibly:: C:\Documents and Settings\\Application Data\\ for `roaming profiles `_ but that is another story. On Linux (and other Unices) the dir, according to the `XDG spec `_, is:: ~/.local/share/ ``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 config dir (``user_config_dir``) - user cache dir (``user_cache_dir``) - site data dir (``site_data_dir``) - site config dir (``site_config_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/.local/share/SuperApp >>> site_data_dir(appname, appauthor) '/usr/local/share/SuperApp' >>> site_data_dir(appname, appauthor, multipath=True) '/usr/local/share/SuperApp:/usr/share/SuperApp' >>> user_cache_dir(appname, appauthor) '/home/trentm/.cache/SuperApp' >>> user_log_dir(appname, appauthor) '/home/trentm/.cache/SuperApp/log' >>> user_config_dir(appname) '/home/trentm/.config/SuperApp' >>> site_config_dir(appname) '/etc/xdg/SuperApp' >>> os.environ['XDG_CONFIG_DIRS'] = '/etc:/usr/local/etc' >>> site_config_dir(appname, multipath=True) '/etc/SuperApp:/usr/local/etc/SuperApp' ``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-1.4.3/setup.cfg0000644000076500000240000000007513057460772014555 0ustar jrstaff00000000000000[wheel] universal = 1 [egg_info] tag_build = tag_date = 0 appdirs-1.4.3/setup.py0000644000076500000240000000375113053765231014444 0ustar jrstaff00000000000000#!/usr/bin/env python import sys import os import os.path # appdirs is a dependency of setuptools, so allow installing without it. try: from setuptools import setup except ImportError: from distutils.core import setup import appdirs tests_require = [] if sys.version_info < (2, 7): tests_require.append("unittest2") def read(fname): inf = open(os.path.join(os.path.dirname(__file__), fname)) out = "\n" + inf.read().replace("\r\n", "\n") inf.close() return out setup( name='appdirs', version=appdirs.__version__, description='A small Python module for determining appropriate ' + \ 'platform-specific dirs, e.g. a "user data dir".', long_description=read('README.rst') + '\n' + read('CHANGES.rst'), classifiers=[c.strip() for c in """ Development Status :: 4 - Beta Intended Audience :: Developers License :: OSI Approved :: MIT License Operating System :: OS Independent Programming Language :: Python :: 2 Programming Language :: Python :: 2.6 Programming Language :: Python :: 2.7 Programming Language :: Python :: 3 Programming Language :: Python :: 3.2 Programming Language :: Python :: 3.3 Programming Language :: Python :: 3.4 Programming Language :: Python :: 3.5 Programming Language :: Python :: 3.6 Programming Language :: Python :: Implementation :: PyPy Programming Language :: Python :: Implementation :: CPython Topic :: Software Development :: Libraries :: Python Modules """.split('\n') if c.strip()], test_suite='test.test_api', tests_require=tests_require, keywords='application directory log cache user', author='Trent Mick', author_email='trentm@gmail.com', maintainer='Trent Mick; Sridhar Ratnakumar; Jeff Rouse', maintainer_email='trentm@gmail.com; github@srid.name; jr@its.to', url='http://github.com/ActiveState/appdirs', license='MIT', py_modules=["appdirs"], ) appdirs-1.4.3/test/0000755000076500000240000000000013057460772013711 5ustar jrstaff00000000000000appdirs-1.4.3/test/__init__.py0000644000076500000240000000000013044552622016000 0ustar jrstaff00000000000000appdirs-1.4.3/test/test_api.py0000644000076500000240000000254713044554453016077 0ustar jrstaff00000000000000import sys import appdirs if sys.version_info < (2, 7): import unittest2 as unittest else: import unittest if sys.version_info[0] < 3: STRING_TYPE = basestring else: STRING_TYPE = str class Test_AppDir(unittest.TestCase): def test_metadata(self): self.assertTrue(hasattr(appdirs, "__version__")) self.assertTrue(hasattr(appdirs, "__version_info__")) def test_helpers(self): self.assertIsInstance( appdirs.user_data_dir('MyApp', 'MyCompany'), STRING_TYPE) self.assertIsInstance( appdirs.site_data_dir('MyApp', 'MyCompany'), STRING_TYPE) self.assertIsInstance( appdirs.user_cache_dir('MyApp', 'MyCompany'), STRING_TYPE) self.assertIsInstance( appdirs.user_state_dir('MyApp', 'MyCompany'), STRING_TYPE) self.assertIsInstance( appdirs.user_log_dir('MyApp', 'MyCompany'), STRING_TYPE) def test_dirs(self): dirs = appdirs.AppDirs('MyApp', 'MyCompany', version='1.0') self.assertIsInstance(dirs.user_data_dir, STRING_TYPE) self.assertIsInstance(dirs.site_data_dir, STRING_TYPE) self.assertIsInstance(dirs.user_cache_dir, STRING_TYPE) self.assertIsInstance(dirs.user_state_dir, STRING_TYPE) self.assertIsInstance(dirs.user_log_dir, STRING_TYPE) if __name__ == "__main__": unittest.main()