pytest-threadpool 0.2.0__py3-none-any.whl

pytest_threadpool/__init__.py

@@ -0,0 +1,6 @@
+"""pytest-threadpool: Parallel test execution for free-threaded Python."""
+
+from pytest_threadpool._api import not_parallelizable, parallelizable
+from pytest_threadpool._constants import ParallelScope
+
+__all__ = ["ParallelScope", "not_parallelizable", "parallelizable"]

pytest_threadpool/_api.py

@@ -0,0 +1,23 @@
+"""Public marker helpers for pytest-threadpool."""
+
+from typing import Literal
+
+import pytest
+
+
+def parallelizable(
+    scope: Literal["children", "parameters", "all"],
+) -> pytest.MarkDecorator:
+    """Mark a test/class/module for parallel execution.
+
+    Args:
+        scope: Parallelism strategy.
+            ``"children"`` -- all nested tests run concurrently.
+            ``"parameters"`` -- parametrized variants run concurrently.
+            ``"all"`` -- children + parameters combined.
+    """
+    return pytest.mark.parallelizable(scope)
+
+
+not_parallelizable: pytest.MarkDecorator = pytest.mark.not_parallelizable
+"""Opt out of inherited parallel execution."""

pytest_threadpool/_constants.py

@@ -0,0 +1,30 @@
+"""Constants and enums for pytest-threadpool."""
+
+from enum import StrEnum
+
+
+class ParallelScope(StrEnum):
+    """Parallelism strategies for test execution."""
+
+    CHILDREN = "children"
+    PARAMETERS = "parameters"
+    ALL = "all"
+
+
+PARALLEL_SCOPES = frozenset(s.value for s in ParallelScope)
+
+MARKER_PARALLELIZABLE = "parallelizable"
+MARKER_NOT_PARALLELIZABLE = "not_parallelizable"
+MARKER_PARALLEL_ONLY = "parallel_only"
+
+
+class _GroupPrefix(StrEnum):
+    """Internal group key prefixes for parallel batching."""
+
+    CLASS = "class"
+    MOD_CHILDREN = "mod_children"
+    PKG_CHILDREN = "pkg_children"
+    PARAMS = "params"
+
+
+SCOPE_NOT = "not"

pytest_threadpool/_fixtures.py

@@ -0,0 +1,79 @@
+"""Fixture finalizer save/restore helpers for parallel execution."""
+
+from _pytest.scope import Scope
+
+
+class FixtureManager:
+    """Helpers for saving/restoring fixture finalizers during parallel execution.
+
+    Uses protected members of pytest internals (FixtureDef, TopRequest,
+    SetupState) because there is no public API for direct finalizer
+    manipulation.  These are the same internals that pytest's own
+    runner.py and fixtures.py use.
+    """
+
+    @staticmethod
+    def save_and_clear_function_fixtures(item) -> list:
+        """After an item's setup, save its function-scoped fixture finalizers
+        and invalidate FixtureDef caches so the next item gets fresh fixtures.
+
+        Returns a list of saved finalizer callables for this item.
+        """
+        saved = []
+        request = getattr(item, "_request", None)
+        if not request or not hasattr(request, "_fixture_defs"):
+            return saved
+
+        # noinspection PyProtectedMember
+        # request._fixture_defs, fixturedef._scope, fixturedef._finalizers:
+        # No public API for direct finalizer access; mirrors pytest's own
+        # FixtureDef/TopRequest internals.
+        for fixturedef in request._fixture_defs.values():  # pyright: ignore[reportPrivateUsage]
+            if fixturedef._scope is Scope.Function:  # pyright: ignore[reportPrivateUsage]
+                saved.extend(fixturedef._finalizers)  # pyright: ignore[reportPrivateUsage]
+                fixturedef._finalizers.clear()  # pyright: ignore[reportPrivateUsage]
+                fixturedef.cached_result = None
+
+        return saved
+
+    @staticmethod
+    def clear_function_fixture_caches(item) -> None:
+        """Invalidate function-scoped fixture caches after a failed setup.
+
+        When setup fails, the fixture def's execute() raises before
+        registering in request._fixture_defs.  We use _arg2fixturedefs
+        (populated during collection) to find all candidate fixture defs.
+        """
+        request = getattr(item, "_request", None)
+        if not request:
+            return
+
+        # noinspection PyProtectedMember
+        # request._arg2fixturedefs: populated during collection, maps
+        # argname -> list[FixtureDef].  Unlike _fixture_defs, this is
+        # available even when setup fails mid-execution.
+        arg2fds = getattr(request, "_arg2fixturedefs", {})
+        for fixturedefs in arg2fds.values():  # pyright: ignore[reportPrivateUsage]
+            for fixturedef in fixturedefs:
+                if fixturedef._scope is Scope.Function and fixturedef.cached_result is not None:  # pyright: ignore[reportPrivateUsage]
+                    fixturedef.cached_result = None
+
+    @staticmethod
+    def save_collector_finalizers(session, next_item) -> list:
+        """Save finalizers from stack nodes that would be torn down when
+        transitioning to next_item.  Clears them from the stack so
+        teardown_exact() pops the nodes without side effects.
+
+        Returns a list of (node, [finalizers]) tuples.
+        """
+        needed = set(next_item.listchain())
+        saved = []
+        # noinspection PyProtectedMember
+        # session._setupstate: no public API for setup state management;
+        # mirrors pytest's own runner.py (SetupState).
+        for node in list(session._setupstate.stack):  # pyright: ignore[reportPrivateUsage]
+            if node not in needed:
+                fins_list, _exc_info = session._setupstate.stack[node]  # pyright: ignore[reportPrivateUsage]
+                saved.append((node, list(fins_list)))
+                fins_list.clear()
+        return saved

