Format docstrings in a consistent style

Author: bluetech

doc/en/reference.rst

@@ -182,7 +182,7 @@ Mark a test function as using the given fixture names.
 
 .. py:function:: pytest.mark.usefixtures(*names)
 
-    :param args: the names of the fixture to use, as strings
+    :param args: The names of the fixture to use, as strings.
 
 .. note::
 
@@ -209,8 +209,10 @@ Marks a test function as *expected to fail*.
         Condition for marking the test function as xfail (``True/False`` or a
         :ref:`condition string <string conditions>`). If a bool, you also have
         to specify ``reason`` (see :ref:`condition string <string conditions>`).
-    :keyword str reason: Reason why the test function is marked as xfail.
-    :keyword Exception raises: Exception subclass expected to be raised by the test function; other exceptions will fail the test.
+    :keyword str reason:
+        Reason why the test function is marked as xfail.
+    :keyword Type[Exception] raises:
+        Exception subclass expected to be raised by the test function; other exceptions will fail the test.
     :keyword bool run:
         If the test function should actually be executed. If ``False``, the function will always xfail and will
         not be executed (useful if a function is segfaulting).
@@ -224,7 +226,7 @@ Marks a test function as *expected to fail*.
           a new release of a library fixes a known bug).
 
 
-custom marks
+Custom marks
 ~~~~~~~~~~~~
 
 Marks are created dynamically using the factory object ``pytest.mark`` and applied as a decorator.
@@ -473,7 +475,7 @@ caplog
 .. autofunction:: _pytest.logging.caplog()
     :no-auto-options:
 
-    This returns a :class:`_pytest.logging.LogCaptureFixture` instance.
+    Returns a :class:`_pytest.logging.LogCaptureFixture` instance.
 
 .. autoclass:: _pytest.logging.LogCaptureFixture
     :members:
@@ -491,7 +493,7 @@ monkeypatch
 .. autofunction:: _pytest.monkeypatch.monkeypatch()
     :no-auto-options:
 
-    This returns a :class:`MonkeyPatch` instance.
+    Returns a :class:`MonkeyPatch` instance.
 
 .. autoclass:: _pytest.monkeypatch.MonkeyPatch
     :members:

src/_pytest/_argcomplete.py

@@ -1,7 +1,8 @@
-"""allow bash-completion for argparse with argcomplete if installed
-needs argcomplete>=0.5.6 for python 3.2/3.3 (older versions fail
+"""Allow bash-completion for argparse with argcomplete if installed.
+
+Needs argcomplete>=0.5.6 for python 3.2/3.3 (older versions fail
 to find the magic string, so _ARGCOMPLETE env. var is never set, and
-this does not need special code.
+this does not need special code).
 
 Function try_argcomplete(parser) should be called directly before
 the call to ArgumentParser.parse_args().
@@ -10,8 +11,7 @@
 arguments specification, in order to get "dirname/" after "dirn<TAB>"
 instead of the default "dirname ":
 
-   optparser.add_argument(Config._file_or_dir, nargs='*'
-                               ).completer=filescompleter
+   optparser.add_argument(Config._file_or_dir, nargs='*').completer=filescompleter
 
 Other, application specific, completers should go in the file
 doing the add_argument calls as they need to be specified as .completer
@@ -20,35 +20,43 @@
 
 SPEEDUP
 =======
+
 The generic argcomplete script for bash-completion
-(/etc/bash_completion.d/python-argcomplete.sh )
+(/etc/bash_completion.d/python-argcomplete.sh)
 uses a python program to determine startup script generated by pip.
 You can speed up completion somewhat by changing this script to include
   # PYTHON_ARGCOMPLETE_OK
 so the the python-argcomplete-check-easy-install-script does not
 need to be called to find the entry point of the code and see if that is
-marked  with PYTHON_ARGCOMPLETE_OK
+marked  with PYTHON_ARGCOMPLETE_OK.
 
 INSTALL/DEBUGGING
 =================
+
 To include this support in another application that has setup.py generated
 scripts:
-- add the line:
+
+- Add the line:
     # PYTHON_ARGCOMPLETE_OK
