Make docstring style more consistent

src/xdist/dsession.py

@@ -24,7 +24,7 @@ class Interrupted(KeyboardInterrupt):
 
 
 class DSession:
-    """A pytest plugin which runs a distributed test session
+    """A pytest plugin which runs a distributed test session.
 
     At the beginning of the test session this creates a NodeManager
     instance which creates and starts all nodes.  Nodes then emit
@@ -60,7 +60,7 @@ class DSession:
 
     @property
     def session_finished(self):
-        """Return True if the distributed session has finished
+        """Return True if the distributed session has finished.
 
         This means all nodes have executed all test items.  This is
         used by pytest_runtestloop to break out of its loop.
@@ -250,7 +250,7 @@ class DSession:
             terminalreporter.write_sep("=", f"xdist: {self._summary_report}")
 
     def worker_collectionfinish(self, node, ids):
-        """worker has finished test collection.
+        """Worker has finished test collection.
 
         This adds the collection for this node to the scheduler.  If
         the scheduler indicates collection is finished (i.e. all
@@ -490,7 +490,7 @@ class TerminalDistReporter:
 
 
 def get_default_max_worker_restart(config):
-    """gets the default value of --max-worker-restart option if it is not provided.
+    """Gets the default value of --max-worker-restart option if it is not provided.
 
     Use a reasonable default to avoid workers from restarting endlessly due to crashing collections (#226).
     """

src/xdist/looponfail.py

@@ -1,10 +1,10 @@
 """
-    Implement -f aka looponfailing for pytest.
+Implement -f aka looponfailing for pytest.
 
-    NOTE that we try to avoid loading and depending on application modules
+NOTE that we try to avoid loading and depending on application modules
-    within the controlling process (the one that starts repeatedly test
+within the controlling process (the one that starts repeatedly test
-    processes) otherwise changes to source code can crash
+processes) otherwise changes to source code can crash
-    the controlling process which should best never happen.
+the controlling process which should best never happen.
 """
 
 import os

src/xdist/newhooks.py

@@ -17,12 +17,12 @@ import pytest
 
 @pytest.hookspec()
 def pytest_xdist_setupnodes(config, specs):
-    """called before any remote node is set up."""
+    """Called before any remote node is set up."""
 
 
 @pytest.hookspec()
 def pytest_xdist_newgateway(gateway):
-    """called on new raw gateway creation."""
+    """Called on new raw gateway creation."""
 
 
 @pytest.hookspec(
@@ -31,7 +31,7 @@ def pytest_xdist_newgateway(gateway):
     )
 )
 def pytest_xdist_rsyncstart(source, gateways):
-    """called before rsyncing a directory to remote gateways takes place."""
+    """Called before rsyncing a directory to remote gateways takes place."""
 
 
 @pytest.hookspec(
@@ -40,17 +40,17 @@ def pytest_xdist_rsyncstart(source, gateways):
     )
 )
 def pytest_xdist_rsyncfinish(source, gateways):
-    """called after rsyncing a directory to remote gateways takes place."""
+    """Called after rsyncing a directory to remote gateways takes place."""
 
 
 @pytest.hookspec(firstresult=True)
 def pytest_xdist_getremotemodule():
-    """called when creating remote node"""
+    """Called when creating remote node."""
 
 
 @pytest.hookspec()
 def pytest_configure_node(node):
-    """configure node information before it gets instantiated."""
+    """Configure node information before it gets instantiated."""
 
 
 @pytest.hookspec()
@@ -65,12 +65,12 @@ def pytest_testnodedown(node, error):
 
 @pytest.hookspec()
 def pytest_xdist_node_collection_finished(node, ids):
-    """called by the controller node when a worker node finishes collecting."""
+    """Called by the controller node when a worker node finishes collecting."""
 
 
 @pytest.hookspec(firstresult=True)
 def pytest_xdist_make_scheduler(config, log):
-    """return a node scheduler implementation"""
+    """Return a node scheduler implementation."""
 
 
 @pytest.hookspec(firstresult=True)

src/xdist/plugin.py

@@ -305,7 +305,7 @@ def pytest_cmdline_main(config):
 
 
 def is_xdist_worker(request_or_session) -> bool:
-    """Return `True` if this is an xdist worker, `False` otherwise
+    """Return `True` if this is an xdist worker, `False` otherwise.
 
     :param request_or_session: the `pytest` `request` or `session` object
     """
@@ -313,7 +313,7 @@ def is_xdist_worker(request_or_session) -> bool:
 
 
 def is_xdist_controller(request_or_session) -> bool:
-    """Return `True` if this is the xdist controller, `False` otherwise
+    """Return `True` if this is the xdist controller, `False` otherwise.
 
     Note: this method also returns `False` when distribution has not been
     activated at all.

src/xdist/remote.py

@@ -1,9 +1,9 @@
 """
-    This module is executed in remote subprocesses and helps to
+This module is executed in remote subprocesses and helps to
-    control a remote testing session and relay back information.
+control a remote testing session and relay back information.
-    It assumes that 'py' is importable and does not have dependencies
+It assumes that 'py' is importable and does not have dependencies
-    on the rest of the xdist code.  This means that the xdist-plugin
+on the rest of the xdist code.  This means that the xdist-plugin
-    needs not to be installed in remote environments.
+needs not to be installed in remote environments.
 """
 
 import contextlib

src/xdist/scheduler/each.py

@@ -4,7 +4,7 @@ from xdist.workermanage import parse_spec_config
 
 
 class EachScheduling:
-    """Implement scheduling of test items on all nodes
+    """Implement scheduling of test items on all nodes.
 
     If a node gets added after the test run is started then it is
     assumed to replace a node which got removed before it finished
@@ -48,7 +48,7 @@ class EachScheduling:
 
     @property
     def has_pending(self):
-        """Return True if there are pending test items
+        """Return True if there are pending test items.
 
         This indicates that collection has finished and nodes are
         still processing test items, so this can be thought of as
@@ -64,7 +64,7 @@ class EachScheduling:
         self.node2pending[node] = []
 
     def add_node_collection(self, node, collection):
-        """Add the collected test items from a node
+        """Add the collected test items from a node.
 
         Collection is complete once all nodes have submitted their
         collection.  In this case its pending list is set to an empty
@@ -119,7 +119,7 @@ class EachScheduling:
         return crashitem
 
     def schedule(self):
-        """Schedule the test items on the nodes
+        """Schedule the test items on the nodes.
 
         If the node's pending list is empty it is a new node which
         needs to run all the tests.  If the pending list is already

src/xdist/scheduler/load.py

@@ -23,7 +23,7 @@ class LoadScheduling:
     submit a collection. This is used to know when all nodes have
     finished collection or how large the chunks need to be created.
 
-    Attributes:
+    Attributes::
 
     :numnodes: The expected number of nodes taking part.  The actual
        number of nodes will vary during the scheduler's lifetime as
@@ -95,7 +95,7 @@ class LoadScheduling:
 
     @property
     def has_pending(self):
-        """Return True if there are pending test items
+        """Return True if there are pending test items.
 
         This indicates that collection has finished and nodes are
         still processing test items, so this can be thought of as
@@ -121,7 +121,7 @@ class LoadScheduling:
         self.node2pending[node] = []
 
     def add_node_collection(self, node, collection):
-        """Add the collected test items from a node
+        """Add the collected test items from a node.
 
         The collection is stored in the ``.node2collection`` map.
         Called by the ``DSession.worker_collectionfinish`` hook.
@@ -142,7 +142,7 @@ class LoadScheduling:
         self.node2collection[node] = list(collection)
 
     def mark_test_complete(self, node, item_index, duration=0):
-        """Mark test item as completed by node
+        """Mark test item as completed by node.
 
         The duration it took to execute the item is used as a hint to
         the scheduler.
@@ -161,7 +161,7 @@ class LoadScheduling:
             self.check_schedule(node)
 
     def check_schedule(self, node, duration=0):
-        """Maybe schedule new items on the node
+        """Maybe schedule new items on the node.
 
         If there are any globally pending nodes left then this will
         check if the given node should be given any more tests.  The
@@ -195,7 +195,7 @@ class LoadScheduling:
         self.log("num items waiting for node:", len(self.pending))
 
     def remove_node(self, node):
-        """Remove a node from the scheduler
+        """Remove a node from the scheduler.
 
         This should be called either when the node crashed or at
         shutdown time.  In the former case any pending items assigned
@@ -219,7 +219,7 @@ class LoadScheduling:
         return crashitem
 
     def schedule(self):
-        """Initiate distribution of the test collection
+        """Initiate distribution of the test collection.
 
         Initiate scheduling of the items across the nodes.  If this
         gets called again later it behaves the same as calling

src/xdist/scheduler/loadfile.py

@@ -44,7 +44,10 @@ class LoadFileScheduling(LoadScopeScheduling):
         This function will group tests with the scope determined by splitting
         the first ``::`` from the left. That is, test will be grouped in a
         single work unit when they reside in the same file.
-         In the above example, scopes will be::
+
+        In the above example, scopes will be::
+
+        .. code-block:: text
 
             example/loadsuite/test/test_beta.py
             example/loadsuite/test/test_delta.py

src/xdist/scheduler/loadscope.py

@@ -22,7 +22,7 @@ class LoadScopeScheduling:
     When created, ``numnodes`` defines how many nodes are expected to submit a
     collection. This is used to know when all nodes have finished collection.
 
-    Attributes:
+    Attributes::
 
     :numnodes: The expected number of nodes taking part.  The actual number of
        nodes will vary during the scheduler's lifetime as nodes are added by

src/xdist/scheduler/worksteal.py

@@ -22,7 +22,7 @@ class WorkStealingScheduling:
     test remains), an attempt is made to reassign ("steal") some tests from
     other nodes to this node.
 
-    Attributes:
+    Attributes::
 
     :numnodes: The expected number of nodes taking part.  The actual
        number of nodes will vary during the scheduler's lifetime as
@@ -101,7 +101,7 @@ class WorkStealingScheduling:
 
     @property
     def has_pending(self):
-        """Return True if there are pending test items
+        """Return True if there are pending test items.
 
         This indicates that collection has finished and nodes are
         still processing test items, so this can be thought of as
@@ -127,7 +127,7 @@ class WorkStealingScheduling:
         self.node2pending[node] = []
 
     def add_node_collection(self, node, collection):
-        """Add the collected test items from a node
+        """Add the collected test items from a node.
 
         The collection is stored in the ``.node2collection`` map.
         Called by the ``DSession.worker_collectionfinish`` hook.
@@ -148,7 +148,7 @@ class WorkStealingScheduling:
         self.node2collection[node] = list(collection)
 
     def mark_test_complete(self, node, item_index, duration=None):
-        """Mark test item as completed by node
+        """Mark test item as completed by node.
 
         This is called by the ``DSession.worker_testreport`` hook.
         """
@@ -233,7 +233,7 @@ class WorkStealingScheduling:
         self.steal_requested_from_node = steal_from.node
 
     def remove_node(self, node):
-        """Remove a node from the scheduler
+        """Remove a node from the scheduler.
 
         This should be called either when the node crashed or at
         shutdown time.  In the former case any pending items assigned
@@ -263,7 +263,7 @@ class WorkStealingScheduling:
         return crashitem
 
     def schedule(self):
-        """Initiate distribution of the test collection
+        """Initiate distribution of the test collection.
 
         Initiate scheduling of the items across the nodes.  If this
         gets called again later it behaves the same as calling

src/xdist/workermanage.py

@@ -166,7 +166,7 @@ class NodeManager:
 
 
 class HostRSync(execnet.RSync):
-    """RSyncer that filters out common files"""
+    """RSyncer that filters out common files."""
 
     PathLike = Union[str, "os.PathLike[str]"]
 
@@ -314,7 +314,7 @@ class WorkerController:
             self._shutdown_sent = True
 
     def sendcommand(self, name, **kwargs):
-        """send a named parametrized command to the other side."""
+        """Send a named parametrized command to the other side."""
         self.log(f"sending command {name}(**{kwargs})")
         self.channel.send((name, kwargs))
 

testing/acceptance_test.py

@@ -482,7 +482,7 @@ class TestTerminalReporting:
         )
 
     def test_logfinish_hook(self, pytester: pytest.Pytester) -> None:
-        """Ensure the pytest_runtest_logfinish hook is being properly handled"""
+        """Ensure the pytest_runtest_logfinish hook is being properly handled."""
         pytester.makeconftest(
             """
             def pytest_runtest_logfinish():
@@ -613,7 +613,7 @@ def test_fixture_teardown_failure(pytester: pytest.Pytester) -> None:
 def test_config_initialization(
     pytester: pytest.Pytester, monkeypatch: pytest.MonkeyPatch, pytestconfig
 ) -> None:
-    """Ensure workers and controller are initialized consistently. Integration test for #445"""
+    """Ensure workers and controller are initialized consistently. Integration test for #445."""
     pytester.makepyfile(
         **{
             "dir_a/test_foo.py": """
@@ -637,7 +637,7 @@ def test_config_initialization(
 
 @pytest.mark.parametrize("when", ["setup", "call", "teardown"])
 def test_crashing_item(pytester, when) -> None:
-    """Ensure crashing item is correctly reported during all testing stages"""
+    """Ensure crashing item is correctly reported during all testing stages."""
     code = dict(setup="", call="", teardown="")
     code[when] = "os._exit(1)"
     p = pytester.makepyfile(
@@ -770,7 +770,7 @@ def test_tmpdir_disabled(pytester: pytest.Pytester) -> None:
 
 @pytest.mark.parametrize("plugin", ["xdist.looponfail"])
 def test_sub_plugins_disabled(pytester, plugin) -> None:
-    """Test that xdist doesn't break if we disable any of its sub-plugins. (#32)"""
+    """Test that xdist doesn't break if we disable any of its sub-plugins (#32)."""
     p1 = pytester.makepyfile(
         """
         def test_ok():
@@ -800,9 +800,7 @@ class TestWarnings:
     def test_warning_captured_deprecated_in_pytest_6(
         self, pytester: pytest.Pytester
     ) -> None:
-        """
+        """Do not trigger the deprecated pytest_warning_captured hook in pytest 6+ (#562)."""
-        Do not trigger the deprecated pytest_warning_captured hook in pytest 6+ (#562)
-        """
         from _pytest import hookspec
 
         if not hasattr(hookspec, "pytest_warning_captured"):
@@ -834,7 +832,7 @@ class TestWarnings:
     @pytest.mark.parametrize("n", ["-n0", "-n1"])
     def test_custom_subclass(self, pytester, n) -> None:
         """Check that warning subclasses that don't honor the args attribute don't break
-        pytest-xdist (#344)
+        pytest-xdist (#344).
         """
         pytester.makepyfile(
             """
@@ -1117,7 +1115,7 @@ def test_error_report_styles(pytester, tb) -> None:
 
 
 def test_color_yes_collection_on_non_atty(pytester, request) -> None:
-    """skip collect progress report when working on non-terminals.
+    """Skip collect progress report when working on non-terminals.
 
     Similar to pytest-dev/pytest#1397
     """
@@ -1142,9 +1140,7 @@ def test_color_yes_collection_on_non_atty(pytester, request) -> None:
 
 
 def test_without_terminal_plugin(pytester, request) -> None:
-    """
+    """No output when terminal plugin is disabled."""
-    No output when terminal plugin is disabled
-    """
     pytester.makepyfile(
         """
         def test_1():
@@ -1158,9 +1154,7 @@ def test_without_terminal_plugin(pytester, request) -> None:
 
 
 def test_internal_error_with_maxfail(pytester: pytest.Pytester) -> None:
-    """
+    """Internal error when using --maxfail option (#62, #65)."""
-    Internal error when using --maxfail option (#62, #65).
-    """
     pytester.makepyfile(
         """
         import pytest
@@ -1181,9 +1175,7 @@ def test_internal_error_with_maxfail(pytester: pytest.Pytester) -> None:
 
 
 def test_maxfail_causes_early_termination(pytester: pytest.Pytester) -> None:
-    """
+    """Ensure subsequent tests on a worker aren't run when using --maxfail (#1024)."""
-    Ensure subsequent tests on a worker aren't run when using --maxfail (#1024).
-    """
     pytester.makepyfile(
         """
         def test1():

testing/test_newhooks.py

@@ -14,9 +14,9 @@ class TestHooks:
         )
 
     def test_runtest_logreport(self, pytester: pytest.Pytester) -> None:
-        """Test that log reports from pytest_runtest_logreport when running
+        """Test that log reports from pytest_runtest_logreport when running with
-        with xdist contain "node", "nodeid", "worker_id", and "testrun_uid" attributes. (#8)
+        xdist contain "node", "nodeid", "worker_id", and "testrun_uid"
-        """
+        attributes (#8)."""
         pytester.makeconftest(
             """
             def pytest_runtest_logreport(report):

testing/test_plugin.py

@@ -11,7 +11,7 @@ from xdist.workermanage import NodeManager
 
 @pytest.fixture
 def monkeypatch_3_cpus(monkeypatch: pytest.MonkeyPatch):
-    """Make pytest-xdist believe the system has 3 CPUs"""
+    """Make pytest-xdist believe the system has 3 CPUs."""
     # block import
     monkeypatch.setitem(sys.modules, "psutil", None)  # type: ignore
     monkeypatch.delattr(os, "sched_getaffinity", raising=False)

testing/test_workermanage.py

@@ -350,8 +350,7 @@ class MyWarning(UserWarning):
     ],
 )
 def test_unserialize_warning_msg(w_cls):
-    """Test that warning serialization process works well"""
+    """Test that warning serialization process works well."""
-
     # Create a test warning message
     with pytest.warns(UserWarning) as w:
         if not isinstance(w_cls, str):
@@ -392,8 +391,7 @@ class MyWarningUnknown(UserWarning):
 
 
 def test_warning_serialization_tweaked_module():
-    """Test for GH#404"""
+    """Test for GH#404."""
-
     # Create a test warning message
     with pytest.warns(UserWarning) as w:
         warnings.warn("hello", MyWarningUnknown)