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

NAMEBASE=		python-platformdirs
VERSION=		4.2.1
KEYWORDS=		python
VARIANTS=		v11 v12
SDESC[v11]=		Finds platform-specific directories (3.11)
SDESC[v12]=		Finds platform-specific directories (3.12)
HOMEPAGE=		https://github.com/platformdirs/platformdirs
CONTACT=		Python_Automaton[python@ironwolf.systems]

DOWNLOAD_GROUPS=	main
SITES[main]=		PYPIWHL/b0/15/1691fa5aaddc0c4ea4901c26f6137c29d5f6673596fe960a0340e8c308e1
DISTFILE[1]=		platformdirs-4.2.1-py3-none-any.whl:main
DF_INDEX=		1
SPKGS[v11]=		single
SPKGS[v12]=		single

OPTIONS_AVAILABLE=	PY311 PY312
OPTIONS_STANDARD=	none
VOPTS[v11]=		PY311=ON PY312=OFF
VOPTS[v12]=		PY311=OFF PY312=ON

DISTNAME=		platformdirs-4.2.1.dist-info

GENERATED=		yes

[PY311].USES_ON=			python:v11,wheel

[PY312].USES_ON=			python:v12,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]
17d5a1161b3fd67b390023cb2d3b026bbd40abde6fdb052dfbd3a29c3ba22ee1        17770 platformdirs-4.2.1-py3-none-any.whl