Merge pull request #674 from brianv0/docstring_support

Support for W505 - doc line length

docs/intro.rst

@@ -157,6 +157,8 @@ Quick help is available on the command line::
     --count              print total number of errors and warnings to standard
                          error and set exit code to 1 if total is not null
     --max-line-length=n  set maximum allowed line length (default: 79)
+    --max-doc-length=n   set maximum allowed doc line length and perform these
+                         checks (unchecked if not set)
     --hang-closing       hang closing bracket instead of matching indentation of
                          opening bracket's line
     --format=format      set the error format [default|pylint|<custom>]
@@ -169,9 +171,9 @@ Quick help is available on the command line::
     Configuration:
       The project options are read from the [pycodestyle] section of the
       tox.ini file or the setup.cfg file located in any parent folder of the
-      path(s) being processed.  Allowed options are: exclude, filename, select,
-      ignore, max-line-length, hang-closing, count, format, quiet, show-pep8,
-      show-source, statistics, verbose.
+      path(s) being processed.  Allowed options are: exclude, filename,
+      select, ignore, max-line-length, max-doc-length, hang-closing, count,
+      format, quiet, show-pep8, show-source, statistics, verbose.
 
       --config=path      user config file location
       (default: ~/.config/pycodestyle)
@@ -406,6 +408,8 @@ This is the current list of error and warning codes:
 +------------+----------------------------------------------------------------------+
 | W504 (*)   | line break after binary operator                                     |
 +------------+----------------------------------------------------------------------+
+| W505 (\*^) | doc line too long (82 > 79 characters)                               |
++------------+----------------------------------------------------------------------+
 +------------+----------------------------------------------------------------------+
 | **W6**     | *Deprecation warning*                                                |
 +------------+----------------------------------------------------------------------+
@@ -423,14 +427,15 @@ This is the current list of error and warning codes:
 +------------+----------------------------------------------------------------------+
 
 
-**(*)** In the default configuration, the checks **E121**, **E123**, **E126**,
-**E133**, **E226**, **E241**, **E242**, **E704**, **W503** and **W504** are ignored
+**(*)** In the default configuration, the checks **E121**, **E123**, **E126**, **E133**,
+**E226**, **E241**, **E242**, **E704**, **W503**, **W504** and **W505** are ignored
 because they are not rules unanimously accepted, and `PEP 8`_ does not enforce them.
 Please note that if the option **--ignore=errors** is used,
 the default configuration will be overridden and ignore only the check(s) you skip.
 The check **W503** is mutually exclusive with check **W504**.
 The check **E133** is mutually exclusive with check **E123**.  Use switch
-``--hang-closing`` to report **E133** instead of **E123**.
+``--hang-closing`` to report **E133** instead of **E123**. Use switch
+``--max-doc-length=n`` to report **W505**.
 
 **(^)** These checks can be disabled at the line level using the ``# noqa``
 special comment.  This possibility should be reserved for special cases.

setup.cfg

@@ -8,3 +8,4 @@ license_file = LICENSE
 select =
 ignore = E226,E24,W504
 max_line_length = 79
+max_doc_length = 72

testsuite/E26.py

@@ -50,10 +50,10 @@ def oof():
     #foo not parsed
     """
 
-    ###########################################################################
-    #                               A SEPARATOR                               #
-    ###########################################################################
+    ####################################################################
+    #                            A SEPARATOR                           #
+    ####################################################################
 
-    # ####################################################################### #
-    # ########################## another separator ########################## #
-    # ####################################################################### #
+    # ################################################################ #
+    # ####################### another separator ###################### #
+    # ################################################################ #

testsuite/E50.py

@@ -62,27 +62,27 @@
 #: E501 E225 E226
 very_long_identifiers=and_terrible_whitespace_habits(are_no_excuse+for_long_lines)
 #
-#: E501
+#: E501 W505
 '''multiline string
 with a long long long long long long long long long long long long long long long long line
 '''
-#: E501
+#: E501 W505
 '''same thing, but this time without a terminal newline in the string
 long long long long long long long long long long long long long long long long line'''
 #
 # issue 224 (unavoidable long lines in docstrings)
 #: Okay
 """
 I'm some great documentation.  Because I'm some great documentation, I'm
