pytest-threadpool 0.2.0__tar.gz

pytest_threadpool-0.2.0/.claude/settings.local.json

@@ -0,0 +1,30 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(PYTHON_GIL=0 .venv/bin/pytest:*)",
+      "Bash(.venv/bin/pytest:*)",
+      "Bash(python3:*)",
+      "Bash(uv run:*)",
+      "Bash(PYTHON_GIL=0 uv run:*)",
+      "Bash(do PYTHON_GIL=0:*)",
+      "Bash(python:*)",
+      "Bash(ls:*)",
+      "Bash(pip install:*)",
+      "Bash(pip show:*)",
+      "Bash(PYTHONPATH=/home/work/repos/pytest-freethreaded-example/src python:*)",
+      "Bash(/home/work/repos/pytest-freethreaded-example/.venv/bin/pip install:*)",
+      "Bash(uv pip:*)",
+      "Bash(grep:*)",
+      "Bash(wc:*)",
+      "Bash(git:*)",
+      "Read(//tmp/**)",
+      "Bash(mkdir -p test_debug)",
+      "Bash(cp /home/work/repos/pytest-freethreaded-example/tests/cases/setup_mixed_pass_fail.py /tmp/test_debug/test_case.py)",
+      "Bash(ruff check:*)",
+      "Bash(cat:*)",
+      "Bash(uv sync:*)",
+      "Bash(find:*)",
+      "Bash(find src:*)"
+    ]
+  }
+}

pytest_threadpool-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv sync --python 3.14t --group dev
+      - run: uv run ruff format --check src/ tests/
+      - run: uv run ruff check src/ tests/
+      - run: uv run pyright src/
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.13t", "3.14t", "3.15t"]
+    steps:
+      - uses: actions/checkout@v4
+      - 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: Upload coverage reports to Codecov
+        if: matrix.python == '3.14t'
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}

pytest_threadpool-0.2.0/.gitignore

@@ -0,0 +1,165 @@
+### Python template
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+uv.lock
+

pytest_threadpool-0.2.0/ANALYSIS.md

