#129 - CR fixes

Author: shacharoo

src/pydocstyle/checker.py

@@ -423,29 +423,42 @@ def _get_leading_words(line):
 
     @staticmethod
     def _is_a_docstring_section(context):
-        """Check if the suspected line is really a section.
+        """Check if the suspected context is really a section header.
 
-        This is done by checking the following conditions:
-        * Does the current line has a suffix after the suspected section name?
-        * Is the previous line not empty?
-        * Does the previous line end with a punctuation mark?
-
-        If so, this is probably not a real section name. For example:
+        Lets have a look at the following example docstring:
             '''Title.
 
             Some part of the docstring that specifies what the function
-            returns. <----- Not a real section name.
+            returns. <----- Not a real section name. It has a suffix and the
+                            previous line is not empty and does not end with
+                            a punctuation sign.
+
+            This is another line in the docstring. It describes stuff,
+            but we forgot to add a blank line between it and the section name.
+            Returns  <----- A real section name. The previous line ends with
+            -------         a period, therefore it is in a new
+                            grammatical context.
+            Bla.
+
             '''
+
+        To make sure this is really a section we check these conditions:
+            * There's no suffix to the section name.
+            * The previous line ends with punctuation.
+            * The previous line is empty.
+
+        If one of the conditions is true, we will consider the line as
+        a section name.
         """
         section_name_suffix = context.line.lstrip(context.section_name).strip()
 
         punctuation = [',', ';', '.', '-', '\\', '/', ']', '}', ')']
         prev_line_ends_with_punctuation = \
             any(context.previous_line.strip().endswith(x) for x in punctuation)
 
-        return not (section_name_suffix != '' and not
-                    prev_line_ends_with_punctuation and not
-                    context.previous_line.strip() == '')
+        return (is_blank(section_name_suffix) or
+                prev_line_ends_with_punctuation or
+                is_blank(context.previous_line))
 
     @classmethod
     def _check_section_underline(cls, section_name, context, indentation):
@@ -466,7 +479,7 @@ def _check_section_underline(cls, section_name, context, indentation):
 
         for line in context.following_lines:
             line_set = ''.join(set(line.strip()))
-            if line_set != '':
+            if not is_blank(line_set):
                 dash_line_found = line_set == '-'
                 break
             next_non_empty_line_offset += 1
@@ -481,13 +494,13 @@ def _check_section_underline(cls, section_name, context, indentation):
 
             dash_line = context.following_lines[next_non_empty_line_offset]
             if dash_line.strip() != "-" * len(section_name):
-                yield violations.D409(section_name,
-                                      len(section_name),
+                yield violations.D409(len(section_name),
+                                      section_name,
                                       len(dash_line.strip()))
 
             line_after_dashes = \
                 context.following_lines[next_non_empty_line_offset + 1]
-            if line_after_dashes.strip() != '':
+            if not is_blank(line_after_dashes):
                 yield violations.D410(section_name)
 
             if leading_space(dash_line) > indentation:
@@ -516,10 +529,10 @@ def _check_section(cls, docstring, definition, context):
             yield violations.D214(capitalized_section)
 
         suffix = context.line.strip().lstrip(context.section_name)
-        if suffix != '':
+        if suffix:
             yield violations.D406(capitalized_section, context.line.strip())
 
-        if context.previous_line.strip() != '':
+        if not is_blank(context.previous_line):
             yield violations.D411(capitalized_section)
 
         for err in cls._check_section_underline(capitalized_section,
@@ -564,15 +577,16 @@ def _suspected_as_section(_line):
         suspected_section_indices = [i for i, line in enumerate(lines) if
                                      _suspected_as_section(line)]
 
-        context = namedtuple('SectionContext', ('section_name',
-                                                'previous_line',
-                                                'line',
-                                                'following_lines'))
+        SectionContext = namedtuple('SectionContext', ('section_name',
+                                                       'previous_line',
+                                                       'line',
+                                                       'following_lines'))
 
-        contexts = (context(self._get_leading_words(lines[i].strip()),
-                            lines[i - 1],
-                            lines[i],
-                            lines[i + 1:]) for i in suspected_section_indices)
+        contexts = (SectionContext(self._get_leading_words(lines[i].strip()),
+                                   lines[i - 1],
+                                   lines[i],
+                                   lines[i + 1:])
+                    for i in suspected_section_indices)
 
         for ctx in contexts:
             if self._is_a_docstring_section(ctx):

src/pydocstyle/violations.py

@@ -220,7 +220,7 @@ def to_rst(cls):
                          '{0!r}')
 D409 = D4xx.create_error('D409', 'Section underline should match the length '
                                  'of its name',
-                         'len({0!r}) == {1!r}, got {2!r} dashes')
+                         '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}')
 

src/tests/test_cases/sections.py

@@ -45,7 +45,7 @@ def no_underline():
 
 @expect(_D213)
 @expect("D408: Section underline should be in the line following the "
-        "section\'s name ('Returns')")
+        "section's name ('Returns')")
 def blank_line_before_underline():
     """Valid headline.
 
@@ -58,7 +58,7 @@ def blank_line_before_underline():
 
 @expect(_D213)
 @expect("D409: Section underline should match the length of its name "
-        "(len('Returns') == 7, got 2 dashes)")
+        "(Expected 7 dashes in section 'Returns', got 2)")
 def bad_underline_length():
     """Valid headline.
 
@@ -140,7 +140,7 @@ def section_name_in_first_line():
 @expect("D405: Section name should be properly capitalized "
         "('Short Summary', not 'Short summary')")
 @expect("D409: Section underline should match the length of its name "
-        "(len('Returns') == 7, got 6 dashes)")
+        "(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 "

src/tests/test_integration.py

@@ -436,6 +436,7 @@ def test_illegal_convention(env):
     assert "Illegal convention 'illegal_conv'." in err
     assert 'Possible conventions' in err
     assert 'pep257' in err
+    assert 'numpy' in err
 
 
 def test_empty_select_cli(env):