djavu-asus/emacs/elpy/rpc-venv/lib/python3.11/site-packages/platformdirs-3.11.0.dist-info/METADATA

   1 Metadata-Version: 2.1
   2 Name: platformdirs
   3 Version: 3.11.0
   4 Summary: A small Python package for determining appropriate platform-specific dirs, e.g. a "user data dir".
   5 Project-URL: Documentation, https://platformdirs.readthedocs.io
   6 Project-URL: Homepage, https://github.com/platformdirs/platformdirs
   7 Project-URL: Source, https://github.com/platformdirs/platformdirs
   8 Project-URL: Tracker, https://github.com/platformdirs/platformdirs/issues
   9 Maintainer-email: Bernát Gábor <gaborjbernat@gmail.com>, Julian Berman <Julian@GrayVines.com>, Ofek Lev <oss@ofek.dev>, Ronny Pfannschmidt <opensource@ronnypfannschmidt.de>
  10 License-Expression: MIT
  11 License-File: LICENSE
  12 Keywords: appdirs,application,cache,directory,log,user
  13 Classifier: Development Status :: 5 - Production/Stable
  14 Classifier: Intended Audience :: Developers
  15 Classifier: License :: OSI Approved :: MIT License
  16 Classifier: Operating System :: OS Independent
  17 Classifier: Programming Language :: Python
  18 Classifier: Programming Language :: Python :: 3 :: Only
  19 Classifier: Programming Language :: Python :: 3.7
  20 Classifier: Programming Language :: Python :: 3.8
  21 Classifier: Programming Language :: Python :: 3.9
  22 Classifier: Programming Language :: Python :: 3.10
  23 Classifier: Programming Language :: Python :: 3.11
  24 Classifier: Programming Language :: Python :: 3.12
  25 Classifier: Programming Language :: Python :: Implementation :: CPython
  26 Classifier: Programming Language :: Python :: Implementation :: PyPy
  27 Classifier: Topic :: Software Development :: Libraries :: Python Modules
  28 Requires-Python: >=3.7
  29 Requires-Dist: typing-extensions>=4.7.1; python_version < '3.8'
  30 Provides-Extra: docs
  31 Requires-Dist: furo>=2023.7.26; extra == 'docs'
  32 Requires-Dist: proselint>=0.13; extra == 'docs'
  33 Requires-Dist: sphinx-autodoc-typehints>=1.24; extra == 'docs'
  34 Requires-Dist: sphinx>=7.1.1; extra == 'docs'
  35 Provides-Extra: test
  36 Requires-Dist: appdirs==1.4.4; extra == 'test'
  37 Requires-Dist: covdefaults>=2.3; extra == 'test'
  38 Requires-Dist: pytest-cov>=4.1; extra == 'test'
  39 Requires-Dist: pytest-mock>=3.11.1; extra == 'test'
  40 Requires-Dist: pytest>=7.4; extra == 'test'
  41 Description-Content-Type: text/x-rst
  42
  43 The problem
  44 ===========
  45
  46 .. image:: https://github.com/platformdirs/platformdirs/actions/workflows/check.yml/badge.svg
  47    :target: https://github.com/platformdirs/platformdirs/actions
  48
  49 When writing desktop application, finding the right location to store user data
  50 and configuration varies per platform. Even for single-platform apps, there
  51 may by plenty of nuances in figuring out the right location.
  52
  53 For example, if running on macOS, you should use::
  54
  55     ~/Library/Application Support/<AppName>
  56
  57 If on Windows (at least English Win) that should be::
  58
  59     C:\Documents and Settings\<User>\Application Data\Local Settings\<AppAuthor>\<AppName>
  60
  61 or possibly::
  62
  63     C:\Documents and Settings\<User>\Application Data\<AppAuthor>\<AppName>
  64
  65 for `roaming profiles <https://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-vista/cc766489(v=ws.10)>`_ but that is another story.
  66
  67 On Linux (and other Unices), according to the `XDG Basedir Spec`_, it should be::
  68
  69     ~/.local/share/<AppName>
  70
  71 .. _XDG Basedir Spec: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
  72
  73 ``platformdirs`` to the rescue
  74 ==============================
  75
  76 This kind of thing is what the ``platformdirs`` package is for.
  77 ``platformdirs`` will help you choose an appropriate:
  78
  79 - user data dir (``user_data_dir``)
  80 - user config dir (``user_config_dir``)
  81 - user cache dir (``user_cache_dir``)
  82 - site data dir (``site_data_dir``)
  83 - site config dir (``site_config_dir``)
  84 - user log dir (``user_log_dir``)
  85 - user documents dir (``user_documents_dir``)
  86 - user downloads dir (``user_downloads_dir``)
  87 - user pictures dir (``user_pictures_dir``)
  88 - user videos dir (``user_videos_dir``)
  89 - user music dir (``user_music_dir``)
  90 - user desktop dir (``user_desktop_dir``)
  91 - user runtime dir (``user_runtime_dir``)
  92
  93 And also:
  94
  95 - Is slightly opinionated on the directory names used. Look for "OPINION" in
  96   documentation and code for when an opinion is being applied.
  97
  98 Example output
  99 ==============
 100
 101 On macOS:
 102
 103 .. code-block:: pycon
 104
 105     >>> from platformdirs import *
 106     >>> appname = "SuperApp"
 107     >>> appauthor = "Acme"
 108     >>> user_data_dir(appname, appauthor)
 109     '/Users/trentm/Library/Application Support/SuperApp'
 110     >>> site_data_dir(appname, appauthor)
 111     '/Library/Application Support/SuperApp'
 112     >>> user_cache_dir(appname, appauthor)
 113     '/Users/trentm/Library/Caches/SuperApp'
 114     >>> user_log_dir(appname, appauthor)
 115     '/Users/trentm/Library/Logs/SuperApp'
 116     >>> user_documents_dir()
 117     '/Users/trentm/Documents'
 118     >>> user_downloads_dir()
 119     '/Users/trentm/Downloads'
 120     >>> user_pictures_dir()
 121     '/Users/trentm/Pictures'
 122     >>> user_videos_dir()
 123     '/Users/trentm/Movies'
 124     >>> user_music_dir()
 125     '/Users/trentm/Music'
 126     >>> user_desktop_dir()
 127     '/Users/trentm/Desktop'
 128     >>> user_runtime_dir(appname, appauthor)
 129     '/Users/trentm/Library/Caches/TemporaryItems/SuperApp'
 130
 131 On Windows:
 132
 133 .. code-block:: pycon
 134
 135     >>> from platformdirs import *
 136     >>> appname = "SuperApp"
 137     >>> appauthor = "Acme"
 138     >>> user_data_dir(appname, appauthor)
 139     'C:\\Users\\trentm\\AppData\\Local\\Acme\\SuperApp'
 140     >>> user_data_dir(appname, appauthor, roaming=True)
 141     'C:\\Users\\trentm\\AppData\\Roaming\\Acme\\SuperApp'
 142     >>> user_cache_dir(appname, appauthor)
 143     'C:\\Users\\trentm\\AppData\\Local\\Acme\\SuperApp\\Cache'
 144     >>> user_log_dir(appname, appauthor)
 145     'C:\\Users\\trentm\\AppData\\Local\\Acme\\SuperApp\\Logs'
 146     >>> user_documents_dir()
 147     'C:\\Users\\trentm\\Documents'
 148     >>> user_downloads_dir()
 149     'C:\\Users\\trentm\\Downloads'
 150     >>> user_pictures_dir()
 151     'C:\\Users\\trentm\\Pictures'
 152     >>> user_videos_dir()
 153     'C:\\Users\\trentm\\Videos'
 154     >>> user_music_dir()
 155     'C:\\Users\\trentm\\Music'
 156     >>> user_desktop_dir()
 157     'C:\\Users\\trentm\\Desktop'
 158     >>> user_runtime_dir(appname, appauthor)
 159     'C:\\Users\\trentm\\AppData\\Local\\Temp\\Acme\\SuperApp'
 160
 161 On Linux:
 162
 163 .. code-block:: pycon
 164
 165     >>> from platformdirs import *
 166     >>> appname = "SuperApp"
 167     >>> appauthor = "Acme"
 168     >>> user_data_dir(appname, appauthor)
 169     '/home/trentm/.local/share/SuperApp'
 170     >>> site_data_dir(appname, appauthor)
 171     '/usr/local/share/SuperApp'
 172     >>> site_data_dir(appname, appauthor, multipath=True)
 173     '/usr/local/share/SuperApp:/usr/share/SuperApp'
 174     >>> user_cache_dir(appname, appauthor)
 175     '/home/trentm/.cache/SuperApp'
 176     >>> user_log_dir(appname, appauthor)
 177     '/home/trentm/.cache/SuperApp/log'
 178     >>> user_config_dir(appname)
 179     '/home/trentm/.config/SuperApp'
 180     >>> user_documents_dir()
 181     '/home/trentm/Documents'
 182     >>> user_downloads_dir()
 183     '/home/trentm/Downloads'
 184     >>> user_pictures_dir()
 185     '/home/trentm/Pictures'
 186     >>> user_videos_dir()
 187     '/home/trentm/Videos'
 188     >>> user_music_dir()
 189     '/home/trentm/Music'
 190     >>> user_desktop_dir()
 191     '/home/trentm/Desktop'
 192     >>> user_runtime_dir(appname, appauthor)
 193     '/run/user/{os.getuid()}/SuperApp'
 194     >>> site_config_dir(appname)
 195     '/etc/xdg/SuperApp'
 196     >>> os.environ["XDG_CONFIG_DIRS"] = "/etc:/usr/local/etc"
 197     >>> site_config_dir(appname, multipath=True)
 198     '/etc/SuperApp:/usr/local/etc/SuperApp'
 199
 200 On Android::
 201
 202     >>> from platformdirs import *
 203     >>> appname = "SuperApp"
 204     >>> appauthor = "Acme"
 205     >>> user_data_dir(appname, appauthor)
 206     '/data/data/com.myApp/files/SuperApp'
 207     >>> user_cache_dir(appname, appauthor)
 208     '/data/data/com.myApp/cache/SuperApp'
 209     >>> user_log_dir(appname, appauthor)
 210     '/data/data/com.myApp/cache/SuperApp/log'
 211     >>> user_config_dir(appname)
 212     '/data/data/com.myApp/shared_prefs/SuperApp'
 213     >>> user_documents_dir()
 214     '/storage/emulated/0/Documents'
 215     >>> user_downloads_dir()
 216     '/storage/emulated/0/Downloads'
 217     >>> user_pictures_dir()
 218     '/storage/emulated/0/Pictures'
 219     >>> user_videos_dir()
 220     '/storage/emulated/0/DCIM/Camera'
 221     >>> user_music_dir()
 222     '/storage/emulated/0/Music'
 223     >>> user_desktop_dir()
 224     '/storage/emulated/0/Desktop'
 225     >>> user_runtime_dir(appname, appauthor)
 226     '/data/data/com.myApp/cache/SuperApp/tmp'
 227
 228 Note: Some android apps like Termux and Pydroid are used as shells. These
 229 apps are used by the end user to emulate Linux environment. Presence of
 230 ``SHELL`` environment variable is used by Platformdirs to differentiate
 231 between general android apps and android apps used as shells. Shell android
 232 apps also support ``XDG_*`` environment variables.
 233
 234
 235 ``PlatformDirs`` for convenience
 236 ================================
 237
 238 .. code-block:: pycon
 239
 240     >>> from platformdirs import PlatformDirs
 241     >>> dirs = PlatformDirs("SuperApp", "Acme")
 242     >>> dirs.user_data_dir
 243     '/Users/trentm/Library/Application Support/SuperApp'
 244     >>> dirs.site_data_dir
 245     '/Library/Application Support/SuperApp'
 246     >>> dirs.user_cache_dir
 247     '/Users/trentm/Library/Caches/SuperApp'
 248     >>> dirs.user_log_dir
 249     '/Users/trentm/Library/Logs/SuperApp'
 250     >>> dirs.user_documents_dir
 251     '/Users/trentm/Documents'
 252     >>> dirs.user_downloads_dir
 253     '/Users/trentm/Downloads'
 254     >>> dirs.user_pictures_dir
 255     '/Users/trentm/Pictures'
 256     >>> dirs.user_videos_dir
 257     '/Users/trentm/Movies'
 258     >>> dirs.user_music_dir
 259     '/Users/trentm/Music'
 260     >>> dirs.user_desktop_dir
 261     '/Users/trentm/Desktop'
 262     >>> dirs.user_runtime_dir
 263     '/Users/trentm/Library/Caches/TemporaryItems/SuperApp'
 264
 265 Per-version isolation
 266 =====================
 267
 268 If you have multiple versions of your app in use that you want to be
 269 able to run side-by-side, then you may want version-isolation for these
 270 dirs::
 271
 272     >>> from platformdirs import PlatformDirs
 273     >>> dirs = PlatformDirs("SuperApp", "Acme", version="1.0")
 274     >>> dirs.user_data_dir
 275     '/Users/trentm/Library/Application Support/SuperApp/1.0'
 276     >>> dirs.site_data_dir
 277     '/Library/Application Support/SuperApp/1.0'
 278     >>> dirs.user_cache_dir
 279     '/Users/trentm/Library/Caches/SuperApp/1.0'
 280     >>> dirs.user_log_dir
 281     '/Users/trentm/Library/Logs/SuperApp/1.0'
 282     >>> dirs.user_documents_dir
 283     '/Users/trentm/Documents'
 284     >>> dirs.user_downloads_dir
 285     '/Users/trentm/Downloads'
 286     >>> dirs.user_pictures_dir
 287     '/Users/trentm/Pictures'
 288     >>> dirs.user_videos_dir
 289     '/Users/trentm/Movies'
 290     >>> dirs.user_music_dir
 291     '/Users/trentm/Music'
 292     >>> dirs.user_desktop_dir
 293     '/Users/trentm/Desktop'
 294     >>> dirs.user_runtime_dir
 295     '/Users/trentm/Library/Caches/TemporaryItems/SuperApp/1.0'
 296
 297 Be wary of using this for configuration files though; you'll need to handle
 298 migrating configuration files manually.
 299
 300 Why this Fork?
 301 ==============
 302
 303 This repository is a friendly fork of the wonderful work started by
 304 `ActiveState <https://github.com/ActiveState/appdirs>`_ who created
 305 ``appdirs``, this package's ancestor.
 306
 307 Maintaining an open source project is no easy task, particularly
 308 from within an organization, and the Python community is indebted
 309 to ``appdirs`` (and to Trent Mick and Jeff Rouse in particular) for
 310 creating an incredibly useful simple module, as evidenced by the wide
 311 number of users it has attracted over the years.
 312
 313 Nonetheless, given the number of long-standing open issues
 314 and pull requests, and no clear path towards `ensuring
 315 that maintenance of the package would continue or grow
 316 <https://github.com/ActiveState/appdirs/issues/79>`_, this fork was
 317 created.
 318
 319 Contributions are most welcome.