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 5416c42c749bec8492c1029bc3d462ec5d56a471..f8c81cc15105fb6e1c013182da7b971742ea7cbe 100644 (file)
--- 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 f06a25cff26b856e5de1f7d32465450c7668c2b0..4ba2a6cf60c4b65f4b29435a7680a4befca52927 100644 (file)
--- 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 (file)
index 0000000..69a918f
--- /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 c12802ca7f29ae7c9f2f52dadbbd340fa3c295d5..ff80bbf1b6be98fb12902ea2762e524a6b61eb12 100644 (file)
--- 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