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

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

@@ -3,6 +3,7 @@ name: CI
 on:
   push:
     branches: [main]
+    tags-ignore: ["v*"]
   pull_request:
     branches: [main]
   workflow_call:
@@ -25,7 +26,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python: ["3.13t", "3.14t", "3.15t"]
+        python: ["3.13", "3.13t", "3.14", "3.14t", "3.15", "3.15t"]
     steps:
       - uses: actions/checkout@v4
         with:

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

@@ -13,7 +13,9 @@ 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.
+> Free-threaded builds (3.13t, 3.14t, 3.15t) ship with the GIL disabled and
+> provide true parallelism. Standard builds (3.13, 3.14, 3.15) are also
+> supported — threads work, but the GIL serializes CPU-bound code.
 
 ## Architecture rules
 

{pytest_threadpool-0.3.3 → pytest_threadpool-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pytest-threadpool
-Version: 0.3.3
+Version: 0.3.4
 Summary: Parallel test execution for free-threaded Python builds
 License-Expression: MIT
 License-File: LICENSE
@@ -10,6 +10,9 @@ 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
@@ -18,18 +21,22 @@ Description-Content-Type: text/markdown
 # pytest-threadpool
 
 [![PyPI - Version](https://img.shields.io/pypi/v/pytest-threadpool)](https://pypi.org/project/pytest-threadpool/)
-[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pytest-threadpool)](https://pypi.org/project/pytest-threadpool/)
+[![Python](https://img.shields.io/badge/python-3.13%20%7C%203.13t%20%7C%203.14%20%7C%203.14t%20%7C%203.15%20%7C%203.15t-blue?logo=python&logoColor=white)](https://pypi.org/project/pytest-threadpool/)
 [![License](https://img.shields.io/github/license/pytest-threadpool/pytest-threadpool)](https://github.com/pytest-threadpool/pytest-threadpool/blob/main/LICENSE)
 [![GitHub](https://img.shields.io/badge/GitHub-pytest--threadpool-blue?logo=github)](https://github.com/pytest-threadpool/pytest-threadpool)
 [![CI](https://github.com/pytest-threadpool/pytest-threadpool/actions/workflows/ci.yml/badge.svg)](https://github.com/pytest-threadpool/pytest-threadpool/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/pytest-threadpool/pytest-threadpool/branch/main/graph/badge.svg)](https://codecov.io/gh/pytest-threadpool/pytest-threadpool)
 
-**Status: Beta** · Parallel test execution for free-threaded Python builds (3.13t+).
+**Status: Beta** · Parallel test execution using threads.
 
 Runs test *bodies*, function-scoped fixture setup, and function-scoped fixture
 teardown concurrently in a thread pool while keeping shared fixtures
 (module/class/session scope) sequential.
 
+Works on any Python 3.13+. Free-threaded builds (3.13t, 3.14t, 3.15t) get true
+parallelism for CPU-bound tests. Standard builds still benefit from parallel
+execution of I/O-bound tests (network, database, file operations).
+
 ## Installation
 
 ```bash
@@ -167,9 +174,12 @@ pytest
 
 | Component | Versions |
 |-----------|----------|
-| Python    | 3.13t, 3.14t, 3.15t |
+| Python    | 3.13, 3.13t, 3.14, 3.14t, 3.15, 3.15t |
 | 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.
+
 ## Known limitations
 
 - **Private pytest API usage** — The plugin relies on internal `_pytest` APIs

{pytest_threadpool-0.3.3 → pytest_threadpool-0.3.4}/README.md

@@ -1,18 +1,22 @@
 # pytest-threadpool
 
 [![PyPI - Version](https://img.shields.io/pypi/v/pytest-threadpool)](https://pypi.org/project/pytest-threadpool/)
-[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pytest-threadpool)](https://pypi.org/project/pytest-threadpool/)
+[![Python](https://img.shields.io/badge/python-3.13%20%7C%203.13t%20%7C%203.14%20%7C%203.14t%20%7C%203.15%20%7C%203.15t-blue?logo=python&logoColor=white)](https://pypi.org/project/pytest-threadpool/)
 [![License](https://img.shields.io/github/license/pytest-threadpool/pytest-threadpool)](https://github.com/pytest-threadpool/pytest-threadpool/blob/main/LICENSE)
 [![GitHub](https://img.shields.io/badge/GitHub-pytest--threadpool-blue?logo=github)](https://github.com/pytest-threadpool/pytest-threadpool)
 [![CI](https://github.com/pytest-threadpool/pytest-threadpool/actions/workflows/ci.yml/badge.svg)](https://github.com/pytest-threadpool/pytest-threadpool/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/pytest-threadpool/pytest-threadpool/branch/main/graph/badge.svg)](https://codecov.io/gh/pytest-threadpool/pytest-threadpool)
 
-**Status: Beta** · Parallel test execution for free-threaded Python builds (3.13t+).
+**Status: Beta** · Parallel test execution using threads.
 
 Runs test *bodies*, function-scoped fixture setup, and function-scoped fixture
 teardown concurrently in a thread pool while keeping shared fixtures
 (module/class/session scope) sequential.
 
+Works on any Python 3.13+. Free-threaded builds (3.13t, 3.14t, 3.15t) get true
+parallelism for CPU-bound tests. Standard builds still benefit from parallel
+execution of I/O-bound tests (network, database, file operations).
+
 ## Installation
 
 ```bash
@@ -150,9 +154,12 @@ pytest
 
 | Component | Versions |
 |-----------|----------|
-| Python    | 3.13t, 3.14t, 3.15t |
+| Python    | 3.13, 3.13t, 3.14, 3.14t, 3.15, 3.15t |
 | 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.
+
 ## Known limitations
 
 - **Private pytest API usage** — The plugin relies on internal `_pytest` APIs

pytest_threadpool-0.3.4/codecov.yml

@@ -0,0 +1,11 @@
+coverage:
+  status:
+    project:
+      default:
+        target: auto
+        threshold: 1%
+    patch:
+      default:
+        target: auto
+
+comment: false

pytest_threadpool-0.3.4/examples/__init__.py

@@ -0,0 +1,3 @@
+from pytest_threadpool import parallelizable
+
+pytestmark = parallelizable("all")

pytest_threadpool-0.3.4/examples/test_di/__init__.py

@@ -0,0 +1 @@
+

pytest_threadpool-0.3.4/examples/test_di/conftest.py

@@ -0,0 +1,28 @@
+"""Fixtures resolving from the static DI container.
+
+- ``request_handler`` injects a fresh RequestHandler per test (Factory).
+- ``test_context`` injects a per-test TestContext (ContextLocal, reset per test).
+"""
+
+import pytest
+
+from examples.test_di.container import Container
+
+
+@pytest.fixture
+def request_handler():
+    """Fresh RequestHandler per test (Factory provider)."""
+    return Container.request_handler()
+
+
+@pytest.fixture
+def test_context():
+    """Per-test TestContext — ContextLocal + reset = test-local scope.
+
+    ContextLocal uses contextvars, so the instance follows the execution
+    context — not the OS thread.  Safe across await boundaries.
+    The reset() in teardown gives the next test a fresh instance.
+    """
+    ctx = Container.test_context()
+    yield ctx
+    Container.test_context.reset()

pytest_threadpool-0.3.4/examples/test_di/container.py

@@ -0,0 +1,44 @@
+"""DI container wiring four provider scopes — pure stdlib, no GIL re-enablement.
+
+- Singleton:      one Config for the entire session
+- ThreadLocal:    one DbConnection per worker thread
+- ContextLocal:   one TestContext per test (survives await, reset between tests)
+- Factory:        fresh RequestHandler every injection
+
+All providers are class attributes — use ``Container.config()`` etc. directly.
+
+.. note::
+
+   The `dependency-injector <https://github.com/ets-labs/python-dependency-injector>`_
+   library offers similar provider scopes, but its C-extension is not marked as
+   free-threaded safe.  On 3.13t+ builds Python will fall back to the GIL-enabled
+   interpreter when it is imported, negating the benefit of free-threaded execution.
+   This example uses pure-stdlib providers to avoid that limitation.
+"""
+
+from examples.test_di.providers import ContextLocal, Factory, Singleton, ThreadLocal
+from examples.test_di.services import Config, DbConnection, RequestHandler, TestContext
+
+
+class Container:
+    config = Singleton(
+        Config,
+        db_url="postgresql://localhost/testdb",
+        pool_size=4,
+    )
+
+    db_connection = ThreadLocal(
+        DbConnection,
+        config=config,
+    )
+
+    test_context = ContextLocal(
+        TestContext,
+        config=config,
+    )
+
+    request_handler = Factory(
+        RequestHandler,
+        db=db_connection,
+        config=config,
+    )

pytest_threadpool-0.3.4/examples/test_di/providers.py

@@ -0,0 +1,104 @@
+"""Pure-stdlib DI providers — no C extensions, no GIL re-enablement.
+
+Four scopes built on threading and contextvars primitives:
+
+- ``Singleton``:        one instance for the process lifetime (thread-safe).
+- ``ThreadLocal``:      one instance per OS thread.
+- ``ContextLocal``:     one instance per execution context (survives await).
+- ``Factory``:          fresh instance on every call.
+"""
+
+import contextlib
+import contextvars
+import threading
+from typing import Any
+
+
+class Singleton:
+    """Thread-safe singleton — one instance for the entire process."""
+
+    def __init__(self, cls: type, **kwargs: Any):
+        self._cls = cls
+        self._kwargs = kwargs
+        self._instance: Any = None
+        self._lock = threading.Lock()
+
+    def __call__(self) -> Any:
+        if self._instance is None:
+            with self._lock:
+                if self._instance is None:
+                    self._instance = self._cls(**self._resolve_kwargs())
+        return self._instance
+
+    def reset(self) -> None:
+        with self._lock:
+            self._instance = None
+
+    def _resolve_kwargs(self) -> dict:
+        return {k: v() if callable(v) else v for k, v in self._kwargs.items()}
+
+
+class ThreadLocal:
+    """Thread-local singleton — one instance per OS thread."""
+
+    def __init__(self, cls: type, **kwargs: Any):
+        self._cls = cls
+        self._kwargs = kwargs
+        self._local = threading.local()
+
+    def __call__(self) -> Any:
+        try:
+            return self._local.instance
+        except AttributeError:
+            self._local.instance = self._cls(**self._resolve_kwargs())
+            return self._local.instance
+
+    def reset(self) -> None:
+        with contextlib.suppress(AttributeError):
+            del self._local.instance
+
+    def _resolve_kwargs(self) -> dict:
+        return {k: v() if callable(v) else v for k, v in self._kwargs.items()}
+
+
+class ContextLocal:
+    """Context-local singleton — one instance per execution context.
+
+    Uses ``contextvars.ContextVar``, so the instance follows the async
+    execution flow across ``await`` boundaries, even if the coroutine
+    resumes on a different OS thread.
+    """
+
+    _SENTINEL = object()
+
+    def __init__(self, cls: type, **kwargs: Any):
+        self._cls = cls
+        self._kwargs = kwargs
+        self._var: contextvars.ContextVar = contextvars.ContextVar(f"_di_{cls.__name__}")
+
+    def __call__(self) -> Any:
+        instance = self._var.get(self._SENTINEL)
+        if instance is self._SENTINEL:
+            instance = self._cls(**self._resolve_kwargs())
+            self._var.set(instance)
+        return instance
+
+    def reset(self) -> None:
+        self._var.set(self._SENTINEL)  # type: ignore[arg-type]
+
+    def _resolve_kwargs(self) -> dict:
+        return {k: v() if callable(v) else v for k, v in self._kwargs.items()}
+
+
+class Factory:
+    """Factory — fresh instance on every call."""
+
+    def __init__(self, cls: type, **kwargs: Any):
+        self._cls = cls
+        self._kwargs = kwargs
+
+    def __call__(self) -> Any:
+        return self._cls(**self._resolve_kwargs())
+
+    def _resolve_kwargs(self) -> dict:
+        return {k: v() if callable(v) else v for k, v in self._kwargs.items()}

pytest_threadpool-0.3.4/examples/test_di/services.py

@@ -0,0 +1,53 @@
+"""Minimal service classes for the DI example."""
+
+import threading
+import uuid
+
+
+class Config:
+    """Application config — intended as a Singleton (shared across all tests)."""
+
+    def __init__(self, db_url: str, pool_size: int):
+        self.db_url = db_url
+        self.pool_size = pool_size
+        self.instance_id = uuid.uuid4()
+
+
+class DbConnection:
+    """Database connection — intended as ThreadLocal (one per worker thread).
+
+    In a real app this would be sqlalchemy.Session, asyncpg.Connection, etc.
+    """
+
+    def __init__(self, config: Config):
+        self.config = config
+        self.instance_id = uuid.uuid4()
+        self.thread_id = threading.current_thread().ident
+
+
+class TestContext:
+    """Per-test context — intended as ContextLocal (one per execution context).
+
+    In a real app this would be a request context, unit-of-work, or
+    transaction that should be the same instance within one test
+    but fresh for each test.  Any function can resolve it from the
+    container without receiving it as a parameter.
+    """
+
+    def __init__(self, config: Config):
+        self.config = config
+        self.instance_id = uuid.uuid4()
+        self.data: dict = {}
+
+
+class RequestHandler:
+    """Request handler — intended as Factory (fresh instance per injection).
+
+    In a real app this would be a use-case, service, or controller object
+    that gets a fresh instance per test / per request.
+    """
+
+    def __init__(self, db: DbConnection, config: Config):
+        self.db = db
+        self.config = config
+        self.instance_id = uuid.uuid4()

pytest_threadpool-0.3.4/examples/test_di/test_factory.py

@@ -0,0 +1,19 @@
+"""Factory scope: fresh RequestHandler for every injection."""
+
+import threading
+from typing import ClassVar
+
+import pytest
+
+
+class TestFactory:
+    """RequestHandler is a Factory — every injection must be a fresh instance."""
+
+    _seen_ids: ClassVar[set] = set()
+    _lock = threading.Lock()
+
+    @pytest.mark.parametrize("_worker", range(6))
+    def test_handler_is_fresh(self, request_handler, _worker):
+        with self._lock:
+            assert request_handler.instance_id not in self._seen_ids, "Factory reused an instance"
+            self._seen_ids.add(request_handler.instance_id)

pytest_threadpool-0.3.4/examples/test_di/test_local.py

@@ -0,0 +1,99 @@
+"""ContextLocal (per-test) scope: same instance within a test, fresh between tests.
+
+Pattern: ContextLocal provider + per-test reset in fixture teardown.
+
+Any function can resolve ``Container.test_context()`` and get the same
+instance as the calling test — even across ``await`` boundaries that may
+resume on a different thread.  ``ContextLocal`` uses ``contextvars``
+under the hood, so the context follows the execution flow, not the OS thread.
+
+Parallel tests each run in their own context, so writes in one test
+never leak into another.
+"""
+
+import asyncio
+import functools
+import threading
+from typing import ClassVar
+
+import pytest
+
+from examples.test_di.container import Container
+
+
+def async_test(fn):
+    """Run an async test function in its own event loop."""
+
+    @functools.wraps(fn)
+    def wrapper(*args, **kwargs):
+        return asyncio.run(fn(*args, **kwargs))
+
+    return wrapper
+
+
+def _helper_that_reads_from_container() -> dict:
+    """Simulate a function deep in the call stack resolving from the container."""
+    return Container.test_context().data
+
+
+def _helper_that_writes_to_container(key: str, value: str) -> None:
+    """Simulate a function deep in the call stack writing to the context."""
+    Container.test_context().data[key] = value
+
+
+async def _async_helper_that_reads_from_container() -> dict:
+    """Async function that resolves the context — may run on a different thread."""
+    await asyncio.sleep(0.01)
+    return Container.test_context().data
+
+
+class TestLocal:
+    """Each test gets its own TestContext via ContextLocal + reset."""
+
+    _seen_ids: ClassVar[set] = set()
+    _lock = threading.Lock()
+
+    @pytest.mark.parametrize("_worker", range(6))
+    def test_write_then_read_from_container(self, test_context, _worker):
+        """Test writes to context, a helper resolves the same context from the container."""
+        test_context.data["worker"] = str(_worker)
+
+        data = _helper_that_reads_from_container()
+
+        assert data["worker"] == str(_worker)
+        assert data is test_context.data
+
+    @pytest.mark.parametrize("_worker", range(6))
+    def test_helper_writes_visible_to_test(self, test_context, _worker):
+        """A helper writes via the container, the test sees it through its fixture."""
+        _helper_that_writes_to_container("source", "helper")
+
+        assert test_context.data["source"] == "helper"
+
+    @pytest.mark.parametrize("_worker", range(6))
+    def test_parallel_tests_are_isolated(self, test_context, _worker):
+        """Each parallel test starts with an empty context — no cross-test leakage."""
+        assert test_context.data == {}, f"Context leaked from another test: {test_context.data}"
+        test_context.data["mine"] = str(_worker)
+
+    @pytest.mark.parametrize("_worker", range(6))
+    def test_context_is_fresh_per_test(self, test_context, _worker):
+        """Each test invocation gets a unique TestContext instance."""
+        with self._lock:
+            assert test_context.instance_id not in self._seen_ids, (
+                "ContextLocal+reset reused an instance across tests"
+            )
+            self._seen_ids.add(test_context.instance_id)
+
+    @async_test
+    @pytest.mark.parametrize("_worker", range(6))
+    async def test_context_survives_await(self, test_context, _worker):
+        """Context is preserved across await boundaries that may switch threads."""
+        test_context.data["before_await"] = str(_worker)
+
+        await asyncio.sleep(0.01)
+
+        data = await _async_helper_that_reads_from_container()
+
+        assert data["before_await"] == str(_worker)
+        assert data is test_context.data

pytest_threadpool-0.3.4/examples/test_di/test_singleton.py

@@ -0,0 +1,20 @@
+"""Singleton scope: one Config instance shared across all tests."""
+
+import threading
+from typing import ClassVar
+
+import pytest
+
+
+class TestSingleton:
+    """Config is a Singleton — every test must see the exact same instance."""
+
+    _seen_ids: ClassVar[set] = set()
+    _lock = threading.Lock()
+
+    @pytest.mark.parametrize("_worker", range(6))
+    def test_config_is_shared(self, request_handler, _worker):
+        config = request_handler.config
+        with self._lock:
+            self._seen_ids.add(config.instance_id)
+            assert len(self._seen_ids) == 1, f"Singleton produced {len(self._seen_ids)} instances"

pytest_threadpool-0.3.4/examples/test_di/test_thread_local.py

@@ -0,0 +1,77 @@
+"""ThreadLocal scope: one DbConnection per worker thread.
+
+ThreadLocal binds to the OS thread.  This means it does NOT survive
+``await`` boundaries — if the event loop resumes a coroutine on a
+different thread, a new instance is created.  Use ContextLocal
+(see test_local.py) when you need context that follows the execution
+flow across awaits.
+"""
+
+import asyncio
+import functools
+import threading
+from typing import ClassVar
+
+import pytest
+
+from examples.test_di.container import Container
+
+
+def async_test(fn):
+    """Run an async test function in its own event loop."""
+
+    @functools.wraps(fn)
+    def wrapper(*args, **kwargs):
+        return asyncio.run(fn(*args, **kwargs))
+
+    return wrapper
+
+
+class TestThreadLocal:
+    """DbConnection is ThreadLocal — same instance within a thread,
+    different instances across threads.
+    """
+
+    _ids_by_thread: ClassVar[dict] = {}
+    _lock = threading.Lock()
+
+    @pytest.mark.parametrize("_worker", range(6))
+    def test_db_is_per_thread(self, request_handler, _worker):
+        db = request_handler.db
+        tid = threading.current_thread().ident
+        with self._lock:
+            if tid in self._ids_by_thread:
+                assert self._ids_by_thread[tid] == db.instance_id, (
+                    "ThreadLocal returned different instance on same thread"
+                )
+            else:
+                self._ids_by_thread[tid] = db.instance_id
+
+    @async_test
+    @pytest.mark.parametrize("_worker", range(6))
+    async def test_thread_local_does_not_survive_await(self, _worker):
+        """ThreadLocal may return a different instance after an await.
+
+        If ``asyncio.run()`` uses a thread pool internally, an ``await``
+        can resume on a different OS thread — and ThreadLocal is keyed
+        by thread, so it produces a new instance.  This is the key
+        difference from ContextLocal.
+        """
+        before = Container.db_connection()
+        before_tid = threading.current_thread().ident
+
+        results: dict = {}
+
+        async def resolve_after_await():
+            await asyncio.sleep(0.01)
+            results["db"] = Container.db_connection()
+            results["tid"] = threading.current_thread().ident
+
+        await resolve_after_await()
+
+        if before_tid != results["tid"]:
+            assert before.instance_id != results["db"].instance_id, (
+                "ThreadLocal returned same instance on different thread"
+            )
+        else:
+            assert before.instance_id == results["db"].instance_id

pytest_threadpool-0.3.4/examples/test_logging/test_file_logging.py

@@ -0,0 +1,30 @@
+"""Per-test file logging — each test writes to its own log file.
+
+When you need persistent debug output that survives the test run
+(e.g. for CI artifacts), write to a file in ``tmp_path``.  Each test
+gets its own temporary directory, so no coordination is needed.
+
+After the run, inspect logs in the ``tmp_path_factory`` base dir
+or configure CI to upload the ``/tmp/pytest-*`` tree as artifacts.
+"""
+
+from time import sleep
+
+import pytest
+
+
+class TestFileLogging:
+    """Each test writes debug output to its own temp file."""
+
+    @pytest.mark.parametrize("_worker", range(4))
+    def test_per_test_log_file(self, _worker, tmp_path):
+        """Write debug data to a file in tmp_path — isolated per test."""
+        log_file = tmp_path / "debug.log"
+
+        with log_file.open("w") as f:
+            f.write(f"worker {_worker}: starting\n")
+            sleep(0.01)
+            f.write(f"worker {_worker}: done\n")
+
+        lines = log_file.read_text().splitlines()
+        assert lines == [f"worker {_worker}: starting", f"worker {_worker}: done"]