Switch to ruff for formatting and use codespell and docformatter

Signed-off-by: Bernát Gábor <bgabor8@bloomberg.net>

.pre-commit-config.yaml

@@ -15,6 +15,12 @@ repos:
       - id: docformatter
         additional_dependencies: [ "tomli>=2.0.1" ]
         args: [ "--in-place", "--config", "./pyproject.toml" ]
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: "v0.1.15"
+    hooks:
+      - id: ruff-format
+      - id: ruff
+        args: [ "--fix", "--unsafe-fixes", "--exit-non-zero-on-fix" ]
   - repo: https://github.com/tox-dev/tox-ini-fmt
     rev: "1.3.1"
     hooks:

CHANGES.rst

@@ -182,15 +182,15 @@ appdirs 1.4.0 (2017-08-17)
 - [PR #42] AppAuthor is now optional on Windows
 - [issue 41] Support Jython on Windows, Mac, and Unix-like platforms. Windows
   support requires `JNA <https://github.com/twall/jna>`_.
-- [PR #44] Fix incorrect behaviour of the site_config_dir method
+- [PR #44] Fix incorrect behavior of the site_config_dir method
 
 appdirs 1.3.0 (2014-04-22)
 --------------------------
 - [Unix, issue 16] Conform to XDG standard, instead of breaking it for
   everybody
 - [Unix] Removes gratuitous case mangling of the case, since \*nix-es are
   usually case sensitive, so mangling is not wise
-- [Unix] Fixes the utterly wrong behaviour in ``site_data_dir``, return result
+- [Unix] Fixes the utterly wrong behavior in ``site_data_dir``, return result
   based on XDG_DATA_DIRS and make room for respecting the standard which
   specifies XDG_DATA_DIRS is a multiple-value variable
 - [Issue 6] Add ``*_config_dir`` which are distinct on nix-es, according to
@@ -210,7 +210,7 @@ appdirs 1.1.0 (2010-09-02)
 - [Unix, issue 2, issue 7] appdirs now conforms to `XDG base directory spec
   <https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html>`_.
 - [Mac, issue 5] Fix ``site_data_dir()`` on Mac.
-- [Mac] Drop use of 'Carbon' module in favour of hardcoded paths; supports
+- [Mac] Drop use of 'Carbon' module in favor of hardcoded paths; supports
   Python3 now.
 - [Windows] Append "Cache" to ``user_cache_dir`` on Windows by default. Use
   ``opinion=False`` option to disable this.
@@ -225,19 +225,16 @@ appdirs 1.1.0 (2010-09-02)
 - [Linux] Change default ``user_cache_dir()`` on Linux to be singular, e.g.
   "~/.superapp/cache".
 - [Windows] Add ``roaming`` option to ``user_data_dir()`` (for use on Windows only)
-  and change the default ``user_data_dir`` behaviour to use a *non*-roaming
+  and change the default ``user_data_dir`` behavior to use a *non*-roaming
   profile dir (``CSIDL_LOCAL_APPDATA`` instead of ``CSIDL_APPDATA``). Why? Because
   a large roaming profile can cause login speed issues. The "only syncs on
-  logout" behaviour can cause surprises in appdata info.
+  logout" behavior can cause surprises in appdata info.
 
 
 appdirs 1.0.1 (never released)
 ------------------------------
 
 Started this changelog 27 July 2010. Before that this module originated in the
 `Komodo <https://www.activestate.com/komodo-ide>`_ product as ``applib.py`` and then
-as `applib/location.py
-<https://github.com/ActiveState/applib/blob/master/applib/location.py>`_ (used by
-`PyPM <https://code.activestate.com/pypm/>`_ in `ActivePython
-<https://www.activestate.com/activepython>`_). This is basically a fork of
-applib.py 1.0.1 and applib/location.py 1.0.1.
+as ``applib/location.py`` (used by `PyPM <https://code.activestate.com/pypm/>`_ in `ActivePython
+<https://www.activestate.com/activepython>`_). This is basically a fork of applib.py 1.0.1 and applib/location.py 1.0.1.

docs/conf.py

@@ -1,5 +1,6 @@
 # noqa: INP001
 """Configuration for Sphinx."""
+
 from __future__ import annotations
 
 from datetime import datetime, timezone

pyproject.toml

@@ -92,6 +92,8 @@ lint.preview = true
   "D",       # don"t care about documentation in tests
   "S603",    # `subprocess` call: check for execution of untrusted input
   "PLR2004", # Magic value used in comparison, consider replacing with a constant variable
+  "PLC2701", # Private name import
+  "PLR0917", # Too many positional arguments
 ]
 
 [tool.codespell]
@@ -102,6 +104,7 @@ quiet-level = 3
 [tool.docformatter]
 blank = true
 recursive = true
+pre-summary-newline = true
 wrap-descriptions = 120
 wrap-summaries = 120
 

src/platformdirs/__init__.py

@@ -1,6 +1,8 @@
 """
-Utilities for determining application-specific dirs. See <https://github.com/platformdirs/platformdirs> for details and
-usage.
+Utilities for determining application-specific dirs.
+
+See <https://github.com/platformdirs/platformdirs> for details and usage.
+
 """
 
 from __future__ import annotations
@@ -20,20 +22,20 @@
 
 def _set_platform_dir_class() -> type[PlatformDirsABC]:
     if sys.platform == "win32":
-        from platformdirs.windows import Windows as Result
+        from platformdirs.windows import Windows as Result  # noqa: PLC0415
     elif sys.platform == "darwin":
-        from platformdirs.macos import MacOS as Result
+        from platformdirs.macos import MacOS as Result  # noqa: PLC0415
     else:
-        from platformdirs.unix import Unix as Result
+        from platformdirs.unix import Unix as Result  # noqa: PLC0415
 
     if os.getenv("ANDROID_DATA") == "/data" and os.getenv("ANDROID_ROOT") == "/system":
         if os.getenv("SHELL") or os.getenv("PREFIX"):
             return Result
 
-        from platformdirs.android import _android_folder
+        from platformdirs.android import _android_folder  # noqa: PLC0415
 
         if _android_folder() is not None:
-            from platformdirs.android import Android
+            from platformdirs.android import Android  # noqa: PLC0415
 
             return Android  # return to avoid redefinition of result
 
@@ -585,41 +587,41 @@ def site_runtime_path(
 
 
 __all__ = [
-    "__version__",
-    "__version_info__",
-    "PlatformDirs",
     "AppDirs",
+    "PlatformDirs",
     "PlatformDirsABC",
-    "user_data_dir",
-    "user_config_dir",
-    "user_cache_dir",
-    "user_state_dir",
-    "user_log_dir",
-    "user_documents_dir",
-    "user_downloads_dir",
-    "user_pictures_dir",
-    "user_videos_dir",
-    "user_music_dir",
-    "user_desktop_dir",
-    "user_runtime_dir",
-    "site_data_dir",
-    "site_config_dir",
+    "__version__",
+    "__version_info__",
     "site_cache_dir",
+    "site_cache_path",
+    "site_config_dir",
+    "site_config_path",
+    "site_data_dir",
+    "site_data_path",
     "site_runtime_dir",
-    "user_data_path",
-    "user_config_path",
+    "site_runtime_path",
+    "user_cache_dir",
     "user_cache_path",
-    "user_state_path",
-    "user_log_path",
+    "user_config_dir",
+    "user_config_path",
+    "user_data_dir",
+    "user_data_path",
+    "user_desktop_dir",
+    "user_desktop_path",
+    "user_documents_dir",
     "user_documents_path",
+    "user_downloads_dir",
     "user_downloads_path",
-    "user_pictures_path",
-    "user_videos_path",
+    "user_log_dir",
+    "user_log_path",
+    "user_music_dir",
     "user_music_path",
-    "user_desktop_path",
+    "user_pictures_dir",
+    "user_pictures_path",
+    "user_runtime_dir",
     "user_runtime_path",
-    "site_data_path",
-    "site_config_path",
-    "site_cache_path",
-    "site_runtime_path",
+    "user_state_dir",
+    "user_state_path",
+    "user_videos_dir",
+    "user_videos_path",
 ]

src/platformdirs/android.py

@@ -13,10 +13,11 @@
 
 class Android(PlatformDirsABC):
     """
-    Follows the guidance `from here <https://android.stackexchange.com/a/216132>`_. Makes use of the
-    `appname <platformdirs.api.PlatformDirsABC.appname>`,
-    `version <platformdirs.api.PlatformDirsABC.version>`,
-    `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
+    Follows the guidance `from here <https://android.stackexchange.com/a/216132>`_.
+
+    Makes use of the `appname <platformdirs.api.PlatformDirsABC.appname>`, `version
+    <platformdirs.api.PlatformDirsABC.version>`, `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
+
     """
 
     @property
@@ -120,7 +121,7 @@ def _android_folder() -> str | None:
     """:return: base folder for the Android OS or None if it cannot be found"""
     try:
         # First try to get path to android app via pyjnius
-        from jnius import autoclass
+        from jnius import autoclass  # noqa: PLC0415
 
         context = autoclass("android.content.Context")
         result: str | None = context.getFilesDir().getParentFile().getAbsolutePath()
@@ -141,7 +142,7 @@ def _android_documents_folder() -> str:
     """:return: documents folder for the Android OS"""
     # Get directories with pyjnius
     try:
-        from jnius import autoclass
+        from jnius import autoclass  # noqa: PLC0415
 
         context = autoclass("android.content.Context")
         environment = autoclass("android.os.Environment")
@@ -157,7 +158,7 @@ def _android_downloads_folder() -> str:
     """:return: downloads folder for the Android OS"""
     # Get directories with pyjnius
     try:
-        from jnius import autoclass
+        from jnius import autoclass  # noqa: PLC0415
 
         context = autoclass("android.content.Context")
         environment = autoclass("android.os.Environment")
@@ -173,7 +174,7 @@ def _android_pictures_folder() -> str:
     """:return: pictures folder for the Android OS"""
     # Get directories with pyjnius
     try:
-        from jnius import autoclass
+        from jnius import autoclass  # noqa: PLC0415
 
         context = autoclass("android.content.Context")
         environment = autoclass("android.os.Environment")
@@ -189,7 +190,7 @@ def _android_videos_folder() -> str:
     """:return: videos folder for the Android OS"""
     # Get directories with pyjnius
     try:
-        from jnius import autoclass
+        from jnius import autoclass  # noqa: PLC0415
 
         context = autoclass("android.content.Context")
         environment = autoclass("android.os.Environment")
@@ -205,7 +206,7 @@ def _android_music_folder() -> str:
     """:return: music folder for the Android OS"""
     # Get directories with pyjnius
     try:
-        from jnius import autoclass
+        from jnius import autoclass  # noqa: PLC0415
 
         context = autoclass("android.content.Context")
         environment = autoclass("android.os.Environment")

src/platformdirs/api.py

@@ -11,10 +11,10 @@
     from typing import Iterator, Literal
 
 
-class PlatformDirsABC(ABC):
+class PlatformDirsABC(ABC):  # noqa: PLR0904
     """Abstract base class for platform directories."""
 
-    def __init__(  # noqa: PLR0913
+    def __init__(  # noqa: PLR0913, PLR0917
         self,
         appname: str | None = None,
         appauthor: str | None | Literal[False] = None,
@@ -34,34 +34,47 @@ def __init__(  # noqa: PLR0913
         :param multipath: See `multipath`.
         :param opinion: See `opinion`.
         :param ensure_exists: See `ensure_exists`.
+
         """
         self.appname = appname  #: The name of application.
         self.appauthor = appauthor
         """
-        The name of the app author or distributing body for this application. Typically, it is the owning company name.
-        Defaults to `appname`. You may pass ``False`` to disable it.
+        The name of the app author or distributing body for this application.
+
+        Typically, it is the owning company name. Defaults to `appname`. You may pass ``False`` to disable it.
+
         """
         self.version = version
         """
-        An optional version path element to append to the path. You might want to use this if you want multiple versions
-        of your app to be able to run independently. If used, this would typically be ``<major>.<minor>``.
+        An optional version path element to append to the path.
+
+        You might want to use this if you want multiple versions of your app to be able to run independently. If used,
+        this would typically be ``<major>.<minor>``.
+
         """
         self.roaming = roaming
         """
-        Whether to use the roaming appdata directory on Windows. That means that for users on a Windows network setup
-        for roaming profiles, this user data will be synced on login (see
+        Whether to use the roaming appdata directory on Windows.
+
+        That means that for users on a Windows network setup for roaming profiles, this user data will be synced on
+        login (see
         `here <http://technet.microsoft.com/en-us/library/cc766489(WS.10).aspx>`_).
+
         """
         self.multipath = multipath
         """
         An optional parameter which indicates that the entire list of data dirs should be returned.
+
         By default, the first item would only be returned.
+
         """
         self.opinion = opinion  #: A flag to indicating to use opinionated values.
         self.ensure_exists = ensure_exists
         """
         Optionally create the directory (and any missing parents) upon access if it does not exist.
+
         By default, no directories are created.
+
         """
 
     def _append_app_name_and_version(self, *base: str) -> str:

src/platformdirs/macos.py

@@ -10,11 +10,14 @@
 
 class MacOS(PlatformDirsABC):
     """
-    Platform directories for the macOS operating system. Follows the guidance from `Apple documentation
-    <https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/MacOSXDirectories/MacOSXDirectories.html>`_.
+    Platform directories for the macOS operating system.
+
+    Follows the guidance from
+    `Apple documentation <https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/MacOSXDirectories/MacOSXDirectories.html>`_.
     Makes use of the `appname <platformdirs.api.PlatformDirsABC.appname>`,
     `version <platformdirs.api.PlatformDirsABC.version>`,
     `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
+
     """
 
     @property

src/platformdirs/unix.py

@@ -20,17 +20,17 @@ def getuid() -> int:
     from os import getuid
 
 
-class Unix(PlatformDirsABC):
+class Unix(PlatformDirsABC):  # noqa: PLR0904
     """
-    On Unix/Linux, we follow the
-    `XDG Basedir Spec <https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html>`_. The spec allows
-    overriding directories with environment variables. The examples show are the default values, alongside the name of
-    the environment variable that overrides them. Makes use of the
-    `appname <platformdirs.api.PlatformDirsABC.appname>`,
-    `version <platformdirs.api.PlatformDirsABC.version>`,
-    `multipath <platformdirs.api.PlatformDirsABC.multipath>`,
-    `opinion <platformdirs.api.PlatformDirsABC.opinion>`,
-    `ensure_exists <platformdirs.api.PlatformDirsABC.ensure_exists>`.
+    On Unix/Linux, we follow the `XDG Basedir Spec <https://specifications.freedesktop.org/basedir-spec/basedir-spec-
+    latest.html>`_.
+
+    The spec allows overriding directories with environment variables. The examples show are the default values,
+    alongside the name of the environment variable that overrides them. Makes use of the `appname
+    <platformdirs.api.PlatformDirsABC.appname>`, `version <platformdirs.api.PlatformDirsABC.version>`, `multipath
+    <platformdirs.api.PlatformDirsABC.multipath>`, `opinion <platformdirs.api.PlatformDirsABC.opinion>`, `ensure_exists
+    <platformdirs.api.PlatformDirsABC.ensure_exists>`.
+
     """
 
     @property
@@ -246,7 +246,12 @@ def _get_user_media_dir(env_var: str, fallback_tilde_path: str) -> str:
 
 
 def _get_user_dirs_folder(key: str) -> str | None:
-    """Return directory from user-dirs.dirs config file. See https://freedesktop.org/wiki/Software/xdg-user-dirs/."""
+    """
+    Return directory from user-dirs.dirs config file.
+
+    See https://freedesktop.org/wiki/Software/xdg-user-dirs/.
+
+    """
     user_dirs_config_path = Path(Unix().user_config_dir) / "user-dirs.dirs"
     if user_dirs_config_path.exists():
         parser = ConfigParser()