Exempt properties from D401 (#546)

* Exempt properties from D401 * Add test and release note * Add property_decorators configuration option * Fix failing test * Clarify Function is_overload and is_property * Fix crash * Fix typo * Fix test * Also count functools.cached_property as property * Add cached_property tests * Make line less then 80 characters long * Blacken * Revert "Add cached_property tests" This reverts commit caf8f42. * Update docs/release_notes.rst Co-authored-by: Sambhav Kothari <sambhavs.email@gmail.com>

Author: TomFryers

docs/release_notes.rst

@@ -8,6 +8,9 @@ Release Notes
 Current Development Version
 ---------------------------
 
+New Features
+
+* Add support for `property_decorators` config to ignore D401
 
 6.1.1 - May 17th, 2021
 ---------------------------

docs/snippets/config.rst

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

src/pydocstyle/checker.py

@@ -131,8 +131,12 @@ def check_source(
  source,
  filename,
  ignore_decorators=None,
+ property_decorators=None,
  ignore_inline_noqa=False,
  ):
+ self.property_decorators = (
+ {} if property_decorators is None else property_decorators
+ )
  module = parse(StringIO(source), filename)
  for definition in module:
  for this_check in self.checks:
@@ -500,7 +504,11 @@ def check_imperative_mood(self, function, docstring): # def context
  "Returns the pathname ...".
 
  """
- if docstring and not function.is_test:
+ if (
+ docstring
+ and not function.is_test
+ and not function.is_property(self.property_decorators)
+ ):
  stripped = ast.literal_eval(docstring).strip()
  if stripped:
  first_word = strip_non_alphanumeric(stripped.split()[0])
@@ -1040,6 +1048,7 @@ def check(
  select=None,
  ignore=None,
  ignore_decorators=None,
+ property_decorators=None,
  ignore_inline_noqa=False,
 ):
  """Generate docstring errors that exist in `filenames` iterable.
@@ -1092,7 +1101,11 @@ def check(
  with tk.open(filename) as file:
  source = file.read()
  for error in ConventionChecker().check_source(
- source, filename, ignore_decorators, ignore_inline_noqa
+ source,
+ filename,
+ ignore_decorators,
+ property_decorators,
+ ignore_inline_noqa,
  ):
  code = getattr(error, 'code', None)
  if code in checked_codes:

src/pydocstyle/cli.py

@@ -42,12 +42,14 @@ def run_pydocstyle():
  filename,
  checked_codes,
  ignore_decorators,
+ property_decorators,
  ) in conf.get_files_to_check():
  errors.extend(
  check(
  (filename,),
  select=checked_codes,
  ignore_decorators=ignore_decorators,
+ property_decorators=property_decorators,
  )
  )
  except IllegalConfiguration as error:

src/pydocstyle/config.py

@@ -186,6 +186,9 @@ class ConfigurationParser:
  DEFAULT_MATCH_RE = r'(?!test_).*\.py'
  DEFAULT_MATCH_DIR_RE = r'[^\.].*'
  DEFAULT_IGNORE_DECORATORS_RE = ''
+ DEFAULT_PROPERTY_DECORATORS = (
+ "property,cached_property,functools.cached_property"
+ )
  DEFAULT_CONVENTION = conventions.pep257
 
  PROJECT_CONFIG_FILES = (
@@ -266,12 +269,21 @@ def _get_ignore_decorators(conf):
  re(conf.ignore_decorators) if conf.ignore_decorators else None
  )
 
+ def _get_property_decorators(conf):
+ """Return the `property_decorators` as None or set."""
+ return (
+ set(conf.property_decorators.split(","))
+ if conf.property_decorators
+ else None
+ )
+
  for name in self._arguments:
  if os.path.isdir(name):
  for root, dirs, filenames in os.walk(name):
  config = self._get_config(os.path.abspath(root))
  match, match_dir = _get_matches(config)
  ignore_decorators = _get_ignore_decorators(config)
+ property_decorators = _get_property_decorators(config)
 
  # Skip any dirs that do not match match_dir
  dirs[:] = [d for d in dirs if match_dir(d)]
@@ -283,13 +295,20 @@ def _get_ignore_decorators(conf):
  full_path,
  list(config.checked_codes),
  ignore_decorators,
+ property_decorators,
  )
  else:
  config = self._get_config(os.path.abspath(name))
  match, _ = _get_matches(config)
  ignore_decorators = _get_ignore_decorators(config)
+ property_decorators = _get_property_decorators(config)
  if match(name):
