Merge branch 'master' into splitfiles

# Conflicts:
#	src/pydocstyle.py
#	src/pydocstyle/tests/test_decorators.py

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.dirname(__file__), '..'))
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', 'src'))
 
 # -- General configuration ------------------------------------------------
 

docs/release_notes.rst

@@ -16,8 +16,17 @@ New Features
 * Added D404 - First word of the docstring should not be "This". It is turned
   off by default (#183).
 
+* Added the ability to ignore specific function and method docstrings with
+  inline comments:
+
+    1. "# noqa" skips all checks.
+
+    2. "# noqa: D102,D203" can be used to skip specific checks.
+
 Bug Fixes
 
+* Fixed an issue where file paths were printed in lower case (#179, #181).
+
 * The error code D300 is now also being reported if a docstring has
   uppercase literals (``R`` or ``U``) as prefix (#176).
 

docs/snippets/in_file.rst

@@ -0,0 +1,15 @@
+``pydocstyle`` supports inline commenting to skip specific checks on
+specific functions or methods. The supported comments that can be added are:
+
+1. ``"# noqa"`` skips all checks.
+
+2. ``"# noqa: D102,D203"`` can be used to skip specific checks. Note that
+   this is compatible with skips from `flake8 <http://flake8.pycqa.org/>`_,
+   e.g. ``# noqa: D102,E501,D203``.
+
+For example, this will skip the check for a period at the end of a function
+docstring::
+
+    >>> def bad_function():  # noqa: D400
+    ...     """Omit a period in the docstring as an exception"""
+    ...     pass

docs/usage.rst

@@ -17,3 +17,9 @@ Configuration Files
 ^^^^^^^^^^^^^^^^^^^
 
 .. include:: snippets/config.rst
+
+
+In-file configuration
+^^^^^^^^^^^^^^^^^^^^^
+
+.. include:: snippets/in_file.rst

requirements.txt

@@ -1,3 +1,4 @@
 -r requirements/docs.txt
 -r requirements/tests.txt
+-r requirements/test_env.txt
 -r requirements/runtime.txt

requirements/tests.txt

@@ -1,4 +1,4 @@
-pytest==2.7.3
-pytest-pep8
-mock
+pytest==3.0.2
+pytest-pep8==1.0.6
+mock==2.0.0
 pathlib

src/pydocstyle/checker.py

@@ -49,10 +49,14 @@ def check_source(self, source, filename):
             for check in self.checks:
                 terminate = False
                 if isinstance(definition, check._check_for):
-                    error = check(None, definition, definition.docstring)
+                    if definition.skipped_error_codes != 'all':
+                        error = check(None, definition, definition.docstring)
+                    else:
+                        error = None
                     errors = error if hasattr(error, '__iter__') else [error]
                     for error in errors:
-                        if error is not None:
+                        if error is not None and error.code not in \
+                                definition.skipped_error_codes:
                             partition = check.__doc__.partition('.\n')
                             message, _, explanation = partition
                             error.set_context(explanation=explanation,

src/pydocstyle/parser.py

@@ -41,6 +41,10 @@ class Value(object):
     """A generic object with a list of preset fields."""
 
     def __init__(self, *args):
+        if len(self._fields) != len(args):
+            raise ValueError('got {0} arguments for {1} fields for {2}: {3}'
+                             .format(len(args), len(self._fields),
+                                     self.__class__.__name__, self._fields))
         vars(self).update(zip(self._fields, args))
 
     def __hash__(self):
@@ -59,7 +63,7 @@ class Definition(Value):
     """A Python source code definition (could be class, function, etc)."""
 
     _fields = ('name', '_source', 'start', 'end', 'decorators', 'docstring',
-               'children', 'parent')
+               'children', 'parent', 'skipped_error_codes')
 
     _human = property(lambda self: humanize(type(self).__name__))
     kind = property(lambda self: self._human.split()[-1])
@@ -87,14 +91,19 @@ def is_empty_or_comment(line):
         return ''.join(reversed(list(filtered_src)))
 
     def __str__(self):
-        return 'in %s %s `%s`' % (self._publicity, self._human, self.name)
+        out = 'in {0} {1} `{2}`'.format(self._publicity, self._human,
+                                        self.name)
+        if self.skipped_error_codes:
+            out += ' (skipping {0})'.format(self.skipped_error_codes)
+        return out
 
 
 class Module(Definition):
     """A Python source code module."""
 
     _fields = ('name', '_source', 'start', 'end', 'decorators', 'docstring',
-               'children', 'parent', '_all', 'future_imports')
+               'children', 'parent', '_all', 'future_imports',
+               'skipped_error_codes')
     is_public = True
     _nest = staticmethod(lambda s: {'def': Function, 'class': Class}[s])
     module = property(lambda self: self)
@@ -364,17 +373,17 @@ def parse_all(self):
         if self.current.value not in '([':
             raise AllError('Could not evaluate contents of __all__. ')
         if self.current.value == '[':
-            msg = ("%s WARNING: __all__ is defined as a list, this means "
-                   "pydocstyle cannot reliably detect contents of the __all__ "
-                   "variable, because it can be mutated. Change __all__ to be "
-                   "an (immutable) tuple, to remove this warning. Note, "
-                   "pydocstyle uses __all__ to detect which definitions are "
-                   "public, to warn if public definitions are missing "
-                   "docstrings. If __all__ is a (mutable) list, pydocstyle "
-                   "cannot reliably assume its contents. pydocstyle will "
-                   "proceed assuming __all__ is not mutated.\n"
-                   % self.filename)
-            sys.stderr.write(msg)
+            sys.stderr.write(
+                "{0} WARNING: __all__ is defined as a list, this means "
+                "pydocstyle cannot reliably detect contents of the __all__ "
+                "variable, because it can be mutated. Change __all__ to be "
+                "an (immutable) tuple, to remove this warning. Note, "
+                "pydocstyle uses __all__ to detect which definitions are "
+                "public, to warn if public definitions are missing "
+                "docstrings. If __all__ is a (mutable) list, pydocstyle "
+                "cannot reliably assume its contents. pydocstyle will "
+                "proceed assuming __all__ is not mutated.\n"
+                .format(self.filename))
         self.consume(tk.OP)
 
         self.all = []
@@ -386,17 +395,17 @@ def parse_all(self):
                     self.current.value == ','):
                 all_content += self.current.value
             else:
-                raise AllError('Unexpected token kind in  __all__: %r. ' %
-                               self.current.kind)
+                raise AllError('Unexpected token kind in  __all__: {0!r}. '
+                               .format(self.current.kind))
             self.stream.move()
         self.consume(tk.OP)
         all_content += ")"
         try:
             self.all = eval(all_content, {})
         except BaseException as e:
             raise AllError('Could not evaluate contents of __all__.'
-                           '\bThe value was %s. The exception was:\n%s'
-                           % (all_content, e))
+                           '\bThe value was {0}. The exception was:\n{1}'
+                           .format(all_content, e))
 
     def parse_module(self):
         """Parse a module (and its children) and return a Module object."""
