#230 - CR fixes + more error codes!

Author: shacharoo

src/pydocstyle/checker.py

@@ -4,20 +4,15 @@
 import string
 import sys
 import tokenize as tk
-from itertools import takewhile, tee
+from itertools import takewhile
 from re import compile as re
 from collections import namedtuple
 
 from . import violations
 from .config import IllegalConfiguration
 from .parser import (Package, Module, Class, NestedClass, Definition, AllError,
                      Method, Function, NestedFunction, Parser, StringIO)
-from .utils import log, is_blank
-
-try:
-    from itertools import zip_longest
-except ImportError:
-    from itertools import izip_longest as zip_longest
+from .utils import log, is_blank, pairwise
 
 
 __all__ = ('check', )
@@ -39,16 +34,6 @@ def decorator(f):
     return decorator
 
 
-def pairwise(iterable, default_value):
-    """Return pairs of items from `iterable`.
-
-    pairwise([1, 2, 3], default_value=None) -> (1, 2) (2, 3), (3, None)
-    """
-    a, b = tee(iterable)
-    _ = next(b, default_value)
-    return zip_longest(a, b, fillvalue=default_value)
-
-
 class ConventionChecker(object):
     """Checker for PEP 257 and numpy conventions.
 
@@ -489,48 +474,62 @@ def _check_section_underline(cls, section_name, context, indentation):
             * The indentation of the dashed line is equal to the docstring's
               indentation (D215).
         """
-        dash_line_found = False
-        next_non_empty_line_offset = 0
+        blank_lines_after_header = 0
 
         for line in context.following_lines:
-            line_set = ''.join(set(line.strip()))
-            if not is_blank(line_set):
-                dash_line_found = line_set == '-'
+            if not is_blank(line):
                 break
-            next_non_empty_line_offset += 1
+            blank_lines_after_header += 1
+        else:
+            # There are only blank lines after the header.
+            yield violations.D407(section_name)
+            return
+
+        non_empty_line = context.following_lines[blank_lines_after_header]
+        dash_line_found = ''.join(set(non_empty_line.strip())) == '-'
 
         if not dash_line_found:
             yield violations.D407(section_name)
-            if next_non_empty_line_offset > 0:
+            if blank_lines_after_header > 0:
                 yield violations.D412(section_name)
         else:
-            if next_non_empty_line_offset > 0:
+            if blank_lines_after_header > 0:
                 yield violations.D408(section_name)
 
-            dash_line = context.following_lines[next_non_empty_line_offset]
-            if dash_line.strip() != "-" * len(section_name):
+            if non_empty_line.strip() != "-" * len(section_name):
                 yield violations.D409(len(section_name),
                                       section_name,
-                                      len(dash_line.strip()))
+                                      len(non_empty_line.strip()))
 
-            if leading_space(dash_line) > indentation:
+            if leading_space(non_empty_line) > indentation:
                 yield violations.D215(section_name)
 
-            if next_non_empty_line_offset + 1 < len(context.following_lines):
+            line_after_dashes_index = blank_lines_after_header + 1
+            # If the line index after the dashes is in range (perhaps we have
+            # a header + underline followed by another section header).
+            if line_after_dashes_index < len(context.following_lines):
                 line_after_dashes = \
-                    context.following_lines[next_non_empty_line_offset + 1]
+                    context.following_lines[line_after_dashes_index]
                 if is_blank(line_after_dashes):
-                    yield violations.D412(section_name)
+                    rest_of_lines = \
+                        context.following_lines[line_after_dashes_index:]
+                    if not is_blank(''.join(rest_of_lines)):
+                        yield violations.D412(section_name)
+                    else:
+                        yield violations.D414(section_name)
+            else:
+                yield violations.D414(section_name)
+
 
     @classmethod
     def _check_section(cls, docstring, definition, context):
-        """D4{05,06,10,11}, D214: Section name checks.
+        """D4{05,06,10,11,13}, D214: Section name checks.
 
         Check for valid section names. Checks that:
             * The section name is properly capitalized (D405).
             * The section is not over-indented (D214).
             * The section name has no superfluous suffix to it (D406).
-            * There's a blank line after the section (D410).
+            * There's a blank line after the section (D410, D413).
             * There's a blank line before the section (D411).
 
         Also yields all the errors from `_check_section_underline`.
@@ -551,7 +550,10 @@ def _check_section(cls, docstring, definition, context):
 
         if (not context.following_lines or
                 not is_blank(context.following_lines[-1])):
-            yield violations.D410(capitalized_section)
+            if context.is_last_section:
+                yield violations.D413(capitalized_section)
+            else:
+                yield violations.D410(capitalized_section)
 
         if not is_blank(context.previous_line):
             yield violations.D411(capitalized_section)
@@ -601,15 +603,17 @@ def _suspected_as_section(_line):
                                                        'previous_line',
                                                        'line',
                                                        'following_lines',
