punit 1.12.2__tar.gz → 1.12.3__tar.gz

{punit-1.12.2/src/pUnit.egg-info → punit-1.12.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pUnit
-Version: 1.12.2
+Version: 1.12.3
 Summary: A modernized unit-test framework for Python.
 Author-email: Shaun Wilson <mrshaunwilson@msn.com>
 License-Expression: MIT

{punit-1.12.2 → punit-1.12.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pUnit"
-version = "1.12.2"
+version = "1.12.3"
 description = "A modernized unit-test framework for Python."
 keywords = ["test", "unittest", "unit-test", "xUnit", "nUnit", "pytest"]
 authors = [

{punit-1.12.2 → punit-1.12.3/src/pUnit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pUnit
-Version: 1.12.2
+Version: 1.12.3
 Summary: A modernized unit-test framework for Python.
 Author-email: Shaun Wilson <mrshaunwilson@msn.com>
 License-Expression: MIT

{punit-1.12.2 → punit-1.12.3}/src/pUnit.egg-info/SOURCES.txt

@@ -13,10 +13,9 @@ src/punit/TextIOCapture.py
 src/punit/__init__.py
 src/punit/__main__.py
 src/punit/cli.py
-src/punit/parallel.py
+src/punit/parallelism.py
 src/punit/py.typed
 src/punit/runner.py
-src/punit/sequential.py
 src/punit/assertions/__init__.py
 src/punit/assertions/collections.py
 src/punit/assertions/exceptions.py

{punit-1.12.2 → punit-1.12.3}/src/punit/__init__.py

@@ -14,12 +14,12 @@ from .conditions import skip
 from .teardowns import Teardown, teardown
 from .theories import theory, inlinedata
 from .traits import trait
-from .sequential import sequential
+from .parallelism import parallel, sequential
 
 from . import mocks
 
-__version__ = '1.12.2'
-__commit__ = '3afa951'
+__version__ = '1.12.3'
+__commit__ = 'f1990b5'
 __all__ = [
     '__version__', '__commit__',
     'assertions',
@@ -36,4 +36,5 @@ __all__ = [
     'fails',
     'skip',
     'sequential',
+    'parallel',
 ]

{punit-1.12.2 → punit-1.12.3}/src/punit/cli.py

@@ -205,7 +205,7 @@ class CommandLineInterface:
         return self.__aliases
 
     @property
-    def parallel(self) -> int | None:
+    def parallelism(self) -> int | None:
         return self.__parallelism
 
     @property

punit-1.12.2/src/punit/parallel.py → punit-1.12.3/src/punit/parallelism.py

@@ -2,14 +2,90 @@
 # SPDX-License-Identifier: MIT
 
 """
-Parallel test execution infrastructure for pUnit.
+Parallelism for pUnit.
 
-Provides a pool of worker threads, each with its own asyncio event loop,
-for executing tests in parallel.
+pUnit provides three mechanisms for controlling test execution parallelism:
+the **``--parallel [THREADS]``** CLI flag, the **``@parallel``** decorator,
+and the **``@sequential``** decorator.
+
+CLI flag
+--------
+The ``--parallel [THREADS]`` option enables multi-threaded parallel execution.
+Each worker thread runs its own asyncio event loop for isolation.
+
+* ``--parallel`` (bare flag, no number) runs tests using
+  ``cpu_count // 2`` workers.
+* ``--parallel N`` runs tests using *N* workers.
+* No flag means tests run sequentially, one after another.
+
+When parallel mode is active the runner processes each test file in four
+batches: parallel facts, parallel theories, sequential facts, then
+sequential theories.
+
+@parallel decorator
+-------------------
+Marking a fact or theory with ``@parallel`` triggers **auto-enable** mode.
+When pUnit scans the test package and finds at least one ``@parallel``
+decorated test (and no ``--parallel`` flag was given on the CLI):
+
+* Parallel execution is enabled automatically with
+  ``cpu_count // 2`` workers.
+* **Only** ``@parallel``-marked tests run in the concurrent batch.
+* All other tests are treated as sequential (as if they carried ``@sequential``).
+
+Applying ``@parallel`` to a **class** marks every method of that class.
+
+``@parallel`` is a no-op when ``--parallel`` is specified on the CLI; the
+CLI flag takes full priority.
+
+@sequential decorator
+---------------------
+Marking a fact or theory with ``@sequential`` forces it to run as a
+sequential test **after** all parralel tests for that file have
+completed.  This lets you co-run certain tests one-at-a-time inside
+an otherwise parallel test suite (for example, tests that share mutable
+state).
+
+When no ``@parallel`` decorator is present and ``--parallel`` is not used
+on the CLI, all tests run sequentially (the default).
+
+Examples
+--------
+
+Enable parallel mode for the entire test package via CLI::
+
+    punit tests/ --parallel 4
+
+Run only selected tests in parallel -- no CLI flag needed::
+
+    from punit import fact, parallel
+
+    @fact
+    @parallel
+    def test_network_io():
+        ...
+
+    @fact
+    def test_database_setup():
+        # Runs sequentially alongside the parallel tests
+        ...
+
+Mix parallel and sequential tests inside a parallel suite::
+
+    from punit import fact, parallel, sequential
+
+    @parallel
+    class SlowTests:
+        @fact
+        def test_heavy_computation(self):
+            ...
+
+        @fact
+        @sequential
+        def test_shared_file_handle(self):
+            # Runs one-at-a-time after all other SlowTests finish
+            ...
 
-Each test is wrapped in a coroutine that creates a ``TestResult``, runs
-setup -> test -> teardown, and yields the populated result.  The main thread
-dispatches these coroutines to worker threads and collects the results.
 """
 
 from __future__ import annotations
@@ -20,7 +96,7 @@ import queue
 import threading
 import time
 from types import ModuleType
-from typing import Any
+from typing import Any, Callable
 
 from .TestResult import TestResult
 
@@ -239,7 +315,7 @@ async def _execute_fact(
 
 async def _execute_theory(
     theory: Any,
-    data: tuple,
+    data: tuple[Any, ...],
     module: ModuleType,
     module_report_name: str,
     filename: str,
@@ -330,6 +406,151 @@ async def _execute_theory(
     return result
 
 
+def sequential(target: Callable[..., Any] | type) -> Callable[..., Any]:
+    """Mark a test function, method, or class for **sequential** execution.
+
+    When pUnit is started with ``--parallel THREADS`` (where *THREADS* > 1),
+    tests decorated without ``@sequential`` run in parallel up to *N* at
+    any given point.  ``@sequential`` tests are **not** added to the
+    concurrent dispatch queue -- after all peers at the same scope finish
+    concurrently, the sequential tests run one after another in their
+    definition order.
+
+    When applied to a **class**, all methods of the class are automatically
+    marked as sequential.
+
+    The decorator returns the original ``target`` unchanged; it installs the
+    ``__punit_sequential`` marker attribute on the unwrapped function (or the
+    class object itself for class targets).
+
+    Parameters
+    ----------
+    target : Callable | type
+        The test function, method, or class to mark.
+
+    Returns
+    -------
+    Callable
+        The original, undecorated target.
+
+    Example
+    -------
+
+    .. code-block:: python
+
+        from punit import fact, sequential
+
+        @fact
+        @sequential
+        def my_test():
+            assert True
+
+        class MyTestCase:
+            @fact
+            @sequential
+            def test_one(self):
+                assert True
+
+        # Apply @sequential to an entire class -- all methods run sequentially
+        @sequential
+        class SequentialTestCase:
+            @fact
+            def test_one(self):
+                assert True
+
+            @fact
+            def test_two(self):
+                assert True
+
+    """
+    import inspect
+
+    if isinstance(target, type):
+        setattr(target, "__punit_sequential", True)
+        for name, method in inspect.getmembers(target, predicate=inspect.isfunction):
+            setattr(method, "__punit_sequential", True)
+        return target
+
+    unwrapped = inspect.unwrap(target)
+    setattr(unwrapped, "__punit_sequential", True)
+    return target
+
+
+def parallel(target: Callable[..., Any]) -> Callable[..., Any]:
+    """Mark a test function, method, or class for **parallel** execution.
+
+    When pUnit detects any ``@parallel``-decorated tests in a test package at
+    runtime, it automatically triggers (multi-threaded) parallel execution for
+    the entire test run -- no ``--parallel`` CLI flag is required.
+
+    When ``@parallel`` triggers auto-enable:
+
+    * Only tests marked with ``@parallel`` run in the parallel batch
+    * Tests not marked with ``@parallel`` are treated as sequential
+      (as if decorated with ``@sequential``)
+    * The thread pool is initialized with ``cpu_count // 2`` workers
+    * This auto-enable is superseded by ``--parallel`` on the CLI
+
+    When ``--parallel`` is specified on the CLI, this decorator has no effect;
+    the existing ``--parallel`` behavior takes priority and all
+    non-``@sequential`` tests run in parallel as before.
+
+    When applied to a class, all methods of the class are automatically marked
+    as parallel.
+
+    The decorator returns the original ``target`` unchanged; it installs the
+    ``__punit_parallel`` marker attribute on the unwrapped function (or the
+    class object itself for class targets).
+
+    Parameters
+    ----------
+    target : Callable | type
+        The test function, method, or class to mark.
+
+    Returns
+    -------
+    Callable
+        The original, undecorated target.
+
+    Example
+    -------
+
+    .. code-block:: python
+
+        from punit import fact, parallel
+
+        @fact
+        @parallel
+        def my_parallel_test():
+            assert True
+
+        class ParallelTestCase:
+            @fact
+            @parallel
+            def test_one(self):
+                assert True
+
+            @fact
+            def test_sequential(self):
+                # Runs sequentially (not in parallel batch)
+                assert True
+
+    """
+    import inspect
+
+    if isinstance(target, type):
+        setattr(target, "__punit_parallel", True)
+        for name, method in inspect.getmembers(target, predicate=inspect.isfunction):
+            setattr(method, "__punit_parallel", True)
+        return target
+
+    unwrapped = inspect.unwrap(target)
+    setattr(unwrapped, "__punit_parallel", True)
+    return target
+
+
 __all__ = [
-    'ThreadPool'
+    'ThreadPool',
+    'parallel',
+    'sequential'
 ]

{punit-1.12.2 → punit-1.12.3}/src/punit/runner.py

@@ -13,7 +13,7 @@ from typing import Any, Callable, Optional
 
 from .TextIOCapture import setup_global_text_io, _PERSISTENT_STDOUT, _PERSISTENT_STDERR
 from .cli import CommandLineInterface
-from .parallel import ThreadPool, _execute_fact, _execute_theory
+from .parallelism import ThreadPool, _execute_fact, _execute_theory
 from .facts.FactManager import FactManager
 from .setups.SetupManager import SetupManager
 from .teardowns.TeardownManager import TeardownManager
@@ -43,19 +43,25 @@ def _is_sequential(target: Any) -> bool:
     return getattr(unwrapped, '__punit_sequential', None) is True
 
 
+def _is_parallel(target: Any) -> bool:
+    """Return True if *target* is marked with ``@parallel``."""
+    unwrapped = inspect.unwrap(target)
+    return getattr(unwrapped, '__punit_parallel', None) is True
+
+
 def _get_parallelism(cli: 'CommandLineInterface') -> int:
     """Resolve the parallelism level from CLI.
 
-    Returns ``-1`` when parallel mode is disabled (use sequential flow).
+    Returns ``-1`` when parallelism is disabled (use sequential flow).
     Returns the worker count when enabled; ``0`` maps to ``cpu_count // 2``.
     """
-    mode = cli.parallel
-    if mode is None:
+    parallelism = cli.parallelism
+    if parallelism is None:
         return -1
-    if mode <= 0:
+    if parallelism <= 0:
         cores = os.cpu_count() or 1
         return max(1, cores // 2)
-    return mode
+    return parallelism
 
 
 class TestRunner:
@@ -167,6 +173,22 @@ class TestRunner:
         if self.__cli.verbose and (not test_result.is_success) and test_result.exception is not None:
             print(f'Test File:\n    {test_result.file_name}\nError:\n    {test_result.exception}\n    Traceback:\n{"".join(traceback.format_tb(test_result.exception.__traceback__))}')
 
+    def __detect_parallel_tests(self) -> bool:
+        """Return True if any registered fact or theory is marked with ``@parallel``."""
+        fm = FactManager.instance()
+        modules = getattr(fm, '_FactManager__modules', {})
+        for facts in modules.values():
+            for fact in facts:
+                if _is_parallel(fact.target):
+                    return True
+        tm = TheoryManager.instance()
+        modules = getattr(tm, '_TheoryManager__modules', {})
+        for theories in modules.values():
+            for theory in theories:
+                if _is_parallel(theory.target):
+                    return True
+        return False
+
     async def __run_facts(self, host_name: str, test_module: ModuleType, filename: str, module_report_name: str, results: list[TestResult]) -> None:
         """Run all facts for a test module and return their results."""
         facts = FactManager.instance().get(test_module.__name__)
@@ -288,6 +310,14 @@ class TestRunner:
         if parallelism > 0:
             return await self._run_parallel(results, test_package_path)
 
+        # Auto-enable parallel mode when @parallel-decorated tests are detected
+        has_parallel_tests = self.__detect_parallel_tests()
+        if has_parallel_tests:
+            cores = os.cpu_count() or 1
+            parallelism = max(1, cores // 2)
+            await self._run_parallel_parallel_only(results, test_package_path, parallelism)
+            return results
+
         for filename in self.__filenames:
             ts = time.time()
             if not self.__test_package_name:
@@ -333,6 +363,82 @@ class TestRunner:
     # Parallel execution
     # ------------------------------------------------------------------
 
+    async def _run_parallel_parallel_only(
+        self,
+        results: list[TestResult],
+        test_package_path: str,
+        parallelism: int,
+    ) -> None:
+        """Execute ``@parallel``-decorated tests in a worker pool, rest sequentially.
+
+        This is used when ``@parallel`` decorators are detected at runtime and
+        no ``--parallel`` CLI flag was provided: only tests marked with
+        ``@parallel`` go into the parallel batch, everything else runs one-by-one.
+        """
+        try:
+            pool = ThreadPool(parallelism)
+            with pool:
+                module_report_name = ''
+                for filename in self.__filenames:
+                    try:
+                        if not self.__test_package_name:
+                            module_import_name = filename
+                        else:
+                            module_import_name = filename.replace(test_package_path, '').replace('/', '.')
+                            if module_import_name.endswith('.py'):
+                                module_import_name = module_import_name[:-3]
+                        module_report_name = module_import_name.lstrip('.')
+                        if not self.__test_package_name:
+                            test_module = importlib.import_module(module_import_name)
+                        else:
+                            test_module = importlib.import_module(module_import_name, self.__test_package_name)
+                        host_name = socket.gethostname()
+
+                        await self._run_parallel_facts_parallel_only(host_name, test_module, filename, module_report_name, results, pool)
+                        if self.__cli.failfast and any(e.is_success is False for e in results):
+                            break
+
+                        await self._run_parallel_theories_parallel_only(host_name, test_module, filename, module_report_name, results, pool)
+                        if self.__cli.failfast and any(e.is_success is False for e in results):
+                            break
+
+                        facts = FactManager.instance().get(test_module.__name__)
+                        for fact in facts:
+                            if _is_parallel(fact.target):
+                                continue
+                            test_result = await _execute_fact(fact, test_module, module_report_name, filename, host_name, self.__test_package_name)
+                            results.append(test_result)
+                            self.print_test_result(test_result)
+                            if self.__cli.failfast and not test_result.is_success:
+                                return
+
+                        theories = TheoryManager.instance().get(test_module.__name__)
+                        for theory in theories:
+                            if _is_parallel(theory.target):
+                                continue
+                            for data in theory.datas:
+                                test_result = await _execute_theory(theory, data, test_module, module_report_name, filename, host_name, self.__test_package_name)
+                                results.append(test_result)
+                                self.print_test_result(test_result)
+                                if self.__cli.failfast and not test_result.is_success:
+                                    return
+
+                    except Exception as ex:
+                        result = TestResult()
+                        result.class_name = '*'
+                        result.module_name = module_report_name
+                        result.test_name = '*'
+                        result.start_time = time.time()
+                        result.stop_time = time.time()
+                        result.is_success = False
+                        result.exception = ex
+                        results.append(result)
+                        self.print_test_result(result)
+                        if self.__cli.failfast:
+                            break
+        except Exception:
+            pass
+
     async def _run_parallel(self, results: list[TestResult], test_package_path: str) -> list[TestResult]:
         """Execute all tests with a worker pool (each worker has its own event loop)."""
         parallelism = _get_parallelism(self.__cli)
@@ -474,3 +580,54 @@ class TestRunner:
                 self.print_test_result(test_result)
                 if self.__cli.failfast and not test_result.is_success:
                     return
+
+    async def _run_parallel_facts_parallel_only(
+        self,
+        host_name: str,
+        test_module: ModuleType,
+        filename: str,
+        module_report_name: str,
+        results: list[TestResult],
+        pool: ThreadPool
+    ) -> None:
+        """Run @parallel facts in parallel (auto-enable mode)."""
+        facts = FactManager.instance().get(test_module.__name__)
+        coros: list[Any] = []
+        for fact in facts:
+            if not _is_parallel(fact.target):
+                continue
+            coro = _execute_fact(fact, test_module, module_report_name, filename, host_name, self.__test_package_name)
+            coros.append(coro)
+        if coros:
+            test_results = await asyncio.gather(*coros)
+            for test_result in test_results:
+                results.append(test_result)
+                self.print_test_result(test_result)
+                if self.__cli.failfast and not test_result.is_success:
+                    return
+
+    async def _run_parallel_theories_parallel_only(
+        self,
+        host_name: str,
+        test_module: ModuleType,
+        filename: str,
+        module_report_name: str,
+        results: list[TestResult],
+        pool: ThreadPool
+    ) -> None:
+        """Run @parallel theory data-points in parallel (auto-enable mode)."""
+        theories = TheoryManager.instance().get(test_module.__name__)
+        coros: list[Any] = []
+        for theory in theories:
+            if not _is_parallel(theory.target):
+                continue
+            for data in theory.datas:
+                coro = _execute_theory(theory, data, test_module, module_report_name, filename, host_name, self.__test_package_name)
+                coros.append(coro)
+        if coros:
+            test_results = await asyncio.gather(*coros)
+            for test_result in test_results:
+                results.append(test_result)
+                self.print_test_result(test_result)
+                if self.__cli.failfast and not test_result.is_success:
+                    return

punit-1.12.2/src/punit/sequential.py

@@ -1,63 +0,0 @@
-# SPDX-FileCopyrightText: © 2024 Shaun Wilson
-# SPDX-License-Identifier: MIT
-
-"""
-``@sequential`` decorator for pUnit.
-
-When running tests with ``--parallel``, any test decorated with
-``@sequential`` is deferred to a sequential pass that runs after all
-parallel peers at the same scope have finished.
-"""
-
-from __future__ import annotations
-
-from typing import Any, Callable
-
-
-def sequential(target: Callable[..., Any]) -> Callable[..., Any]:
-    """Mark a test function or method for **sequential** (sequential) execution.
-
-    When pUnit is started with ``--parralel THREADS`` (where *THREADS* > 1),
-    tests decorated without ``@sequential`` run in parallel up to *N* at
-    any given point.  ``@sequential`` tests are **not** added to the
-    concurrent dispatch queue -- after all peers at the same scope finish
-    concurrently, the sequential tests run one after another in their
-    definition order.
-
-    The decorator returns the original ``target`` unchanged; it installs the
-    ``__punit_sequential`` marker attribute on the unwrapped function.
-
-    Parameters
-    ----------
-    target : Callable
-        The test function or method to mark.
-
-    Returns
-    -------
-    Callable
-        The original, undecorated target.
-
-    Example
-    -------
-
-    .. code-block:: python
-
-        from punit import fact, sequential
-
-        @fact
-        @sequential
-        def my_test():
-            assert True
-
-        class MyTestCase:
-            @fact
-            @sequential
-            def test_one(self):
-                assert True
-
-    """
-    import inspect
-
-    unwrapped = inspect.unwrap(target)
-    setattr(unwrapped, "__punit_sequential", True)
-    return target