diff --git a/docs/explanation.rst b/docs/explanation.rst index d613361..36f98c7 100644 --- a/docs/explanation.rst +++ b/docs/explanation.rst @@ -224,7 +224,10 @@ documentation \`` +- ``appauthor`` adds a parent directory: ``AppData\Local\\``. When ``appauthor`` is ``None`` (the default), + it falls back to ``appname``, producing a doubled path like ``AppData\Local\MyApp\MyApp``. This follows the Windows + convention of grouping applications by publisher. If your application does not need an author directory, pass + ``appauthor=False`` to get ``AppData\Local\MyApp`` instead. - ``roaming=True`` switches from ``AppData\Local`` to ``AppData\Roaming``, which syncs across machines in a Windows domain. Use roaming for user preferences that should follow the user; use local (default) for machine-specific data like caches. diff --git a/docs/howto.rst b/docs/howto.rst index 9d2aa8f..47df58c 100644 --- a/docs/howto.rst +++ b/docs/howto.rst @@ -222,6 +222,30 @@ See :ref:`xdg-env-vars` for the full list of supported XDG variables, and the :r Platform-specific recipes *************************** +Windows: controlling the author directory +========================================= + +On Windows, ``platformdirs`` creates a two-level directory structure: ``AppData\Local\\``. When +``appauthor`` is omitted (``None``), it defaults to ``appname``, producing a doubled path like +``AppData\Local\MyApp\MyApp``. Choose the right value based on your needs: + +.. code-block:: python + + from platformdirs import user_data_dir + + # Explicit author -- AppData\Local\AcmeCompany\MyApp + user_data_dir("MyApp", "AcmeCompany") + + # No author -- AppData\Local\MyApp (flat structure) + user_data_dir("MyApp", appauthor=False) + + # Default (appauthor=None) -- AppData\Local\MyApp\MyApp + # appauthor falls back to appname + user_data_dir("MyApp") + +Use an explicit author string when you publish multiple apps under the same organization. Use ``appauthor=False`` when +you want a flat structure with just the app name. On non-Windows platforms, ``appauthor`` is always ignored. + Windows: roaming vs local profiles ================================== diff --git a/docs/parameters.rst b/docs/parameters.rst index b3ef9a8..f63628d 100644 --- a/docs/parameters.rst +++ b/docs/parameters.rst @@ -75,14 +75,22 @@ directory is returned without any app-specific subdirectory. ``appauthor`` ============= -The app author or distributing organization. On Windows, this adds an additional parent directory: +The app author or distributing organization. On Windows, this adds an additional parent directory above ``appname``: .. code-block:: pycon >>> user_data_dir("SuperApp", "Acme") # on Windows 'C:\\Users\\trentm\\AppData\\Local\\Acme\\SuperApp' -Set to ``False`` to suppress the author directory even on Windows: +When ``None`` (the default), ``appauthor`` falls back to ``appname``, which means the app name appears **twice** in the +path: + +.. code-block:: pycon + + >>> user_data_dir("SuperApp") # on Windows, appauthor defaults to appname + 'C:\\Users\\trentm\\AppData\\Local\\SuperApp\\SuperApp' + +Set to ``False`` to suppress the author directory entirely: .. code-block:: pycon diff --git a/docs/tutorial.rst b/docs/tutorial.rst index c6f83fd..75a1779 100644 --- a/docs/tutorial.rst +++ b/docs/tutorial.rst @@ -60,6 +60,15 @@ The result depends on the platform you're running on: 'C:\\Users\\\\AppData\\Local\\AcmeCompany\\MyApp' +Notice on Windows the path includes both the author (``AcmeCompany``) and the app name (``MyApp``). If we omit +``appauthor``, it defaults to ``appname``, producing ``AppData\Local\MyApp\MyApp``. To get a flat +``AppData\Local\MyApp``, pass ``appauthor=False``: + +.. code-block:: pycon + + >>> user_data_dir("MyApp", appauthor=False) # on Windows + 'C:\\Users\\\\AppData\\Local\\MyApp' + Each function returns a :class:`str`. If we prefer a :class:`~pathlib.Path`, we use the ``_path`` variant: .. code-block:: pycon diff --git a/src/platformdirs/api.py b/src/platformdirs/api.py index 0a5e01f..1e3b9a9 100644 --- a/src/platformdirs/api.py +++ b/src/platformdirs/api.py @@ -50,6 +50,13 @@ def __init__( # noqa: PLR0913, PLR0917 Typically, it is the owning company name. Defaults to `appname`. You may pass ``False`` to disable it. + .. note:: + + On Windows, the directory structure is ``//``. When ``appauthor`` is ``None`` (the + default), it falls back to ``appname``, resulting in ``//`` (e.g. + ``AppData/Local/myapp/myapp``). Pass ``appauthor=False`` to omit the author directory entirely and get + ``/``. + """ self.version = version """An optional version path element to append to the path.