feat: add option to format compatible with black (#196)

* docs: update docs for new --black option

* amend! docs: update docs for new --black option

* feat: set default options for black

* test: for set default options for black

* feat: set pre-summary space for black compatibility

* test: for black option defaults

* chore: set black true in pyproject.toml and format code base

* chore: add requirements for --black option

* chore: clean-up code smells

* style: fix unwrapped docstring

* fix: update help message to include non-cap option

Author: weibullguy

docs/source/requirements.rst

@@ -202,7 +202,12 @@ the requirement falls in, the type of requirement, and whether
     ' docformatter_10.1.3.2', ' Shall not place a newline between description text and a wrapped link.', ' Derived', ' Shall', ' Yes [PR #182]'
     ' docformatter_10.2', ' Should format docstrings using NumPy style.', ' Style', ' Should', ' No'
     ' docformatter_10.3', ' Should format docstrings using Google style.', ' Style', ' Should', ' No'
-    ' docformatter_10.4', ' Should format docstrings using Sphinx style.',' Style', ' Should', ' No'
+    ' docformatter_10.4', ' Should format docstrings using Sphinx style.', ' Style', ' Should', ' No'
+    ' docformatter_10.5', ' Should format docstrings compatible with black.', ' Style', ' Should', ' Yes [PR #192]'
+    ' docformatter_10.5.1', ' Should wrap summaries at 88 characters by default in black mode.', ' Style', ' Should', ' Yes'
+    ' docformatter_10.5.2', ' Should wrap descriptions at 88 characters by default in black mode.', ' Style', ' Should', ' Yes'
+    ' docformatter_10.5.3', ' Should insert a space before the first word in the summary if that word is quoted when in black mode.', ' Style', ' Should', ' Yes'
+    ' docformatter_10.5.4', ' Default black mode options should be over-rideable by passing arguments or using configuration files.', ' Style', ' Should', ' Yes'
     ' docformatter_11', '**Program Control**'
     ' docformatter_11.1', ' Should check formatting and report incorrectly documented docstrings.', ' Stakeholder', ' Should', ' Yes [*PR #32*]'
     ' docformatter_11.2', ' Should fix formatting and save changes to file.', ' Stakeholder', ' Should', ' Yes'
@@ -239,6 +244,9 @@ with *convention* requirements.
 ``docformatter`` currently provides these arguments for *style* requirements.
 ::
 
+    --black [boolean, default False]
+        Boolean to indicate whether to format docstrings to be compatible
+        with black.
     --blank [boolean, default False]
         Boolean to indicate whether to add a blank line after the
         elaborate description.
@@ -303,8 +311,6 @@ The following are new *style* arguments needed to accommodate the various style
 
     --syntax [string, default "sphinx"]
         One of sphinx, numpy, or google
-    --black [boolean, default False]
-        Formats docstrings to be compatible with black.
 
 Issue and Version Management
 ----------------------------

docs/source/usage.rst

@@ -22,7 +22,7 @@ help output provides a summary of these options:
 .. code-block:: console
 
     usage: docformatter [-h] [-i | -c] [-r] [--wrap-summaries length]
-                        [--wrap-descriptions length] [--blank]
+                        [--wrap-descriptions length] [--black] [--blank]
                         [--pre-summary-newline] [--make-summary-multi-line]
                         [--force-wrap] [--range start_line end_line]
                         [--docstring-length min_length max_length]
@@ -51,6 +51,11 @@ help output provides a summary of these options:
                             wrap descriptions at this length; set to 0 to
                             disable wrapping
                             (default: 72)
+      --black
+                            make formatting consistent with black, setting
+                            wrap-summaries and wrap-descriptions to a default 88
+                            if not otherwise specified
+                            (default: False)
       --blank
                             add blank line after elaborate description
                             (default: False)

pyproject.toml

@@ -92,8 +92,7 @@ disable = [
 ]
 
 [tool.docformatter]
-wrap-summaries = 79
-wrap-descriptions = 72
+black = true
 non-strict = false
 
 [tool.pydocstyle]

src/docformatter/__main__.py

@@ -41,10 +41,83 @@
 import docformatter.format as _format
 
 
+def _help():
+    """Print docformatter's help."""
+    print(
+        """\
+usage: docformatter [-h] [-i | -c] [-d] [-r] [-e [EXCLUDE ...]]
+                    [-n [NON-CAP ...]] [--black] [--wrap-summaries length]
+                    [--wrap-descriptions length] [--force-wrap]
+                    [--tab-width width] [--blank] [--pre-summary-newline]
+                    [--pre-summary-space] [--make-summary-multi-line]
+                    [--close-quotes-on-newline] [--range line line]
+                    [--docstring-length length length] [--non-strict]
+                    [--config CONFIG] [--version] files [files ...]
+
+positional arguments:
+  files                 files to format or '-' for standard in
+
+options:
+  -h, --help            show this help message and exit
+  -i, --in-place        make changes to files instead of printing diffs
+  -c, --check           only check and report incorrectly formatted files
+  -d, --diff            when used with `--check` or `--in-place`, also what
+                        changes would be made
+  -r, --recursive       drill down directories recursively
+  -e [EXCLUDE ...], --exclude [EXCLUDE ...]
+                        in recursive mode, exclude directories and files by
+                        names
+  -n [NON-CAP ...], --non-cap [NON-CAP ...]
+                        list of words not to capitalize when they appear as the
+                        first word in the summary
+
+  --black               make formatting compatible with standard black options
+                        (default: False)
+  --wrap-summaries length
+                        wrap long summary lines at this length; set to 0 to
+                        disable wrapping (default: 79, 88 with --black option)
+  --wrap-descriptions length
+                        wrap descriptions at this length; set to 0 to disable
+                        wrapping (default: 72, 88 with --black option)
+  --force-wrap          force descriptions to be wrapped even if it may result
+                        in a mess (default: False)
+  --tab-width width     tabs in indentation are this many characters when
+                        wrapping lines (default: 1)
+  --blank               add blank line after description (default: False)
+  --pre-summary-newline
+                        add a newline before the summary of a multi-line
+                        docstring (default: False)
+  --pre-summary-space   add a space after the opening triple quotes
+                        (default: False)
+  --make-summary-multi-line
+                        add a newline before and after the summary of a
+                        one-line docstring (default: False)
+  --close-quotes-on-newline
+                        place closing triple quotes on a new-line when a
+                        one-line docstring wraps to two or more lines
+                        (default: False)
+  --range line line     apply docformatter to docstrings between these lines;
+                        line numbers are indexed at 1 (default: None)
+  --docstring-length length length
+                        apply docformatter to docstrings of given length range
+                        (default: None)
+  --non-strict          don't strictly follow reST syntax to identify lists
+                        (see issue #67) (default: False)
+  --config CONFIG       path to file containing docformatter options
+  --version             show program's version number and exit
+"""
+    )
+
+
 def _main(argv, standard_out, standard_error, standard_in):
     """Run internal main entry point."""
     configurator = _configuration.Configurater(argv)
-    configurator.do_parse_arguments()
+
+    if "--help" in configurator.args_lst:
+        _help()
+        sys.exit()
+    else:
+        configurator.do_parse_arguments()
 
     formator = _format.Formatter(
         configurator.args,

src/docformatter/configuration.py

@@ -133,24 +133,54 @@ def do_parse_arguments(self) -> None:
             action="store",
             nargs="*",
             default=self.flargs_dct.get("non-cap", None),
-            help="list of words not to capitalize when they appear as the "
+            help="list of words not to capitalize "
+            "when they appear as the "
             "first word in the summary",
         )
+        self.parser.add_argument(
+            "--black",
+            action="store_true",
+            default=self.flargs_dct.get("black", "false").lower() == "true",
+            help="make formatting compatible with standard black options "
+            "(default: False)",
+        )
+
+        self.args = self.parser.parse_known_args(self.args_lst[1:])[0]
+
+        # Default black line length is 88 so use this when not specified
+        # otherwise use PEP-8 defaults
+        if self.args.black:
+            _default_wrap_summaries = 88
+            _default_wrap_descriptions = 88
+            _default_pre_summary_space = "true"
+        else:
+            _default_wrap_summaries = 79
+            _default_wrap_descriptions = 72
+            _default_pre_summary_space = "false"
+
         self.parser.add_argument(
             "--wrap-summaries",
-            default=int(self.flargs_dct.get("wrap-summaries", 79)),
+            default=int(
+                self.flargs_dct.get("wrap-summaries", _default_wrap_summaries)
+            ),
             type=int,
             metavar="length",
             help="wrap long summary lines at this length; "
-            "set to 0 to disable wrapping (default: 79)",
+            "set to 0 to disable wrapping (default: 79, 88 with --black "
+            "option)",
         )
         self.parser.add_argument(
             "--wrap-descriptions",
-            default=int(self.flargs_dct.get("wrap-descriptions", 72)),
+            default=int(
+                self.flargs_dct.get(
+                    "wrap-descriptions", _default_wrap_descriptions
+                )
+            ),
             type=int,
             metavar="length",
             help="wrap descriptions at this length; "
-            "set to 0 to disable wrapping (default: 72)",
+            "set to 0 to disable wrapping (default: 72, 88 with --black "
+            "option)",
         )
         self.parser.add_argument(
             "--force-wrap",
@@ -187,7 +217,9 @@ def do_parse_arguments(self) -> None:
         self.parser.add_argument(
             "--pre-summary-space",
             action="store_true",
-            default=self.flargs_dct.get("pre-summary-space", "false").lower()
+            default=self.flargs_dct.get(
+                "pre-summary-space", _default_pre_summary_space
+            ).lower()
             == "true",
             help="add a space after the opening triple quotes "
             "(default: False)",
@@ -258,6 +290,7 @@ def do_parse_arguments(self) -> None:
         )
 
         self.args = self.parser.parse_args(self.args_lst[1:])
+
         if self.args.line_range:
             if self.args.line_range[0] <= 0:
                 self.parser.error("--range must be positive numbers")