Test cases for canonical examples of conventions (#429)

* Test cases for canonical examples of conventions

This change adds test cases for the examples from the official docs of
each of the three default conventions:

* google: the "3.8.2 Modules", "3.8.3 Functions and Methods", and
  "3.8.4 Classes" examples from the
  [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html)
* numpy: the content of the "example.py" file from the "Example" page of
  the [numpydoc manual](https://numpydoc.readthedocs.io/)
* pep257: the "One-line Docstrings" and "Multi-line Docstrings" examples
  from the
  [PEP 257 -- Docstring Conventions](https://www.python.org/dev/peps/pep-0257/)
  specification

These test cases help validate which existing errors should be excluded
from each of the default conventions, and will help identify new errors
or changes to existing errors in the future that should be excluded from
the default conventions.

* Use normcase to fix test failures on windows

Author: justinludwig

src/tests/test_cases/canonical_google_examples.py

@@ -0,0 +1,108 @@
+"""A one line summary of the module or program, terminated by a period.
+
+Leave one blank line.  The rest of this docstring should contain an
+overall description of the module or program.  Optionally, it may also
+contain a brief description of exported classes and functions and/or usage
+examples.
+
+  Typical usage example:
+
+  foo = ClassFoo()
+  bar = foo.FunctionBar()
+"""
+# above: "2.8.2 Modules" section example
+# https://google.github.io/styleguide/pyguide.html#382-modules
+
+# Examples from the official "Google Python Style Guide" documentation:
+#     * As HTML: https://google.github.io/styleguide/pyguide.html
+#     * Source Markdown:
+#         https://github.com/google/styleguide/blob/gh-pages/pyguide.md
+
+import os
+from .expected import Expectation
+
+expectation = Expectation()
+expect = expectation.expect
+
+# module docstring expected violations:
+expectation.expected.add((
+    os.path.normcase(__file__),
+    "D213: Multi-line docstring summary should start at the second line"))
+
+
+# "3.8.3 Functions and Methods" section example
+# https://google.github.io/styleguide/pyguide.html#383-functions-and-methods
+@expect("D213: Multi-line docstring summary should start at the second line",
+        arg_count=3)
+@expect("D401: First line should be in imperative mood "
+        "(perhaps 'Fetch', not 'Fetches')", arg_count=3)
+@expect("D406: Section name should end with a newline "
+        "('Raises', not 'Raises:')", arg_count=3)
+@expect("D406: Section name should end with a newline "
+        "('Returns', not 'Returns:')", arg_count=3)
+@expect("D407: Missing dashed underline after section ('Raises')", arg_count=3)
+@expect("D407: Missing dashed underline after section ('Returns')",
+        arg_count=3)
+@expect("D413: Missing blank line after last section ('Raises')", arg_count=3)
+def fetch_bigtable_rows(big_table, keys, other_silly_variable=None):
+    """Fetches rows from a Bigtable.
+
+    Retrieves rows pertaining to the given keys from the Table instance
+    represented by big_table.  Silly things may happen if
+    other_silly_variable is not None.
+
+    Args:
+        big_table: An open Bigtable Table instance.
+        keys: A sequence of strings representing the key of each table row
+            to fetch.
+        other_silly_variable: Another optional variable, that has a much
+            longer name than the other args, and which does nothing.
+
+    Returns:
+        A dict mapping keys to the corresponding table row data
+        fetched. Each row is represented as a tuple of strings. For
+        example:
+
+        {'Serak': ('Rigel VII', 'Preparer'),
+         'Zim': ('Irk', 'Invader'),
+         'Lrrr': ('Omicron Persei 8', 'Emperor')}
+
+        If a key from the keys argument is missing from the dictionary,
+        then that row was not found in the table.
+
+    Raises:
+        IOError: An error occurred accessing the bigtable.Table object.
+    """
+
+
+# "3.8.4 Classes" section example
+# https://google.github.io/styleguide/pyguide.html#384-classes
+@expect("D203: 1 blank line required before class docstring (found 0)")
+@expect("D213: Multi-line docstring summary should start at the second line")
+@expect("D406: Section name should end with a newline "
+        "('Attributes', not 'Attributes:')")
+@expect("D407: Missing dashed underline after section ('Attributes')")
+@expect("D413: Missing blank line after last section ('Attributes')")
+class SampleClass(object):
+    """Summary of class here.
+
+    Longer class information....
+    Longer class information....
+
+    Attributes:
+        likes_spam: A boolean indicating if we like SPAM or not.
+        eggs: An integer count of the eggs we have laid.
+    """
+
+    @expect("D401: First line should be in imperative mood "
+            "(perhaps 'Init', not 'Inits')", arg_count=2)
+    def __init__(self, likes_spam=False):
+        """Inits SampleClass with blah."""
+        if self:  # added to avoid NameError when run via @expect decorator
+            self.likes_spam = likes_spam
+            self.eggs = 0
+
+    @expect("D401: First line should be in imperative mood "
+            "(perhaps 'Perform', not 'Performs')", arg_count=1)
+    def public_method(self):
+        """Performs operation blah."""

src/tests/test_cases/canonical_numpy_examples.py

@@ -0,0 +1,163 @@
+"""This is the docstring for the example.py module.  Modules names should
+have short, all-lowercase names.  The module name may have underscores if
+this improves readability.
+
+Every module should have a docstring at the very top of the file.  The
+module's docstring may extend over multiple lines.  If your docstring does
+extend over multiple lines, the closing three quotation marks must be on
+a line by itself, preferably preceded by a blank line.
+
+"""
+
+# Example source file from the official "numpydoc docstring guide"
+# documentation (with the modification of commenting out all the original
+# ``import`` lines, plus adding this note and ``Expectation`` code):
+#     * As HTML: https://numpydoc.readthedocs.io/en/latest/example.html
+#     * Source Python:
+#         https://github.com/numpy/numpydoc/blob/master/doc/example.py
+
+# from __future__ import division, absolute_import, print_function
+#
+# import os  # standard library imports first
+#
+# Do NOT import using *, e.g. from numpy import *
+#
+# Import the module using
+#
+#   import numpy
+#
+# instead or import individual functions as needed, e.g
+#
+#  from numpy import array, zeros
+#
+# If you prefer the use of abbreviated module names, we suggest the
+# convention used by NumPy itself::
+#
+# import numpy as np
+# import matplotlib as mpl
+# import matplotlib.pyplot as plt
+#
+# These abbreviated names are not to be used in docstrings; users must
+# be able to paste and execute docstrings after importing only the
+# numpy module itself, unabbreviated.
+
+import os
+from .expected import Expectation
+
+expectation = Expectation()
+expect = expectation.expect
+
+# module docstring expected violations:
+expectation.expected.add((
+    os.path.normcase(__file__),
+    "D205: 1 blank line required between summary line and description "
+    "(found 0)"))
+expectation.expected.add((
+    os.path.normcase(__file__),
+    "D213: Multi-line docstring summary should start at the second line"))
+expectation.expected.add((
+    os.path.normcase(__file__),
+    "D400: First line should end with a period (not 'd')"))
+expectation.expected.add((
+    os.path.normcase(__file__),
+    "D404: First word of the docstring should not be `This`"))
+expectation.expected.add((
+    os.path.normcase(__file__),
+    "D415: First line should end with a period, question mark, or exclamation "
+    "point (not 'd')"))
+
+
+@expect("D213: Multi-line docstring summary should start at the second line",
+        arg_count=3)
+@expect("D401: First line should be in imperative mood; try rephrasing "
+        "(found 'A')", arg_count=3)
+@expect("D413: Missing blank line after last section ('Examples')",
+        arg_count=3)
+def foo(var1, var2, long_var_name='hi'):
+    r"""A one-line summary that does not use variable names.
+
+    Several sentences providing an extended description. Refer to
+    variables using back-ticks, e.g. `var`.
+
+    Parameters
+    ----------
+    var1 : array_like
+        Array_like means all those objects -- lists, nested lists, etc. --
+        that can be converted to an array.  We can also refer to
+        variables like `var1`.
+    var2 : int
+        The type above can either refer to an actual Python type
+        (e.g. ``int``), or describe the type of the variable in more
+        detail, e.g. ``(N,) ndarray`` or ``array_like``.
+    long_var_name : {'hi', 'ho'}, optional
+        Choices in brackets, default first when optional.
+
+    Returns
+    -------
+    type
+        Explanation of anonymous return value of type ``type``.
+    describe : type
+        Explanation of return value named `describe`.
+    out : type
+        Explanation of `out`.
+    type_without_description
+
+    Other Parameters
+    ----------------
+    only_seldom_used_keywords : type
+        Explanation
+    common_parameters_listed_above : type
+        Explanation
+
+    Raises
+    ------
+    BadException
+        Because you shouldn't have done that.
+
+    See Also
+    --------
+    numpy.array : Relationship (optional).
+    numpy.ndarray : Relationship (optional), which could be fairly long, in
+                    which case the line wraps here.
+    numpy.dot, numpy.linalg.norm, numpy.eye
+
+    Notes
+    -----
+    Notes about the implementation algorithm (if needed).
+
+    This can have multiple paragraphs.
+
+    You may include some math:
+
+    .. math:: X(e^{j\omega } ) = x(n)e^{ - j\omega n}
+
+    And even use a Greek symbol like :math:`\omega` inline.
+
+    References
+    ----------
+    Cite the relevant literature, e.g. [1]_.  You may also cite these
+    references in the notes section above.
+
+    .. [1] O. McNoleg, "The integration of GIS, remote sensing,
+       expert systems and adaptive co-kriging for environmental habitat
+       modelling of the Highland Haggis using object-oriented, fuzzy-logic
+       and neural-network techniques," Computers & Geosciences, vol. 22,
+       pp. 585-588, 1996.
+
+    Examples
+    --------
+    These are written in doctest format, and should illustrate how to
+    use the function.
+
+    >>> a = [1, 2, 3]
+    >>> print([x + 3 for x in a])
+    [4, 5, 6]
+    >>> print("a\nb")
+    a
+    b
+    """
+    # After closing class docstring, there should be one blank line to
+    # separate following codes (according to PEP257).
+    # But for function, method and module, there should be no blank lines
+    # after closing the docstring.
+    pass

src/tests/test_cases/canonical_pep257_examples.py

@@ -0,0 +1,39 @@
+"""Examples from the pep257 specification."""
+
+# Examples from the official "Python PEP 257 -- Docstring Conventions"
+# documentation:
+#     * As HTML: https://www.python.org/dev/peps/pep-0257
+#     * Source reST: https://github.com/python/peps/blob/master/pep-0257.txt
+
+from .expected import Expectation
+
+expectation = Expectation()
+expect = expectation.expect
+
+
+# "One-line Docstrings" section example
+# https://www.python.org/dev/peps/pep-0257/#id16
+def kos_root():
+    """Return the pathname of the KOS root directory."""
+    global _kos_root
+    if _kos_root:
+        return _kos_root
+
+
+# "Multiline-line Docstrings" section example
+# https://www.python.org/dev/peps/pep-0257/#id17
+@expect("D213: Multi-line docstring summary should start at the second line")
+@expect("D405: Section name should be properly capitalized "
+        "('Keyword Arguments', not 'Keyword arguments')")
+@expect("D407: Missing dashed underline after section ('Keyword Arguments')")
+@expect("D413: Missing blank line after last section ('Keyword Arguments')")
+def complex(real=0.0, imag=0.0):
+    """Form a complex number.
+
+    Keyword arguments:
+    real -- the real part (default 0.0)
+    imag -- the imaginary part (default 0.0)
+    """
+    if imag == 0.0 and real == 0.0:
+        complex_zero = 0  # added to avoid NameError with @expect decorator
+        return complex_zero

src/tests/test_definitions.py

@@ -19,6 +19,9 @@
     'superfluous_quotes',
     'noqa',
     'sections',
+    'canonical_google_examples',
+    'canonical_numpy_examples',
+    'canonical_pep257_examples',
 ])
 def test_complex_file(test_case):
     """Run domain-specific tests from test.py file."""