testing: fix some docstring issues

In preparation for enforcing some docstring lints.

Author: bluetech

doc/en/example/nonpython/conftest.py

@@ -9,7 +9,8 @@ def pytest_collect_file(parent, path):
 
 class YamlFile(pytest.File):
     def collect(self):
-        import yaml  # we need a yaml parser, e.g. PyYAML
+        # We need a yaml parser, e.g. PyYAML.
+        import yaml
 
         raw = yaml.safe_load(self.fspath.open())
         for name, spec in sorted(raw.items()):
@@ -23,12 +24,12 @@ def __init__(self, name, parent, spec):
 
     def runtest(self):
         for name, value in sorted(self.spec.items()):
-            # some custom test execution (dumb example follows)
+            # Some custom test execution (dumb example follows).
             if name != value:
                 raise YamlException(self, name, value)
 
     def repr_failure(self, excinfo):
-        """ called when self.runtest() raises an exception. """
+        """Called when self.runtest() raises an exception."""
         if isinstance(excinfo.value, YamlException):
             return "\n".join(
                 [
@@ -43,4 +44,4 @@ def reportinfo(self):
 
 
 class YamlException(Exception):
-    """ custom exception for error reporting. """
+    """Custom exception for error reporting."""

scripts/release.py

@@ -1,6 +1,4 @@
-"""
-Invoke development tasks.
-"""
+"""Invoke development tasks."""
 import argparse
 import os
 from pathlib import Path

testing/acceptance_test.py

@@ -403,15 +403,12 @@ def pytest_sessionfinish(exitstatus):
         result.stdout.fnmatch_lines(["pytest_sessionfinish_called"])
         assert result.ret == ExitCode.USAGE_ERROR
 
-    @pytest.mark.usefixtures("recwarn")
     def test_namespace_import_doesnt_confuse_import_hook(self, testdir):
-        """
-        Ref #383. Python 3.3's namespace package messed with our import hooks
+        """Ref #383.
+
+        Python 3.3's namespace package messed with our import hooks.
         Importing a module that didn't exist, even if the ImportError was
         gracefully handled, would make our test crash.
-
-        Use recwarn here to silence this warning in Python 2.7:
-            ImportWarning: Not importing directory '...\not_a_package': missing __init__.py
         """
         testdir.mkdir("not_a_package")
         p = testdir.makepyfile(
@@ -457,10 +454,8 @@ def test_foo(invalid_fixture):
         )
 
     def test_plugins_given_as_strings(self, tmpdir, monkeypatch, _sys_snapshot):
-        """test that str values passed to main() as `plugins` arg
-        are interpreted as module names to be imported and registered.
-        #855.
-        """
+        """Test that str values passed to main() as `plugins` arg are
+        interpreted as module names to be imported and registered (#855)."""
         with pytest.raises(ImportError) as excinfo:
             pytest.main([str(tmpdir)], plugins=["invalid.module"])
         assert "invalid" in str(excinfo.value)
@@ -664,8 +659,7 @@ def test_cmdline_python_package(self, testdir, monkeypatch):
         result.stderr.fnmatch_lines(["*not*found*test_missing*"])
 
     def test_cmdline_python_namespace_package(self, testdir, monkeypatch):
-        """
-        test --pyargs option with namespace packages (#1567)
+        """Test --pyargs option with namespace packages (#1567).
 
         Ref: https://packaging.python.org/guides/packaging-namespace-packages/
         """
@@ -1011,9 +1005,7 @@ def test_pytest_plugins_as_module(testdir):
 
 
 def test_deferred_hook_checking(testdir):
-    """
-    Check hooks as late as possible (#1821).
-    """
+    """Check hooks as late as possible (#1821)."""
     testdir.syspathinsert()
     testdir.makepyfile(
         **{
@@ -1089,8 +1081,7 @@ def test2():
 
 
 def test_fixture_order_respects_scope(testdir):
-    """Ensure that fixtures are created according to scope order, regression test for #2405
-    """
+    """Ensure that fixtures are created according to scope order (#2405)."""
     testdir.makepyfile(
         """
         import pytest
@@ -1115,7 +1106,8 @@ def test_value():
 
 
 def test_frame_leak_on_failing_test(testdir):
-    """pytest would leak garbage referencing the frames of tests that failed that could never be reclaimed (#2798)
+    """Pytest would leak garbage referencing the frames of tests that failed
+    that could never be reclaimed (#2798).
 
     Unfortunately it was not possible to remove the actual circles because most of them
     are made of traceback objects which cannot be weakly referenced. Those objects at least

testing/code/test_excinfo.py

@@ -464,7 +464,7 @@ def f(x):
         assert lines[1] == "        pass"
 
     def test_repr_source_excinfo(self) -> None:
-        """ check if indentation is right """
+        """Check if indentation is right."""
         try:
 
             def f():

testing/freeze/create_executable.py

@@ -1,6 +1,4 @@
-"""
-Generates an executable with pytest runner embedded using PyInstaller.
-"""
+"""Generate an executable with pytest runner embedded using PyInstaller."""
 if __name__ == "__main__":
     import pytest
     import subprocess

testing/logging/test_fixture.py

@@ -268,10 +268,10 @@ def test_log_level_override(request, caplog):
 
 
 def test_log_report_captures_according_to_config_option_upon_failure(testdir):
-    """ Test that upon failure:
-    (1) `caplog` succeeded to capture the DEBUG message and assert on it => No `Exception` is raised
-    (2) The `DEBUG` message does NOT appear in the `Captured log call` report
-    (3) The stdout, `INFO`, and `WARNING` messages DO appear in the test reports due to `--log-level=INFO`
+    """Test that upon failure:
+    (1) `caplog` succeeded to capture the DEBUG message and assert on it => No `Exception` is raised.
+    (2) The `DEBUG` message does NOT appear in the `Captured log call` report.
+    (3) The stdout, `INFO`, and `WARNING` messages DO appear in the test reports due to `--log-level=INFO`.
     """
     testdir.makepyfile(
         """

testing/logging/test_reporting.py

@@ -1066,10 +1066,8 @@ def test_second():
 
 
 def test_colored_captured_log(testdir):
-    """
-    Test that the level names of captured log messages of a failing test are
-    colored.
-    """
+    """Test that the level names of captured log messages of a failing test
+    are colored."""
     testdir.makepyfile(
         """
         import logging
@@ -1092,9 +1090,7 @@ def test_foo():
 
 
 def test_colored_ansi_esc_caplogtext(testdir):
-    """
-    Make sure that caplog.text does not contain ANSI escape sequences.
-    """
+    """Make sure that caplog.text does not contain ANSI escape sequences."""
     testdir.makepyfile(
         """
         import logging
@@ -1111,8 +1107,7 @@ def test_foo(caplog):
 
 
 def test_logging_emit_error(testdir: Testdir) -> None:
-    """
-    An exception raised during emit() should fail the test.
+    """An exception raised during emit() should fail the test.
 
     The default behavior of logging is to print "Logging error"
     to stderr with the call stack and some extra details.
@@ -1138,10 +1133,8 @@ def test_bad_log():
 
 
 def test_logging_emit_error_supressed(testdir: Testdir) -> None:
-    """
-    If logging is configured to silently ignore errors, pytest
-    doesn't propagate errors either.
-    """
+    """If logging is configured to silently ignore errors, pytest
+    doesn't propagate errors either."""
     testdir.makepyfile(
         """
         import logging

testing/python/approx.py

@@ -488,9 +488,7 @@ def test_expected_value_type_error(self, x):
         ],
     )
     def test_comparison_operator_type_error(self, op):
-        """
-        pytest.approx should raise TypeError for operators other than == and != (#2003).
-        """
+        """pytest.approx should raise TypeError for operators other than == and != (#2003)."""
         with pytest.raises(TypeError):
             op(1, approx(1, rel=1e-6, abs=1e-12))
 

testing/python/collect.py

@@ -984,8 +984,7 @@ def test_traceback_error_during_import(self, testdir):
         result.stdout.fnmatch_lines([">*asd*", "E*NameError*"])
 
     def test_traceback_filter_error_during_fixture_collection(self, testdir):
-        """integration test for issue #995.
-        """
+        """Integration test for issue #995."""
         testdir.makepyfile(
             """
             import pytest
@@ -1011,8 +1010,9 @@ def test_failing_fixture(fail_fixture):
         result.stdout.fnmatch_lines(["*ValueError: fail me*", "* 1 error in *"])
 
     def test_filter_traceback_generated_code(self) -> None:
-        """test that filter_traceback() works with the fact that
+        """Test that filter_traceback() works with the fact that
         _pytest._code.code.Code.path attribute might return an str object.
+
         In this case, one of the entries on the traceback was produced by
         dynamically generated code.
         See: https://bitbucket.org/pytest-dev/py/issues/71
@@ -1033,8 +1033,9 @@ def test_filter_traceback_generated_code(self) -> None:
         assert not filter_traceback(traceback[-1])
 
     def test_filter_traceback_path_no_longer_valid(self, testdir) -> None:
-        """test that filter_traceback() works with the fact that
+        """Test that filter_traceback() works with the fact that
         _pytest._code.code.Code.path attribute might return an str object.
+
         In this case, one of the files in the traceback no longer exists.
         This fixes #1133.
         """
@@ -1250,8 +1251,7 @@ def test_injection(self):
 
 
 def test_syntax_error_with_non_ascii_chars(testdir):
-    """Fix decoding issue while formatting SyntaxErrors during collection (#578)
-    """
+    """Fix decoding issue while formatting SyntaxErrors during collection (#578)."""
     testdir.makepyfile("☃")
     result = testdir.runpytest()
     result.stdout.fnmatch_lines(["*ERROR collecting*", "*SyntaxError*", "*1 error in*"])

testing/python/fixtures.py

@@ -1684,10 +1684,8 @@ def test_func2(request):
         reprec.assertoutcome(passed=2)
 
     def test_callables_nocode(self, testdir):
-        """
-        an imported mock.call would break setup/factory discovery
-        due to it being callable and __code__ not being a code object
-        """
+        """An imported mock.call would break setup/factory discovery due to
+        it being callable and __code__ not being a code object."""
         testdir.makepyfile(
             """
            class _call(tuple):
@@ -3333,9 +3331,7 @@ def fixture1(self):
         )
 
     def test_show_fixtures_different_files(self, testdir):
-        """
-        #833: --fixtures only shows fixtures from first file
-        """
+        """`--fixtures` only shows fixtures from first file (#833)."""
         testdir.makepyfile(
             test_a='''
             import pytest

testing/python/metafunc.py

@@ -29,9 +29,9 @@
 
 class TestMetafunc:
     def Metafunc(self, func, config=None) -> python.Metafunc:
-        # the unit tests of this class check if things work correctly
+        # The unit tests of this class check if things work correctly
         # on the funcarg level, so we don't need a full blown
-        # initialization
+        # initialization.
         class FuncFixtureInfoMock:
             name2fixturedefs = None
 
@@ -136,7 +136,7 @@ def func(request):
             metafunc.parametrize("request", [1])
 
     def test_find_parametrized_scope(self) -> None:
-        """unittest for _find_parametrized_scope (#3941)"""
+        """Unit test for _find_parametrized_scope (#3941)."""
         from _pytest.python import _find_parametrized_scope
 
         @attr.s
@@ -285,30 +285,29 @@ def test_idval_hypothesis(self, value) -> None:
         escaped.encode("ascii")
 
     def test_unicode_idval(self) -> None:
-        """This tests that Unicode strings outside the ASCII character set get
+        """Test that Unicode strings outside the ASCII character set get
         escaped, using byte escapes if they're in that range or unicode
         escapes if they're not.
 
         """
         values = [
-            ("", ""),
-            ("ascii", "ascii"),
-            ("ação", "a\\xe7\\xe3o"),
-            ("josé@blah.com", "jos\\[email protected]"),
+            ("", r""),
+            ("ascii", r"ascii"),
+            ("ação", r"a\xe7\xe3o"),
+            ("josé@blah.com", r"jos\[email protected]"),
             (
-                "δοκ.ιμή@παράδειγμα.δοκιμή",
-                "\\u03b4\\u03bf\\u03ba.\\u03b9\\u03bc\\u03ae@\\u03c0\\u03b1\\u03c1\\u03ac\\u03b4\\u03b5\\u03b9\\u03b3"
-                "\\u03bc\\u03b1.\\u03b4\\u03bf\\u03ba\\u03b9\\u03bc\\u03ae",
+                r"δοκ.ιμή@παράδειγμα.δοκιμή",
+                r"\u03b4\u03bf\u03ba.\u03b9\u03bc\u03ae@\u03c0\u03b1\u03c1\u03ac\u03b4\u03b5\u03b9\u03b3"
+                r"\u03bc\u03b1.\u03b4\u03bf\u03ba\u03b9\u03bc\u03ae",
             ),
         ]
         for val, expected in values:
             assert _idval(val, "a", 6, None, nodeid=None, config=None) == expected
 
     def test_unicode_idval_with_config(self) -> None:
-        """unittest for expected behavior to obtain ids with
+        """Unit test for expected behavior to obtain ids with
         disable_test_id_escaping_and_forfeit_all_rights_to_community_support
-        option. (#5294)
-        """
+        option (#5294)."""
 
         class MockConfig:
             def __init__(self, config):
@@ -335,25 +334,20 @@ def getini(self, name):
             assert actual == expected
 
     def test_bytes_idval(self) -> None:
-        """unittest for the expected behavior to obtain ids for parametrized
-        bytes values:
-        - python2: non-ascii strings are considered bytes and formatted using
-        "binary escape", where any byte < 127 is escaped into its hex form.
-        - python3: bytes objects are always escaped using "binary escape".
-        """
+        """Unit test for the expected behavior to obtain ids for parametrized
+        bytes values: bytes objects are always escaped using "binary escape"."""
         values = [
-            (b"", ""),
-            (b"\xc3\xb4\xff\xe4", "\\xc3\\xb4\\xff\\xe4"),
-            (b"ascii", "ascii"),
-            ("αρά".encode(), "\\xce\\xb1\\xcf\\x81\\xce\\xac"),
+            (b"", r""),
+            (b"\xc3\xb4\xff\xe4", r"\xc3\xb4\xff\xe4"),
+            (b"ascii", r"ascii"),
+            ("αρά".encode(), r"\xce\xb1\xcf\x81\xce\xac"),
         ]
         for val, expected in values:
             assert _idval(val, "a", 6, idfn=None, nodeid=None, config=None) == expected
 
     def test_class_or_function_idval(self) -> None:
-        """unittest for the expected behavior to obtain ids for parametrized
-        values that are classes or functions: their __name__.
-        """
+        """Unit test for the expected behavior to obtain ids for parametrized
+        values that are classes or functions: their __name__."""
 
         class TestClass:
             pass
@@ -484,9 +478,9 @@ def ids(val: object) -> str:
         assert result == ["a-a0", "a-a1", "a-a2"]
 
     def test_idmaker_with_idfn_and_config(self) -> None:
-        """unittest for expected behavior to create ids with idfn and
+        """Unit test for expected behavior to create ids with idfn and
         disable_test_id_escaping_and_forfeit_all_rights_to_community_support
-        option. (#5294)
+        option (#5294).
         """
 
         class MockConfig:
@@ -516,9 +510,9 @@ def getini(self, name):
             assert result == [expected]
 
     def test_idmaker_with_ids_and_config(self) -> None:
-        """unittest for expected behavior to create ids with ids and
+        """Unit test for expected behavior to create ids with ids and
         disable_test_id_escaping_and_forfeit_all_rights_to_community_support
-        option. (#5294)
+        option (#5294).
         """
 
         class MockConfig:
@@ -1420,9 +1414,8 @@ def test_foo(x):
 
 
 class TestMetafuncFunctionalAuto:
-    """
-    Tests related to automatically find out the correct scope for parametrized tests (#1832).
-    """
+    """Tests related to automatically find out the correct scope for
+    parametrized tests (#1832)."""
 
     def test_parametrize_auto_scope(self, testdir: Testdir) -> None:
         testdir.makepyfile(