Implement W505 - Max Doc Length check

Author: brianv0

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.

pycodestyle.py

@@ -102,6 +102,7 @@ def lru_cache(maxsize=128):  # noqa as it's a fake implementation.
     # Methods and nested class and function.
     'method': 1,
 }
+MAX_DOC_LENGTH = 72
 REPORT_FORMAT = {
     'default': '%(path)s:%(row)d:%(col)d: %(code)s %(text)s',
     'pylint': '%(path)s:%(row)d: [%(code)s] %(text)s',
@@ -1585,9 +1586,64 @@ def python_3000_async_await_keywords(logical_line, tokens):
         )
 
 
-##############################################################################
+########################################################################
+@register_check
+def maximum_doc_length(logical_line, max_doc_length, noqa, tokens):
+    r"""Limit all doc lines to a maximum of 72 characters.
+
+    For flowing long blocks of text (docstrings or comments), limiting
+    the length to 72 characters is recommended.
+
+    Reports warning W505
+    """
+    if max_doc_length is None or noqa:
+        return
+
+    prev_token = None
+    skip_lines = set()
+    # Skip lines that
+    for token_type, text, start, end, line in tokens:
+        if token_type not in SKIP_COMMENTS.union([tokenize.STRING]):
+            skip_lines.add(line)
+
+    for token_type, text, start, end, line in tokens:
+        # Skip lines that aren't pure strings
+        if token_type == tokenize.STRING and skip_lines:
+            continue
+        if token_type in (tokenize.STRING, tokenize.COMMENT):
+            # Only check comment-only lines
+            if prev_token is None or prev_token in SKIP_TOKENS:
+                lines = line.splitlines()
+                for line_num, physical_line in enumerate(lines):
+                    if hasattr(physical_line, 'decode'):  # Python 2
+                        # The line could contain multi-byte characters
+                        try:
+                            physical_line = physical_line.decode('utf-8')
+                        except UnicodeError:
+                            pass
+                    if start[0] + line_num == 1 and line.startswith('#!'):
+                        return
+                    length = len(physical_line)
+                    chunks = physical_line.split()
+                    if token_type == tokenize.COMMENT:
+                        if (len(chunks) == 2 and
+                                length - len(chunks[-1]) < MAX_DOC_LENGTH):
+                            continue
+                    if len(chunks) == 1 and line_num + 1 < len(lines):
+                        if (len(chunks) == 1 and
+                                length - len(chunks[-1]) < MAX_DOC_LENGTH):
+                            continue
+                    if length > max_doc_length:
+                        doc_error = (start[0] + line_num, max_doc_length)
+                        yield (doc_error, "W505 doc line too long "
+                                          "(%d > %d characters)"
+                               % (length, max_doc_length))
+        prev_token = token_type
+
+
+########################################################################
 # Helper functions
-##############################################################################
+########################################################################
 
 
 if sys.version_info < (3,):
@@ -1758,6 +1814,7 @@ def __init__(self, filename=None, lines=None,
         self._logical_checks = options.logical_checks
         self._ast_checks = options.ast_checks
         self.max_line_length = options.max_line_length
+        self.max_doc_length = options.max_doc_length
         self.multiline = False  # in a multiline string?
         self.hang_closing = options.hang_closing
         self.verbose = options.verbose
@@ -2324,8 +2381,8 @@ def get_parser(prog='pycodestyle', version=__version__):
                           usage="%prog [options] input ...")
     parser.config_options = [
         'exclude', 'filename', 'select', 'ignore', 'max-line-length',
-        'hang-closing', 'count', 'format', 'quiet', 'show-pep8',
-        'show-source', 'statistics', 'verbose']
+        'max-doc-length', 'hang-closing', 'count', 'format', 'quiet',
+        'show-pep8', 'show-source', 'statistics', 'verbose']
     parser.add_option('-v', '--verbose', default=0, action='count',
                       help="print status messages, or debug with -vv")
     parser.add_option('-q', '--quiet', default=0, action='count',
@@ -2361,6 +2418,10 @@ def get_parser(prog='pycodestyle', version=__version__):
                       default=MAX_LINE_LENGTH,
                       help="set maximum allowed line length "
                            "(default: %default)")
+    parser.add_option('--max-doc-length', type='int', metavar='n',
+                      default=None,
+                      help="set maximum allowed doc line length and perform "
+                           "these checks (unchecked if not set)")
     parser.add_option('--hang-closing', action='store_true',
                       help="hang closing bracket instead of matching "
                            "indentation of opening bracket's line")

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/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/utf-8.py

@@ -2,34 +2,34 @@
 
 # Some random text with multi-byte characters (utf-8 encoded)
 #
-# Εδώ μάτσο κειμένων τη, τρόπο πιθανό διευθυντές ώρα μη. Νέων απλό παράγει ροή
-# κι, το επί δεδομένη καθορίζουν. Πάντως ζητήσεις περιβάλλοντος ένα με, τη
-# ξέχασε αρπάζεις φαινόμενο όλη. Τρέξει εσφαλμένη χρησιμοποίησέ νέα τι. Θα όρο
+# Εδώ μάτσο κειμένων τη, τρόπο πιθανό διευθυντές ώρα μη. Νέων απλό π ροή
+# κι, το επί δεδομένη καθορίζουν. Πάντως ζητήσεις περιβάλλοντος ένα με,
+# ξέχασε αρπάζεις φαινόμενο όλη. Τρέξει εσφαλμένη χρησιμοποίησέ νέα τι.
 # πετάνε φακέλους, άρα με διακοπής λαμβάνουν εφαμοργής. Λες κι μειώσει
 # καθυστερεί.
 
 # 79 narrow chars
-# 01 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 [79]
+# 01 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3[79]
 
 # 78 narrow chars (Na) + 1 wide char (W)
-# 01 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8情
+# 01 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 情
 
 # 3 narrow chars (Na) + 40 wide chars (W)
 # 情 情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情
 
-# 3 narrow chars (Na) + 76 wide chars (W)
-# 情 情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情
+# 3 narrow chars (Na) + 69 wide chars (W)
+# 情 情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情
 
 #
-#: E501
+#: E501 W505
 # 80 narrow chars (Na)
 # 01 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6  [80]
 #
-#: E501
+#: E501 W505
 # 78 narrow chars (Na) + 2 wide char (W)
 # 01 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8情情
 #
-#: E501
+#: E501 W505
 # 3 narrow chars (Na) + 77 wide chars (W)
 # 情 情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情情
 #