-going to give you a reference to some valuable information about some API
-that I'm calling:
+going to give you a reference to some valuable information about some
+API that I'm calling:
 
     http://msdn.microsoft.com/en-us/library/windows/desktop/aa363858(v=vs.85).aspx
 """
-#: E501
+#: E501 W505
 """
 longnospaceslongnospaceslongnospaceslongnospaceslongnospaceslongnospaceslongnospaceslongnospaces"""
-#: E501
+#: E501 W505
 # Regression test for #622
 def foo():
     """Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis pulvinar vitae
@@ -92,19 +92,20 @@ def foo():
 This
                                                                        almost_empty_line
 """
-#: E501
+#: E501 W505
 """
 This
                                                                         almost_empty_line
 """
-#: E501
+#: E501 W505
 # A basic comment
 # with a long long long long long long long long long long long long long long long long line
 
 #
 #: Okay
 # I'm some great comment.  Because I'm so great, I'm going to give you a
-# reference to some valuable information about some API that I'm calling:
+# reference to some valuable information about some API that I'm
+# calling:
 #
 #     http://msdn.microsoft.com/en-us/library/windows/desktop/aa363858(v=vs.85).aspx
 
@@ -118,7 +119,7 @@ def foo():
 #                                                                      almost_empty_line
 
 #
-#: E501
+#: E501 W505
 # This
 #                                                                       almost_empty_line
 

testsuite/support.py

@@ -151,11 +151,11 @@ def init_tests(pep8style):
 
     A test file can provide many tests.  Each test starts with a
     declaration.  This declaration is a single line starting with '#:'.
-    It declares codes of expected failures, separated by spaces or 'Okay'
-    if no failure is expected.
+    It declares codes of expected failures, separated by spaces or
+    'Okay' if no failure is expected.
     If the file does not contain such declaration, it should pass all
-    tests.  If the declaration is empty, following lines are not checked,
-    until next declaration.
+    tests.  If the declaration is empty, following lines are not
+    checked, until next declaration.
 
     Examples:
 

testsuite/test_api.py

@@ -209,6 +209,12 @@ def parse_argv(argstring):
         self.assertEqual(options.select, ('E24',))
         self.assertEqual(options.ignore, ('',))
 
+        options = parse_argv('--max-doc-length=72').options
+        self.assertEqual(options.max_doc_length, 72)
+
+        options = parse_argv('').options
+        self.assertEqual(options.max_doc_length, None)
+
         pep8style = pycodestyle.StyleGuide(paths=[E11])
         self.assertFalse(pep8style.ignore_code('E112'))
         self.assertFalse(pep8style.ignore_code('W191'))

testsuite/test_blank_lines.py

@@ -35,8 +35,8 @@ def assertNoErrors(self, actual):
 
 class TestBlankLinesDefault(BlankLinesTestCase):
     """
-    Tests for default blank with 2 blank lines for top level and 1 blank line
-    for methods.
+    Tests for default blank with 2 blank lines for top level and 1
+    blank line for methods.
     """
 
     def test_initial_no_blank(self):
@@ -51,8 +51,8 @@ def test_initial_no_blank(self):
 
     def test_initial_lines_one_blank(self):
         """
-        It will accept 1 blank lines before the first line of actual code,
-        even if in other places it asks for 2
+        It will accept 1 blank lines before the first line of actual
+        code, even if in other places it asks for 2
         """
         result = self.check("""
 def some_function():
