punit 1.7.2__tar.gz → 1.8.1__tar.gz

{punit-1.7.2/src/pUnit.egg-info → punit-1.8.1}/PKG-INFO

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

{punit-1.7.2 → punit-1.8.1}/pyproject.toml

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

{punit-1.7.2 → punit-1.8.1/src/pUnit.egg-info}/PKG-INFO

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

{punit-1.7.2 → punit-1.8.1}/src/pUnit.egg-info/SOURCES.txt

@@ -32,6 +32,8 @@ src/punit/reports/HtmlReportGenerator.py
 src/punit/reports/JUnitReportGenerator.py
 src/punit/reports/JsonReportGenerator.py
 src/punit/reports/__init__.py
+src/punit/results/__init__.py
+src/punit/results/fails.py
 src/punit/setups/Setup.py
 src/punit/setups/SetupManager.py
 src/punit/setups/__init__.py

{punit-1.7.2 → punit-1.8.1}/src/punit/TestResult.py

@@ -2,7 +2,7 @@
 # SPDX-License-Identifier: MIT
 
 import sys
-from typing import Any, TextIO, Optional, cast
+from typing import Any, Optional, TextIO
 
 
 class TextIOCapture:
@@ -27,11 +27,28 @@ class TextIOCapture:
 
 
 class TestResult:
+    """
+    Accumulates the outcome of a single test execution.
+
+    Example
+    -------
+
+    Create and populate a result manually:
+
+    .. code-block:: python
+
+        result = TestResult()
+        result.module_name = 'tests.example'
+        result.test_name = 'test_something'
+        result.is_success = True
+
+    """
 
     __class_name: Optional[str]
     __exception: Exception | None
     __file_name: str | None
     __host_name: str | None
+    __expected_failure_reason: str | None
     __is_success: bool | None
     __module_name: str | None
     __package_name: str | None
@@ -47,6 +64,7 @@ class TestResult:
         self.__exception = None
         self.__file_name = None
         self.__host_name = None
+        self.__expected_failure_reason = None
         self.__is_success = None
         self.__module_name = None
         self.__package_name = None
@@ -69,6 +87,14 @@ class TestResult:
     def class_name(self, value: Optional[str]) -> None:
         self.__class_name = value
 
+    @property
+    def expected_failure_reason(self) -> str | None:
+        return self.__expected_failure_reason
+
+    @expected_failure_reason.setter
+    def expected_failure_reason(self, value: str | None) -> None:
+        self.__expected_failure_reason = value
+
     @property
     def exception(self) -> Exception | None:
         return self.__exception
@@ -93,6 +119,16 @@ class TestResult:
     def host_name(self, value: str) -> None:
         self.__host_name = value
 
+    @property
+    def is_expected_failure(self) -> bool:
+        """Deprecated: use ``expected_failure_reason is not None`` instead."""
+        return self.expected_failure_reason is not None
+
+    @is_expected_failure.setter
+    def is_expected_failure(self, value: bool) -> None:
+        # Deprecated no-op; consumers should set expected_failure_reason directly.
+        pass
+
     @property
     def is_success(self) -> bool:
         return False if self.__is_success is None else self.__is_success
@@ -102,8 +138,8 @@ class TestResult:
         self.__is_success = value
 
     @property
-    def module_name(self) -> str:
-        return cast(str, self.__module_name)
+    def module_name(self) -> str | None:
+        return self.__module_name
 
     @module_name.setter
     def module_name(self, value: str) -> None:
@@ -175,7 +211,7 @@ class TestResult:
         elif took >= 0.000000001:
             return f'{(took*1000000):.3f}'.rstrip('0').rstrip('.') + 'μs'
         else:
-            return f'{(took*1000):.3f}'.rstrip('0').rstrip('.') + 'ms'
+            return f'{(took*1000000):.3f}'.rstrip('0').rstrip('.') + 'ns'
 
     def capture_output(self, quiet: bool = False) -> None:
         self.__stdout_capture = TextIOCapture(sys.stdout, quiet)

{punit-1.7.2 → punit-1.8.1}/src/punit/__init__.py

@@ -1,8 +1,11 @@
 # SPDX-FileCopyrightText: © 2024 Shaun Wilson
 # SPDX-License-Identifier: MIT
 
