Debian packaging for appdirs
Go to file
Benjamin Drung 74a9bbb862 Import Debian changes 1.4.0-3
appdirs (1.4.0-3) unstable; urgency=medium

  * Mention Eddy Petrișor in copyright file (Closes: #848313)
  * Bump Standards-Version to 3.9.8 (no changes needed)
  * Use https for copyright format specification
  * Use secure HTTPS for git URIs

appdirs (1.4.0-2) unstable; urgency=medium

  * Build pypy-appdirs package.
  * Add myself to Uploaders.
  * Add autopkgtest support.

appdirs (1.4.0-1) unstable; urgency=medium

  * New upstream release.
  * Use pypi.debian.net redirector for debian/watch
  * Bump Standards-Version to 3.9.6 (no changes required)
  * Update Vcs-Browser to point to cgit URL

appdirs (1.3.0-2) unstable; urgency=medium

  * Remove appdirs-1.3.0.egg-info symlink on upgrade. (Closes: #747088)

appdirs (1.3.0-1) unstable; urgency=medium

  * New upstream release.
  * debian/rules: Add missing test/__init__.py for tests.

appdirs (1.2.0+git20130326-1) unstable; urgency=low

  * Initial version. (Closes: #737107)
2018-06-22 12:08:21 +02:00
appdirs.egg-info Import Upstream version 1.4.0 2018-06-22 12:08:21 +02:00
debian Import Debian changes 1.4.0-3 2018-06-22 12:08:21 +02:00
test Import Upstream version 1.4.0 2018-06-22 12:08:21 +02:00
CHANGES.rst Import Upstream version 1.4.0 2018-06-22 12:08:21 +02:00
LICENSE.txt Import Upstream version 1.4.0 2018-06-22 12:08:21 +02:00
MANIFEST.in Import Upstream version 1.4.0 2018-06-22 12:08:21 +02:00
Makefile.py Import Upstream version 1.4.0 2018-06-22 12:08:21 +02:00
PKG-INFO Import Upstream version 1.4.0 2018-06-22 12:08:21 +02:00
README.rst Import Upstream version 1.4.0 2018-06-22 12:08:21 +02:00
appdirs.py Import Upstream version 1.4.0 2018-06-22 12:08:21 +02:00
setup.cfg Import Upstream version 1.4.0 2018-06-22 12:08:21 +02:00
setup.py Import Upstream version 1.4.0 2018-06-22 12:08:21 +02:00

README.rst

.. 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/<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 <http://bit.ly/9yl3b6>`_ but that is another story.

On Linux (and other Unices) the dir, according to the `XDG
spec <http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html>`_, 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'