@@ -63,8 +63,8 @@ def some_function():
 
     def test_initial_lines_two_blanks(self):
         """
-        It will accept 2 blank lines before the first line of actual code,
-        as normal.
+        It will accept 2 blank lines before the first line of actual
+        code, as normal.
         """
         result = self.check("""
 
@@ -76,8 +76,8 @@ def some_function():
 
     def test_method_less_blank_lines(self):
         """
-        It will trigger an error when less than 1 blank lin is found before
-        method definitions.
+        It will trigger an error when less than 1 blank lin is found
+        before method definitions.
         """
         result = self.check("""# First comment line.
 class X:
@@ -93,8 +93,8 @@ def b():
 
     def test_method_less_blank_lines_comment(self):
         """
-        It will trigger an error when less than 1 blank lin is found before
-        method definition, ignoring comments.
+        It will trigger an error when less than 1 blank lin is found
+        before method definition, ignoring comments.
         """
         result = self.check("""# First comment line.
 class X:
@@ -111,8 +111,8 @@ def b():
 
     def test_top_level_fewer_blank_lines(self):
         """
-        It will trigger an error when less 2 blank lines are found before top
-        level definitions.
+        It will trigger an error when less 2 blank lines are found
+        before top level definitions.
         """
         result = self.check("""# First comment line.
 # Second line of comment.
@@ -146,8 +146,8 @@ class AFarEnoughClass(object):
 
     def test_top_level_more_blank_lines(self):
         """
-        It will trigger an error when more 2 blank lines are found before top
-        level definitions.
+        It will trigger an error when more 2 blank lines are found
+        before top level definitions.
         """
         result = self.check("""# First comment line.
 # Second line of comment.
@@ -177,8 +177,8 @@ class AFarEnoughClass(object):
 
     def test_method_more_blank_lines(self):
         """
-        It will trigger an error when more than 1 blank line is found before
-        method definition
+        It will trigger an error when more than 1 blank line is found
+        before method definition
         """
         result = self.check("""# First comment line.
 
@@ -209,8 +209,8 @@ def veryFar(self):
 
     def test_initial_lines_more_blank(self):
         """
-        It will trigger an error for more than 2 blank lines before the first
-        line of actual code.
+        It will trigger an error for more than 2 blank lines before the
+        first line of actual code.
         """
         result = self.check("""
 
@@ -222,8 +222,8 @@ def some_function():
 
     def test_blank_line_between_decorator(self):
         """
-        It will trigger an error when the decorator is followed by a blank
-        line.
+        It will trigger an error when the decorator is followed by a
+        blank line.
         """
         result = self.check("""# First line.
 
@@ -245,8 +245,8 @@ def some_method(self):
 
     def test_blank_line_decorator(self):
         """
-        It will accept the decorators which are adjacent to the function and
-        method definition.
+        It will accept the decorators which are adjacent to the function
+        and method definition.
         """
         result = self.check("""# First line.
 
@@ -340,7 +340,8 @@ def b():
     def test_method_nested_fewer_follow_lines(self):
         """
         It will trigger an error when less than 1 blank line is
-        found between a method and previous definitions, even when nested.
+        found between a method and previous definitions, even when
+        nested.
         """
         result = self.check("""
 def a():
@@ -374,7 +375,8 @@ class C:
     def test_method_nested_ok(self):
         """
         Will not trigger an error when 1 blank line is found
-        found between a method and previous definitions, even when nested.
+        found between a method and previous definitions, even when
+        nested.
         """
         result = self.check("""
 def a():
@@ -394,8 +396,8 @@ class C:
 
 class TestBlankLinesTwisted(BlankLinesTestCase):
     """
-    Tests for blank_lines with 3 blank lines for top level and 2 blank line
-    for methods as used by the Twisted coding style.
+    Tests for blank_lines with 3 blank lines for top level and 2 blank
+    line for methods as used by the Twisted coding style.
     """
 
     def setUp(self):
@@ -408,8 +410,8 @@ def tearDown(self):
 
     def test_initial_lines_one_blanks(self):
         """
-        It will accept less than 3 blank lines before the first line of actual
-        code.
+        It will accept less than 3 blank lines before the first line of
+        actual code.
         """
         result = self.check("""
 
@@ -422,8 +424,8 @@ def some_function():
 
     def test_initial_lines_tree_blanks(self):
         """
-        It will accept 3 blank lines before the first line of actual code,
-        as normal.
+        It will accept 3 blank lines before the first line of actual
+        code, as normal.
         """
         result = self.check("""
 
@@ -436,8 +438,8 @@ def some_function():
 
     def test_top_level_fewer_blank_lines(self):
         """
-        It will trigger an error when less 2 blank lines are found before top
-        level definitions.
+        It will trigger an error when less 2 blank lines are found
+        before top level definitions.
         """
         result = self.check("""# First comment line.
 # Second line of comment.
@@ -476,8 +478,8 @@ class AFarEnoughClass(object):
 
     def test_top_level_more_blank_lines(self):
         """
-        It will trigger an error when more 2 blank lines are found before top
-        level definitions.
+        It will trigger an error when more 2 blank lines are found
+        before top level definitions.
         """
         result = self.check("""# First comment line.
 # Second line of comment.