From c01de1c73ebe002318118c0ab924434946313489 Mon Sep 17 00:00:00 2001 From: Ran Benita Date: Wed, 3 Apr 2024 00:15:21 +0300 Subject: [PATCH] Make docstring style more consistent --- src/xdist/dsession.py | 8 ++++---- src/xdist/looponfail.py | 10 +++++----- src/xdist/newhooks.py | 16 ++++++++-------- src/xdist/plugin.py | 4 ++-- src/xdist/remote.py | 10 +++++----- src/xdist/scheduler/each.py | 8 ++++---- src/xdist/scheduler/load.py | 14 +++++++------- src/xdist/scheduler/loadfile.py | 5 ++++- src/xdist/scheduler/loadscope.py | 2 +- src/xdist/scheduler/worksteal.py | 12 ++++++------ src/xdist/workermanage.py | 4 ++-- testing/acceptance_test.py | 28 ++++++++++------------------ testing/test_newhooks.py | 6 +++--- testing/test_plugin.py | 2 +- testing/test_workermanage.py | 6 ++---- 15 files changed, 64 insertions(+), 71 deletions(-) diff --git a/src/xdist/dsession.py b/src/xdist/dsession.py index 6be93e0..1f55239 100644 --- a/src/xdist/dsession.py +++ b/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). """ diff --git a/src/xdist/looponfail.py b/src/xdist/looponfail.py index 929f3d4..e88d2ac 100644 --- a/src/xdist/looponfail.py +++ b/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 - within the controlling process (the one that starts repeatedly test - processes) otherwise changes to source code can crash - the controlling process which should best never happen. +NOTE that we try to avoid loading and depending on application modules +within the controlling process (the one that starts repeatedly test +processes) otherwise changes to source code can crash +the controlling process which should best never happen. """ import os diff --git a/src/xdist/newhooks.py b/src/xdist/newhooks.py index 1603951..ceac11e 100644 --- a/src/xdist/newhooks.py +++ b/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) diff --git a/src/xdist/plugin.py b/src/xdist/plugin.py index cef61c0..116a0f0 100644 --- a/src/xdist/plugin.py +++ b/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. diff --git a/src/xdist/remote.py b/src/xdist/remote.py index 70aa870..93f722e 100644 --- a/src/xdist/remote.py +++ b/src/xdist/remote.py @@ -1,9 +1,9 @@ """ - This module is executed in remote subprocesses and helps to - control a remote testing session and relay back information. - It assumes that 'py' is importable and does not have dependencies - on the rest of the xdist code. This means that the xdist-plugin - needs not to be installed in remote environments. +This module is executed in remote subprocesses and helps to +control a remote testing session and relay back information. +It assumes that 'py' is importable and does not have dependencies +on the rest of the xdist code. This means that the xdist-plugin +needs not to be installed in remote environments. """ import contextlib diff --git a/src/xdist/scheduler/each.py b/src/xdist/scheduler/each.py index 329ce68..91084bf 100644 --- a/src/xdist/scheduler/each.py +++ b/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 diff --git a/src/xdist/scheduler/load.py b/src/xdist/scheduler/load.py index 87d9cb2..6d7b231 100644 --- a/src/xdist/scheduler/load.py +++ b/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 diff --git a/src/xdist/scheduler/loadfile.py b/src/xdist/scheduler/loadfile.py index 9ddd535..25b72da 100644 --- a/src/xdist/scheduler/loadfile.py +++ b/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 diff --git a/src/xdist/scheduler/loadscope.py b/src/xdist/scheduler/loadscope.py index af92935..ad94714 100644 --- a/src/xdist/scheduler/loadscope.py +++ b/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 diff --git a/src/xdist/scheduler/worksteal.py b/src/xdist/scheduler/worksteal.py index 055efa4..fc102bd 100644 --- a/src/xdist/scheduler/worksteal.py +++ b/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 diff --git a/src/xdist/workermanage.py b/src/xdist/workermanage.py index 1de00ad..fcb70e8 100644 --- a/src/xdist/workermanage.py +++ b/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)) diff --git a/testing/acceptance_test.py b/testing/acceptance_test.py index 40745f6..d82562e 100644 --- a/testing/acceptance_test.py +++ b/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(): diff --git a/testing/test_newhooks.py b/testing/test_newhooks.py index dcd2bc0..e3a8ac6 100644 --- a/testing/test_newhooks.py +++ b/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 - with xdist contain "node", "nodeid", "worker_id", and "testrun_uid" attributes. (#8) - """ + """Test that log reports from pytest_runtest_logreport when running with + xdist contain "node", "nodeid", "worker_id", and "testrun_uid" + attributes (#8).""" pytester.makeconftest( """ def pytest_runtest_logreport(report): diff --git a/testing/test_plugin.py b/testing/test_plugin.py index 951b882..74de0d4 100644 --- a/testing/test_plugin.py +++ b/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) diff --git a/testing/test_workermanage.py b/testing/test_workermanage.py index 367ce8a..e7fa3f5 100644 --- a/testing/test_workermanage.py +++ b/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)