Contributing isoscope scheduler

.pre-commit-config.yaml

@@ -33,3 +33,4 @@ repos:
           - execnet>=2.1.0
           - types-psutil
           - setproctitle
+          - filelock>=3.13.1

CHANGELOG.rst

@@ -1,3 +1,10 @@
+pytest-xdist 3.ZZZ.ZZZ (2024-zz-zz)
+===================================
+
+Features
+--------
+- `#1126 <https://github.com/pytest-dev/pytest-xdist/pull/1126>`_: New ``isoscope`` scheduler.
+
 pytest-xdist 3.6.1 (2024-04-28)
 ===============================
 

docs/distribution.rst

@@ -49,6 +49,19 @@ The test distribution algorithm is configured with the ``--dist`` command-line o
 
 .. _distribution modes:
 
+* ``--dist isoscope``: Scope Isolation Scheduler. Tests are grouped by module for
+  test functions and by class for test methods. Tests are executed one group at a
+  time, distributed across available workers. This groupwise isolation guarantees
+  that all tests in one group complete execution before running another group of
+  tests. This can be useful when module-level or class-level fixtures of one group
+  could create undesirable side-effects for tests in other test groups, while
+  taking advantage of distributed execution of tests within each group. Grouping
+  by class takes priority over grouping by module. NOTE: the use of this scheduler
+  requires distributed coordination for setup and teardown such as provided by
+  the ``iso_scheduling`` fixture or an alternate implementation of distributed
+  coordination - see the ``iso_scheduling.coordinate_setup_teardown`` usage example
+  in iso_scheduling_plugin.py.
+
 * ``--dist load`` **(default)**: Sends pending tests to any worker that is
   available, without any guaranteed order. Scheduling can be fine-tuned with
   the `--maxschedchunk` option, see output of `pytest --help`.

pyproject.toml

@@ -35,6 +35,7 @@ classifiers = [
 requires-python = ">=3.8"
 dependencies = [
     "execnet>=2.1",
+    "filelock>=3.13.1",
     "pytest>=7.0.0",
 ]
 dynamic = ["version"]
@@ -48,6 +49,7 @@ Tracker = "https://github.com/pytest-dev/pytest-xdist/issues"
 
 [project.entry-points.pytest11]
 xdist = "xdist.plugin"
+"xdist.iso_scheduling_plugin" = "xdist.iso_scheduling_plugin"
 "xdist.looponfail" = "xdist.looponfail"
 
 [project.optional-dependencies]

src/xdist/dsession.py

@@ -15,6 +15,7 @@
 from xdist.remote import Producer
 from xdist.remote import WorkerInfo
 from xdist.scheduler import EachScheduling
+from xdist.scheduler import IsoScopeScheduling
 from xdist.scheduler import LoadFileScheduling
 from xdist.scheduler import LoadGroupScheduling
 from xdist.scheduler import LoadScheduling
@@ -113,6 +114,8 @@ def pytest_xdist_make_scheduler(
         dist = config.getvalue("dist")
         if dist == "each":
             return EachScheduling(config, log)
+        if dist == "isoscope":
+            return IsoScopeScheduling(config, log)
         if dist == "load":
             return LoadScheduling(config, log)
         if dist == "loadscope":