-  near the top of the main python entry point
-- include in the file calling parse_args():
+  near the top of the main python entry point.
+
+- Include in the file calling parse_args():
     from _argcomplete import try_argcomplete, filescompleter
-   , call try_argcomplete just before parse_args(), and optionally add
-   filescompleter to the positional arguments' add_argument()
+  Call try_argcomplete just before parse_args(), and optionally add
+  filescompleter to the positional arguments' add_argument().
+
 If things do not work right away:
-- switch on argcomplete debugging with (also helpful when doing custom
+
+- Switch on argcomplete debugging with (also helpful when doing custom
   completers):
     export _ARC_DEBUG=1
-- run:
+
+- Run:
     python-argcomplete-check-easy-install-script $(which appname)
     echo $?
-  will echo 0 if the magic line has been found, 1 if not
-- sometimes it helps to find early on errors using:
+  will echo 0 if the magic line has been found, 1 if not.
+
+- Sometimes it helps to find early on errors using:
     _ARGCOMPLETE=1 _ARC_DEBUG=1 appname
   which should throw a KeyError: 'COMPLINE' (which is properly set by the
   global argcomplete script).
@@ -63,29 +71,29 @@
 
 
 class FastFilesCompleter:
-    "Fast file completer class"
+    """Fast file completer class."""
 
     def __init__(self, directories: bool = True) -> None:
         self.directories = directories
 
     def __call__(self, prefix: str, **kwargs: Any) -> List[str]:
-        """only called on non option completions"""
+        # Only called on non option completions.
         if os.path.sep in prefix[1:]:
             prefix_dir = len(os.path.dirname(prefix) + os.path.sep)
         else:
             prefix_dir = 0
         completion = []
         globbed = []
         if "*" not in prefix and "?" not in prefix:
-            # we are on unix, otherwise no bash
+            # We are on unix, otherwise no bash.
             if not prefix or prefix[-1] == os.path.sep:
                 globbed.extend(glob(prefix + ".*"))
             prefix += "*"
         globbed.extend(glob(prefix))
         for x in sorted(globbed):
             if os.path.isdir(x):
                 x += "/"
-            # append stripping the prefix (like bash, not like compgen)
+            # Append stripping the prefix (like bash, not like compgen).
             completion.append(x[prefix_dir:])
         return completion
 

src/_pytest/_code/code.py

@@ -71,9 +71,8 @@ def __eq__(self, other):
 
     @property
     def path(self) -> Union[py.path.local, str]:
-        """Return a path object pointing to source code (or a str in case
-        of OSError / non-existing file).
-        """
+        """Return a path object pointing to source code, or an ``str`` in
+        case of ``OSError`` / non-existing file."""
         if not self.raw.co_filename:
             return ""
         try:
@@ -420,15 +419,16 @@ def from_exc_info(
         exc_info: Tuple["Type[_E]", "_E", TracebackType],
         exprinfo: Optional[str] = None,
     ) -> "ExceptionInfo[_E]":
-        """Returns an ExceptionInfo for an existing exc_info tuple.
+        """Return an ExceptionInfo for an existing exc_info tuple.
 
         .. warning::
 
             Experimental API
 
-        :param exprinfo: a text string helping to determine if we should
-                         strip ``AssertionError`` from the output, defaults
-                         to the exception message/``__str__()``
+        :param exprinfo:
+            A text string helping to determine if we should strip
+            ``AssertionError`` from the output. Defaults to the exception
+            message/``__str__()``.
         """
         _striptext = ""
         if exprinfo is None and isinstance(exc_info[1], AssertionError):
@@ -444,15 +444,16 @@ def from_exc_info(
     def from_current(
         cls, exprinfo: Optional[str] = None
     ) -> "ExceptionInfo[BaseException]":
-        """Returns an ExceptionInfo matching the current traceback.
+        """Return an ExceptionInfo matching the current traceback.
 
         .. warning::
 
             Experimental API
 
-        :param exprinfo: a text string helping to determine if we should
-                         strip ``AssertionError`` from the output, defaults
-                         to the exception message/``__str__()``
+        :param exprinfo:
+            A text string helping to determine if we should strip
+            ``AssertionError`` from the output. Defaults to the exception
+            message/``__str__()``.
         """
         tup = sys.exc_info()
         assert tup[0] is not None, "no current exception"
@@ -467,7 +468,7 @@ def for_later(cls) -> "ExceptionInfo[_E]":
         return cls(None)
 
     def fill_unfilled(self, exc_info: Tuple["Type[_E]", _E, TracebackType]) -> None:
-        """fill an unfilled ExceptionInfo created with for_later()"""
+        """Fill an unfilled ExceptionInfo created with ``for_later()``."""
         assert self._excinfo is None, "ExceptionInfo was already filled"
         self._excinfo = exc_info
 
@@ -568,7 +569,8 @@ def getrepr(
             Show locals per traceback entry.
             Ignored if ``style=="native"``.
 
-        :param str style: long|short|no|native|value traceback style
+        :param str style:
+            long|short|no|native|value traceback style.
 
         :param bool abspath:
             If paths should be changed to absolute or left unchanged.
@@ -583,7 +585,8 @@ def getrepr(
         :param bool truncate_locals:
             With ``showlocals==True``, make sure locals can be safely represented as strings.
 
-        :param bool chain: if chained exceptions in Python 3 should be shown.
+        :param bool chain:
+            If chained exceptions in Python 3 should be shown.
 
         .. versionchanged:: 3.9
 
@@ -643,7 +646,7 @@ class FormattedExcinfo:
     astcache = attr.ib(default=attr.Factory(dict), init=False, repr=False)
 
     def _getindent(self, source: "Source") -> int:
-        # figure out indent for given source
+        # Figure out indent for the given source.
         try:
             s = str(source.getstatement(len(source) - 1))
         except KeyboardInterrupt:
@@ -704,7 +707,7 @@ def get_exconly(
     ) -> List[str]:
         lines = []
         indentstr = " " * indent
-        # get the real exception information out
+        # Get the real exception information out.
         exlines = excinfo.exconly(tryshort=True).split("\n")
         failindent = self.fail_marker + indentstr[1:]
         for line in exlines:
@@ -730,8 +733,7 @@ def repr_locals(self, locals: Mapping[str, object]) -> Optional["ReprLocals"]:
                         str_repr = saferepr(value)
                     else:
                         str_repr = safeformat(value)
-                    # if len(str_repr) < 70 or not isinstance(value,
-                    #                            (list, tuple, dict)):
+                    # if len(str_repr) < 70 or not isinstance(value, (list, tuple, dict)):
                     lines.append("{:<10} = {}".format(name, str_repr))
                     # else:
                     #    self._line("%-10s =\\" % (name,))
@@ -809,16 +811,17 @@ def repr_traceback(self, excinfo: ExceptionInfo) -> "ReprTraceback":
     def _truncate_recursive_traceback(
         self, traceback: Traceback
     ) -> Tuple[Traceback, Optional[str]]:
-        """
-        Truncate the given recursive traceback trying to find the starting point
-        of the recursion.
+        """Truncate the given recursive traceback trying to find the starting
+        point of the recursion.
 
-        The detection is done by going through each traceback entry and finding the
-        point in which the locals of the frame are equal to the locals of a previous frame (see ``recursionindex()``.
+        The detection is done by going through each traceback entry and
+        finding the point in which the locals of the frame are equal to the
+        locals of a previous frame (see ``recursionindex()``).
 
-        Handle the situation where the recursion process might raise an exception (for example
-        comparing numpy arrays using equality raises a TypeError), in which case we do our best to
-        warn the user of the error and show a limited traceback.
+        Handle the situation where the recursion process might raise an
+        exception (for example comparing numpy arrays using equality raises a
+        TypeError), in which case we do our best to warn the user of the
+        error and show a limited traceback.
         """
         try:
             recursionindex = traceback.recursionindex()
@@ -863,8 +866,8 @@ def repr_excinfo(self, excinfo: ExceptionInfo) -> "ExceptionChainRepr":
                     excinfo_._getreprcrash() if self.style != "value" else None
                 )  # type: Optional[ReprFileLocation]
             else:
-                # fallback to native repr if the exception doesn't have a traceback:
-                # ExceptionInfo objects require a full traceback to work
+                # Fallback to native repr if the exception doesn't have a traceback:
+                # ExceptionInfo objects require a full traceback to work.
                 reprtraceback = ReprTracebackNative(
                     traceback.format_exception(type(e), e, None)
                 )
@@ -915,7 +918,7 @@ def toterminal(self, tw: TerminalWriter) -> None:
 # This class is abstract -- only subclasses are instantiated.
 @attr.s(**{ATTRS_EQ_FIELD: False})  # type: ignore
 class ExceptionRepr(TerminalRepr):
-    # Provided by in subclasses.
+    # Provided by subclasses.
     reprcrash = None  # type: Optional[ReprFileLocation]
     reprtraceback = None  # type: ReprTraceback
 
@@ -942,7 +945,7 @@ class ExceptionChainRepr(ExceptionRepr):
     def __attrs_post_init__(self) -> None:
         super().__attrs_post_init__()
         # reprcrash and reprtraceback of the outermost (the newest) exception
-        # in the chain
+        # in the chain.
         self.reprtraceback = self.chain[-1][0]
         self.reprcrash = self.chain[-1][1]
 
@@ -974,7 +977,7 @@ class ReprTraceback(TerminalRepr):
     entrysep = "_ "
 
     def toterminal(self, tw: TerminalWriter) -> None:
-        # the entries might have different styles
+        # The entries might have different styles.
         for i, entry in enumerate(self.reprentries):
             if entry.style == "long":
                 tw.line("")
@@ -1017,7 +1020,7 @@ class ReprEntry(TerminalRepr):
     style = attr.ib(type="_TracebackStyle")
 
     def _write_entry_lines(self, tw: TerminalWriter) -> None:
-        """Writes the source code portions of a list of traceback entries with syntax highlighting.
+        """Write the source code portions of a list of traceback entries with syntax highlighting.
 
         Usually entries are lines like these:
 
@@ -1099,8 +1102,8 @@ class ReprFileLocation(TerminalRepr):
     message = attr.ib(type=str)
 
     def toterminal(self, tw: TerminalWriter) -> None:
-        # filename and lineno output for each entry,
-        # using an output format that most editors understand
+        # Filename and lineno output for each entry, using an output format
+        # that most editors understand.
         msg = self.message
         i = msg.find("\n")
         if i != -1:
@@ -1175,10 +1178,10 @@ def getfslineno(obj: object) -> Tuple[Union[str, py.path.local], int]:
     return code.path, code.firstlineno
 
 
-# relative paths that we use to filter traceback entries from appearing to the user;
-# see filter_traceback
+# Relative paths that we use to filter traceback entries from appearing to the user;
+# see filter_traceback.
 # note: if we need to add more paths than what we have now we should probably use a list
-# for better maintenance
+# for better maintenance.
 
 _PLUGGY_DIR = py.path.local(pluggy.__file__.rstrip("oc"))
 # pluggy is either a package or a single module depending on the version
@@ -1197,14 +1200,14 @@ def filter_traceback(entry: TracebackEntry) -> bool:
     * internal traceback from pytest or its internal libraries, py and pluggy.
     """
     # entry.path might sometimes return a str object when the entry
-    # points to dynamically generated code
-    # see https://bitbucket.org/pytest-dev/py/issues/71
+    # points to dynamically generated code.
+    # See https://bitbucket.org/pytest-dev/py/issues/71.
     raw_filename = entry.frame.code.raw.co_filename
     is_generated = "<" in raw_filename and ">" in raw_filename
     if is_generated:
         return False
     # entry.path might point to a non-existing file, in which case it will
-    # also return a str object. see #1133
+    # also return a str object. See #1133.
     p = py.path.local(entry.path)
     return (
         not p.relto(_PLUGGY_DIR) and not p.relto(_PYTEST_DIR) and not p.relto(_PY_DIR)