Skip to main content

A small Python module for determining appropriate platform-specific dirs, e.g. a "user data dir".

Project description

https://secure.travis-ci.org/ActiveState/appdirs.png

the problem

What directory should your app use for storing user data? If running on Mac OS X, you should use:

~/Library/Application Support/<AppName>

If on Windows (at least English Win XP) that should be:

C:\Documents and Settings\<User>\Application Data\Local Settings\<AppAuthor>\<AppName>

or possibly:

C:\Documents and Settings\<User>\Application Data\<AppAuthor>\<AppName>

for roaming profiles but that is another story.

On Linux (and other Unices) the dir, according to the XDG spec, is:

~/.local/share/<AppName>

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.4

  • [PR #92] Don’t import appdirs from setup.py

Project officially classified as Stable which is important for inclusion in other distros such as ActivePython.

First of several incremental releases to catch up on maintenance.

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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

appdirs-1.4.4.tar.gz (13.5 kB view details)

Uploaded Source

Built Distribution

appdirs-1.4.4-py2.py3-none-any.whl (9.6 kB view details)

Uploaded Python 2 Python 3

File details

Details for the file appdirs-1.4.4.tar.gz.

File metadata

  • Download URL: appdirs-1.4.4.tar.gz
  • Upload date:
  • Size: 13.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.15.0 pkginfo/1.5.0.1 requests/2.23.0 setuptools/46.1.3 requests-toolbelt/0.9.1 tqdm/4.45.0 CPython/3.5.4

File hashes

Hashes for appdirs-1.4.4.tar.gz
Algorithm Hash digest
SHA256 7d5d0167b2b1ba821647616af46a749d1c653740dd0d2415100fe26e27afdf41
MD5 d6bca12613174185dd9abc8a29f4f012
BLAKE2b-256 d7d805696357e0311f5b5c316d7b95f46c669dd9c15aaeecbb48c7d0aeb88c40

See more details on using hashes here.

File details

Details for the file appdirs-1.4.4-py2.py3-none-any.whl.

File metadata

  • Download URL: appdirs-1.4.4-py2.py3-none-any.whl
  • Upload date:
  • Size: 9.6 kB
  • Tags: Python 2, Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.15.0 pkginfo/1.5.0.1 requests/2.23.0 setuptools/46.1.3 requests-toolbelt/0.9.1 tqdm/4.45.0 CPython/3.5.4

File hashes

Hashes for appdirs-1.4.4-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 a841dacd6b99318a741b166adb07e19ee71a274450e68237b4650ca1055ab128
MD5 1d638a5913a8d8ed8e7c7d789ece149c
BLAKE2b-256 3b002344469e2084fb287c2e0b57b72910309874c3245463acd6cf5e3db69324

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page