+"""pUnit -- a modernized unit-testing framework for Python."""
+
 from .assertions import collections, exceptions, numeric, strings
 from .facts import fact
+from .results import fails
 from .setups import Setup, setup
 from .teardowns import Teardown, teardown
 from .theories import theory, inlinedata
@@ -12,8 +15,8 @@ from .assertions.exceptions import raises
 from .assertions.numeric import approx
 
 
-__version__ = '1.7.2'
-__commit__ = 'b60afab'
+__version__ = '1.8.1'
+__commit__ = 'faca395'
 __all__ = [
     '__version__', '__commit__',
     'assertions',
@@ -22,9 +25,9 @@ __all__ = [
     'numeric', 'approx',
     'strings',
     'fact',
-    'metadata',
     'setup', 'Setup',
     'teardown', 'Teardown',
     'theory', 'inlinedata',
-    'trait'
+    'trait',
+    'fails',
 ]

{punit-1.7.2 → punit-1.8.1}/src/punit/__main__.py

@@ -16,7 +16,7 @@ from .teardowns.TeardownManager import TeardownManager
 
 
 async def async_main() -> None:
-    ts = time.time()
+    start_time = time.time()
     cli = CommandLineInterface.parse()
     if cli.help:  # pragma: no cover
         cli.print_help()
@@ -26,27 +26,27 @@ async def async_main() -> None:
         cli.print_version()
     os.chdir(cli.workdir)
     if cli.no_pathfix is not True:
-        pathbase = str(Path.cwd())
-        srcbase = os.path.join(pathbase, 'src')
-        if os.path.exists(srcbase) and srcbase not in sys.path:
-            sys.path.append(srcbase)
-        if pathbase not in sys.path:
-            sys.path.append(pathbase)
+        cwd_path = str(Path.cwd())
+        src_path = os.path.join(cwd_path, 'src')
+        if os.path.exists(src_path) and src_path not in sys.path:
+            sys.path.append(src_path)
+        if cwd_path not in sys.path:
+            sys.path.append(cwd_path)
     test_module_discovery = TestModuleDiscovery(
         os.path.join(cli.workdir, cli.test_package_name),
         cli.includePatterns,
         cli.excludePatterns,
         cli)
     test_module_discovery.discover()
-    testRunner = TestRunner(cli.test_package_name, test_module_discovery.filenames, cli)
-    results = await testRunner.run()
-    totalTime = time.time() - ts
-    failureCount = 0
+    test_runner = TestRunner(cli.test_package_name, test_module_discovery.filenames, cli)
+    results = await test_runner.run()
+    total_time = time.time() - start_time
+    failure_count = 0
     for result in results:
         if not result.is_success:
-            failureCount += 1  # pragma: no cover
+            failure_count += 1  # pragma: no cover
     if not cli.quiet:
-        print(f'Total: {len(results)}, Failures: {failureCount}, Took: {totalTime:.3f}s')
+        print(f'Total: {len(results)}, Failures: {failure_count}, Took: {total_time:.3f}s')
     if cli.reportFormat is not None:  # pragma: no cover
         report: str = ''
         match cli.reportFormat:
@@ -74,7 +74,7 @@ async def async_main() -> None:
         pass
 
     if cli.no_exitcode is not True:
-        if failureCount:
+        if failure_count:
             # test failures trigger exit code 119 (for automation gating)
             sys.exit(119)
         if TeardownManager.instance().teardown_error_count > 0:

punit-1.8.1/src/punit/assertions/__init__.py

@@ -0,0 +1,28 @@
+# SPDX-FileCopyrightText: © 2024 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+"""Assertion helpers for pUnit tests.
+
+With pUnit, assertions are typically performed using Python's ``assert`` statement.
+This module provides several helper submodules that offer additional assertion
+capabilities beyond the built-in ``assert`` keyword.
+
+Sub-modules
+-----------
+
+* :py:mod:`punit.assertions.collections`; helpers for comparing sequences and collections.
+* :py:mod:`punit.assertions.exceptions`; helpers for asserting raised exceptions.
+* :py:mod:`punit.assertions.numeric`; helpers for approximate numeric comparisons.
+* :py:mod:`punit.assertions.strings`; helpers for string comparisons and checks.
+
+"""
+
+from . import collections, exceptions, numeric, strings
+
+
+__all__ = [
+    'collections',
+    'exceptions',
+    'numeric',
+    'strings'
+]

{punit-1.7.2 → punit-1.8.1}/src/punit/assertions/collections.py

@@ -1,6 +1,13 @@
 # SPDX-FileCopyrightText: © 2024 Shaun Wilson
 # SPDX-License-Identifier: MIT
 
+"""Collection assertion helpers for comparing sequences and containers.
+
+Provides utilities to check sequence equality, length bounds, and emptiness
+beyond Python's built-in ``assert`` statement.
+
+"""
+
 from typing import Any, Callable, Optional, Sequence, cast
 
 
@@ -10,11 +17,30 @@ def are_same(actual: Sequence[Any] | set[Any] | dict[Any, Any] | None, expected:
 
     Can optionally specify *sort* so that differences in order do not cause failure.
 
-    :param actual: The sequence to check.
-    :param expected: The sequence to compare against.
-    :param sort: Sort sequences before performing comparisons.
-    :param sort_function: Custom function to use when sorting.
-    :returns bool: True if the sequences contain the same elements in the same order, False otherwise.
+    Args:
+        actual: The sequence to check.
+        expected: The sequence to compare against.
+        sort: Sort sequences before performing comparisons.
+        sort_function: Custom function to use when sorting.
+
+    Returns:
+        True if the sequences contain the same elements in the same order, False otherwise
+
+    Example
+    -------
+
+    .. code-block:: python
+
+        from punit import collections
+
+        a = [1, 2, 3]
+        b = [1, 2, 3]
+        c = [3, 2, 1]
+
+        assert collections.are_same(a, b)
+        assert not collections.are_same(b, c)
+        assert collections.are_same(None, None)
+        assert not collections.are_same(a, None)
     """
     if actual is expected:
         return True
@@ -52,12 +78,31 @@ def are_same(actual: Sequence[Any] | set[Any] | dict[Any, Any] | None, expected:
 
 def has_length(actual: Sequence[Any] | set[Any] | dict[Any, Any] | None, min: Optional[int] = None, max: Optional[int] = None) -> bool:
     """
-    Check if actual value has the expected number of elements.
+    Check if actual value's length falls within the inclusive range [min, max].
+
+    Args:
+        actual: The sequence (or collection) to check.
+        min: Inclusive lower bound on length (``len(actual) >= min``).
+        max: Inclusive upper bound on length (``len(actual) <= max``).
 
-    :param actual: The actual value to check.
-    :param int|None expected: The expected number of elements
+    Returns:
+        True if the length satisfies the bounds, False otherwise.
+        When actual is None, returns True only when both bounds are effectively zero.
 
-    :returns bool: True if the sequence has exactly the expected number of elements, False otherwise
+    Example
+    -------
+
+    .. code-block:: python
+
+        from punit import collections
+
+        a = [1]
+        b = [1, 2]
+
+        assert collections.has_length(a, min=1)
+        assert collections.has_length(b, min=2)
+        assert collections.has_length([1, 2, 3], max=3)
+        assert not collections.has_length(a, min=2)
     """
     if actual is None:
         if ((min is None or min == 0) and (max is None or max == 0)):
@@ -74,8 +119,22 @@ def is_none_or_empty(actual: Sequence[Any] | set[Any] | dict[Any, Any] | None) -
     """
     Check if actual value is None or empty.
 
-    :param actual: The actual to check.
-    :returns: True if the value is None or empty, False otherwise.
+    Args:
+        actual: The sequence to check.
+
+    Returns:
+        True if the value is None or empty, False otherwise
+
+    Example
+    -------
+
+    .. code-block:: python
+
+        from punit import collections
+
+        assert not collections.is_none_or_empty([1, 2, 3])
+        assert collections.is_none_or_empty([])
+        assert collections.is_none_or_empty(None)
     """
     if actual is None:
         return True

punit-1.8.1/src/punit/assertions/exceptions.py

@@ -0,0 +1,87 @@
+# SPDX-FileCopyrightText: © 2024 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+"""Exception assertion helpers for verifying raised exceptions.
+
+Provides the ``raises`` class which can verify that a callable raises an
+exception of the expected type using either Python 3.11+ generic syntax or
+an explicit ``expect`` keyword argument.
+
+Example
+-------
+
+.. code-block:: python
+
+    from punit import exceptions
+
+    class MyException(Exception):
+        pass
+
+    def raises_exception():
+        raise MyException()
+
+    assert exceptions.raises[MyException](raises_exception)
+    assert exceptions.raises[MyException](raises_exception, exact=True)
+
+"""
+
+from typing import Any, Callable, Generic, Optional, TypeVar, cast, get_args
+
+
+TError = TypeVar('TError', bound=Exception)
+
+
+class raises(Generic[TError]):
+    """Assert that a callable raises an expected exception.
+
+    Use ``raises`` to verify that a function, method, or lambda expression
+    raises an exception of the expected type. Two syntaxes are supported:
+
+    * Python >=3.11 generic syntax: ``raises[MyException](action)``
+    * Explicit expect argument (for <=3.11): ``raises(action, expect=MyException)``
+
+    The ``exact`` parameter controls whether the raised exception must be an exact
+    type match (not a subclass) of the expected type.
+
+    Example
+    -------
+
+    .. code-block:: python
+
+        class MyException(Exception):
+            pass
+
+        def raises_exception():
+            raise MyException()
+
+        assert raises[MyException](raises_exception)
+        assert not raises[ValueError](raises_exception)
+        assert raises[MyException](raises_exception, exact=True)
+    """
+
+    __action: Callable[[], Any]
+    __exact: bool
+    __expect: Optional[TError | type]
+
+    def __init__(self, action: Callable[[], Any], *, exact: bool = False, expect: Optional[TError | type] = None) -> None:
+        self.__action = action
+        self.__exact = exact
+        self.__expect = expect
+
+    def __bool__(self) -> bool:
+        try:
+            self.__action()
+        except BaseException as ex:
+            expected = self.__expect
+            if expected is None and hasattr(self, '__orig_class__') is not None:
+                expected = get_args(getattr(self, '__orig_class__'))[0]
+            if self.__exact:
+                return type(ex) is expected
+            elif expected is not None:
+                return issubclass(type(ex), cast(Any, expected))
+        return False
+
+
+__all__ = [
+    'raises'
+]

{punit-1.7.2 → punit-1.8.1}/src/punit/assertions/numeric.py

@@ -1,6 +1,35 @@
 # SPDX-FileCopyrightText: © 2026 Shaun Wilson
 # SPDX-License-Identifier: MIT
 
+"""Numeric assertion helpers for approximate comparisons and checks.
+
+Provides the ``approx`` class (inspired by pytest.approx) for directional
+tolerance-based numeric comparisons, plus standalone helpers like
+``isclose``, ``isnan``, ``isinfinite``, and ``percentage``.
+
+The ``approx`` class supports natural Python comparison syntax with
+directional (one-sided) tolerance:
+
+    * ``x == approx(expected)``; approximately equal (bidirectional tolerance)
+    * ``x > approx(threshold)``; strictly greater than (tolerance extends below)
+    * ``x >= approx(threshold)``;  at least the threshold (tolerance extends below)
+    * ``x < approx(threshold)``;  strictly less than (tolerance extends above)
+    * ``x <= approx(threshold)``;  at most the threshold (tolerance extends above)
+
+Example
+-------
+
+.. code-block:: python
+
+    from punit.assertions.numeric import approx, isclose, isnan
+
+    assert 0.1 + 0.2 == approx(0.3)
+    assert isclose(1 + 2j, 1.0 + 2.0j)
+    assert not isclose(3, 3.000000001)
+    assert isnan(float('nan'))
+
+"""
+
 from __future__ import annotations
 
 from decimal import Decimal
@@ -38,7 +67,7 @@ def _real_expected(base: '_ApproxComparator') -> float:
     """
     Return *base._expected* as float for real-only operations.
 
-    Raises ``TypeError`` when the expected value is complex — those
+    Raises ``TypeError`` when the expected value is complex;  those
     comparisons belong to ``isclose`` / ``_approximately_equal``.
     """
     if isinstance(base._expected, complex):
@@ -61,21 +90,26 @@ def isclose(
     complex inputs the real and imaginary parts are compared independently using the
     same tolerances.
 
-    :param a: First numeric value.
-    :param b: Second numeric value.
-    :param rel_tol: Relative tolerance (default 1e-9).
-    :param abs_tol: Absolute tolerance (default 0.0).
-    :returns: True if ``|a - b| <= max(rel_tol * |b|, abs_tol)`` for real values, or
+    Args:
+        a: First numeric value.
+        b: Second numeric value.
+        rel_tol: Relative tolerance (default 1e-9).
+        abs_tol: Absolute tolerance (default 0.0).
+
+    Returns:
+        True if ``|a - b| <= max(rel_tol * |b|, abs_tol)`` for real values, or
         equivalent per-component comparison for complex.
 
-    **Example**::
+    Example
+    -------
+
+    .. code-block:: python
 
-        >>> isclose(1 + 2j, 1.0 + 2.0j)
-        True
-        >>> isclose(3, 3.000000001)
-        False
-        >>> isclose(3, 3.000000001, rel_tol=1e-6)
-        True
+        from punit.assertions.numeric import isclose
+
+        assert isclose(1 + 2j, 1.0 + 2.0j)
+        assert not isclose(3, 3.000000001)
+        assert isclose(3, 3.000000001, rel_tol=1e-6)
     """
     if isinstance(a, complex) or isinstance(b, complex):
         a_c = a if isinstance(a, complex) else complex(a, 0)
@@ -511,6 +545,22 @@ def isnan(value: Numeric) -> bool:
     Check if value is NaN (Not a Number).
 
     For complex inputs, returns True only if both the real and imaginary parts are NaN.
+
+    Args:
+        value: The numeric value to check.
+
+    Returns:
+        True if value is NaN, False otherwise.
+
+    Example
+    -------
+
+    .. code-block:: python
+
+        from punit.assertions.numeric import isnan
+
+        assert isnan(float('nan'))
+        assert not isnan(0.0)
     """
     if isinstance(value, complex):
         return math.isnan(value.real) and math.isnan(value.imag)
@@ -522,6 +572,22 @@ def isinfinite(value: Numeric) -> bool:
     Check if value is infinite (positive or negative).
 
     For complex inputs, returns True only if either the real or imaginary part is infinite.
+
+    Args:
+        value: The numeric value to check.
+
+    Returns:
+        True if value is infinite, False otherwise.
+
+    Example
+    -------
+
+    .. code-block:: python
+
+        from punit.assertions.numeric import isinfinite
+
+        assert isinfinite(float('inf'))
+        assert not isinfinite(0.0)
     """
     if isinstance(value, complex):
         return math.isinf(value.real) or math.isinf(value.imag)
@@ -536,16 +602,34 @@ def percentage(
     """
     Calculate the percentage difference between two numeric values.
 
-    When relative_to_expected=True, uses value_b as reference: abs(a - b) / |b| * 100.
-    When relative_to_expected=False, uses symmetric form: abs(a - b) / ((|a| + |b|) / 2) * 100.
+    When relative_to_expected=True, uses value_b as reference::
+
+        abs(a - b) / |b| * 100
+
+    When relative_to_expected=False, uses symmetric form::
+
+        abs(a - b) / ((|a| + |b|) / 2) * 100
 
     For complex inputs, magnitudes (``abs()``) are used consistently: the numerator is
     the magnitude of the difference, and the denominator is the magnitude of the reference.
 
-    :param value_a: The first numeric value.
-    :param value_b: The second numeric value (reference when relative_to_expected=True).
-    :param relative_to_expected: If True, use value_b as reference (default).
-    :returns float: The percentage difference as a float. Returns ``inf`` if both values are zero but differ, otherwise ``0.0``.
+    Args:
+        value_a: The first numeric value.
+        value_b: The second numeric value (reference when relative_to_expected=True).
+        relative_to_expected: If True, use value_b as reference (default).
+
+    Returns:
+        The percentage difference as a float. Returns ``inf`` if both values are zero but differ, otherwise ``0.0``.
+
+    Example
+    -------
+
+    .. code-block:: python
+
+        from punit.assertions.numeric import percentage
+
+        assert percentage(10, 100) == 90.0
+        assert percentage(0, 0) == 0.0
     """
     diff_mag = abs(value_a - value_b)
     if relative_to_expected: