Switch to ruff for formatting and use codespell and docformatter (#261)

Author: gaborbernat

.pre-commit-config.yaml

@@ -4,15 +4,23 @@ repos:
     hooks:
       - id: end-of-file-fixer
       - id: trailing-whitespace
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.2.6
+    hooks:
+      - id: codespell
+        additional_dependencies: [ "tomli>=2.0.1" ]
+  - repo: https://github.com/PyCQA/docformatter
+    rev: v1.7.5
+    hooks:
+      - 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.14"
+    rev: "v0.1.15"
     hooks:
+      - id: ruff-format
       - id: ruff
-        args: [--fix, --exit-non-zero-on-fix]
-  - repo: https://github.com/psf/black
-    rev: 24.1.1
-    hooks:
-      - id: black
+        args: [ "--fix", "--unsafe-fixes", "--exit-non-zero-on-fix" ]
   - repo: https://github.com/tox-dev/tox-ini-fmt
     rev: "1.3.1"
     hooks:
@@ -22,7 +30,7 @@ repos:
     rev: "1.7.0"
     hooks:
       - id: pyproject-fmt
-        additional_dependencies: ["tox>=4.11.4"]
+        additional_dependencies: ["tox>=4.12.1"]
   - repo: meta
     hooks:
       - id: check-hooks-apply

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

@@ -67,33 +67,47 @@ build.hooks.vcs.version-file = "src/platformdirs/version.py"
 build.targets.sdist.include = ["/src", "/tests", "/tox.ini"]
 version.source = "vcs"
 
-[tool.black]
-line-length = 120
-
 [tool.ruff]
 select = ["ALL"]
 line-length = 120
 target-version = "py38"
-isort = {known-first-party = ["platformdirs", "tests"], required-imports = ["from __future__ import annotations"]}
+isort = { known-first-party = ["platformdirs", "tests"], required-imports = ["from __future__ import annotations"] }
 ignore = [
-    "ANN101",  # Missing type annotation for `self` in method
-    "D301",  #  Use `r"""` if any backslashes in a docstring
-    "D205",  # 1 blank line required between summary line and description
-    "D401",  # First line of docstring should be in imperative mood
-    "D203",  # `one-blank-line-before-class` (D203) and `no-blank-line-before-class` (D211) are incompatible
-    "D212",  # `multi-line-summary-first-line` (D212) and `multi-line-summary-second-line` (D213) are incompatible
-    "S104",  # Possible binding to all interface
+  "ANN101", # Missing type annotation for `self` in method
+  "D301",   # Use `r"""` if any backslashes in a docstring
+  "D205",   # 1 blank line required between summary line and description
+  "D401",   # The first line of docstring should be in imperative mood
+  "D203",   # `one-blank-line-before-class` (D203) and `no-blank-line-before-class` (D211) are incompatible
+  "D212",   # `multi-line-summary-first-line` (D212) and `multi-line-summary-second-line` (D213) are incompatible
+  "S104",   # Possible binding to all interfaces
+  "CPY",    # no copyright notices
 ]
+format.preview = true
+lint.preview = true
 [tool.ruff.per-file-ignores]
 "tests/**/*.py" = [
-    "S101",  # asserts allowed in tests...
-    "FBT",  # don"t care about booleans as positional arguments in tests
-    "INP001", # no implicit namespace
-    "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
+  "S101",    # asserts allowed in tests...
+  "FBT",     # don"t care about booleans as positional arguments in tests
+  "INP001",  # no implicit namespace
+  "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]
+builtin = "clear,usage,en-GB_to_en-US"
+count = true
+quiet-level = 3
+
+[tool.docformatter]
+blank = true
+recursive = true
+pre-summary-newline = true
+wrap-descriptions = 120
+wrap-summaries = 120
+
 [tool.coverage]
 html.show_contexts = true
 html.skip_covered = false

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,22 +22,22 @@
 
 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
+            return Android  # return to avoid redefinition of a result
 
     return Result
 
@@ -507,7 +509,7 @@ def user_log_path(
 
 
 def user_documents_path() -> Path:
-    """:returns: documents path tied to the user"""
+    """:returns: documents a path tied to the user"""
     return PlatformDirs().user_documents_path
 
 
@@ -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/__main__.py

@@ -24,7 +24,7 @@
 
 
 def main() -> None:
-    """Run main entry point."""
+    """Run the main entry point."""
     app_name = "MyApp"
     app_author = "MyCompany"
 

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
@@ -44,7 +45,7 @@ def site_config_dir(self) -> str:
 
     @property
     def user_cache_dir(self) -> str:
-        """:return: cache directory tied to the user, e.g. e.g. ``/data/user/<userid>/<packagename>/cache/<AppName>``"""
+        """:return: cache directory tied to the user, e.g.,``/data/user/<userid>/<packagename>/cache/<AppName>``"""
         return self._append_app_name_and_version(cast(str, _android_folder()), "cache")
 
     @property
@@ -119,13 +120,13 @@ def site_runtime_dir(self) -> str:
 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
+        # First try to get a path to android app via pyjnius
+        from jnius import autoclass  # noqa: PLC0415
 
         context = autoclass("android.content.Context")
         result: str | None = context.getFilesDir().getParentFile().getAbsolutePath()
     except Exception:  # noqa: BLE001
-        # if fails find an android folder looking path on the sys.path
+        # if fails find an android folder looking a path on the sys.path
         pattern = re.compile(r"/data/(data|user/\d+)/(.+)/files")
         for path in sys.path:
             if pattern.match(path):
@@ -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")