pytest-threadpool 0.3.4__tar.gz → 0.3.5__tar.gz

{pytest_threadpool-0.3.4 → pytest_threadpool-0.3.5}/.github/workflows/ci.yml

@@ -34,9 +34,23 @@ jobs:
       - uses: astral-sh/setup-uv@v6
       - run: uv python install ${{ matrix.python }}
       - run: uv sync --python ${{ matrix.python }} --group dev
-      - run: uv run --python ${{ matrix.python }} pytest -v --tb=short --cov --cov-branch --cov-report=xml
+      - name: Run tests
+        id: tests
+        env:
+          COVERAGE_PROCESS_START: pyproject.toml
+        run: uv run --python ${{ matrix.python }} coverage run -m pytest -v --tb=short
+      - name: Generate coverage report
+        if: always() && steps.tests.outcome != 'cancelled'
+        run: |
+          uv run --python ${{ matrix.python }} coverage combine
+          uv run --python ${{ matrix.python }} coverage report --format=markdown >> "$GITHUB_STEP_SUMMARY"
+          uv run --python ${{ matrix.python }} coverage xml
+          sed -i 's|<source></source>|<source>.</source>|' coverage.xml
       - name: Upload coverage reports to Codecov
-        if: matrix.python == '3.14t'
+        if: always() && matrix.python == '3.14t' && steps.tests.outcome != 'cancelled'
         uses: codecov/codecov-action@v5
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
+          files: coverage.xml
+          fail_ci_if_error: true
+          verbose: true

pytest_threadpool-0.3.5/.pre-commit-config.yaml

@@ -0,0 +1,17 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.6
+    hooks:
+      - id: ruff-format
+        args: [--check, src/, tests/]
+      - id: ruff
+        args: [src/, tests/]
+
+  - repo: local
+    hooks:
+      - id: pyright
+        name: pyright
+        entry: uv run pyright src/
+        language: system
+        types: [python]
+        pass_filenames: false

pytest_threadpool-0.3.5/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## 0.3.5
+
+### Fixes
+
+- Fixed crash (KeyError) when a worker thread throws an unexpected exception
+  outside the normal test lifecycle — failures are now reported gracefully
+  instead of taking down the entire test run.
+- `--threadpool` with a non-numeric value (e.g. `--threadpool foo`) now raises
+  a clean `pytest.UsageError` instead of an unhandled `ValueError` traceback.
+- `@parallelizable("children")` applied directly to a test function now emits
+  a warning explaining that functions have no children, instead of being
+  silently ignored.
+
+### Cleanup
+
+- Moved `ParallelScope` import to module top in `_markers.py`, removed
+  misleading circular-import comment.

{pytest_threadpool-0.3.4 → pytest_threadpool-0.3.5}/CONTRIBUTING.md

@@ -127,9 +127,6 @@ src/pytest_threadpool/
     _runner.py        # ParallelRunner: parallel execution orchestration
     plugin.py         # pytest hook implementations (wiring only)
 