pytest_threadpool/_grouping.py

@@ -0,0 +1,106 @@
+"""Group key computation for parallel test batching."""
+
+from pytest_threadpool._constants import (
+    SCOPE_NOT,
+    ParallelScope,
+    _GroupPrefix,
+)
+from pytest_threadpool._markers import MarkerResolver
+
+
+class GroupKeyBuilder:
+    """Computes parallel batch group keys for test items."""
+
+    @staticmethod
+    def group_key(item) -> tuple | None:
+        """Compute a group key for parallel batching.
+
+        Returns a hashable key if the item should be part of a parallel batch,
+        or None for sequential execution.
+        Consecutive items with the same non-None key form a parallel batch.
+
+        Marker priority: not_parallelizable > own > class > module > package.
+        """
+        own = MarkerResolver.own_scope(item)
+        cls = MarkerResolver.class_scope(item)
+        mod = MarkerResolver.module_scope(item)
+        pkg = MarkerResolver.package_scope(item)
+
+        # not_parallelizable at any level forces sequential
+        if own == SCOPE_NOT:
+            return None
+        if item.cls and cls == SCOPE_NOT:
+            return None
+
+        child_parallel = False
+        param_parallel = False
+
+        # The most specific level with an explicit marker determines behavior
+        if own is not None:
+            if own == ParallelScope.ALL:
+                child_parallel = True
+                param_parallel = True
+            elif own == ParallelScope.PARAMETERS:
+                param_parallel = True
+        elif item.cls and cls is not None:
+            if cls in (ParallelScope.CHILDREN, ParallelScope.ALL):
+                child_parallel = True
+            if cls in (ParallelScope.PARAMETERS, ParallelScope.ALL):
+                param_parallel = True
+        elif mod is not None and mod != SCOPE_NOT:
+            if mod in (ParallelScope.CHILDREN, ParallelScope.ALL):
+                child_parallel = True
+            if mod in (ParallelScope.PARAMETERS, ParallelScope.ALL):
+                param_parallel = True
+        elif pkg is not None and pkg != SCOPE_NOT:
+            if pkg in (ParallelScope.CHILDREN, ParallelScope.ALL):
+                child_parallel = True
+            if pkg in (ParallelScope.PARAMETERS, ParallelScope.ALL):
+                param_parallel = True
+
+        if child_parallel:
+            if GroupKeyBuilder._is_package_level(item, own, cls, mod, pkg):
+                return (_GroupPrefix.PKG_CHILDREN, item.module.__package__)
+            if item.cls:
+                fp_key = MarkerResolver.fixture_param_key(item)
+                if fp_key:
+                    return (_GroupPrefix.CLASS, item.cls, fp_key)
+                return (_GroupPrefix.CLASS, item.cls)
+            return (_GroupPrefix.MOD_CHILDREN, id(item.module))
+
+        if param_parallel:
+            callspec = getattr(item, "callspec", None)
+            if callspec:
+                fp_key = MarkerResolver.fixture_param_key(item)
+                if fp_key:
+                    return (_GroupPrefix.PARAMS, item.cls, item.originalname, fp_key)
+                return (_GroupPrefix.PARAMS, item.cls, item.originalname)
+
+        return None
+
+    @staticmethod
+    def _is_package_level(item, own, cls, mod, pkg) -> bool:
+        """True when the effective children marker comes from the package level."""
+        if own is not None:
+            return False
+        if item.cls and cls is not None:
+            return False
+        if mod is not None and mod != SCOPE_NOT:
+            return False
+        return pkg is not None and pkg in (ParallelScope.CHILDREN, ParallelScope.ALL)
+
+    @staticmethod
+    def build_groups(items) -> list[tuple[object, list]]:
+        """Group consecutive items by parallel group key.
+
+        Returns a list of (key, [items]) tuples.
+        """
+        groups: list[tuple[object, list]] = []
+        prev_key = object()
+        for item in items:
+            key = GroupKeyBuilder.group_key(item)
+            if key != prev_key:
+                groups.append((key, []))
+                prev_key = key
+            groups[-1][1].append(item)
+        return groups

pytest_threadpool/_markers.py

