Merge pull request #127 from Nurdok/package_error

D104: Missing docstring in public package

Author: Nurdok

docs/conf.py

@@ -18,7 +18,7 @@
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-sys.path.insert(0, os.path.join(os.path.abspath('.'), '..'))
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..'))
 
 # -- General configuration ------------------------------------------------
 
@@ -266,8 +266,9 @@
 issuetracker = 'github'
 issuetracker_project = 'GreenSteam/pep257'
 
+
 def generate_error_code_table():
-    from ..pep257 import ErrorRegistry
+    from pep257 import ErrorRegistry
     with open(os.path.join('snippets', 'error_code_table.rst'), 'wt') as outf:
         outf.write(ErrorRegistry.to_rst())
 

docs/release_notes.rst

@@ -5,7 +5,12 @@ Release Notes
 Current Development Version
 ---------------------------
 
-Nothing here yet!
+New Features
+
+* Added the D104 error code - "Missing docstring in public package". This new
+  error is turned on by default. Missing docstring in `__init__.py` files which
+  previously resulted in D100 errors ("Missing docstring in public module")
+  will now result in D104 (#105, #127).
 
 
 0.6.0 - July 20th, 2015

pep257.py

@@ -141,6 +141,11 @@ def __str__(self):
         return 'at module level'
 
 
+class Package(Module):
+
+    """A package is a __init__.py module."""
+
+
 class Function(Definition):
 
     _nest = staticmethod(lambda s: {'def': NestedFunction,
@@ -398,8 +403,11 @@ def parse_module(self):
         children = list(self.parse_definitions(Module, all=True))
         assert self.current is None, self.current
         end = self.line
-        module = Module(self.filename, self.source, start, end,
-                        [], docstring, children, None, self.all)
+        cls = Module
+        if self.filename.endswith('__init__.py'):
+            cls = Package
+        module = cls(self.filename, self.source, start, end,
+                     [], docstring, children, None, self.all)
         for child in module.children:
             child.parent = module
         log.debug("finished parsing module.")
@@ -580,6 +588,7 @@ def to_rst(cls):
 D101 = D1xx.create_error('D101', 'Missing docstring in public class')
 D102 = D1xx.create_error('D102', 'Missing docstring in public method')
 D103 = D1xx.create_error('D103', 'Missing docstring in public function')
+D104 = D1xx.create_error('D104', 'Missing docstring in public package')
 
 D2xx = ErrorRegistry.create_group('D2', 'Whitespace Issues')
 D200 = D2xx.create_error('D200', 'One-line docstring should fit on one line '
@@ -926,7 +935,8 @@ def check_docstring_missing(self, definition, docstring):
         if (not docstring and definition.is_public or
                 docstring and is_blank(eval(docstring))):
             codes = {Module: D100, Class: D101, NestedClass: D101,
-                     Method: D102, Function: D103, NestedFunction: D103}
+                     Method: D102, Function: D103, NestedFunction: D103,
+                     Package: D104}
             return codes[type(definition)]()
 
     @check_for(Definition)

test_pep257.py

@@ -279,3 +279,13 @@ def foo():
         assert code == 0
         assert 'D301' not in err
         assert 'D302' not in err
+
+
+def test_missing_docstring_in_package():
+    with Pep257Env() as env:
+        with env.open('__init__.py', 'wt') as init:
+            pass  # an empty package file
+        out, err, code = env.invoke_pep257()
+        assert code == 1
+        assert 'D100' not in err  # shouldn't be treated as a module
+        assert 'D104' in err  # missing docstring in package