Merge pull request #204 from Eric89GXL/skip-dec

Allow skipping decorated functions

Author: Nurdok

docs/release_notes.rst

@@ -10,6 +10,7 @@ Current Development Version
 Major Updates
 
 * Support for Python 2.6 has been dropped (#206, #217).
+* Decorator-based skipping via ``--ignore-decorators`` has been added (#204).
 
 Bug Fixes
 

docs/snippets/cli.rst

@@ -36,6 +36,11 @@ Usage
                             search only dirs that exactly match <pattern> regular
                             expression; default is --match-dir='[^\.].*', which
                             matches all dirs that don't start with a dot
+      --ignore-decorators=<decorators>
+                            ignore any functions or methods that are decorated by
+                            a function with a name fitting the <decorators>
+                            regular expression; default is --ignore-decorators=''
+                            which does not ignore any decorated functions.
 
 
 Return Code

docs/snippets/config.rst

@@ -32,6 +32,7 @@ Available options are:
 * ``add_ignore``
 * ``match``
 * ``match_dir``
+* ``ignore_decorators``
 
 See the :ref:`cli_usage` section for more information.
 

src/pydocstyle/checker.py

@@ -9,8 +9,8 @@
 
 from . import violations
 from .config import IllegalConfiguration
-# TODO: handle
-from .parser import *
+from .parser import (Package, Module, Class, NestedClass, Definition, AllError,
+                     Method, Function, NestedFunction, Parser, StringIO)
 from .utils import log, is_blank
 
 
@@ -43,36 +43,41 @@ class PEP257Checker(object):
 
     """
 
-    def check_source(self, source, filename):
+    def check_source(self, source, filename, ignore_decorators):
         module = parse(StringIO(source), filename)
         for definition in module:
-            for check in self.checks:
+            for this_check in self.checks:
                 terminate = False
-                if isinstance(definition, check._check_for):
-                    if definition.skipped_error_codes != 'all':
-                        error = check(None, definition, definition.docstring)
+                if isinstance(definition, this_check._check_for):
+                    skipping_all = (definition.skipped_error_codes == 'all')
+                    decorator_skip = ignore_decorators is not None and any(
+                        len(ignore_decorators.findall(dec.name)) > 0
+                        for dec in definition.decorators)
+                    if not skipping_all and not decorator_skip:
+                        error = this_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 and error.code not in \
                                 definition.skipped_error_codes:
-                            partition = check.__doc__.partition('.\n')
+                            partition = this_check.__doc__.partition('.\n')
                             message, _, explanation = partition
                             error.set_context(explanation=explanation,
                                               definition=definition)
                             yield error
-                            if check._terminal:
+                            if this_check._terminal:
                                 terminate = True
                                 break
                 if terminate:
                     break
 
     @property
     def checks(self):
-        all = [check for check in vars(type(self)).values()
-               if hasattr(check, '_check_for')]
-        return sorted(all, key=lambda check: not check._terminal)
+        all = [this_check for this_check in vars(type(self)).values()
+               if hasattr(this_check, '_check_for')]
+        return sorted(all, key=lambda this_check: not this_check._terminal)
 
     @check_for(Definition, terminal=True)
     def check_docstring_missing(self, definition, docstring):
@@ -387,7 +392,7 @@ def check_starts_with_this(self, function, docstring):
 parse = Parser()
 
 
-def check(filenames, select=None, ignore=None):
+def check(filenames, select=None, ignore=None, ignore_decorators=None):
     """Generate docstring errors that exist in `filenames` iterable.
 
     By default, the PEP-257 convention is checked. To specifically define the
@@ -432,7 +437,8 @@ def check(filenames, select=None, ignore=None):
         try:
             with tokenize_open(filename) as file:
                 source = file.read()
-            for error in PEP257Checker().check_source(source, filename):
+            for error in PEP257Checker().check_source(source, filename,
+                                                      ignore_decorators):
                 code = getattr(error, 'code', None)
                 if code in checked_codes:
                     yield error

src/pydocstyle/cli.py

@@ -45,8 +45,10 @@ def run_pydocstyle(use_pep257=False):
 
     errors = []
     try:
-        for filename, checked_codes in conf.get_files_to_check():
-            errors.extend(check((filename,), select=checked_codes))
+        for filename, checked_codes, ignore_decorators in \
+                conf.get_files_to_check():
+            errors.extend(check((filename,), select=checked_codes,
+                                ignore_decorators=ignore_decorators))
     except IllegalConfiguration:
         # An illegal configuration file was found during file generation.
         return ReturnCode.invalid_options

src/pydocstyle/config.py

@@ -64,11 +64,13 @@ class ConfigurationParser(object):
     """
 
     CONFIG_FILE_OPTIONS = ('convention', 'select', 'ignore', 'add-select',
-                           'add-ignore', 'match', 'match-dir')
+                           'add-ignore', 'match', 'match-dir',
+                           'ignore-decorators')
     BASE_ERROR_SELECTION_OPTIONS = ('ignore', 'select', 'convention')
 
     DEFAULT_MATCH_RE = '(?!test_).*\.py'
     DEFAULT_MATCH_DIR_RE = '[^\.].*'
+    DEFAULT_IGNORE_DECORATORS_RE = ''
     DEFAULT_CONVENTION = conventions.pep257
 
     PROJECT_CONFIG_FILES = (
@@ -112,7 +114,7 @@ def parse(self):
 
         self._run_conf = self._create_run_config(self._options)
 
-        config = self._create_check_config(self._options, use_dafaults=False)
+        config = self._create_check_config(self._options, use_defaults=False)
         self._override_by_cli = config
 
     @check_initialized
@@ -139,31 +141,42 @@ def _get_matches(config):
             match_dir_func = re(config.match_dir + '$').match
             return match_func, match_dir_func
 
+        def _get_ignore_decorators(config):
+            """Return the `ignore_decorators` as None or regex."""
+            if config.ignore_decorators:  # not None and not ''
+                ignore_decorators = re(config.ignore_decorators)
+            else:
+                ignore_decorators = None
+            return ignore_decorators
+
         for name in self._arguments:
             if os.path.isdir(name):
                 for root, dirs, filenames in os.walk(name):
                     config = self._get_config(root)
                     match, match_dir = _get_matches(config)
+                    ignore_decorators = _get_ignore_decorators(config)
 
                     # Skip any dirs that do not match match_dir
                     dirs[:] = [dir for dir in dirs if match_dir(dir)]
 
                     for filename in filenames:
                         if match(filename):
                             full_path = os.path.join(root, filename)
-                            yield full_path, list(config.checked_codes)
+                            yield (full_path, list(config.checked_codes),
+                                   ignore_decorators)
             else:
                 config = self._get_config(name)
                 match, _ = _get_matches(config)
+                ignore_decorators = _get_ignore_decorators(config)
                 if match(name):
-                    yield name, list(config.checked_codes)
+                    yield (name, list(config.checked_codes), ignore_decorators)
 
     # --------------------------- Private Methods -----------------------------
 
     def _get_config(self, node):
         """Get and cache the run configuration for `node`.
 
-        If no configuration exists (not local and not for the parend node),
+        If no configuration exists (not local and not for the parent node),
         returns and caches a default configuration.
 
         The algorithm:
@@ -298,14 +311,11 @@ def _merge_configuration(self, parent_config, child_options):
 
         self._set_add_options(error_codes, child_options)
 
-        match = child_options.match \
-            if child_options.match is not None else parent_config.match
-        match_dir = child_options.match_dir \
-            if child_options.match_dir is not None else parent_config.match_dir
-
-        return CheckConfiguration(checked_codes=error_codes,
-                                  match=match,
-                                  match_dir=match_dir)
+        kwargs = dict(checked_codes=error_codes)
+        for key in ('match', 'match_dir', 'ignore_decorators'):
+            kwargs[key] = \
+                getattr(child_options, key) or getattr(parent_config, key)
+        return CheckConfiguration(**kwargs)
 
     def _parse_args(self, args=None, values=None):
         """Parse the options using `self._parser` and reformat the options."""
@@ -320,29 +330,25 @@ def _create_run_config(options):
         return RunConfiguration(**values)
 
     @classmethod
-    def _create_check_config(cls, options, use_dafaults=True):
+    def _create_check_config(cls, options, use_defaults=True):
         """Create a `CheckConfiguration` object from `options`.
 
-        If `use_dafaults`, any of the match options that are `None` will
+        If `use_defaults`, any of the match options that are `None` will
         be replaced with their default value and the default convention will be
         set for the checked codes.
 
         """
-        match = cls.DEFAULT_MATCH_RE \
-            if options.match is None and use_dafaults \
-            else options.match
-
-        match_dir = cls.DEFAULT_MATCH_DIR_RE \
-            if options.match_dir is None and use_dafaults \
-            else options.match_dir
-
         checked_codes = None
 
-        if cls._has_exclusive_option(options) or use_dafaults:
+        if cls._has_exclusive_option(options) or use_defaults:
             checked_codes = cls._get_checked_errors(options)
 
-        return CheckConfiguration(checked_codes=checked_codes,
-                                  match=match, match_dir=match_dir)
+        kwargs = dict(checked_codes=checked_codes)
+        for key in ('match', 'match_dir', 'ignore_decorators'):
+            kwargs[key] = getattr(cls, 'DEFAULT_{0}_RE'.format(key.upper())) \
+                if getattr(options, key) is None and use_defaults \
+                else getattr(options, key)
+        return CheckConfiguration(**kwargs)
 
     @classmethod
     def _get_section_name(cls, parser):
@@ -518,12 +524,20 @@ def _create_option_parser(cls):
                      "matches all dirs that don't start with "
                      "a dot").format(cls.DEFAULT_MATCH_DIR_RE))
 
