punit 1.12.2__tar.gz → 1.12.4__tar.gz

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

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: pUnit
-Version: 1.12.2
+Version: 1.12.4
 Summary: A modernized unit-test framework for Python.
 Author-email: Shaun Wilson <mrshaunwilson@msn.com>
 License-Expression: MIT
 Project-URL: Documentation, https://punit.readthedocs.io/
 Project-URL: Homepage, https://github.com/wilson0x4d/punit
 Project-URL: Repository, https://github.com/wilson0x4d/punit.git
-Keywords: test,unittest,unit-test,xUnit,nUnit,pytest
+Keywords: test,unittest,unit-test,xUnit,nUnit,pytest,mock,patch,parallelism,vscode,vscodium
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
@@ -25,6 +25,26 @@ Dynamic: license-file
 
 This README is only a high-level introduction to **pUnit**. For more detailed documentation, please view the official docs at [https://pUnit.readthedocs.io](https://pUnit.readthedocs.io).
 
+## Features
+
+- **IDE Support**; Run/Debug tests and review results with full error detail from within vscode using the [x4d.punit-testadapter](https://marketplace.visualstudio.com/items?itemName=x4d.punit-testadapter) extension ([also available for VSCodium via Open VSX](https://open-vsx.org/extension/x4d/punit-testadapter))
+- **Fact/Theory Based TEsting**; Separate `@fact` and `@theory` decorators distinguish invariant tests from variant (parameterized) tests, allowing for more concise test permutation syntaxes.
+- **Parallel Test Execution**; Optionally run tests concurrently with multiple worker threads, each with its own async event loop. Enable via `--parallel` CLI flag or `@parallel` decorator. Mix parallel and `@sequential`-marked tests in the same file.
+- **Dual-Scope Setup/Teardown**; Module-scoped and class-scoped setup/teardown as bare decorated functions, no fixture plumbing or injection required. Configure with `@setup` and `@teardown`.
+- **Per-Test Output Capture**; Captures each test's stdout/stderr output in isolation, included in the test results and all report formats.
+- **Traits**; Categorical name/value test metadata queryable at discovery time via CLI flags. Unlike traditional marks, traits are filterable during discovery, not at decoration, and can also be used to filter in the IDE.
+- **Expected Failures with Inversion**; Invert test results for known bugs with human-readable reason tracking. Mark with `@fails(reason)`, useful for TDD workflows.
+- **Mock Objects**; Single-class mocking with fluent API (`.returns()`, `.side_effect()`), origin conformance, delegate/spy support, nested child mocks, and iterator protocol. Located in `punit.mocks`.
+- **Module Patching**; Decorator and context-manager patching for arbitrary Python paths with automatic restoration, with support for complex dotted attribute paths.
+- **Argument Matchers**; Lightweight and extensible matchers (`is_any`, `contains`, `is_gt`, `is_lt`, `in_range`, `neg`) for flexible mock call assertions.
+- **Conditionals**; Skip tests using boolean, callback, or unconditional logic via `@skip()`. Evaluates at execution time, allowing for complex state mutation/evaluation in test suites.
+- **Multi-Format Reports**; Built-in HTML, jUnit XML, and JSON reports which include captured output, precise timing, and full error detail. Enable with `--report` and combine with `--output` to write to a file, great for CI/CD integrations.
+- **Multi-Level Test Filtering**; Unified test pipeline that combines filename globbing, case-insensitive regex on test names, trait queries, and `--filter @FILEPATH` filters (loaded from ``FILEPATH``), `--filter @stdin` allows piping lists of filters in via stdin.
+- **Direct File Execution**; Run individual `.py` files without a `tests/` package or `__init__.py`. Pass file paths directly to the CLI.
+- **Assertion Helpers for Exceptions**; Type-safe exception assertion via generic syntax `raises[MyException](action)`. Supports strict (`exact=True`) and subclass matching.
+- **Assertion Helpers for Collections**; Assert sequences, lists, sets, dicts, and tuples using `are_same`, `has_length` and `is_none_or_empty` for comparing elements, length bounds, and emptiness, or ordering.
+- **Assertion Helpers for Numericals**; Directional comparators using `> approx(threshold)` with tolerance below and `< approx(threshold)` with tolerance above, also supports fluent syntaxes for more complex numerical requirements such as invariant boundary control, mixtures, etc.
+
 ## Command-Line Usage
 
 Running pUnit with no arguments will perform test auto-discovery and execution:
@@ -99,7 +119,7 @@ Options:
         Default: '*.py'
     -e, --exclude PATTERN
         Exclude test files matching PATTERN, overriding --include
-        Default: '__*__' (dunders)
+        Default: '__*__' (dunder files)
     -f, --filter PATTERN|@FILEPATH
         Only execute tests matching PATTERN
         Default: '*'
@@ -109,7 +129,7 @@ Options:
         Execute tests with the specified trait, negated by prefixing with '!'.
         If VALUE is specified, matches tests with the trait having specified value.
         If VALUE is not specified, matches any test with the trait having any value.
-        Default: No filtering based on traits.        
+        Default: No filtering based on traits.
     -w, --working-directory PATH
         Working directory (defaults to start directory)
     -n, --no-default-patterns
@@ -127,6 +147,12 @@ Options:
         If `--report` is used, instead of writing to stdout
         write to FILENAME. In this case `--report` does not
         suppress any program output.
+    FILE
+        One or more .py files to run directly.
+        When any FILE is specified, only those files are tested;
+        -p/--test-package, --include, and --exclude patterns on
+        discovered files are ignored (test filtering via -f/-t
+        still applies).
 ```
 
 ## Writing Tests

{punit-1.12.2 → punit-1.12.4}/README.md

@@ -2,6 +2,26 @@
 
 This README is only a high-level introduction to **pUnit**. For more detailed documentation, please view the official docs at [https://pUnit.readthedocs.io](https://pUnit.readthedocs.io).
 
+## Features
+
+- **IDE Support**; Run/Debug tests and review results with full error detail from within vscode using the [x4d.punit-testadapter](https://marketplace.visualstudio.com/items?itemName=x4d.punit-testadapter) extension ([also available for VSCodium via Open VSX](https://open-vsx.org/extension/x4d/punit-testadapter))
+- **Fact/Theory Based TEsting**; Separate `@fact` and `@theory` decorators distinguish invariant tests from variant (parameterized) tests, allowing for more concise test permutation syntaxes.
+- **Parallel Test Execution**; Optionally run tests concurrently with multiple worker threads, each with its own async event loop. Enable via `--parallel` CLI flag or `@parallel` decorator. Mix parallel and `@sequential`-marked tests in the same file.
+- **Dual-Scope Setup/Teardown**; Module-scoped and class-scoped setup/teardown as bare decorated functions, no fixture plumbing or injection required. Configure with `@setup` and `@teardown`.
+- **Per-Test Output Capture**; Captures each test's stdout/stderr output in isolation, included in the test results and all report formats.
+- **Traits**; Categorical name/value test metadata queryable at discovery time via CLI flags. Unlike traditional marks, traits are filterable during discovery, not at decoration, and can also be used to filter in the IDE.
+- **Expected Failures with Inversion**; Invert test results for known bugs with human-readable reason tracking. Mark with `@fails(reason)`, useful for TDD workflows.
+- **Mock Objects**; Single-class mocking with fluent API (`.returns()`, `.side_effect()`), origin conformance, delegate/spy support, nested child mocks, and iterator protocol. Located in `punit.mocks`.
+- **Module Patching**; Decorator and context-manager patching for arbitrary Python paths with automatic restoration, with support for complex dotted attribute paths.
+- **Argument Matchers**; Lightweight and extensible matchers (`is_any`, `contains`, `is_gt`, `is_lt`, `in_range`, `neg`) for flexible mock call assertions.
+- **Conditionals**; Skip tests using boolean, callback, or unconditional logic via `@skip()`. Evaluates at execution time, allowing for complex state mutation/evaluation in test suites.
+- **Multi-Format Reports**; Built-in HTML, jUnit XML, and JSON reports which include captured output, precise timing, and full error detail. Enable with `--report` and combine with `--output` to write to a file, great for CI/CD integrations.
+- **Multi-Level Test Filtering**; Unified test pipeline that combines filename globbing, case-insensitive regex on test names, trait queries, and `--filter @FILEPATH` filters (loaded from ``FILEPATH``), `--filter @stdin` allows piping lists of filters in via stdin.
+- **Direct File Execution**; Run individual `.py` files without a `tests/` package or `__init__.py`. Pass file paths directly to the CLI.
+- **Assertion Helpers for Exceptions**; Type-safe exception assertion via generic syntax `raises[MyException](action)`. Supports strict (`exact=True`) and subclass matching.
+- **Assertion Helpers for Collections**; Assert sequences, lists, sets, dicts, and tuples using `are_same`, `has_length` and `is_none_or_empty` for comparing elements, length bounds, and emptiness, or ordering.
+- **Assertion Helpers for Numericals**; Directional comparators using `> approx(threshold)` with tolerance below and `< approx(threshold)` with tolerance above, also supports fluent syntaxes for more complex numerical requirements such as invariant boundary control, mixtures, etc.
+
 ## Command-Line Usage
 
 Running pUnit with no arguments will perform test auto-discovery and execution:
@@ -76,7 +96,7 @@ Options:
         Default: '*.py'
     -e, --exclude PATTERN
         Exclude test files matching PATTERN, overriding --include
-        Default: '__*__' (dunders)
+        Default: '__*__' (dunder files)
     -f, --filter PATTERN|@FILEPATH
         Only execute tests matching PATTERN
         Default: '*'
@@ -86,7 +106,7 @@ Options:
         Execute tests with the specified trait, negated by prefixing with '!'.
         If VALUE is specified, matches tests with the trait having specified value.
         If VALUE is not specified, matches any test with the trait having any value.
-        Default: No filtering based on traits.        
+        Default: No filtering based on traits.
     -w, --working-directory PATH
         Working directory (defaults to start directory)
     -n, --no-default-patterns
@@ -104,6 +124,12 @@ Options:
         If `--report` is used, instead of writing to stdout
         write to FILENAME. In this case `--report` does not
         suppress any program output.
+    FILE
+        One or more .py files to run directly.
+        When any FILE is specified, only those files are tested;
+        -p/--test-package, --include, and --exclude patterns on
+        discovered files are ignored (test filtering via -f/-t
+        still applies).
 ```
 
 ## Writing Tests

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

@@ -1,8 +1,8 @@
 [project]
 name = "pUnit"
-version = "1.12.2"
+version = "1.12.4"
 description = "A modernized unit-test framework for Python."
-keywords = ["test", "unittest", "unit-test", "xUnit", "nUnit", "pytest"]
+keywords = ["test", "unittest", "unit-test", "xUnit", "nUnit", "pytest", "mock", "patch", "parallelism", "vscode", "vscodium"]
 authors = [
     { name="Shaun Wilson", email="mrshaunwilson@msn.com" }
 ]

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

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: pUnit
-Version: 1.12.2
+Version: 1.12.4
 Summary: A modernized unit-test framework for Python.
 Author-email: Shaun Wilson <mrshaunwilson@msn.com>
 License-Expression: MIT
 Project-URL: Documentation, https://punit.readthedocs.io/
 Project-URL: Homepage, https://github.com/wilson0x4d/punit
 Project-URL: Repository, https://github.com/wilson0x4d/punit.git
-Keywords: test,unittest,unit-test,xUnit,nUnit,pytest
+Keywords: test,unittest,unit-test,xUnit,nUnit,pytest,mock,patch,parallelism,vscode,vscodium
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
@@ -25,6 +25,26 @@ Dynamic: license-file
 
 This README is only a high-level introduction to **pUnit**. For more detailed documentation, please view the official docs at [https://pUnit.readthedocs.io](https://pUnit.readthedocs.io).
 
+## Features
+
+- **IDE Support**; Run/Debug tests and review results with full error detail from within vscode using the [x4d.punit-testadapter](https://marketplace.visualstudio.com/items?itemName=x4d.punit-testadapter) extension ([also available for VSCodium via Open VSX](https://open-vsx.org/extension/x4d/punit-testadapter))
+- **Fact/Theory Based TEsting**; Separate `@fact` and `@theory` decorators distinguish invariant tests from variant (parameterized) tests, allowing for more concise test permutation syntaxes.
+- **Parallel Test Execution**; Optionally run tests concurrently with multiple worker threads, each with its own async event loop. Enable via `--parallel` CLI flag or `@parallel` decorator. Mix parallel and `@sequential`-marked tests in the same file.
+- **Dual-Scope Setup/Teardown**; Module-scoped and class-scoped setup/teardown as bare decorated functions, no fixture plumbing or injection required. Configure with `@setup` and `@teardown`.
+- **Per-Test Output Capture**; Captures each test's stdout/stderr output in isolation, included in the test results and all report formats.
+- **Traits**; Categorical name/value test metadata queryable at discovery time via CLI flags. Unlike traditional marks, traits are filterable during discovery, not at decoration, and can also be used to filter in the IDE.
+- **Expected Failures with Inversion**; Invert test results for known bugs with human-readable reason tracking. Mark with `@fails(reason)`, useful for TDD workflows.
+- **Mock Objects**; Single-class mocking with fluent API (`.returns()`, `.side_effect()`), origin conformance, delegate/spy support, nested child mocks, and iterator protocol. Located in `punit.mocks`.
+- **Module Patching**; Decorator and context-manager patching for arbitrary Python paths with automatic restoration, with support for complex dotted attribute paths.
+- **Argument Matchers**; Lightweight and extensible matchers (`is_any`, `contains`, `is_gt`, `is_lt`, `in_range`, `neg`) for flexible mock call assertions.
+- **Conditionals**; Skip tests using boolean, callback, or unconditional logic via `@skip()`. Evaluates at execution time, allowing for complex state mutation/evaluation in test suites.
+- **Multi-Format Reports**; Built-in HTML, jUnit XML, and JSON reports which include captured output, precise timing, and full error detail. Enable with `--report` and combine with `--output` to write to a file, great for CI/CD integrations.
+- **Multi-Level Test Filtering**; Unified test pipeline that combines filename globbing, case-insensitive regex on test names, trait queries, and `--filter @FILEPATH` filters (loaded from ``FILEPATH``), `--filter @stdin` allows piping lists of filters in via stdin.
+- **Direct File Execution**; Run individual `.py` files without a `tests/` package or `__init__.py`. Pass file paths directly to the CLI.
+- **Assertion Helpers for Exceptions**; Type-safe exception assertion via generic syntax `raises[MyException](action)`. Supports strict (`exact=True`) and subclass matching.
+- **Assertion Helpers for Collections**; Assert sequences, lists, sets, dicts, and tuples using `are_same`, `has_length` and `is_none_or_empty` for comparing elements, length bounds, and emptiness, or ordering.
+- **Assertion Helpers for Numericals**; Directional comparators using `> approx(threshold)` with tolerance below and `< approx(threshold)` with tolerance above, also supports fluent syntaxes for more complex numerical requirements such as invariant boundary control, mixtures, etc.
+
 ## Command-Line Usage
 
 Running pUnit with no arguments will perform test auto-discovery and execution:
@@ -99,7 +119,7 @@ Options:
         Default: '*.py'
     -e, --exclude PATTERN
         Exclude test files matching PATTERN, overriding --include
-        Default: '__*__' (dunders)
+        Default: '__*__' (dunder files)
     -f, --filter PATTERN|@FILEPATH
         Only execute tests matching PATTERN
         Default: '*'
@@ -109,7 +129,7 @@ Options:
         Execute tests with the specified trait, negated by prefixing with '!'.
         If VALUE is specified, matches tests with the trait having specified value.
         If VALUE is not specified, matches any test with the trait having any value.
-        Default: No filtering based on traits.        
+        Default: No filtering based on traits.
     -w, --working-directory PATH
         Working directory (defaults to start directory)
     -n, --no-default-patterns
@@ -127,6 +147,12 @@ Options:
         If `--report` is used, instead of writing to stdout
         write to FILENAME. In this case `--report` does not
         suppress any program output.
+    FILE
+        One or more .py files to run directly.
+        When any FILE is specified, only those files are tested;
+        -p/--test-package, --include, and --exclude patterns on
+        discovered files are ignored (test filtering via -f/-t
+        still applies).
 ```
 
 ## Writing Tests

{punit-1.12.2 → punit-1.12.4}/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.4}/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.4'
+__commit__ = '43fecfd'
 __all__ = [
     '__version__', '__commit__',
     'assertions',
@@ -36,4 +36,5 @@ __all__ = [
     'fails',
     'skip',
     'sequential',
+    'parallel',
 ]

{punit-1.12.2 → punit-1.12.4}/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.4/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.4}/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