Merge pull request #139 from Nurdok/D105

Added D105: missing docstring in magic method

Author: Nurdok

docs/release_notes.rst

@@ -12,6 +12,14 @@ New Features
   previously resulted in D100 errors ("Missing docstring in public module")
   will now result in D104 (#105, #127).
 
+* Added the D105 error code - "Missing docstring in magic method'. This new
+  error is turned on by default. Missing docstrings in magic method which
+  previously resulted in D102 error ("Missing docstring in public method")
+  will now result in D105. Note that exceptions to this rule are variadic
+  magic methods - specifically `__init__`, `__call__` and `__new__`, which
+  will be considered non-magic and missing docstrings in them will result
+  in D102 (#60, #139).
+
 * Support the option to exclude all error codes. Running pep257 with
   `--select=` (or `select=` in the configuration file) will exclude all errors
   which could then be added one by one using `add-select`. Useful for projects

src/pep257.py

@@ -66,14 +66,17 @@ def next(obj, default=nothing):
 NO_VIOLATIONS_RETURN_CODE = 0
 VIOLATIONS_RETURN_CODE = 1
 INVALID_OPTIONS_RETURN_CODE = 2
+VARIADIC_MAGIC_METHODS = ('__init__', '__call__', '__new__')
 
 
 def humanize(string):
     return re(r'(.)([A-Z]+)').sub(r'\1 \2', string).lower()
 
 
 def is_magic(name):
-    return name.startswith('__') and name.endswith('__')
+    return (name.startswith('__') and
+            name.endswith('__') and
+            name not in VARIADIC_MAGIC_METHODS)
 
 
 def is_ascii(string):
@@ -154,8 +157,8 @@ class Function(Definition):
     def is_public(self):
         if self.all is not None:
             return self.name in self.all
-        else:  # TODO: are there any magic functions? not methods
-            return not self.name.startswith('_') or is_magic(self.name)
+        else:
+            return not self.name.startswith('_')
 
 
 class NestedFunction(Function):
@@ -172,7 +175,9 @@ def is_public(self):
             # Given 'foo', match 'foo.bar' but not 'foobar' or 'sfoo'
             if re(r"^{0}\.".format(self.name)).match(decorator.name):
                 return False
-        name_is_public = not self.name.startswith('_') or is_magic(self.name)
+        name_is_public = (not self.name.startswith('_') or
+                          self.name in VARIADIC_MAGIC_METHODS or
+                          is_magic(self.name))
         return self.parent.is_public and name_is_public
 
 
@@ -628,6 +633,7 @@ def to_rst(cls):
 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')
+D105 = D1xx.create_error('D105', 'Missing docstring in magic method')
 
 D2xx = ErrorRegistry.create_group('D2', 'Whitespace Issues')
 D200 = D2xx.create_error('D200', 'One-line docstring should fit on one line '
@@ -1347,8 +1353,9 @@ 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,
-                     Package: D104}
+                     Method: (lambda: D105() if is_magic(definition.name)
+                              else D102()),
+                     Function: D103, NestedFunction: D103, Package: D104}
             return codes[type(definition)]()
 
     @check_for(Definition)

src/tests/test_cases/test.py

@@ -28,6 +28,14 @@ def _ok_since_private():
     def __init__(self=None):
         pass
 
+    @expect('D105: Missing docstring in magic method')
+    def __str__(self=None):
+        pass
+
+    @expect('D102: Missing docstring in public method')
+    def __call__(self=None, x=None, y=None, z=None):
+        pass
+
 
 @expect('D103: Missing docstring in public function')
 def function():