@@ -0,0 +1,142 @@
+# pytest-threadpool: Risk, Bug & Test Gap Analysis
+
+## Overview
+
+pytest-threadpool runs test bodies in parallel via `ThreadPoolExecutor` while keeping all pytest internals (fixtures, setup/teardown, reporting) sequential. This analysis covers risks, potential bugs, and missing test coverage.
+
+---
+
+## Potential Bugs
+
+### 1. ~~Empty `callable_items` after setup failures~~ [RESOLVED — Not a bug]
+
+**Debunked.** When `callable_items` is empty, `workers = 1` (line 365). The guard on line 409 (`if workers > 1 and len(callable_items) > 1`) prevents `ThreadPoolExecutor` creation — execution falls through to the `else` branch (lines 427–431), which iterates over the empty list harmlessly. Phase 3 then correctly reports setup failures via `_report_item`. No unnecessary thread pool is created and no misleading output is produced.
+
+### 2. ~~`_do_call` exception swallowing~~ [RESOLVED — Not a bug]
+
+**Debunked.** When `future.exception()` is not None (lines 416–422), the exception is wrapped in a `CallInfo` via `CallInfo.from_call()` and stored in `call_results[item]`. Then `_report_item(item)` is called immediately (line 426), which builds a report via `pytest_runtest_makereport` and fires `pytest_runtest_logreport` — properly recording it as a test failure in pytest's statistics. Exceptions are not swallowed; they follow the standard reporting path.
+
+### 3. ~~Fixture finalizer ordering after restore~~ [RESOLVED — Not a bug]
+
+**Debunked.** `save_and_clear_function_fixtures()` uses `saved.extend(fixturedef._finalizers)` iterating over `request._fixture_defs.values()`. Since Python 3.7+ dicts preserve insertion order (matching fixture resolution/setup order), and `_teardown_all` runs `for fn in reversed(fns)`, the result is correct LIFO ordering: later-resolved fixtures' finalizers run first, and within each fixture, finalizers run in reverse registration order — matching pytest's normal teardown semantics.
+
+### 4. ~~`sys.modules` iteration in `MarkerResolver.package_scope()`~~ [RESOLVED — Not a bug]
+
+**Debunked.** The code uses `sys.modules.get(pkg)` (line 76 of `_markers.py`) — a single-key dict lookup, not iteration. The analysis incorrectly claims the code "iterates `sys.modules`." Furthermore, `package_scope()` is only called during `GroupKeyBuilder.group_key()`, which runs during the sequential collection/grouping phase before any parallel execution begins. No thread-safety concern exists.
+
+### 5. ~~`_initrequest()` side effects~~ [RESOLVED — Not a bug, duplicate of Risk #1]
+
+**Debunked as a standalone bug.** The `_initrequest()` call mirrors pytest's own `runtestprotocol` in `_pytest/runner.py`. It's the standard way to initialize the request lifecycle for an item. The concern about private API stability is valid but is already covered under Risk #1 (heavy reliance on pytest private API). This is a maintenance risk, not a bug.
+
+---
+
+## Risks
+
+### 1. Heavy reliance on pytest private API (HIGH)
+
+The plugin accesses numerous protected members:
+- `item._request` / `item._initrequest()`
+- `request._fixture_defs`
+- `session._setupstate.stack`
+- `fixturedef._scope`, `._finalizers`, `.cached_result`
+- `TerminalReporter._tw`
+
+**Impact**: Any pytest minor release could break the plugin silently. No compatibility layer or version detection exists beyond `pytest >= 9.0.2`.
+
+### 2. No free-threaded runtime validation (MEDIUM)
+
+The plugin doesn't verify that it's running on free-threaded Python (`PYTHON_GIL=0` or 3.14t+). If run on a GIL-enabled build, tests will execute but without true parallelism, potentially masking concurrency bugs in user code that only manifest under real parallelism.
+
+### 3. Single lock for all terminal output (MEDIUM)
+
+`_LiveReporter` uses one `threading.Lock()` for state updates. The lock protects `_item_state` mutations but doesn't protect the actual terminal write operations in `_render()`. If `_render()` is called from the main thread while a worker thread calls `mark_done()`, the render could read partially-updated state.
+
+### 4. ANSI escape sequence fragility (LOW)
+
+The live reporter uses raw ANSI cursor movement (`\033[F`, `\033[K`) for in-place updates. This assumes:
+- Terminal supports ANSI sequences
+- No other output is written to stdout during rendering
+- Line count calculations are accurate
+
+Broken assumptions produce garbled terminal output.
+
+### 5. Hardcoded barrier timeouts in tests (LOW)
+
+Test cases use `threading.Barrier(N, timeout=10)`. On slow CI or high-contention environments, this could cause flaky test failures that look like concurrency bugs but are just timeout issues.
+
+### 6. ~~No signal/interrupt handling during parallel phase~~ [RESOLVED]
+
+Replaced ThreadPoolExecutor with a daemon-thread worker pool. On SIGINT, pending work items are abandoned (daemon threads exit with the process), fixture teardown still runs, and KeyboardInterrupt is re-raised for pytest's handler.
+
+---
+
+## Missing Tests
+
+### Error & Edge Cases
+- [x] Test body raises `SystemExit` or `KeyboardInterrupt` during parallel execution — tested, both caught and reported as failures
+- [x] All tests in a parallel group fail during setup (empty `callable_items`) — tested + fixed cached error leak
+- [x] Mixed setup pass/fail within a single parallel group — tested + fixed cached error leak
+- [ ] Non-pickleable objects in test state during parallel batches
+- [x] SIGINT during parallel execution phase — fixed with daemon-thread pool, exits promptly
+- [ ] Test that modifies `sys.modules` during parallel execution
+
+### Fixture Scenarios
+- [x] Fixtures with interdependent finalizers (finalizer A must run before finalizer B) — tested, LIFO ordering correct
+- [x] `autouse` fixtures with function scope in parallel groups — tested, works correctly
+- [x] Fixture teardown that raises exceptions in parallel groups — tested + fixed to run all finalizers
+- [ ] Complex fixture parameter combinations where scope changes mid-group
+- [ ] `yield` fixtures with cleanup that depends on execution order
+
+### Scope & Grouping
+- [ ] Deeply nested packages (3+ levels) with mixed marker inheritance
+- [x] Dynamic parametrize (e.g., `pytest_generate_tests`) with parallel markers — tested + fixed grouping bug
+- [x] Groups where all items have `not_parallelizable` — verify no thread pool created — tested, runs on MainThread
+- [ ] Very large groups (100+ tests) to verify thread pool scaling
+
+### Reporting
+- [ ] Mixed verbosity flags (`-v`, `-vv`, `-q`) with parallel output
+- [ ] `--tb=long` / `--tb=short` with parallel test failures
+- [ ] ~~Captured stdout/stderr from parallel tests~~ — capsys is process-global, incompatible with parallel execution by design
+- [ ] `--no-header` and other output-modifying flags
+- [ ] Plugin interaction with `pytest-xdist` (should error or warn)
+
+### Compatibility
+- [ ] Python 3.13t with explicit `PYTHON_GIL=0`
+- [ ] pytest version matrix (9.0.2, 9.1.x, 9.2.x, 10.x)
+- [ ] Interaction with common plugins (`pytest-cov`, `pytest-timeout`, `pytest-randomly`)
+
+### Concurrency Stress
+- [ ] High thread count (16, 32, 64 threads) with many small tests
+- [x] Tests that themselves spawn threads (nested parallelism) — tested, works correctly
+- [ ] Tests with heavy I/O (file writes to same directory) in parallel
+- [ ] Memory pressure: many parallel tests allocating large objects
+
+---
+
+## Summary
+
+| Category | Count | Status |
+|----------|-------|--------|
+| Potential bugs | 5 | **All 5 debunked** — none were actual bugs |
+| Risks | 6 | 1 high, 3 medium, 2 low (unchanged) |
+| Missing test areas | 25+ | Mixed (unchanged) |
+
+All five "potential bugs" were investigated and found to be incorrect or misleading claims. The code handles each scenario correctly. The highest-priority item remains the **dependency on pytest private API** (Risk #1). The second priority is adding **error/edge-case tests** for parallel execution failures.
+
+
+  ┌─────┬───────────────────────────────────────────┬─────────────────────────────────────────────────────────────────────────────────────────────┬───────────────────────────────────────────────┐
+  │  #  │                   Risk                    │                                            Real?                                            │                   Fixable?                    │
+  ├─────┼───────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────┤
+  │ 1   │ Private API reliance                      │ True — inherent to approach                                                                 │ No code fix possible — it's a design tradeoff │
+  ├─────┼───────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────┤
+  │ 2   │ No free-threaded runtime validation       │ True — but by design                                                                        │ Feature request, not a bug                    │
+  ├─────┼───────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────┤
+  │ 3   │ Single lock / unprotected terminal writes │ False — _render() doesn't exist; both mark_running and mark_done hold the lock when writing │ N/A                                           │
+  ├─────┼───────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────┤
+  │ 4   │ ANSI escape fragility                     │ True — already mitigated by plain-mode fallback                                             │ Low severity, no fix needed                   │
+  ├─────┼───────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────┤
+  │ 5   │ Hardcoded barrier timeouts                │ True — test-only concern                                                                    │ Low severity, no production code affected     │
+  ├─────┼───────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────┤
+  │ 6   │ No SIGINT handling                        │ True — ThreadPoolExecutor provides basic cleanup but Phase 4 teardown is skipped            │ Feature request, not a bug                    │
+  └─────┴───────────────────────────────────────────┴─────────────────────────────────────────────────────────────────────────────────────────────┴───────────────────────────────────────────────┘
+

pytest_threadpool-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,164 @@
+# Contributing to pytest-threadpool
+
+## Development setup
+
+```bash
+git clone <repo-url>
+cd pytest-threadpool
+./scripts/setup-dev        # defaults to python 3.14t
+./scripts/setup-dev 3.13t  # or specify a version
+```
+
+This installs a free-threaded Python via uv, syncs all dependencies (including
+dev tools), and sets up a pre-commit hook that runs `ruff format`, `ruff check`,
+and `pyright` before each commit.
+
+> Python 3.13t and 3.14t ship with the GIL disabled by default.
+
+## Architecture rules
+
+### No module-level executable code
+
+All modules define classes, functions, constants, and imports only. No mutable
+state, no object construction, no side effects at import time.
+
+`__init__.py` files contain only markers and imports — never barriers, dicts,
+lists, or other state.
+
+The single exception is `plugin.py`, which defines bare functions that pytest
+discovers as hooks.
+
+### One module, one class
+
+Each module contains a single primary class. A second class is only allowed
+when it is tightly coupled to the first (e.g., two enums in the same domain).
+If a class grows unrelated responsibilities, split it into a new module.
+
+### Shared state lives in classes
+
+Any mutable state needed across tests or across a test run must be held as
+class attributes or instance attributes — never as module-level variables.
+
+```python
+# Good
+class TestState:
+    log = {}
+    barrier = threading.Barrier(3, timeout=10)
+
+# Bad
+_log = {}
+_barrier = threading.Barrier(3, timeout=10)
+```
+
+### Access on need, not on import
+
+State should be created and accessed at the point of use. Importing a module
+should not trigger construction of barriers, connections, or other resources.
+
+### Parallelism tests use `ftdir` fixture
+
+Tests that verify parallel execution (barriers, concurrent writes, thread counts)
+must use the `ftdir` fixture (defined in `conftest.py`) and `run_pytest`. Unlike
+`pytester`, `ftdir` is thread-safe — it uses `tmp_path` instead of `os.chdir()`,
+so tests can run in parallel via `--threadpool` on the outer suite itself.
+
+Each test writes files into its own `tmp_path` directory and runs pytest as a
+subprocess with the exact thread count needed. Use explicit thread counts for
+barrier-based tests (not `auto`) to avoid deadlocks on low-core machines.
+
+```python
+# Good — isolated subprocess via ftdir, explicit thread count
+def test_children_run_concurrently(self, ftdir):
+    ftdir.makepyfile("""
+        import threading, pytest
+        @pytest.mark.parallelizable("children")
+        class TestBarrier:
+            barrier = threading.Barrier(2, timeout=10)
+            def test_a(self): self.barrier.wait()
+            def test_b(self): self.barrier.wait()
+    """)
+    result = ftdir.run_pytest("--threadpool", "2")
+    result.assert_outcomes(passed=2)
+
+# Bad — depends on outer runner flags
+class TestBarrier:
+    barrier = threading.Barrier(2, timeout=10)
+    def test_a(self): self.barrier.wait()
+    def test_b(self): self.barrier.wait()
+```
+
+### Constants over strings
+
+Use `ParallelScope` enum and `_constants` module instead of bare string
+literals. Any string that appears in more than one location belongs in
+`_constants.py`. Enums must use `StrEnum` (not `str, Enum`).
+
+### Plugin hooks are wiring only
+
+`plugin.py` hook functions delegate to classes immediately. No business logic
+in hook functions — keep them thin.
+
+## Project structure
+
+```
+src/pytest_threadpool/
+    __init__.py       # Re-exports only
+    _api.py           # Public API: parallelizable, not_parallelizable
+    _constants.py     # ParallelScope and _GroupPrefix enums
+    _markers.py       # MarkerResolver: marker introspection
+    _grouping.py      # GroupKeyBuilder: parallel batch grouping
+    _fixtures.py      # FixtureManager: finalizer save/restore
+    _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
+```
+
+## Commit message style
+
+Every commit message starts with one or more tags in brackets:
+
+```
+[Tag] Short description
+```
+
+### Tags
+
+| Tag | Scope |
+|-----|-------|
+| `[Runner]` | Core parallel execution engine (`_runner.py`, `_fixtures.py`) |
+| `[Markers]` | Marker resolution and grouping (`_markers.py`, `_grouping.py`, `_constants.py`) |
+| `[Report]` | Terminal reporting and display (`_LiveReporter`) |
+| `[Plugin]` | Plugin hooks and CLI options (`plugin.py`) |
+| `[API]` | Public API changes (`_api.py`, `__init__.py`) |
+| `[Test]` | Test additions or changes only |
+| `[Tooling]` | Ruff, pyright, pre-commit, CI, scripts |
+| `[Docs]` | README, CONTRIBUTING, docstrings |
+| `[Refactor]` | Internal restructuring, no behavior change |
+| `[Fix]` | Bug fix — must include issue number if fixing a known issue |
+
+### Combining tags
+
+Tags can be combined. The fix tag always comes first and includes the issue
+number when one exists:
+
+```
+[Fix #42][Runner] Prevent deadlock when setup fails mid-group
+[Fix][Report] Correct progress count after skipped tests
+[Test][Markers] Add coverage for nested package marker inheritance
+[Tooling] Add ruff PIE and RET rule sets
+```
+
+## Running tests
+
+```bash
+# Run all tests in parallel (each test spawns its own subprocess)
+pytest --threadpool auto
+
+# Run sequentially
+pytest -v
+```