-                                                       'original_index'))
+                                                       'original_index',
+                                                       'is_last_section'))
 
         # First - create a list of possible contexts. Note that the
         # `following_linex` member is until the end of the docstring.
         contexts = (SectionContext(self._get_leading_words(lines[i].strip()),
                                    lines[i - 1],
                                    lines[i],
                                    lines[i + 1:],
-                                   i)
+                                   i,
+                                   False)
                     for i in suspected_section_indices)
 
         # Now that we have manageable objects - rule out false positives.
@@ -623,7 +627,8 @@ def _suspected_as_section(_line):
                                      a.previous_line,
                                      a.line,
                                      lines[a.original_index + 1:end],
-                                     a.original_index)
+                                     a.original_index,
+                                     b is None)
             for err in self._check_section(docstring, definition, new_ctx):
                 yield err
 

src/pydocstyle/utils.py

@@ -1,5 +1,10 @@
 """General shared utilities."""
 import logging
+from itertools import tee
+try:
+    from itertools import zip_longest
+except ImportError:
+    from itertools import izip_longest as zip_longest
 
 
 __version__ = '2.0.0rc'
@@ -9,3 +14,13 @@
 def is_blank(string):
     """Return True iff the string contains only whitespaces."""
     return not string.strip()
+
+
+def pairwise(iterable, default_value):
+    """Return pairs of items from `iterable`.
+
+    pairwise([1, 2, 3], default_value=None) -> (1, 2) (2, 3), (3, None)
+    """
+    a, b = tee(iterable)
+    _ = next(b, default_value)
+    return zip_longest(a, b, fillvalue=default_value)

src/pydocstyle/violations.py

@@ -223,8 +223,11 @@ def to_rst(cls):
                          'Expected {0!r} dashes in section {1!r}, got {2!r}')
 D410 = D4xx.create_error('D410', 'Missing blank line after section', '{0!r}')
 D411 = D4xx.create_error('D411', 'Missing blank line before section', '{0!r}')
-D412 = D4xx.create_error('D412', 'Section content should be in the line '
-                                 'following its header', '{0!r}')
+D412 = D4xx.create_error('D412', 'No blank lines allowed between a section '
+                                 'header and its content', '{0!r}')
+D413 = D4xx.create_error('D413', 'Missing blank line after last section',
+                         '{0!r}')
+D414 = D4xx.create_error('D414', 'Section has no content', '{0!r}')
 
 
 class AttrDict(dict):
@@ -237,5 +240,5 @@ def __getattr__(self, item):
     'pep257': all_errors - {'D203', 'D212', 'D213', 'D214', 'D215', 'D404',
                             'D405', 'D406', 'D407', 'D408', 'D409', 'D410',
                             'D411'},
-    'numpy': all_errors - {'D203', 'D212', 'D213', 'D402'}
+    'numpy': all_errors - {'D203', 'D212', 'D213', 'D402', 'D413'}
 })

src/tests/test_cases/sections.py

@@ -48,11 +48,31 @@ def no_underline():
 
 @expect(_D213)
 @expect("D407: Missing dashed underline after section ('Returns')")
-@expect("D410: Missing blank line after section ('Returns')")
 def no_underline():
     """Valid headline.
 
     Returns
+
+    """
+
+
+@expect(_D213)
+@expect("D410: Missing blank line after section ('Returns')")
+@expect("D414: Section has no content ('Returns')")
+@expect("D411: Missing blank line before section ('Yields')")
+@expect("D414: Section has no content ('Yields')")
+def consecutive_sections():
+    """Valid headline.
+
+    Returns
+    -------
+    Yields
+    ------
+
+    Raises
+    ------
+    Questions.
+
     """
 
 
@@ -84,8 +104,8 @@ def bad_underline_length():
 
 
 @expect(_D213)
-@expect("D410: Missing blank line after section ('Returns')")
-def no_blank_line_after_section():
+@expect("D413: Missing blank line after last section ('Returns')")
+def no_blank_line_after_last_section():
     """Valid headline.
 
     Returns
@@ -133,7 +153,8 @@ def section_underline_overindented():
 
 @expect(_D213)
 @expect("D215: Section underline is over-indented (in section 'Returns')")
-@expect("D410: Missing blank line after section ('Returns')")
+@expect("D413: Missing blank line after last section ('Returns')")
+@expect("D414: Section has no content ('Returns')")
 def section_underline_overindented_and_contentless():
     """Valid headline.
 
@@ -169,8 +190,8 @@ def section_name_in_first_line():
 @expect(_D213)
 @expect("D405: Section name should be properly capitalized "
         "('Short Summary', not 'Short summary')")
-@expect("D412: Section content should be in the line following its header "
-        "('Short Summary')")
+@expect("D412: No blank lines allowed between a section header and its "
+        "content ('Short Summary')")
 @expect("D409: Section underline should match the length of its name "
         "(Expected 7 dashes in section 'Returns', got 6)")
 @expect("D410: Missing blank line after section ('Returns')")

src/tests/test_integration.py

@@ -521,7 +521,9 @@ class Foo(object):
     assert 'D215' in out
     assert 'D405' in out
     assert 'D409' in out
-    assert 'D410' in out
+    assert 'D414' in out
+    assert 'D410' not in out
+    assert 'D413' not in out
 
 
 def test_config_file_inheritance(env):