-hooks/
-    pre-commit        # Git pre-commit hook (ruff + pyright)
-
 scripts/
     setup-dev         # One-command dev environment setup
 ```

pytest_threadpool-0.3.4/README.md → pytest_threadpool-0.3.5/PKG-INFO

@@ -1,3 +1,26 @@
+Metadata-Version: 2.4
+Name: pytest-threadpool
+Version: 0.3.5
+Summary: Parallel test execution for free-threaded Python builds
+Project-URL: Homepage, https://github.com/pytest-threadpool/pytest-threadpool
+Project-URL: Source, https://github.com/pytest-threadpool/pytest-threadpool
+Project-URL: Issues, https://github.com/pytest-threadpool/pytest-threadpool/issues
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: free-threaded,nogil,parallel,pytest,pytest parallel,testing,threadpool
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.13
+Requires-Dist: pytest<=9.0.2,>=9.0.0
+Description-Content-Type: text/markdown
+
 # pytest-threadpool
 
 [![PyPI - Version](https://img.shields.io/pypi/v/pytest-threadpool)](https://pypi.org/project/pytest-threadpool/)
@@ -36,22 +59,28 @@ from pytest_threadpool import parallelizable, not_parallelizable
 
 import pytest
 
-@parallelizable("children")     # all nested tests run in parallel
+
+@parallelizable("children")  # all nested tests run in parallel
 class TestMyFeature:
-    def test_a(self): ...
-    def test_b(self): ...
+  def test_a(self): ...
+
+  def test_b(self): ...
 
-@parallelizable("parameters")   # parametrized variants run in parallel
+
+@parallelizable("parameters")  # parametrized variants run in parallel
 @pytest.mark.parametrize("x", [1, 2, 3])
 def test_with_params(x): ...
 
-@parallelizable("all")          # children + parameters combined
+
+@parallelizable("all")  # children + parameters combined
 class TestEverything:
-    @pytest.mark.parametrize("n", [1, 2])
-    def test_param(self, n): ...
-    def test_plain(self): ...
+  @pytest.mark.parametrize("n", [1, 2])
+  def test_param(self, n): ...
+
+  def test_plain(self): ...
 
-@not_parallelizable             # opt out of inherited parallelism
+
+@not_parallelizable  # opt out of inherited parallelism
 def test_must_be_sequential(): ...
 ```
 
@@ -72,8 +101,8 @@ state between concurrent fixture setups.
 Shared fixtures (module, class, and session scope) are resolved once
 sequentially before workers launch and served from cache to all items.
 
-| Scope      | Behavior                                        |
-|------------|-------------------------------------------------|
+| Scope      | Behavior                                                |
+|------------|---------------------------------------------------------|
 | `function` | Cloned per-item, setup and teardown in parallel workers |
 | `class`    | Resolved once, cached, shared across items              |
 | `module`   | Resolved once, cached, shared across items              |
@@ -103,33 +132,33 @@ import pytest
 
 
 class SharedState:
-    lock = threading.Lock()          # not pickleable
-    event = threading.Event()        # not pickleable
-    results = {}
+  lock = threading.Lock()  # not pickleable
+  event = threading.Event()  # not pickleable
+  results = {}
 
 
 @pytest.mark.parallelizable("children")
 class TestGroupA:
-    def test_a1(self):
-        with SharedState.lock:
-            SharedState.results["a1"] = True
+  def test_a1(self):
+    with SharedState.lock:
+      SharedState.results["a1"] = True
 
-    def test_a2(self):
-        with SharedState.lock:
-            SharedState.results["a2"] = True
+  def test_a2(self):
+    with SharedState.lock:
+      SharedState.results["a2"] = True
 
 
 @pytest.mark.parallelizable("children")
 class TestGroupB:
-    def test_b1(self):
-        SharedState.event.set()
-        with SharedState.lock:
-            SharedState.results["b1"] = True
-
-    def test_b2(self):
-        assert SharedState.event.wait(timeout=10)
-        with SharedState.lock:
-            SharedState.results["b2"] = True
+  def test_b1(self):
+    SharedState.event.set()
+    with SharedState.lock:
+      SharedState.results["b1"] = True
+
+  def test_b2(self):
+    assert SharedState.event.wait(timeout=10)
+    with SharedState.lock:
+      SharedState.results["b2"] = True
 ```
 
 Objects like `threading.Lock`, `threading.Event`, `logging.Logger`, database
@@ -152,14 +181,28 @@ pytest
 
 ## Tested versions
 
-| Component | Versions |
-|-----------|----------|
+| Component | Versions                              |
+|-----------|---------------------------------------|
 | Python    | 3.13, 3.13t, 3.14, 3.14t, 3.15, 3.15t |
-| pytest    | >=9.0.2 |
+| pytest    | 9.0.2                                 |
 
 > **Note:** On standard (GIL-enabled) builds, the GIL limits parallel speedup
 > for CPU-bound tests. I/O-bound tests still run concurrently.
 
+## Examples
+
+The [`examples/`](examples/) directory contains runnable usage patterns:
+
+- **DI container** — dependency injection with Singleton, ThreadLocal, ContextLocal, and Factory scopes
+- **Event bus** — shared in-memory test double with concurrent producers and aggregate verification
+- **Parallel logging** — shared thread-safe log collector (caplog alternative)
+- **Shared state** — barriers, atomic counters, and cross-group coordination
+- **User pool** — custom thread pool with LIFO queue recycling
+
+The [`tests/integration_tests/cases/`](tests/integration_tests/cases/) and
+[`tests/integration_tests/`](tests/integration_tests/) directories are also
+worth browsing for real-world grouping, fixture, and reporting scenarios.
+
 ## Known limitations
 
 - **Private pytest API usage** — The plugin relies on internal `_pytest` APIs
@@ -168,10 +211,18 @@ pytest
 - **No plugin compatibility guarantees** — Interactions with other pytest
   plugins (e.g. `pytest-xdist`, `pytest-timeout`, `pytest-randomly`) are
   untested and may conflict.
-- **No captured stdout in parallel** — Standard output from tests running
-  concurrently is written directly to the terminal. Pytest's built-in capture
-  (`capsys`/`capfd`) is not supported during parallel execution.
+- **No `capsys`/`capfd`/`caplog` in parallel** — These fixtures are not
+  thread-safe. `capsys`/`capfd` fail with "cannot use capsys and capsys at
+  the same time" when requested by parallel tests. `caplog` leaks records
+  across fixtures and its `at_level()` context managers race on the shared
+  root logger. Alternatives:
+  - **`print()`** — Worker output is suppressed by default (buffered by
+    thread-local stream proxies). Pass `-s` (`--capture=no`) to disable
+    suppression and see interleaved output.
+  - **Logging** — Use a per-test `FileHandler` writing to `tmp_path`, or
+    collect structured records in a shared thread-safe list (see
+    [`examples/test_logging/`](examples/test_logging/)).
 
 ## License
 
-MIT
+[Apache 2.0](LICENSE)

pytest_threadpool-0.3.4/PKG-INFO → pytest_threadpool-0.3.5/README.md

@@ -1,23 +1,3 @@
-Metadata-Version: 2.4
-Name: pytest-threadpool
-Version: 0.3.4
-Summary: Parallel test execution for free-threaded Python builds
-License-Expression: MIT
-License-File: LICENSE
-Keywords: free-threaded,nogil,parallel,pytest,pytest parallel,testing,threadpool
-Classifier: Development Status :: 4 - Beta
-Classifier: Framework :: Pytest
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Programming Language :: Python :: 3.15
-Classifier: Topic :: Software Development :: Testing
-Requires-Python: >=3.13
-Requires-Dist: pytest>=9.0.2
-Description-Content-Type: text/markdown
-
 # pytest-threadpool
 
 [![PyPI - Version](https://img.shields.io/pypi/v/pytest-threadpool)](https://pypi.org/project/pytest-threadpool/)
@@ -56,22 +36,28 @@ from pytest_threadpool import parallelizable, not_parallelizable
 
 import pytest
 
-@parallelizable("children")     # all nested tests run in parallel
+
+@parallelizable("children")  # all nested tests run in parallel
 class TestMyFeature:
-    def test_a(self): ...
-    def test_b(self): ...
+  def test_a(self): ...
+
+  def test_b(self): ...
 
-@parallelizable("parameters")   # parametrized variants run in parallel
+
+@parallelizable("parameters")  # parametrized variants run in parallel
 @pytest.mark.parametrize("x", [1, 2, 3])
 def test_with_params(x): ...
 
-@parallelizable("all")          # children + parameters combined
+
+@parallelizable("all")  # children + parameters combined
 class TestEverything:
-    @pytest.mark.parametrize("n", [1, 2])
-    def test_param(self, n): ...
-    def test_plain(self): ...
+  @pytest.mark.parametrize("n", [1, 2])
+  def test_param(self, n): ...
+
+  def test_plain(self): ...
 
-@not_parallelizable             # opt out of inherited parallelism
+
+@not_parallelizable  # opt out of inherited parallelism
 def test_must_be_sequential(): ...
 ```
 