- yield (name, list(config.checked_codes), ignore_decorators)
+ yield (
+ name,
+ list(config.checked_codes),
+ ignore_decorators,
+ property_decorators,
+ )
 
  # --------------------------- Private Methods -----------------------------
 
@@ -485,7 +504,12 @@ def _merge_configuration(self, parent_config, child_options):
  self._set_add_options(error_codes, child_options)
 
  kwargs = dict(checked_codes=error_codes)
- for key in ('match', 'match_dir', 'ignore_decorators'):
+ for key in (
+ 'match',
+ 'match_dir',
+ 'ignore_decorators',
+ 'property_decorators',
+ ):
  kwargs[key] = getattr(child_options, key) or getattr(
  parent_config, key
  )
@@ -519,9 +543,15 @@ def _create_check_config(cls, options, use_defaults=True):
  checked_codes = cls._get_checked_errors(options)
 
  kwargs = dict(checked_codes=checked_codes)
- for key in ('match', 'match_dir', 'ignore_decorators'):
+ defaults = {
+ 'match': "MATCH_RE",
+ 'match_dir': "MATCH_DIR_RE",
+ 'ignore_decorators': "IGNORE_DECORATORS_RE",
+ 'property_decorators': "PROPERTY_DECORATORS",
+ }
+ for key, default in defaults.items():
  kwargs[key] = (
- getattr(cls, f'DEFAULT_{key.upper()}_RE')
+ getattr(cls, f"DEFAULT_{default}")
  if getattr(options, key) is None and use_defaults
  else getattr(options, key)
  )
@@ -855,14 +885,33 @@ def _create_option_parser(cls):
  )
  ),
  )
+ option(
+ '--property-decorators',
+ metavar='<property-decorators>',
+ default=None,
+ help=(
+ "consider any method decorated with one of these "
+ "decorators as a property, and consequently allow "
+ "a docstring which is not in imperative mood; default "
+ "is --property-decorators='{}'".format(
+ cls.DEFAULT_PROPERTY_DECORATORS
+ )
+ ),
+ )
 
  return parser
 
 
 # Check configuration - used by the ConfigurationParser class.
 CheckConfiguration = namedtuple(
  'CheckConfiguration',
- ('checked_codes', 'match', 'match_dir', 'ignore_decorators'),
+ (
+ 'checked_codes',
+ 'match',
+ 'match_dir',
+ 'ignore_decorators',
+ 'property_decorators',
+ ),
 )
 
 

src/pydocstyle/parser.py

@@ -213,10 +213,16 @@ def is_public(self):
  @property
  def is_overload(self):
  """Return True iff the method decorated with overload."""
- for decorator in self.decorators:
- if decorator.name == "overload":
- return True
- return False
+ return any(
+ decorator.name == "overload" for decorator in self.decorators
+ )
+
+ def is_property(self, property_decorator_names):
+ """Return True if the method is decorated with any property decorator."""
+ return any(
+ decorator.name in property_decorator_names
+ for decorator in self.decorators
+ )
 
  @property
  def is_test(self):

src/tests/test_cases/test.py

@@ -42,6 +42,11 @@ def overloaded_method(a):
  "D418: Function/ Method decorated with @overload"
  " shouldn't contain a docstring")
 
+ @property
+ def foo(self):
+ """The foo of the thing, which isn't in imperitive mood."""
+ return "hello"
+
  @expect('D102: Missing docstring in public method')
  def __new__(self=None):
  pass

src/tests/test_definitions.py

@@ -5,6 +5,9 @@
 import pytest
 from pydocstyle.violations import Error, ErrorRegistry
 from pydocstyle.checker import check
+from pydocstyle.config import ConfigurationParser
+
+DEFAULT_PROPERTY_DECORATORS = ConfigurationParser.DEFAULT_PROPERTY_DECORATORS
 
 
 @pytest.mark.parametrize('test_case', [
@@ -35,10 +38,14 @@ def test_complex_file(test_case):
  test_case_file = os.path.join(test_case_dir,
  'test_cases',
  test_case + '.py')
- results = list(check([test_case_file],
- select=set(ErrorRegistry.get_error_codes()),
- ignore_decorators=re.compile(
- 'wraps|ignored_decorator')))
+ results = list(
+ check(
+ [test_case_file],
+ select=set(ErrorRegistry.get_error_codes()),
+ ignore_decorators=re.compile('wraps|ignored_decorator'),
+ property_decorators=DEFAULT_PROPERTY_DECORATORS,
+ )
+ )
  for error in results:
  assert isinstance(error, Error)
  results = {(e.definition.name, e.message) for e in results}