v0.2.0 (#2)

Author: provinzkraut

.github/workflows/test.yaml

@@ -25,6 +25,7 @@ jobs:
         run: pre-commit run --show-diff-on-failure --color=always --all-files
 
   test:
+    name: Python ${{matrix.python-version}} + Pytest ${{matrix.pytest-version}}
     strategy:
       fail-fast: true
       matrix:
@@ -34,6 +35,9 @@ jobs:
           - "3.11"
           - "3.12"
           - "3.13"
+        pytest-version:
+          - "7"
+          - "8"
     runs-on: ubuntu-latest
     steps:
       - name: Check out repository
@@ -44,6 +48,10 @@ jobs:
           python-version: ${{ matrix.python-version }}
       - name: Install uv
         uses: astral-sh/setup-uv@v5
+      - name: Install dependencies
+        run: |
+          uv sync
+          uv pip install pytest=="${{matrix.pytest-version}}"
       - name: Test
         run: uv run pytest
 

README.md

@@ -40,3 +40,70 @@ jobs:
       - name: Run pytest
         run: pytest --cdist-group=${{ matrix.cdist-group }}/4
 ```
+
+## Usage
+
+### Configuration
+
+Pytest-cdist comes with several CLI and pytest-ini options:
+
+| CLI                     | Ini                   | Allowed values                | Default |
+|-------------------------|-----------------------|-------------------------------|---------|
+| `--cdist-justify-items` | `cdist-justify-items` | `none`, `file`, `scope`       | `none`  |
+| `--cdist-group-steal`   | `--cdist-group-steal` | `<group number>:<percentage>` | -       |
+| `--cdist-report`        | -                     | -                             | false   |
+| `--cdist-report-dir`    | `cdist-report-dir`    |                               | `.`     |
+
+
+### Controlling how items are split up
+
+By default, pytest-cdist will split up the items into groups as evenly as possible.
+Sometimes this may not be desired, for example if there's some costly fixtures requested
+by multiple tests, which should ideally only run once. 
+
+To solve this, the `cdist-justify-items` option can be used to configure how items are
+split up. It can take two possible values: 
+
+- `file`: Ensure all items inside a file end up in the same group
+- `scope`: Ensure all items in the same pytest scope end up in the same group
+
+```ini
+[pytest]
+cdist-justify-items=file
+```
+
+```bash
+pytest --cdist-group=1/2 --cdist-justify-items=file
+```
+
+
+### Skewing the group sizes
+
+Normally, items are distributed evenly among groups, which is a good default, but there
+may be cases where this will result in an uneven execution time, if one group contains
+a number of slower tests than the other ones. 
+
+To work around this, the `cdist-group-steal` option can be used. It allows to specific 
+a certain percentage of items a group will "steal" from other groups. For example 
+`--cdist-group-steal=2:30` will cause group `2` to steal 30% of items from all other 
+groups.
+
+```ini
+[pytest]
+cdist-group-steal=2:30
+```
+
+```bash
+pytest --cdist-group=1/2 --cdist-group-steal=2:30
+```
+
+### With pytest-xdist
+
+When running under pytest-xdist, pytest-cdist will honour tests marked with 
+`xdist_group`, and group them together in the same cdist group. 
+
+
+### With pytest-randomly
+
+At the moment, pytest-cdist does not work out of the box with pytest randomly's test
+reordering, unless an explicit seed is passed

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pytest-cdist"
-version = "0.1.0"
+version = "0.2.0"
 description = "Add your description here"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -31,6 +31,7 @@ dev = [
     "pytest-xdist>=3.6.1",
     "mypy>=1.14.0",
     "pre-commit>=4.0.1",
+    "typing-extensions>=4.12.2",
 ]
 
 [project.entry-points.pytest11]

pytest_cdist/plugin.py

@@ -1,30 +1,22 @@
 from __future__ import annotations
+
 import collections
+import dataclasses
 import json
+import os
 import pathlib
-from typing import TypeVar, Literal
+from typing import TypeVar, Literal, TYPE_CHECKING
 
 import pytest
+from _pytest.stash import StashKey
 
-T = TypeVar("T")
+if TYPE_CHECKING:
+    from typing_extensions import TypeAlias
 
+T = TypeVar("T")
+JustifyItemsStrategy: TypeAlias = Literal["none", "file", "scope"]
 
-@pytest.hookimpl
-def pytest_addoption(parser: pytest.Parser) -> None:
-    group = parser.getgroup("cdist")
-    group.addoption("--cdist-group", action="store", default=None)
-    group.addoption("--cdist-report", action="store_true", default=False)
-    group.addoption(
-        "--cdist-report-dir", action="store", default=".", type=pathlib.Path
-    )
-    group.addoption("--cdist-justify-items", action="store", default="none")
-    group.addoption(
-        "--cdist-group-steal",
-        action="store",
-        default=None,
-        help="make a group steal a percentage of items from other groups. '1:30' would "
-        "make group 1 steal 30 % of items from all other groups)",
-    )
+_CDIST_CONFIG_KEY = StashKey["CdistConfig | None"]()
 
 
 def _partition_list(items: list[T], chunk_size: int) -> list[list[T]]:
@@ -83,6 +75,9 @@ def _justify_items(
 
         last_file = get_boundary(items[-1])
         next_group = groups[i + 1 if i < (len(groups) - 1) else 0]
+        if not next_group:
+            continue
+
         next_file = get_boundary(next_group[0])
 
         if last_file == next_file:
@@ -118,53 +113,143 @@ def _justify_xdist_groups(groups: list[list[pytest.Item]]) -> list[list[pytest.I
     return groups
 
 
+@dataclasses.dataclass
+class CdistConfig:
+    current_group: int
+    total_groups: int
+    justify_items_strategy: JustifyItemsStrategy = "none"
+    group_steal: tuple[int, int] | None = None
+    write_report: bool = False
+    report_dir: pathlib.Path = pathlib.Path(".")
+
+    def cli_options(self, config: pytest.Config) -> str:
+        opts = [f"--cdist-group={self.current_group + 1}/{self.total_groups}"]
+
+        if (
+            self.justify_items_strategy != "none"
+            and "cdist-justify-items" not in config.inicfg
+        ):
+            opts.append(f"--cdist-justify-items={self.justify_items_strategy}")
+
+        if self.group_steal and "cdist-group-steal" not in config.inicfg:
+            opts.append(
+                f"--cdist-group-steal={self.group_steal[0] + 1}:{self.group_steal[1]}"
+            )
+
+        if self.write_report:
+            opts.append("--cdist-report")
+
+        if (
+            self.report_dir != pathlib.Path(".")
+            and "cdist-report-dir" not in config.inicfg
+        ):
+            opts.append(f"--cdist-report-dir={str(self.report_dir)}")
+
+        return " ".join(opts)
+
+    @classmethod
+    def from_pytest_config(cls, config: pytest.Config) -> CdistConfig | None:
+        cdist_option = config.getoption("cdist_group")
+
+        if cdist_option is None:
+            return None
+
+        report_dir = pathlib.Path(
+            config.getoption("cdist_report_dir", None)
+            or config.getini("cdist-report-dir")
+        )
+
+        write_report: bool = config.getoption("cdist_report")
+
+        justify_items_strategy: JustifyItemsStrategy = config.getoption(
+            "cdist_justify_items",
+            default=None,
+        ) or config.getini("cdist-justify-items")
+
+        group_steal = _get_group_steal_opt(
+            config.getoption("cdist_group_steal") or config.getini("cdist-group-steal")
+        )
+
+        current_group, total_groups = map(int, cdist_option.split("/"))
+        if not 0 < current_group <= total_groups:
+            raise pytest.UsageError(f"Unknown group {current_group}")
+
+        # using whole numbers (2/2) is more intuitive for the CLI,
+        # but here we want to use the group numbers for zero-based indexing
+        current_group -= 1
+
+        return cls(
+            total_groups=total_groups,
+            current_group=current_group,
+            report_dir=report_dir,
+            write_report=write_report,
+            justify_items_strategy=justify_items_strategy,
+            group_steal=group_steal,
+        )
+
+
+@pytest.hookimpl
+def pytest_addoption(parser: pytest.Parser) -> None:
+    group = parser.getgroup("cdist")
+    group.addoption("--cdist-group", action="store", default=None)
+    group.addoption("--cdist-report", action="store_true", default=False)
+    group.addoption("--cdist-report-dir", action="store")
+    group.addoption("--cdist-justify-items", action="store")
+    group.addoption(
+        "--cdist-group-steal",
+        action="store",
+        default=None,
+        help="make a group steal a percentage of items from other groups. '1:30' would "
+        "make group 1 steal 30%% of items from all other groups)",
+    )
+
+    parser.addini("cdist-justify-items", help="justify items strategy", default="none")
+    parser.addini(
+        "cdist-report-dir", help="cdist report dir", default=".", type="paths"
+    )
+    parser.addini("cdist-group-steal", help="cdist group steal", default=None)
+
+
+def pytest_configure(config: pytest.Config) -> None:
+    cdist_config = CdistConfig.from_pytest_config(config)
+    config.stash[_CDIST_CONFIG_KEY] = cdist_config
+
+
 def pytest_collection_modifyitems(
     session: pytest.Session, config: pytest.Config, items: list[pytest.Item]
 ) -> None:
-    cdist_option = config.getoption("cdist_group")
+    cdist_config = config.stash.get(_CDIST_CONFIG_KEY, None)
 
-    if cdist_option is None:
+    if cdist_config is None:
         return
 
-    report_dir: pathlib.Path = config.getoption("cdist_report_dir")
-    write_report: bool = config.getoption("cdist_report")
-    justify_items_strategy: Literal["none", "file", "scope"] = config.getoption(
-        "cdist_justify_items"
-    )
-    group_steal = _get_group_steal_opt(config.getoption("cdist_group_steal"))
-
-    current_group, total_groups = map(int, cdist_option.split("/"))
-    if not 0 < current_group <= total_groups:
-        raise pytest.UsageError(f"Unknown group {current_group}")
+    groups = _partition_list(items, cdist_config.total_groups)
 
-    # using whole numbers (2/2) is more intuitive for the CLI,
-    # but here we want to use the group numbers for zero-based indexing
-    current_group -= 1
+    if cdist_config.justify_items_strategy != "none":
+        groups = _justify_items(groups, strategy=cdist_config.justify_items_strategy)
 
-    groups = _partition_list(items, total_groups)
-    if justify_items_strategy != "none":
-        groups = _justify_items(groups, strategy=justify_items_strategy)
+    if os.getenv("PYTEST_XDIST_WORKER"):
+        groups = _justify_xdist_groups(groups)
 
-    # if os.getenv("PYTEST_XDIST_WORKER"):
-    groups = _justify_xdist_groups(groups)
-
-    if group_steal is not None:
-        target_group, amount_to_steal = group_steal
+    if cdist_config.group_steal is not None:
+        target_group, amount_to_steal = cdist_config.group_steal
         groups = _distribute_with_bias(
             groups,
             target=target_group,
             bias=amount_to_steal,
         )
 
-    new_items = groups.pop(current_group)
+    new_items = groups.pop(cdist_config.current_group)
     deselect = [item for group in groups for item in group]
 
-    if write_report:
-        report_dir.joinpath(f"pytest_cdist_report_{current_group + 1}.json").write_text(
+    if cdist_config.write_report:
+        cdist_config.report_dir.joinpath(
+            f"pytest_cdist_report_{cdist_config.current_group + 1}.json"
+        ).write_text(
             json.dumps(
                 {
-                    "group": current_group + 1,
-                    "total_groups": total_groups,
+                    "group": cdist_config.current_group + 1,
+                    "total_groups": cdist_config.total_groups,
                     "collected": [i.nodeid for i in items],
                     "selected": [i.nodeid for i in new_items],
                 }
@@ -177,3 +262,10 @@ def pytest_collection_modifyitems(
 
     if deselect:
         config.hook.pytest_deselected(items=deselect)
+
+
+def pytest_report_header(config: pytest.Config) -> list[str]:
+    cdist_config = config.stash.get(_CDIST_CONFIG_KEY, None)
+    if cdist_config is None:
+        return []
+    return ["cdist options: " + cdist_config.cli_options(config)]

pytest_cdist/py.typed

@@ -0,0 +1,6 @@
+def test_one():
+    assert True
+
+
+def test_two():
+    assert False