# Buildsheet autogenerated by ravenadm tool -- Do not edit.

NAMEBASE=		python-platformdirs
VERSION=		4.3.6
KEYWORDS=		python
VARIANTS=		v12 v13
SDESC[v12]=		Finds platform-specific directories (3.12)
SDESC[v13]=		Finds platform-specific directories (3.13)
HOMEPAGE=		https://github.com/tox-dev/platformdirs
CONTACT=		Python_Automaton[python@ironwolf.systems]

DOWNLOAD_GROUPS=	main
SITES[main]=		PYPIWHL/3c/a6/bc1012356d8ece4d66dd75c4b9fc6c1f6650ddd5991e421177d9f8f671be
DISTFILE[1]=		platformdirs-4.3.6-py3-none-any.whl:main
DF_INDEX=		1
SPKGS[v12]=		single
SPKGS[v13]=		single

OPTIONS_AVAILABLE=	PY312 PY313
OPTIONS_STANDARD=	none
VOPTS[v12]=		PY312=ON PY313=OFF
VOPTS[v13]=		PY312=OFF PY313=ON

DISTNAME=		platformdirs-4.3.6.dist-info

GENERATED=		yes

[PY312].USES_ON=			python:v12,wheel

[PY313].USES_ON=			python:v13,wheel

[FILE:2867:descriptions/desc.single]
The problem
===========

When writing desktop application, finding the right location to store user
data
and configuration varies per platform. Even for single-platform apps, there
may by plenty of nuances in figuring out the right location.

For example, if running on macOS, you should use::

    ~/Library/Application Support/<AppName>

If on Windows (at least English Win) 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), according to the `XDG Basedir Spec`_, it
should be::

    ~/.local/share/<AppName>

.. _XDG Basedir Spec:
https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html

platformdirs to the rescue
==============================

This kind of thing is what the platformdirs package is for.
platformdirs 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)
- user documents dir (user_documents_dir)
- user downloads dir (user_downloads_dir)
- user pictures dir (user_pictures_dir)
- user videos dir (user_videos_dir)
- user music dir (user_music_dir)
- user desktop dir (user_desktop_dir)
- user runtime dir (user_runtime_dir)

And also:

- Is slightly opinionated on the directory names used. Look for "OPINION"
in
  documentation and code for when an opinion is being applied.

Example output
==============

On macOS:

.. code-block:: pycon

    >>> from platformdirs 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'
    >>> user_documents_dir()
    '/Users/trentm/Documents'
    >>> user_downloads_dir()
    '/Users/trentm/Downloads'
    >>> user_pictures_dir()
    '/Users/trentm/Pictures'
    >>> user_videos_dir()
    '/Users/trentm/Movies'
    >>> user_music_dir()
    '/Users/trentm/Music'
    >>> user_desktop_dir()
    '/Users/trentm/Desktop'
    >>> user_runtime_dir(appname, appauthor)
    '/Users/trentm/Library/Caches/TemporaryItems/SuperApp'

On Windows:

.. code-block:: pycon

    >>> from platformdirs import *
    >>> appname = "SuperApp"
    >>> appauthor = "Acme"
    >>> user_data_dir(appname, appauthor)
    'C:\\Users\\trentm\\AppData\\Local\\Acme\\SuperApp'
    >>> user_data_dir(appname, appauthor, roaming=True)


[FILE:114:distinfo]
73e575e1408ab8103900836b97580d5307456908a03e92031bab39e4554cc3fb        18439 platformdirs-4.3.6-py3-none-any.whl