Support paragraph breaks in python block comments.

The current python filetype module treats a single empty comment line
(typically created by hitting enter twice while in a block comment) as
the end of a block comment, deleting the empty comment and ending
comment prefix copying. This runs contrary to PEP8, which explicitly
allows for paragraphs in block comments, with an empty comment as the
paragraph separator.

This change implements support for using a single empty comment as a
paragraph separator, with two consecutive empty comments being treated
as the end of the block comment; both empty comment lines are deleted
and comment prefix copying is ended.

rc/filetype/python.kak

@@ -167,14 +167,52 @@ define-command -hidden python-insert-on-new-line %{ evaluate-commands -itersel -
     execute-keys <semicolon>
     try %{
         evaluate-commands -draft -save-regs '/"' %{
-            # copy the commenting prefix
-            execute-keys -save-regs '' k x1s^\h*(#+\h*)<ret> y
+            # Handle block comment continuation/termination.
+            #
+            # This code applies in the context where we have a new line
+            # inserted, and the previous line is a block comment (i.e. a line
+            # that matches '^\h*#+\h*\S*$'). We assume that the comment will
+            # be continued, so we copy the prefix (all leading whitespace, any
+            # '#' characters, and then any additional whitespace before the
+            # next non-whitespace character) into the new line.
+            #
+            # PEP8's text on block comments says they can include an empty
+            # comment (i.e. '^\h*#+\h*$') as a paragraph separator - we
+            # leave a single empty comment as-is, to allow paragraph breaks,
+            # but if we see two consecutive empty comments we exit the
+            # comment block and delete the empty comments.
+            # Reference: https://peps.python.org/pep-0008/#block-comments
+            #
+            # first, make sure we're in the right context - don't wrap this
+            # in a try/catch so we fail out immediately
+            execute-keys -draft kxs^\h*#+\h*<ret>
+
+            # now handle the coment continuation logic
             try %{
-                # if the previous comment isn't empty, create a new one
-                execute-keys x<a-K>^\h*#+\h*$<ret> jxs^\h*<ret>P
+                # try and match a regular block comment, copying the prefix
+                execute-keys -draft -save-regs '' k x 1s^(\h*#+\h*)\S.*$ <ret> y
+                execute-keys -draft P
             } catch %{
-                # if there is no text in the previous comment, remove it completely
-                execute-keys d
+                try %{
+                    # try and match a regular block comment followed by a single
+                    # empty comment line
+                    execute-keys -draft -save-regs '' kKx 1s^(\h*#+\h*)\S+\n\h*#+\h*$ <ret> y
+                    execute-keys -draft P
+                } catch %{
+                    try %{
+                        # try and match a pair of empty comment lines, and delete
+                        # them if we match
+                        execute-keys -draft kKx <a-k> ^\h*#+\h*\n\h*#+\h*$ <ret> <a-d>
+                    } catch %{
+                        # finally, we need a special case for a new line inserted
+                        # into a file that consists of a single empty comment - in
+                        # that case we can't expect to copy the trailing whitespace,
+                        # so we add our own
+                        execute-keys -draft -save-regs '' k x1s^(\h*#+)\h*$<ret> y
+                        execute-keys -draft P
+                        execute-keys -draft i<space>
+                    }
+                }
             }
         }
 

test/regression/5147-python-block-comment-paragraphs/empty-start-of-file-indented/cmd

@@ -0,0 +1 @@
+gjA<ret>

test/regression/5147-python-block-comment-paragraphs/empty-start-of-file-indented/in

@@ -0,0 +1 @@
+    #

test/regression/5147-python-block-comment-paragraphs/empty-start-of-file-indented/out

@@ -0,0 +1,2 @@
+    #
+    # 

test/regression/5147-python-block-comment-paragraphs/empty-start-of-file-indented/rc

@@ -0,0 +1,3 @@
+source "%val{runtime}/colors/default.kak"
+source "%val{runtime}/rc/filetype/python.kak"
+set buffer filetype python

test/regression/5147-python-block-comment-paragraphs/empty-start-of-file/cmd

@@ -0,0 +1 @@
+gjA<ret>

test/regression/5147-python-block-comment-paragraphs/empty-start-of-file/in

@@ -0,0 +1 @@
+#

test/regression/5147-python-block-comment-paragraphs/empty-start-of-file/out

@@ -0,0 +1,2 @@
+#
+# 

test/regression/5147-python-block-comment-paragraphs/empty-start-of-file/rc

@@ -0,0 +1,3 @@
+source "%val{runtime}/colors/default.kak"
+source "%val{runtime}/rc/filetype/python.kak"
+set buffer filetype python

test/regression/5147-python-block-comment-paragraphs/exit-block-indented/cmd

@@ -0,0 +1 @@
+gjA<ret>

test/regression/5147-python-block-comment-paragraphs/exit-block-indented/in

@@ -0,0 +1,4 @@
+    # A new line after a pair of empty comment lines should exit the
+    # block comment.
+    #
+    #

test/regression/5147-python-block-comment-paragraphs/exit-block-indented/out

@@ -0,0 +1,3 @@
+    # A new line after a pair of empty comment lines should exit the
+    # block comment.
+

test/regression/5147-python-block-comment-paragraphs/exit-block-indented/rc

@@ -0,0 +1,3 @@
+source "%val{runtime}/colors/default.kak"
+source "%val{runtime}/rc/filetype/python.kak"
+set buffer filetype python

test/regression/5147-python-block-comment-paragraphs/exit-block/cmd

@@ -0,0 +1 @@
+gjA<ret>

test/regression/5147-python-block-comment-paragraphs/exit-block/in

@@ -0,0 +1,4 @@
+# A new line after a pair of empty comment lines should exit the
+# block comment.
+#
+#

test/regression/5147-python-block-comment-paragraphs/exit-block/out

@@ -0,0 +1,3 @@
+# A new line after a pair of empty comment lines should exit the
+# block comment.
+

test/regression/5147-python-block-comment-paragraphs/exit-block/rc

@@ -0,0 +1,3 @@
+source "%val{runtime}/colors/default.kak"
+source "%val{runtime}/rc/filetype/python.kak"
+set buffer filetype python

test/regression/5147-python-block-comment-paragraphs/not-a-comment-indented/cmd

@@ -0,0 +1 @@
+gjA<ret>

test/regression/5147-python-block-comment-paragraphs/not-a-comment-indented/in

@@ -0,0 +1,4 @@
+    # If we're not in a comment at all, make sure we do the right thing.
+    # (one empty line and a 4-space prefixed line follows)
+
+

test/regression/5147-python-block-comment-paragraphs/not-a-comment-indented/out

@@ -0,0 +1,5 @@
+    # If we're not in a comment at all, make sure we do the right thing.
+    # (one empty line and a 4-space prefixed line follows)
+
+
+

test/regression/5147-python-block-comment-paragraphs/not-a-comment-indented/rc

@@ -0,0 +1,3 @@
+source "%val{runtime}/colors/default.kak"
+source "%val{runtime}/rc/filetype/python.kak"
+set buffer filetype python

test/regression/5147-python-block-comment-paragraphs/not-a-comment/cmd

@@ -0,0 +1 @@
+gjA<ret>

test/regression/5147-python-block-comment-paragraphs/not-a-comment/in

@@ -0,0 +1,4 @@
+# If we're not in a comment at all, make sure we do the right thing.
+# (two empty lines follow)
+
+

test/regression/5147-python-block-comment-paragraphs/not-a-comment/out

@@ -0,0 +1,5 @@
+# If we're not in a comment at all, make sure we do the right thing.
+# (two empty lines follow)
+
+
+

test/regression/5147-python-block-comment-paragraphs/not-a-comment/rc

@@ -0,0 +1,3 @@
+source "%val{runtime}/colors/default.kak"
+source "%val{runtime}/rc/filetype/python.kak"
+set buffer filetype python

test/regression/5147-python-block-comment-paragraphs/paragraph-break-indented/cmd

@@ -0,0 +1 @@
+gjA<ret>

test/regression/5147-python-block-comment-paragraphs/paragraph-break-indented/in

@@ -0,0 +1,3 @@
+    # A new line after a single empty comment line should leave the comment in
+    # place as a possible paragraph separator.
+    #

test/regression/5147-python-block-comment-paragraphs/paragraph-break-indented/out

@@ -0,0 +1,4 @@
+    # A new line after a single empty comment line should leave the comment in
+    # place as a possible paragraph separator.
+    #
+    # 

test/regression/5147-python-block-comment-paragraphs/paragraph-break-indented/rc

@@ -0,0 +1,3 @@
+source "%val{runtime}/colors/default.kak"
+source "%val{runtime}/rc/filetype/python.kak"
+set buffer filetype python

test/regression/5147-python-block-comment-paragraphs/paragraph-break/cmd

@@ -0,0 +1 @@
+gjA<ret>

test/regression/5147-python-block-comment-paragraphs/paragraph-break/in

@@ -0,0 +1,4 @@
+# A new line after a single empty comment line should leave the empty comment
+# in place as a possible paragraph separator, starting a new comment with the
+# prefix copied.
+#

test/regression/5147-python-block-comment-paragraphs/paragraph-break/out

@@ -0,0 +1,5 @@
+# A new line after a single empty comment line should leave the empty comment
+# in place as a possible paragraph separator, starting a new comment with the
+# prefix copied.
+#
+# 

test/regression/5147-python-block-comment-paragraphs/paragraph-break/rc

@@ -0,0 +1,3 @@
+source "%val{runtime}/colors/default.kak"
+source "%val{runtime}/rc/filetype/python.kak"
+set buffer filetype python