@@ -0,0 +1,145 @@
+"""Marker introspection for resolving effective parallel scope."""
+
+import sys
+
+from pytest_threadpool._constants import (
+    MARKER_NOT_PARALLELIZABLE,
+    MARKER_PARALLEL_ONLY,
+    MARKER_PARALLELIZABLE,
+    PARALLEL_SCOPES,
+    SCOPE_NOT,
+)
+
+
+class MarkerResolver:
+    """Resolves the effective parallel scope for a test item.
+
+    Walks the marker priority chain: own > class > module > package.
+    """
+
+    @staticmethod
+    def scope_from_marks(marks) -> str | None:
+        """Extract a parallelizable scope from a list of pytest marks."""
+        if not isinstance(marks, (list, tuple)):
+            marks = [marks]
+        for m in marks:
+            if m.name == MARKER_PARALLELIZABLE:
+                scope = m.args[0] if m.args else ParallelScope.ALL
+                return scope if scope in PARALLEL_SCOPES else None
+        return None
+
+    @staticmethod
+    def has_not_marker(marks) -> bool:
+        """Check if marks contain not_parallelizable."""
+        if not isinstance(marks, (list, tuple)):
+            marks = [marks]
+        return any(m.name == MARKER_NOT_PARALLELIZABLE for m in marks)
+
+    @staticmethod
+    def own_scope(item) -> str | None:
+        """Parallel scope from the item's own markers (not inherited)."""
+        if any(m.name == MARKER_NOT_PARALLELIZABLE for m in item.own_markers):
+            return SCOPE_NOT
+        for m in item.own_markers:
+            if m.name == MARKER_PARALLELIZABLE:
+                scope = m.args[0] if m.args else ParallelScope.ALL
+                return scope if scope in PARALLEL_SCOPES else None
+        return None
+
+    @staticmethod
+    def class_scope(item) -> str | None:
+        """Parallel scope from the item's class."""
+        if not item.cls:
+            return None
+        marks = getattr(item.cls, "pytestmark", [])
+        if MarkerResolver.has_not_marker(marks):
+            return SCOPE_NOT
+        return MarkerResolver.scope_from_marks(marks)
+
+    @staticmethod
+    def module_scope(item) -> str | None:
+        """Parallel scope from the item's module."""
+        marks = getattr(item.module, "pytestmark", [])
+        if MarkerResolver.has_not_marker(marks):
+            return SCOPE_NOT
+        return MarkerResolver.scope_from_marks(marks)
+
+    @staticmethod
+    def package_scope(item) -> str | None:
+        """Parallel scope from the item's package hierarchy."""
+        pkg_name = getattr(item.module, "__package__", None)
+        if not pkg_name:
+            return None
+        parts = pkg_name.split(".")
+        for i in range(len(parts), 0, -1):
+            pkg = ".".join(parts[:i])
+            mod = sys.modules.get(pkg)
+            if mod is None:
+                continue
+            marks = getattr(mod, "pytestmark", [])
+            if MarkerResolver.has_not_marker(marks):
+                return SCOPE_NOT
+            scope = MarkerResolver.scope_from_marks(marks)
+            if scope:
+                return scope
+        return None
+
+    @staticmethod
+    def has_package_parallel_only(item) -> bool:
+        """Check if any package in the item's hierarchy has parallel_only."""
+        pkg_name = getattr(item.module, "__package__", None)
+        if not pkg_name:
+            return False
+        parts = pkg_name.split(".")
+        for i in range(len(parts), 0, -1):
+            mod = sys.modules.get(".".join(parts[:i]))
+            if mod is None:
+                continue
+            marks = getattr(mod, "pytestmark", [])
+            if not isinstance(marks, (list, tuple)):
+                marks = [marks]
+            if any(m.name == MARKER_PARALLEL_ONLY for m in marks):
+                return True
+        return False
+
+    @staticmethod
+    def parametrize_argnames(item) -> set[str]:
+        """Collect arg names from all @pytest.mark.parametrize markers."""
+        names = set()
+        for marker in item.iter_markers("parametrize"):
+            argnames = marker.args[0]
+            if isinstance(argnames, str):
+                names.update(n.strip() for n in argnames.split(","))
+            elif isinstance(argnames, (list, tuple)):
+                names.update(argnames)
+        return names
+
+    @staticmethod
+    def fixture_param_key(item) -> tuple:
+        """Extract non-@parametrize params (fixture params with broader scope).
+
+        These must stay in the group key to prevent merging groups whose
+        class/module/session-scoped fixtures differ.
+        """
+        from _pytest.scope import Scope
+
+        callspec = getattr(item, "callspec", None)
+        if not callspec or not callspec.params:
+            return ()
+        parametrize_names = MarkerResolver.parametrize_argnames(item)
+        # noinspection PyProtectedMember
+        # callspec._arg2scope: no public API; needed to identify
+        # function-scoped params from pytest_generate_tests (which
+        # don't produce parametrize markers visible to iter_markers).
+        arg2scope = getattr(callspec, "_arg2scope", {})
+        fixture_params = {
+            k: v
+            for k, v in callspec.params.items()
+            if k not in parametrize_names
+            and arg2scope.get(k, Scope.Function) is not Scope.Function
+        }
+        return tuple(sorted(fixture_params.items())) if fixture_params else ()
+
+
+# Import here to avoid circular; used only in scope_from_marks / own_scope
+from pytest_threadpool._constants import ParallelScope  # noqa: E402