@@ -410,7 +419,7 @@ def parse_module(self):
         if self.filename.endswith('__init__.py'):
             cls = Package
         module = cls(self.filename, self.source, start, end,
-                     [], docstring, children, None, self.all)
+                     [], docstring, children, None, self.all, None, '')
         for child in module.children:
             child.parent = module
         module.future_imports = self.future_imports
@@ -440,6 +449,7 @@ def parse_definition(self, class_):
         else:
             self.consume(tk.OP)
         if self.current.kind in (tk.NEWLINE, tk.COMMENT):
+            skipped_error_codes = self.parse_skip_comment()
             self.leapfrog(tk.INDENT)
             assert self.current.kind != tk.INDENT
             docstring = self.parse_docstring()
@@ -451,20 +461,33 @@ def parse_definition(self, class_):
                            name)
             end = self.line - 1
         else:  # one-liner definition
+            skipped_error_codes = ''
             docstring = self.parse_docstring()
             decorators = []  # TODO
             children = []
             end = self.line
             self.leapfrog(tk.NEWLINE)
         definition = class_(name, self.source, start, end,
-                            decorators, docstring, children, None)
+                            decorators, docstring, children, None,
+                            skipped_error_codes)
         for child in definition.children:
             child.parent = definition
         self.log.debug("finished parsing %s '%s'. Next token is %r (%s)",
                        class_.__name__, name, self.current.kind,
                        self.current.value)
         return definition
 
