Merge pull request #137 from Nurdok/D211

Added D211: No blank lines allowed before class docstring

Author: Nurdok

docs/error_codes.rst

@@ -6,3 +6,12 @@ Grouping
 
 .. include:: snippets/error_code_table.rst
 
+
+Default Checks
+--------------
+
+Not all error codes are checked for by default. The default behavior is to
+check only error codes that are part of the `PEP257
+<http://www.python.org/dev/peps/pep-0257/>`_ official convention.
+
+All of the above error codes are checked for by default except for D203.

docs/release_notes.rst

@@ -17,6 +17,11 @@ New Features
   which could then be added one by one using `add-select`. Useful for projects
   new to pep257 (#132, #135).
 
+* Added check D211: No blank lines allowed before class docstring. This change
+  is a result of a change to the official PEP257 convention. Therefore, D211
+  will now be checked by default instead of D203, which required a single
+  blank line before a class docstring (#137).
+
 Bug Fixes
 
 * On Python 2.x, D302 ("Use u""" for Unicode docstrings") is not reported
@@ -27,7 +32,7 @@ Bug Fixes
 
 
 0.6.0 - July 20th, 2015
----------------------------
+-----------------------
 
 New Features
 

src/pep257.py

@@ -143,7 +143,6 @@ def __str__(self):
 
 
 class Package(Module):
-
     """A package is a __init__.py module."""
 
 
@@ -190,7 +189,6 @@ class NestedClass(Class):
 
 
 class Decorator(Value):
-
     """A decorator for function, method or class."""
 
     _fields = 'name arguments'.split()
@@ -252,7 +250,6 @@ def __call__(self, filelike, filename):
         self.stream = TokenStream(StringIO(src))
         self.filename = filename
         self.all = None
-        # TODO: what about Python 3.x?
         self.future_imports = defaultdict(lambda: False)
         self._accumulated_decorators = []
         return self.parse_module()
@@ -506,7 +503,6 @@ def parse_from_import_statement(self):
 
 
 class Error(object):
-
     """Error in docstring style."""
 
     # should be overridden by inheriting classes
@@ -655,6 +651,8 @@ def to_rst(cls):
                                  'be on a separate line')
 D210 = D2xx.create_error('D210', 'No whitespaces allowed surrounding '
                                  'docstring text')
+D211 = D2xx.create_error('D211', 'No blank lines allowed before class '
+                                 'docstring', 'found %s')
 
 D3xx = ErrorRegistry.create_group('D3', 'Quotes Issues')
 D300 = D3xx.create_error('D300', 'Use """triple double quotes"""',
@@ -677,7 +675,7 @@ def __getattr__(self, item):
 
 
 conventions = AttrDict({
-    'pep257': set(ErrorRegistry.get_error_codes()),
+    'pep257': set(ErrorRegistry.get_error_codes()) - set(['D203']),
 })
 
 
@@ -934,7 +932,6 @@ def decorator(f):
 
 
 class PEP257Checker(object):
-
     """Checker for PEP 257.
 
     D10x: Missing docstrings
@@ -1053,6 +1050,8 @@ def check_blank_before_after_class(slef, class_, docstring):
             blanks_after = list(map(is_blank, after.split('\n')[1:]))
             blanks_before_count = sum(takewhile(bool, reversed(blanks_before)))
             blanks_after_count = sum(takewhile(bool, blanks_after))
+            if blanks_before_count != 0:
+                yield D211(blanks_before_count)
             if blanks_before_count != 1:
                 yield D203(blanks_before_count)
             if not all(blanks_after) and blanks_after_count != 1:

src/tests/test_cases/test.py

@@ -78,8 +78,19 @@ class LeadingSpaceMissing:
     """Leading space missing."""
 
 
+expect('WithLeadingSpace',
+       'D211: No blank lines allowed before class docstring (found 1)')
+
+
+class WithLeadingSpace:
+
+    """With leading space."""
+
+
 expect('TrailingSpace',
        'D204: 1 blank line required after class docstring (found 0)')
+expect('TrailingSpace',
+       'D211: No blank lines allowed before class docstring (found 1)')
 
 
 class TrailingSpace:

src/tests/test_definitions.py

@@ -1,6 +1,7 @@
 import os
 from ..pep257 import (StringIO, TokenStream, Parser, Error, check,
-                      Module, Class, Method, Function, NestedFunction)
+                      Module, Class, Method, Function, NestedFunction,
+                      ErrorRegistry)
 
 
 _ = type('', (), dict(__repr__=lambda *a: '_', __eq__=lambda *a: True))()
@@ -136,7 +137,8 @@ def test_pep257():
                                  level=1)
         # from .test_cases import test
         results = list(check([os.path.join(os.path.dirname(__file__),
-                                           'test_cases', test_case + '.py')]))
+                                           'test_cases', test_case + '.py')],
+                             select=set(ErrorRegistry.get_error_codes())))
         for error in results:
             assert isinstance(error, Error)
         results = set([(e.definition.name, e.message) for e in results])

src/tests/test_pep257.py

@@ -21,7 +21,6 @@
 
 
 class Pep257Env():
-
     """An isolated environment where pep257.py can be run.
 
     Since running pep257.py as a script is affected by local config files, it's
@@ -80,8 +79,9 @@ def __exit__(self, *args, **kwargs):
 def test_pep257_conformance():
     relative = partial(os.path.join, os.path.dirname(__file__))
     errors = list(pep257.check([relative('..', 'pep257.py'),
-                                relative('test_pep257.py')]))
-    assert errors == []
+                                relative('test_pep257.py')],
+                               select=pep257.conventions.pep257))
+    assert errors == [], errors
 
 
 def test_ignore_list():
@@ -346,3 +346,24 @@ def foo():
         assert 'D100' in err
         assert 'D101' not in err
         assert 'D103' not in err
+
+
+def test_pep257_convention():
+    """Test that the 'pep257' convention options has the correct errors."""
+    with Pep257Env() as env:
+        with env.open('example.py', 'wt') as example:
+            example.write(textwrap.dedent('''
+                class Foo(object):
+
+
+                    """Docstring for this class"""
+                    def foo():
+                        pass
+            '''))
+
+        env.write_config(convention="pep257")
+        _, err, code = env.invoke_pep257()
+        assert code == 1
+        assert 'D100' in err
+        assert 'D211' in err
+        assert 'D203' not in err