Add docformatter which formats Python docstrings to PEP 257

Homepage: https://github.com/PyCQA/docformatter

CHANGELOG.md

@@ -20,12 +20,14 @@ The format is based on [Keep a Changelog].
   ([#263]).
 * [denofmt](https://docs.deno.com/runtime/manual/tools/formatter) for
   js, jsx, ts, tsx, json, jsonc, md files. ([#264])
+* [docformatter](https://github.com/PyCQA/docformatter) for Python docstrings ([#267])
 
 [#229]: https://github.com/radian-software/apheleia/pull/229
 [#260]: https://github.com/radian-software/apheleia/pull/260
 [#261]: https://github.com/radian-software/apheleia/pull/261
 [#263]: https://github.com/radian-software/apheleia/pull/263
 [#264]: https://github.com/radian-software/apheleia/pull/264
+[#267]: https://github.com/radian-software/apheleia/pull/267
 
 ## 4.0 (released 2023-11-23)
 ### Breaking changes

apheleia-formatters.el

@@ -55,6 +55,7 @@
     (denofmt-md . ("deno" "fmt" "-" "--ext" "md"))
     (denofmt-ts . ("deno" "fmt" "-" "--ext" "ts"))
     (denofmt-tsx . ("deno" "fmt" "-" "--ext" "tsx"))
+    (docformatter . ("apheleia-docformatter" file))
     (elm-format . ("elm-format" "--yes" "--stdin"))
     (fish-indent . ("fish_indent"))
     (fourmolu . ("fourmolu"))

scripts/formatters/apheleia-docformatter

@@ -0,0 +1,10 @@
+#!/bin/sh
+
+output=$(docformatter "$@")
+
+# On successful change docformatter gives exit code of 3.
+# Raise error for all other positive exit codes
+ret=$?
+[ $ret -gt 0 ] && [ $ret -ne 3 ] && exit $ret
+
+echo "${output}" | patch --quiet --output=-

test/formatters/installers/docformatter.bash

@@ -0,0 +1,2 @@
+apt-get install -y python3-pip
+pip3 install docformatter

test/formatters/samplecode/docformatter/in.py

@@ -0,0 +1,26 @@
+def single_line_doc():
+    """
+    Line break not necessary
+    """
+
+
+def extend_first_line():
+    """First line
+first line continuation
+    """
+
+
+def add_line_break():
+    """First line.
+    Second line.
+    """
+
+
+def long_lines():
+    """
+
+
+Nullam eu ante vel est convallis dignissim.  Fusce suscipit, wisi nec facilisis facilisis, est dui fermentum leo, quis tempor ligula erat quis odio.  Nunc porta vulputate tellus.  Nunc rutrum turpis sed pede.  Sed bibendum.  Aliquam posuere.  Nunc aliquet, augue nec adipiscing interdum, lacus tellus malesuada massa, quis varius mi purus non odio.  Pellentesque condimentum, magna ut suscipit hendrerit, ipsum augue ornare nulla, non luctus diam neque sit amet urna.  Curabitur vulputate vestibulum lorem.  Fusce sagittis, libero non molestie mollis, magna orci ultrices dolor, at vulputate neque nulla lacinia eros.  Sed id ligula quis est convallis tempor.  Curabitur lacinia pulvinar nibh.  Nam a sapien.
+
+
+    """

test/formatters/samplecode/docformatter/out.py

@@ -0,0 +1,30 @@
+def single_line_doc():
+    """Line break not necessary."""
+
+
+def extend_first_line():
+    """First line first line continuation."""
+
+
+def add_line_break():
+    """First line.
+
+    Second line.
+    """
+
+
+def long_lines():
+    """Nullam eu ante vel est convallis dignissim.
+
+    Fusce suscipit, wisi nec facilisis facilisis, est dui fermentum leo,
+    quis tempor ligula erat quis odio.  Nunc porta vulputate tellus.
+    Nunc rutrum turpis sed pede.  Sed bibendum.  Aliquam posuere.  Nunc
+    aliquet, augue nec adipiscing interdum, lacus tellus malesuada
+    massa, quis varius mi purus non odio.  Pellentesque condimentum,
+    magna ut suscipit hendrerit, ipsum augue ornare nulla, non luctus
+    diam neque sit amet urna.  Curabitur vulputate vestibulum lorem.
+    Fusce sagittis, libero non molestie mollis, magna orci ultrices
+    dolor, at vulputate neque nulla lacinia eros.  Sed id ligula quis
+    est convallis tempor.  Curabitur lacinia pulvinar nibh.  Nam a
+    sapien.
+    """