+    def parse_skip_comment(self):
+        """Parse a definition comment for noqa skips."""
+        skipped_error_codes = ''
+        if self.current.kind == tk.COMMENT:
+            if 'noqa: ' in self.current.value:
+                skipped_error_codes = ''.join(
+                     self.current.value.split('noqa: ')[1:])
+            elif self.current.value.startswith('# noqa'):
+                skipped_error_codes = 'all'
+        return skipped_error_codes
+
     def check_current(self, kind=None, value=None):
         """Verify the current token is of type `kind` and equals `value`."""
         msg = textwrap.dedent("""

src/pydocstyle/tests/test_cases/test.py

@@ -339,5 +339,28 @@ def inner_function():
         """Do inner something."""
         return 0
 
+
+@expect("D400: First line should end with a period (not 'g')")
+@expect("D401: First line should be in imperative mood ('Run', not 'Runs')")
+def docstring_bad():
+    """Runs something"""
+    pass
+
+
+def docstring_bad_ignore_all():  # noqa
+    """Runs something"""
+    pass
+
+
+def docstring_bad_ignore_one():  # noqa: D400,D401
+    """Runs something"""
+    pass
+
+
+@expect("D401: First line should be in imperative mood ('Run', not 'Runs')")
+def docstring_ignore_violations_of_pydocstyle_D400_and_PEP8_E501_but_catch_D401():  # noqa: E501,D400
+    """Runs something"""
+    pass
+
 expect(__file__ if __file__[-1] != 'c' else __file__[:-1],
        'D100: Missing docstring in public module')

src/pydocstyle/tests/test_decorators.py

@@ -166,13 +166,14 @@ def %s(self):
         """ % (name))
 
         module = parser.Module('module_name', source, 0, 1, [],
-                               'Docstring for module', [], None, all)
+                               'Docstring for module', [], None,
+                               all, None, '')
 
         cls = parser.Class('ClassName', source, 0, 1, [],
-                           'Docstring for class', children, module, all)
+                           'Docstring for class', children, module, '')
 
         return parser.Method(name, source, 0, 1, [],
-                             'Docstring for method', children, cls, all)
+                             'Docstring for method', children, cls, '')
 
     def test_is_public_normal(self):
         """Test that methods are normally public, even if decorated."""

src/pydocstyle/tests/test_definitions.py

@@ -140,41 +140,41 @@ def test_parser():
     module = parse(StringIO(source), 'file.py')
     assert len(list(module)) == 8
     assert Module('file.py', _, 1, len(source.split('\n')),
-                  _, '"""Module."""', _, _, dunder_all, {}) == \
+                  _, '"""Module."""', _, _, dunder_all, {}, '') == \
         module
 
     function, class_ = module.children
     assert Function('function', _, _, _, _, '"Function."', _,
-                    module) == function
-    assert Class('class_', _, _, _, _, '"""Class."""', _, module) == class_
+                    module, '') == function
+    assert Class('class_', _, _, _, _, '"""Class."""', _, module, '') == class_
 
     nested_1, nested_2 = function.children
     assert NestedFunction('nested_1', _, _, _, _,
-                          '"""Nested."""', _, function) == nested_1
+                          '"""Nested."""', _, function, '') == nested_1
     assert NestedFunction('nested_2', _, _, _, _, None, _,
-                          function) == nested_2
+                          function, '') == nested_2
     assert nested_1.is_public is False
 
     method_1, method_2 = class_.children
     assert method_1.parent == method_2.parent == class_
     assert Method('method_1', _, _, _, _, '"""Method."""', _,
-                  class_) == method_1
-    assert Method('method_2', _, _, _, _, None, _, class_) == method_2
+                  class_, '') == method_1
+    assert Method('method_2', _, _, _, _, None, _, class_, '') == method_2
 
     nested_3, = method_2.children
     assert NestedFunction('nested_3', _, _, _, _,
-                          '"""Nested."""', _, method_2) == nested_3
+                          '"""Nested."""', _, method_2, '') == nested_3
     assert nested_3.module == module
     assert nested_3.all == dunder_all
 
     module = parse(StringIO(source_alt), 'file_alt.py')
     assert Module('file_alt.py', _, 1, len(source_alt.split('\n')),
-                  _, None, _, _, dunder_all, {}) == module
+                  _, None, _, _, dunder_all, {}, '') == module
 
     module = parse(StringIO(source_alt_nl_at_bracket), 'file_alt_nl.py')
     assert Module('file_alt_nl.py', _, 1,
                   len(source_alt_nl_at_bracket.split('\n')), _, None, _, _,
-                  dunder_all, {}) == module
+                  dunder_all, {}, '') == module
 
     with pytest.raises(AllError):
         parse(StringIO(source_complex_all), 'file_complex_all.py')
@@ -193,7 +193,7 @@ def test_import_parser():
 
         assert Module('file_ucl{0}.py'.format(i), _, 1,
                       _, _, None, _, _,
-                      _, {'unicode_literals': True}) == module
+                      _, {'unicode_literals': True}, '') == module
         assert module.future_imports['unicode_literals']
 
     for i, source_mfi in enumerate((
@@ -208,8 +208,8 @@ def test_import_parser():
         module = parse(StringIO(source_mfi), 'file_mfi{0}.py'.format(i))
         assert Module('file_mfi{0}.py'.format(i), _, 1,
                       _, _, None, _, _,
-                      _, {'unicode_literals': True, 'nested_scopes': True}) \
-            == module
+                      _, {'unicode_literals': True, 'nested_scopes': True},
+                      '') == module
         assert module.future_imports['unicode_literals']
 
     # These are invalid syntax, so there is no need to verify the result
@@ -227,7 +227,7 @@ def test_import_parser():
 
         assert Module('file_invalid{0}.py'.format(i), _, 1,
                       _, _, None, _, _,
-                      _, _) == module
+                      _, _, '') == module
 
 
 def _test_module():