+        # Decorators
+        option('--ignore-decorators', metavar='<decorators>', default=None,
+               help=("ignore any functions or methods that are decorated "
+                     "by a function with a name fitting the <decorators> "
+                     "regular expression; default is --ignore-decorators='{0}'"
+                     " which does not ignore any decorated functions."
+                     .format(cls.DEFAULT_IGNORE_DECORATORS_RE)))
         return parser
 
 
 # Check configuration - used by the ConfigurationParser class.
 CheckConfiguration = namedtuple('CheckConfiguration',
-                                ('checked_codes', 'match', 'match_dir'))
+                                ('checked_codes', 'match', 'match_dir',
+                                 'ignore_decorators'))
 
 
 class IllegalConfiguration(Exception):

src/tests/test_cases/test.py

@@ -1,5 +1,6 @@
 # encoding: utf-8
 # No docstring, so we can test D100
+from functools import wraps
 import os
 import sys
 from .expected import Expectation
@@ -363,5 +364,11 @@ def docstring_ignore_violations_of_pydocstyle_D400_and_PEP8_E501_but_catch_D401(
     """Runs something"""
     pass
 
+
+@wraps(docstring_bad_ignore_one)
+def bad_decorated_function():
+    """Bad (E501) but decorated"""
+    pass
+
 expect(os.path.normcase(__file__ if __file__[-1] != 'c' else __file__[:-1]),
        'D100: Missing docstring in public module')

src/tests/test_definitions.py

@@ -1,6 +1,7 @@
 """Old parser tests."""
 
 import os
+import re
 import pytest
 from pydocstyle.violations import Error, ErrorRegistry
 from pydocstyle.checker import check
@@ -288,7 +289,8 @@ def test_pep257(test_case):
                                   'test_cases',
                                   test_case + '.py')
     results = list(check([test_case_file],
-                         select=set(ErrorRegistry.get_error_codes())))
+                         select=set(ErrorRegistry.get_error_codes()),
+                         ignore_decorators=re.compile('wraps')))
     for error in results:
         assert isinstance(error, Error)
     results = set([(e.definition.name, e.message) for e in results])