Merge branch 'master' of github.com:PyCQA/pydocstyle into imperative-mood-heuristic-2

Author: lordmauve

docs/release_notes.rst

@@ -20,7 +20,8 @@ New Features
 * Decorator-based skipping via ``--ignore-decorators`` has been added (#204).
 * Support for using pycodestyle style wildcards has been added (#72, #209).
 * Superfluous opening quotes are now reported as part of D300 (#166, #225).
-* Support for ``numpy`` conventions verification has been added (#129).
+* Support for ``numpy`` conventions verification has been added (#129, #226).
+* Fixed a false-positive recognition of `D410` and added `D412` (#230, #233).
 
 Bug Fixes
 

src/pydocstyle/checker.py

@@ -12,7 +12,7 @@
 from .config import IllegalConfiguration
 from .parser import (Package, Module, Class, NestedClass, Definition, AllError,
                      Method, Function, NestedFunction, Parser, StringIO)
-from .utils import log, is_blank
+from .utils import log, is_blank, pairwise
 from .wordlists import IMPERATIVE_VERBS, IMPERATIVE_BLACKLIST, stem
 
 
@@ -472,58 +472,73 @@ def _is_a_docstring_section(context):
 
     @classmethod
     def _check_section_underline(cls, section_name, context, indentation):
-        """D4{07,08,09,10}, D215: Section underline checks.
+        """D4{07,08,09,12}, D215: Section underline checks.
 
         Check for correct formatting for docstring sections. Checks that:
             * The line that follows the section name contains
               dashes (D40{7,8}).
             * The amount of dashes is equal to the length of the section
               name (D409).
-            * The line that follows the section header (with or without dashes)
-              is empty (D410).
+            * The section's content does not begin in the line that follows
+              the section header (D412).
             * 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:
-                yield violations.D410(section_name)
+            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()))
 
-            line_after_dashes = \
-                context.following_lines[next_non_empty_line_offset + 1]
-            if not is_blank(line_after_dashes):
-                yield violations.D410(section_name)
-
-            if leading_space(dash_line) > indentation:
+            if leading_space(non_empty_line) > indentation:
                 yield violations.D215(section_name)
 
+            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[line_after_dashes_index]
+                if is_blank(line_after_dashes):
+                    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,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, D413).
             * There's a blank line before the section (D411).
 
         Also yields all the errors from `_check_section_underline`.
@@ -542,6 +557,13 @@ def _check_section(cls, docstring, definition, context):
         if suffix:
             yield violations.D406(capitalized_section, context.line.strip())
 
+        if (not context.following_lines or
+                not is_blank(context.following_lines[-1])):
+            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)
 
@@ -559,13 +581,12 @@ def check_docstring_sections(self, definition, docstring):
 
             Short Summary
             -------------
-
             This is my summary.
 
             Returns
             -------
-
             None.
+
             '''
 
         Section names appear in `SECTION_NAMES`.
@@ -590,18 +611,35 @@ def _suspected_as_section(_line):
         SectionContext = namedtuple('SectionContext', ('section_name',
                                                        'previous_line',
                                                        'line',
-                                                       'following_lines'))
+                                                       'following_lines',
+                                                       '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:])
+                                   lines[i + 1:],
+                                   i,
+                                   False)
                     for i in suspected_section_indices)
 
-        for ctx in contexts:
-            if self._is_a_docstring_section(ctx):
-                for err in self._check_section(docstring, definition, ctx):
-                    yield err
+        # Now that we have manageable objects - rule out false positives.
+        contexts = (c for c in contexts if self._is_a_docstring_section(c))
+
+        # Now we shall trim the `following lines` field to only reach the
+        # next section name.
+        for a, b in pairwise(contexts, None):
+            end = -1 if b is None else b.original_index
+            new_ctx = SectionContext(a.section_name,
+                                     a.previous_line,
+                                     a.line,
+                                     lines[a.original_index + 1:end],
+                                     a.original_index,
+                                     b is None)
+            for err in self._check_section(docstring, definition, new_ctx):
+                yield err
 
 
 parse = Parser()

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

@@ -225,6 +225,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', '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 +242,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

@@ -17,6 +17,7 @@ def not_capitalized():
 
     returns
     -------
+    A value of some sort.
 
     """
 
@@ -29,6 +30,7 @@ def superfluous_suffix():
 
     Returns:
     -------
+    A value of some sort.
 
     """
 
@@ -39,6 +41,37 @@ def no_underline():
     """Toggle the gizmo.
 
     Returns
+    A value of some sort.
+
+    """
+
+
+@expect(_D213)
+@expect("D407: Missing dashed underline 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.
 
     """
 
@@ -52,6 +85,7 @@ def blank_line_before_underline():
     Returns
 
     -------
+    A value of some sort.
 
     """
 
@@ -64,18 +98,19 @@ def bad_underline_length():
 
     Returns
     --
+    A value of some sort.
 
     """
 
 
 @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():
     """Toggle the gizmo.
 
     Returns
     -------
-    A whole lot of values.
+    A value of some sort.
     """
 
 
@@ -87,6 +122,7 @@ def no_blank_line_before_section():
     The function's description.
     Returns
     -------
+    A value of some sort.
 
     """
 
@@ -98,6 +134,7 @@ def section_overindented():
 
         Returns
     -------
+    A value of some sort.
 
     """
 
@@ -109,10 +146,23 @@ def section_underline_overindented():
 
     Returns
         -------
+    A value of some sort.
 
     """
 
 
+@expect(_D213)
+@expect("D215: Section underline is over-indented (in 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.
+
+    Returns
+        -------
+    """
+
+
 @expect(_D213)
 def ignore_non_actual_section():
     """Toggle the gizmo.
@@ -132,21 +182,23 @@ def ignore_non_actual_section():
 def section_name_in_first_line():
     """Returns
     -------
+    A value of some sort.
 
     """
 
 
 @expect(_D213)
 @expect("D405: Section name should be properly capitalized "
         "('Short Summary', not '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')")
 @expect("D411: Missing blank line before section ('Raises')")
 @expect("D406: Section name should end with a newline "
         "('Raises', not 'Raises:')")
 @expect("D407: Missing dashed underline after section ('Raises')")
-@expect("D410: Missing blank line after section ('Raises')")
 def multiple_sections():
     """Toggle the gizmo.
 

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):