@@ -92,8 +78,8 @@ state between concurrent fixture setups.
 Shared fixtures (module, class, and session scope) are resolved once
 sequentially before workers launch and served from cache to all items.
 
-| Scope      | Behavior                                        |
-|------------|-------------------------------------------------|
+| Scope      | Behavior                                                |
+|------------|---------------------------------------------------------|
 | `function` | Cloned per-item, setup and teardown in parallel workers |
 | `class`    | Resolved once, cached, shared across items              |
 | `module`   | Resolved once, cached, shared across items              |
@@ -123,33 +109,33 @@ import pytest
 
 
 class SharedState:
-    lock = threading.Lock()          # not pickleable
-    event = threading.Event()        # not pickleable
-    results = {}
+  lock = threading.Lock()  # not pickleable
+  event = threading.Event()  # not pickleable
+  results = {}
 
 
 @pytest.mark.parallelizable("children")
 class TestGroupA:
-    def test_a1(self):
-        with SharedState.lock:
-            SharedState.results["a1"] = True
+  def test_a1(self):
+    with SharedState.lock:
+      SharedState.results["a1"] = True
 
-    def test_a2(self):
-        with SharedState.lock:
-            SharedState.results["a2"] = True
+  def test_a2(self):
+    with SharedState.lock:
+      SharedState.results["a2"] = True
 
 
 @pytest.mark.parallelizable("children")
 class TestGroupB:
