From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Tue, 23 Apr 2019 17:21:09 +0000 (-0500)
Subject: Use first line of command docstring for help text.
X-Git-Tag: rel_1_0_10~4^2
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=90330cc0f5f4baa9aaaa5d82229dedbef6d7cbf7;p=thirdparty%2Fsqlalchemy%2Falembic.git

Use first line of command docstring for help text.

Fixed bug introduced in release 1.0.9 where the helptext for commands
inadvertently got expanded to include function docstrings from the
command.py module.  The logic has been adjusted to only refer to the first
line of each docstring as was the original intent.

Change-Id: I88d7b31b6b54fd065511d969849aef3977eaf6a0
Fixes: #552
---

diff --git a/alembic/command.py b/alembic/command.py
index 5416c42c..f8c81cc1 100644
--- a/alembic/command.py
+++ b/alembic/command.py
@@ -7,7 +7,7 @@ from .script import ScriptDirectory
 
 
 def list_templates(config):
-    """List available templates
+    """List available templates.
 
     :param config: a :class:`.Config` object.
 
@@ -409,7 +409,7 @@ def history(config, rev_range=None, verbose=False, indicate_current=False):
 
 
 def heads(config, verbose=False, resolve_dependencies=False):
-    """Show current available heads in the script directory
+    """Show current available heads in the script directory.
 
     :param config: a :class:`.Config` instance.
 
diff --git a/alembic/config.py b/alembic/config.py
index f06a25cf..4ba2a6cf 100644
--- a/alembic/config.py
+++ b/alembic/config.py
@@ -486,7 +486,20 @@ class CommandLine(object):
                     positional = spec[0][1:]
                     kwarg = []
 
-                subparser = subparsers.add_parser(fn.__name__, help=fn.__doc__)
+                # parse first line(s) of helptext without a line break
+                help_ = fn.__doc__
+                if help_:
+                    help_text = []
+                    for line in help_.split("\n"):
+                        if not line.strip():
+                            break
+                        else:
+                            help_text.append(line.strip())
+                else:
+                    help_text = ""
+                subparser = subparsers.add_parser(
+                    fn.__name__, help=" ".join(help_text)
+                )
                 add_options(subparser, positional, kwarg)
                 subparser.set_defaults(cmd=(fn, positional, kwarg))
         self.parser = parser
diff --git a/docs/build/unreleased/552.rst b/docs/build/unreleased/552.rst
new file mode 100644
index 00000000..69a918f3
--- /dev/null
+++ b/docs/build/unreleased/552.rst
@@ -0,0 +1,9 @@
+.. change::
+   :tags: bug, commands
+   :tickets: 552
+
+   Fixed bug introduced in release 0.9.0 where the helptext for commands
+   inadvertently got expanded to include function docstrings from the
+   command.py module.  The logic has been adjusted to only refer to the first
+   line(s) preceding the first line break within each docstring, as was the
+   original intent.
diff --git a/tests/test_command.py b/tests/test_command.py
index c12802ca..ff80bbf1 100644
--- a/tests/test_command.py
+++ b/tests/test_command.py
@@ -1,4 +1,5 @@
 from contextlib import contextmanager
+import inspect
 from io import BytesIO
 from io import TextIOWrapper
 import re
@@ -758,3 +759,42 @@ class CommandLineTest(TestBase):
         finally:
             config.command.revision = orig_revision
         eq_(canary.mock_calls, [mock.call(self.cfg, message="foo")])
+
+    def test_help_text(self):
+        commands = {
+            fn.__name__
+            for fn in [getattr(command, n) for n in dir(command)]
+            if inspect.isfunction(fn)
+            and fn.__name__[0] != "_"
+            and fn.__module__ == "alembic.command"
+        }
+        # make sure we found them
+        assert commands.intersection(
+            {"upgrade", "downgrade", "merge", "revision"}
+        )
+
+        # catch help text coming intersection
+        with mock.patch("alembic.config.ArgumentParser") as argparse:
+            config.CommandLine()
+            for kall in argparse().add_subparsers().mock_calls:
+                for sub_kall in kall.call_list():
+                    if sub_kall[0] == "add_parser":
+                        cmdname = sub_kall[1][0]
+                        help_text = sub_kall[2]["help"]
+                        if help_text:
+                            commands.remove(cmdname)
+                            # more than two spaces
+                            assert not re.search(r"   ", help_text)
+
+                            # no markup stuff
+                            assert ":" not in help_text
+
+                            # no newlines
+                            assert "\n" not in help_text
+
+                            # ends with a period
+                            assert help_text.endswith(".")
+
+                            # not too long
+                            assert len(help_text) < 80
+        assert not commands, "Commands without help text: %s" % commands