-    def test_b1(self):
-        SharedState.event.set()
-        with SharedState.lock:
-            SharedState.results["b1"] = True
-
-    def test_b2(self):
-        assert SharedState.event.wait(timeout=10)
-        with SharedState.lock:
-            SharedState.results["b2"] = True
+  def test_b1(self):
+    SharedState.event.set()
+    with SharedState.lock:
+      SharedState.results["b1"] = True
+
+  def test_b2(self):
+    assert SharedState.event.wait(timeout=10)
+    with SharedState.lock:
+      SharedState.results["b2"] = True
 ```
 
 Objects like `threading.Lock`, `threading.Event`, `logging.Logger`, database
@@ -172,14 +158,28 @@ pytest
 
 ## Tested versions
 
-| Component | Versions |
-|-----------|----------|
+| Component | Versions                              |
+|-----------|---------------------------------------|
 | Python    | 3.13, 3.13t, 3.14, 3.14t, 3.15, 3.15t |
-| pytest    | >=9.0.2 |
+| pytest    | 9.0.2                                 |
 
 > **Note:** On standard (GIL-enabled) builds, the GIL limits parallel speedup
 > for CPU-bound tests. I/O-bound tests still run concurrently.
 
+## Examples
+
+The [`examples/`](examples/) directory contains runnable usage patterns:
+
+- **DI container** — dependency injection with Singleton, ThreadLocal, ContextLocal, and Factory scopes
+- **Event bus** — shared in-memory test double with concurrent producers and aggregate verification
+- **Parallel logging** — shared thread-safe log collector (caplog alternative)
+- **Shared state** — barriers, atomic counters, and cross-group coordination
+- **User pool** — custom thread pool with LIFO queue recycling
+
+The [`tests/integration_tests/cases/`](tests/integration_tests/cases/) and
+[`tests/integration_tests/`](tests/integration_tests/) directories are also
+worth browsing for real-world grouping, fixture, and reporting scenarios.
+
 ## Known limitations
 
 - **Private pytest API usage** — The plugin relies on internal `_pytest` APIs
@@ -188,10 +188,18 @@ pytest
 - **No plugin compatibility guarantees** — Interactions with other pytest
   plugins (e.g. `pytest-xdist`, `pytest-timeout`, `pytest-randomly`) are
   untested and may conflict.
-- **No captured stdout in parallel** — Standard output from tests running
-  concurrently is written directly to the terminal. Pytest's built-in capture
-  (`capsys`/`capfd`) is not supported during parallel execution.
+- **No `capsys`/`capfd`/`caplog` in parallel** — These fixtures are not
+  thread-safe. `capsys`/`capfd` fail with "cannot use capsys and capsys at
+  the same time" when requested by parallel tests. `caplog` leaks records
+  across fixtures and its `at_level()` context managers race on the shared
+  root logger. Alternatives:
+  - **`print()`** — Worker output is suppressed by default (buffered by
+    thread-local stream proxies). Pass `-s` (`--capture=no`) to disable
+    suppression and see interleaved output.
+  - **Logging** — Use a per-test `FileHandler` writing to `tmp_path`, or
+    collect structured records in a shared thread-safe list (see
+    [`examples/test_logging/`](examples/test_logging/)).
 
 ## License
 
-MIT
+[Apache 2.0](LICENSE)

pytest_threadpool-0.3.5/ROADMAP.md

@@ -0,0 +1,83 @@
+# Roadmap
+
+## Capture fixture support (capsys / capfd / caplog)
+
+**Goal:** Make `capsys`, `capfd`, and `caplog` work transparently in parallel tests.
+
+**Problem:** These fixtures assume exclusive ownership of global state (`sys.stdout`,
+root logger) during a test's lifetime. When multiple tests run concurrently, output
+interleaves and pytest raises "cannot use capsys and capsys at the same time".
+`caplog` leaks records across tests, and `at_level()` context managers race on the
+shared root logger.
+
+**Approach:** Delayed replay — collect output per-worker during parallel execution,
+then feed it back one item at a time during the sequential reporting phase.
+
+- **capsys/capfd:** The `_ThreadLocalStream` proxy already buffers worker output
+  into per-thread `StringIO`. Instead of discarding on `deactivate()`, associate
+  each buffer with its test item and flush to the real stream before
+  `pytest_runtest_makereport` reads the capture.
+
+- **caplog:** Install a per-thread `logging.Handler` that collects records into a
+  thread-local list. During sequential reporting, replay records into caplog's
+  handler so the fixture sees the correct records for each test.
+
+**Edge cases to handle:**
+- Nested captures (fixtures that call `capsys.readouterr()` mid-test)
+- `caplog.at_level()` context managers across threads
+- Fixtures that mix capsys with print output
+- `capfd` (file descriptor level) vs `capsys` (sys.stdout level)
+
+**Priority:** High — this is the most common friction point for adoption.
+
+## Harden FixtureDef cloning
+
+**Goal:** Make function-scoped fixture cloning more robust against pytest internals
+changes and more transparent to developers.
+
+**Current approach:** `clone_function_fixturedefs` uses `__new__` + `__dict__.update`
+for a shallow copy, then resets `cached_result` and `_finalizers`. This works because
+those are the only two fields mutated during fixture lifecycle — but it's fragile.
+
+**Improvements:**
+
+- **Deep-copy guard:** Validate at clone time that the only mutable fields are the
+  ones we reset. If a future pytest version adds mutable state to `FixtureDef`,
+  the clone should fail loudly (assertion or warning) rather than silently sharing
+  state across workers.
+
+- **Document fixture chain isolation:** When fixture A (function-scoped) depends on
+  fixture B (also function-scoped), both get cloned independently. Chain resolution
+  works because `_arg2fixturedefs` is replaced as a whole, so `getfixturevalue("B")`
+  hits B's clone. This is correct but non-obvious — add inline comments explaining
+  the chain resolution path through the cloned map.
+
+- **`object.__setattr__` on `_arg2fixturedefs`:** Currently bypasses the `Final`
+  typing annotation. If pytest ever enforces immutability at runtime (frozen
+  dataclass, `__slots__`), this breaks. Track whether upstream adds a setter or
+  public mutation API.
+
+**Priority:** Medium — current implementation works, but one pytest release could
+break it silently.
+
+## Plugin compatibility testing
+
+Validate and document interactions with commonly used pytest plugins:
+
+- `pytest-randomly` — test reordering vs parallel group formation
+- `pytest-timeout` — per-test timeouts in worker threads
+- `pytest-repeat` — repeated test execution in parallel groups
+- `pytest-cov` — coverage collection across worker threads
+
+## Public pytest API migration
+
+Track pytest releases for public equivalents of internal APIs currently used:
+
+- `_pytest.fixtures.FixtureDef._finalizers`
+- `_pytest.fixtures.FixtureDef.cached_result`
+- `_pytest.setupplan.SetupState.stack`
+- `_pytest.scope.Scope`
+- `callspec._arg2scope`
+
+Migrate to public APIs as they become available to reduce breakage risk
+across pytest releases.

{pytest_threadpool-0.3.4 → pytest_threadpool-0.3.5}/codecov.yml

@@ -8,4 +8,7 @@ coverage:
       default:
         target: auto
 
+ignore:
+  - "src/pytest_threadpool/_version.py"
+
 comment: false

pytest_threadpool-0.3.5/examples/test_event_bus/event_bus.py

@@ -0,0 +1,85 @@
+"""In-memory event bus — thread-safe test double.
+
+A minimal pub/sub bus that records all published events. Tests publish
+events concurrently, then verify delivery, ordering, and deduplication
+against the shared log.
+
+With pytest-xdist this would require an external broker (Redis, RabbitMQ)
+or a socket-based mock server since each worker is a separate process.
+With pytest-threadpool it's a plain Python object protected by a Lock.
+"""
+
+import threading
+from typing import ClassVar
+
+
+class EventBus:
+    """Thread-safe in-memory event bus for testing."""
+
+    _lock = threading.Lock()
+    _events: ClassVar[list[dict]] = []
+    _subscribers: ClassVar[dict[str, list]] = {}
+    _waiters: ClassVar[list[tuple[str | None, int, threading.Event]]] = []
+
+    @classmethod
+    def publish(cls, topic: str, payload: dict) -> None:
+        with cls._lock:
+            event = {"topic": topic, "payload": payload, "thread": threading.current_thread().name}
+            cls._events.append(event)
+            for callback in cls._subscribers.get(topic, []):
+                callback(event)
+            cls._check_waiters()
+
+    @classmethod
+    def subscribe(cls, topic: str, callback) -> None:
+        with cls._lock:
+            cls._subscribers.setdefault(topic, []).append(callback)
+
+    @classmethod
+    def events(cls, topic: str | None = None) -> list[dict]:
+        with cls._lock:
+            if topic is None:
+                return list(cls._events)
+            return [e for e in cls._events if e["topic"] == topic]
+
+    @classmethod
+    def wait_for(cls, count: int, topic: str | None = None, timeout: float = 10) -> list[dict]:
+        """Block until at least ``count`` events match, then return them."""
+        ready = threading.Event()
+        with cls._lock:
+            matched = cls._filter(topic)
+            if len(matched) >= count:
+                return matched
+            cls._waiters.append((topic, count, ready))
+        if not ready.wait(timeout=timeout):
+            actual = len(cls.events(topic))
+            label = f"topic={topic!r}" if topic else "all topics"
+            raise TimeoutError(
+                f"EventBus.wait_for: expected {count} events on {label}, "
+                f"got {actual} after {timeout}s"
+            )
+        return cls.events(topic)
+
+    @classmethod
+    def reset(cls) -> None:
+        with cls._lock:
+            cls._events.clear()
+            cls._subscribers.clear()
+            cls._waiters.clear()
+
+    @classmethod
+    def _check_waiters(cls) -> None:
+        """Signal any waiters whose condition is met. Must hold _lock."""
+        remaining = []
+        for topic, count, event in cls._waiters:
+            if len(cls._filter(topic)) >= count:
+                event.set()
+            else:
+                remaining.append((topic, count, event))
+        cls._waiters[:] = remaining
+
+    @classmethod
+    def _filter(cls, topic: str | None) -> list[dict]:
+        if topic is None:
+            return list(cls._events)
+        return [e for e in cls._events if e["topic"] == topic]