punit 1.5.3__tar.gz → 1.7.2__tar.gz

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

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

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

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

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

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

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

@@ -32,6 +32,12 @@ src/punit/reports/HtmlReportGenerator.py
 src/punit/reports/JUnitReportGenerator.py
 src/punit/reports/JsonReportGenerator.py
 src/punit/reports/__init__.py
+src/punit/setups/Setup.py
+src/punit/setups/SetupManager.py
+src/punit/setups/__init__.py
+src/punit/teardowns/Teardown.py
+src/punit/teardowns/TeardownManager.py
+src/punit/teardowns/__init__.py
 src/punit/theories/Theory.py
 src/punit/theories/TheoryManager.py
 src/punit/theories/__init__.py

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

@@ -59,7 +59,11 @@ class TestResult:
 
     @property
     def class_name(self) -> Optional[str]:
-        return self.__class_name if self.__class_name is not None and len(self.__class_name) > 0 else None
+        return (
+            self.__class_name
+            if self.__class_name is not None and len(self.__class_name) > 0
+            else None
+        )
 
     @class_name.setter
     def class_name(self, value: Optional[str]) -> None:
@@ -173,13 +177,13 @@ class TestResult:
         else:
             return f'{(took*1000):.3f}'.rstrip('0').rstrip('.') + 'ms'
 
-    def captureOutput(self, quiet: bool = False) -> None:
+    def capture_output(self, quiet: bool = False) -> None:
         self.__stdout_capture = TextIOCapture(sys.stdout, quiet)
         self.__stderr_capture = TextIOCapture(sys.stderr, quiet)
         sys.stdout = self.__stdout_capture
         sys.stderr = self.__stderr_capture
 
-    def releaseOutput(self) -> None:
+    def release_output(self) -> None:
         if self.__stdout_capture is not None and self.__stdout_capture.target is not None:
             sys.stdout = self.__stdout_capture.target
         if self.__stderr_capture is not None and self.__stderr_capture.target is not None:

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

@@ -3,6 +3,8 @@
 
 from .assertions import collections, exceptions, numeric, strings
 from .facts import fact
+from .setups import Setup, setup
+from .teardowns import Teardown, teardown
 from .theories import theory, inlinedata
 from .traits import trait
 
@@ -10,8 +12,8 @@ from .assertions.exceptions import raises
 from .assertions.numeric import approx
 
 
-__version__ = '1.5.3'
-__commit__ = '34475af'
+__version__ = '1.7.2'
+__commit__ = 'b60afab'
 __all__ = [
     '__version__', '__commit__',
     'assertions',
@@ -21,6 +23,8 @@ __all__ = [
     'strings',
     'fact',
     'metadata',
+    'setup', 'Setup',
+    'teardown', 'Teardown',
     'theory', 'inlinedata',
     'trait'
 ]

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

@@ -11,17 +11,19 @@ from .cli import CommandLineInterface
 from .discovery import TestModuleDiscovery
 from .reports import HtmlReportGenerator, JUnitReportGenerator, JsonReportGenerator
 from .runner import TestRunner
+from .setups.SetupManager import SetupManager
+from .teardowns.TeardownManager import TeardownManager
 
 
 async def async_main() -> None:
     ts = time.time()
     cli = CommandLineInterface.parse()
     if cli.help:  # pragma: no cover
-        cli.printHelp()
+        cli.print_help()
     elif cli.verbose and not cli.quiet:  # pragma: no cover
-        cli.printSummary()
+        cli.print_summary()
     elif not cli.quiet:  # pragma: no cover
-        cli.printVersion()
+        cli.print_version()
     os.chdir(cli.workdir)
     if cli.no_pathfix is not True:
         pathbase = str(Path.cwd())
@@ -30,13 +32,13 @@ async def async_main() -> None:
             sys.path.append(srcbase)
         if pathbase not in sys.path:
             sys.path.append(pathbase)
-    testModuleDiscovery = TestModuleDiscovery(
+    test_module_discovery = TestModuleDiscovery(
         os.path.join(cli.workdir, cli.test_package_name),
         cli.includePatterns,
         cli.excludePatterns,
         cli)
-    testModuleDiscovery.discover()
-    testRunner = TestRunner(cli.test_package_name, testModuleDiscovery.filenames, 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
@@ -61,16 +63,25 @@ async def async_main() -> None:
                 with open(cli.outputFilename, 'wb') as file:
                     file.write(report.encode())
                 print(f'\n("{cli.reportFormat}" report written to: {cli.outputFilename})')
-    if failureCount > 0:
-        sys.stdout.flush()
-        sys.stderr.flush()
-        try:
-            os.fsync(sys.stdout.fileno())
-            os.fsync(sys.stderr.fileno())
-        except (AttributeError, ValueError, OSError):
-            # Pass if the stream doesn't support fsync (e.g. some virtualized environments)
-            pass
-        if cli.no_exitcode is not True:  # pragma: no cover
+
+    # not everyone runs python unbuffered as they should, so force a flush
+    sys.stdout.flush()
+    sys.stderr.flush()
+    try:
+        os.fsync(sys.stdout.fileno())
+        os.fsync(sys.stderr.fileno())
+    except (AttributeError, ValueError, OSError):
+        pass
+
+    if cli.no_exitcode is not True:
+        if failureCount:
+            # test failures trigger exit code 119 (for automation gating)
+            sys.exit(119)
+        if TeardownManager.instance().teardown_error_count > 0:
+            # teardown errors also trigger exit code 119 (for automation gating)
+            sys.exit(119)
+        if SetupManager.instance().setup_error_count > 0:
+            # setup errors also trigger exit code 119 (for automation gating)
             sys.exit(119)
 
 

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

@@ -1,6 +1,8 @@
 # SPDX-FileCopyrightText: © 2026 Shaun Wilson
 # SPDX-License-Identifier: MIT
 
+from __future__ import annotations
+
 from decimal import Decimal
 import math
 from typing import cast
@@ -397,7 +399,7 @@ class ApproxRangeComparator:
         self._abs_tol = abs_tol
         self._exclusive = False
 
-    def inclusive(self, flag: bool = True) -> 'ApproxRangeComparator':
+    def inclusive(self, flag: bool = True) -> ApproxRangeComparator:
         """
         Return a new ``ApproxRangeComparator`` with toggled inclusivity.
 
@@ -617,7 +619,7 @@ class approx:
         """Return a ``StrictLessThanComparator`` for strictly ``< expected`` (one-sided tolerance below)."""
         return StrictLessThanComparator(self._expected, self._rel_tol, self._abs_tol)
 
-    def in_range(self, min_val: float, max_val: float) -> 'ApproxRangeComparator':
+    def in_range(self, min_val: float, max_val: float) -> ApproxRangeComparator:
         """Return a comparator for ``[min_val, max_val]`` range checks with directional tolerance."""
         return ApproxRangeComparator(min_val, max_val, self._rel_tol, self._abs_tol)
 

{punit-1.5.3 → punit-1.7.2}/src/punit/cli.py

@@ -1,6 +1,8 @@
 # SPDX-FileCopyrightText: © 2024 Shaun Wilson
 # SPDX-License-Identifier: MIT
 
+from __future__ import annotations
+
 import os
 import sys
 from typing import Optional
@@ -46,7 +48,7 @@ class CommandLineInterface:
         self.__workdir = os.path.curdir
         self.__verbose = False
 
-    def __parse(self, argv: list[str]) -> 'CommandLineInterface':
+    def __parse(self, argv: list[str]) -> CommandLineInterface:
         aliasName: str | None = None
         extractFilter: bool = False
         extractExcludePattern: bool = False
@@ -217,9 +219,9 @@ class CommandLineInterface:
     def no_pathfix(self) -> bool:
         return self.__no_pathfix is True
 
-    def printHelp(self) -> None:
+    def print_help(self) -> None:
         if True:  # pragma: no cover
-            self.printVersion()
+            self.print_version()
             print("""
 Usage: python3 -m punit [-h|--help]
                         [-q|--quiet] [-v|--verbose]
@@ -281,8 +283,8 @@ Options:
 """)
             os._exit(0)
 
-    def printSummary(self) -> None:
-        self.printVersion()
+    def print_summary(self) -> None:
+        self.print_version()
         print(f'Working Directory:\n\t{self.__workdir}')
         print(f'Fail Fast: \n\t{"Yes" if self.__failfast else "No"}')
         if len(self.__includePatterns) > 0:
@@ -295,7 +297,7 @@ Options:
                 print(f'\t{pattern}')
         FilterManager.instance().print()
 
-    def printVersion(self) -> None:
+    def print_version(self) -> None:
         print(f'pUnit {__version__} ({__commit__})')
 
     def validate(self) -> None:
@@ -314,7 +316,7 @@ Options:
             self.__excludePatterns.append('/__*__')
 
     @staticmethod
-    def parse(argv: list[str] = sys.argv) -> 'CommandLineInterface':
+    def parse(argv: list[str] = sys.argv) -> CommandLineInterface:
         result = CommandLineInterface().__parse(argv)
         result.validate()
         return result

{punit-1.5.3 → punit-1.7.2}/src/punit/facts/Fact.py

@@ -3,7 +3,7 @@
 
 import inspect
 from types import BuiltinFunctionType, BuiltinMethodType, FunctionType, MethodType, ModuleType
-from typing import Callable, Coroutine, Union, cast
+from typing import Any, Callable, Coroutine, Union, cast
 
 from ..metadata import CallableMetadata
 
@@ -24,13 +24,14 @@ class Fact:
     def target(self) -> Union[FunctionType, MethodType, BuiltinFunctionType, BuiltinMethodType, Callable]:
         return self.__target
 
-    async def execute(self, module: ModuleType) -> None:
+    async def execute(self, module: ModuleType) -> Any | None:
+        class_instance: Any | None = None
         coro: Coroutine | None = None
         if hasattr(self.__target, '__qualname__') and self.__target.__qualname__.find('.') > -1:
             if isinstance(self.__target, staticmethod):
                 coro = self.__target()
             else:
-                qnparts = self.__target.__qualname__.split('.')
+                qnparts = [p for p in self.__target.__qualname__.split('.') if p != '<locals>']
                 qntarget = module
                 for qnpart in qnparts[0:-1]:
                     qntarget = getattr(qntarget, qnpart)
@@ -38,17 +39,26 @@ class Fact:
                     coro = self.__target.__func__(qntarget)
                 else:
                     # every test execution gets a new instance of class
-                    coro = self.__target(cast(Callable, qntarget)())
+                    class_instance = cast(Any, cast(Callable, qntarget)())
+                    coro = self.__target(class_instance)
         else:
             coro = self.__target()
         if inspect.iscoroutine(coro):
             await coro
+        return class_instance
 
 
 def fact(target: Callable) -> Callable:
     from .FactManager import FactManager
-    if (not inspect.isfunction(target)) and (not isinstance(target, classmethod)) and (not isinstance(target, staticmethod)):
+    unwrapped = inspect.unwrap(target)
+    if not isinstance(unwrapped, (FunctionType, MethodType, BuiltinFunctionType, BuiltinMethodType)):
         raise Exception('@fact can only be applied to functions and methods.')
+    if hasattr(unwrapped, '__punit_decorator'):
+        raise Exception(
+            f'@fact and {getattr(unwrapped, "__punit_decorator")} cannot decorate the same function. '
+            f'Function "{unwrapped.__name__}" has already been decorated.'
+        )
+    setattr(unwrapped, '__punit_decorator', '@fact')
     fact: Fact = Fact(target)
     FactManager.instance().put(fact)
     return target

{punit-1.5.3 → punit-1.7.2}/src/punit/facts/FactManager.py

@@ -2,6 +2,8 @@
 # SPDX-License-Identifier: MIT
 ##
 
+from __future__ import annotations
+
 from typing import Optional
 
 from ..filters.FilterManager import FilterManager
@@ -23,7 +25,7 @@ class FactManager:
         self.__modules = {}
 
     @staticmethod
-    def instance() -> 'FactManager':
+    def instance() -> FactManager:
         if FactManager.__instance is None:
             FactManager.__instance = FactManager()
         return FactManager.__instance

{punit-1.5.3 → punit-1.7.2}/src/punit/filters/FilterManager.py

@@ -1,6 +1,8 @@
 # SPDX-FileCopyrightText: © 2026 Shaun Wilson
 # SPDX-License-Identifier: MIT
 
+from __future__ import annotations
+
 import os
 import select
 import sys
@@ -22,7 +24,7 @@ class FilterManager:
         return self.__filters
 
     @staticmethod
-    def instance() -> 'FilterManager':
+    def instance() -> FilterManager:
         instance = FilterManager.__instance
         if instance is None:
             instance = FilterManager()

{punit-1.5.3 → punit-1.7.2}/src/punit/metadata/CallableMetadata.py

@@ -14,7 +14,8 @@ class CallableMetadata:
 
     def __init__(self, callable: Union[FunctionType, MethodType, BuiltinFunctionType, BuiltinMethodType, Callable]) -> None:
         self.__callable = callable
-        self.__class_name = '.'.join(callable.__qualname__.replace(f'{callable.__module__}.', '').split('.')[0:-1])
+        parts = callable.__qualname__.replace(f'{callable.__module__}.', '').split('.')[0:-1]
+        self.__class_name = '.'.join(p for p in parts if p != '<locals>')
         self.__module_name = callable.__module__
         self.__name = callable.__name__
 

punit-1.7.2/src/punit/runner.py

@@ -0,0 +1,241 @@
+# SPDX-FileCopyrightText: © 2024 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+import importlib
+import os
+import socket
+import time
+import traceback
+from types import ModuleType
+from typing import Any, Optional
+
+from .cli import CommandLineInterface
+from .facts.FactManager import FactManager
+from .setups.SetupManager import SetupManager
+from .teardowns.TeardownManager import TeardownManager
+from .theories.TheoryManager import TheoryManager
+from .TestResult import TestResult
+
+
+class TestRunner:
+
+    __cli: CommandLineInterface
+    __filenames: list[str]
+    __test_package_name: str
+
+    def __init__(self, test_package_name: str, filenames: list[str], cli: CommandLineInterface):
+        self.__cli = cli
+        self.__filenames = filenames
+        self.__test_package_name = test_package_name
+
+    async def __setup(self, module: object, module_name: str, class_name: Optional[str] = None, class_instance: Optional[Any] = None) -> bool:
+        """Execute the setup for a test.
+
+        Returns ``False`` if an error occurred during setup (the test should not run).
+        A class-scoped ``@setup`` handles all tests in that specific class.
+        A module-scoped ``@setup`` handles all bare-function tests in that module.
+        The two scopes are independent -- there is no fallback between them; each scope fires only when it exists and the test belongs to it.
+        """
+        setup_manager = SetupManager.instance()
+
+        if class_name is not None and len(class_name) > 0:
+            # Class-scoped path -- this test lives inside a class
+            sd = setup_manager.get('class', module_name, class_name)
+            if sd is not None:
+                try:
+                    await sd.execute(module, class_instance)  # type: ignore[arg-type]
+                except Exception as ex:
+                    setup_manager.record_error()
+                    if self.__cli.verbose:  # pragma: no cover
+                        target_desc = (
+                            f"{sd.metadata.class_name}.{sd.metadata.name}"
+                            if sd.metadata.class_name
+                            else sd.metadata.name
+                        )
+                        print(f'Setup Error ({target_desc}): {ex}')
+                    return False
+        else:
+            # Module-scoped path -- this is a bare-function test
+            sd = setup_manager.get('module', module_name, '')
+            if sd is not None:
+                try:
+                    await sd.execute(module, class_instance)  # type: ignore[arg-type]
+                except Exception as ex:
+                    setup_manager.record_error()
+                    if self.__cli.verbose:  # pragma: no cover
+                        target_desc = (
+                            f"{sd.metadata.class_name}.{sd.metadata.name}"
+                            if sd.metadata.class_name
+                            else sd.metadata.name
+                        )
+                        print(f'Setup Error ({target_desc}): {ex}')
+                    return False
+        return True
+
+    async def __teardown(self, module: object, module_name: str, class_name: Optional[str] = None, class_instance: Optional[Any] = None) -> None:
+        """Execute the teardown for a test.
+
+        A class-scoped ``@teardown`` handles all tests in that specific class.
+        A module-scoped ``@teardown`` handles all bare-function tests in that
+        module.  The two scopes are independent -- there is no fallback between
+        them; each scope fires only when it exists and the test belongs to it.
+        """
+        teardown_manager = TeardownManager.instance()
+
+        if class_name is not None:
+            # Class-scoped path -- this test lives inside a class
+            td = teardown_manager.get('class', module_name, class_name)
+            if td is not None:
+                try:
+                    await td.execute(module, class_instance)  # type: ignore[arg-type]
+                except Exception as ex:
+                    teardown_manager.record_error()
+                    if self.__cli.verbose:  # pragma: no cover
+                        target_desc = (
+                            f"{td.metadata.class_name}.{td.metadata.name}"
+                            if td.metadata.class_name
+                            else td.metadata.name
+                        )
+                        print(f'Teardown Error ({target_desc}): {ex}')
+        else:
+            # Module-scoped path -- this is a bare-function test
+            td = teardown_manager.get('module', module_name, '')
+            if td is not None:
+                try:
+                    await td.execute(module, class_instance)  # type: ignore[arg-type]
+                except Exception as ex:
+                    teardown_manager.record_error()
+                    if self.__cli.verbose:  # pragma: no cover
+                        target_desc = (
+                            f"{td.metadata.class_name}.{td.metadata.name}"
+                            if td.metadata.class_name
+                            else td.metadata.name
+                        )
+                        print(f'Teardown Error ({target_desc}): {ex}')
+
+    def print_test_result(self, test_result: TestResult):
+        if self.__cli.quiet:
+            return
+        glyph = '🟩' if test_result.is_success else '🟥'
+        data = test_result.properties.get('data')
+        if data is None:
+            data = ''
+        else:
+            try:
+                data = f'({",".join([str(e) for e in data])})'
+            except Exception:
+                data = '(???)'
+        print(f'{glyph} {test_result.module_name}/{"" if test_result.class_name is None or len(test_result.class_name) == 0 else f"{test_result.class_name}/"}{test_result.test_name}{data} [{test_result.tookPretty}]')
+        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__))}')
+
+    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__)
+        for fact in facts:
+            result = TestResult()
+            result.host_name = host_name
+            result.package_name = self.__test_package_name
+            result.file_name = filename
+            result.module_name = module_report_name
+            result.start_time = time.time()
+            result.capture_output(False)
+            # Run pre-test setup; if it fails, skip the fact.
+            class_instance: Any = None
+            if await self.__setup(test_module, test_module.__name__, fact.metadata.class_name, class_instance):
+                try:
+                    class_instance = await fact.execute(test_module)
+                    result.is_success = True
+                except Exception as ex:
+                    result.is_success = False
+                    result.exception = ex
+            else:
+                # Setup failed — record a failure result.
+                result.is_success = False
+            result.stop_time = time.time()
+            result.class_name = fact.metadata.class_name
+            result.test_name = fact.metadata.name
+            results.append(result)
+            await self.__teardown(test_module, test_module.__name__, result.class_name, class_instance)
+            result.release_output()
+            self.print_test_result(result)
+            if self.__cli.failfast and not result.is_success:
+                return
+
+    async def __run_theories(self, host_name: str, test_module: ModuleType, filename: str, module_report_name: str, results: list[TestResult]) -> None:
+        """Run all theory data-points for a test module and return their results."""
+        theories = TheoryManager.instance().get(test_module.__name__)
+        for theory in theories:
+            for data in theory.datas:
+                result = TestResult()
+                result.host_name = host_name
+                result.package_name = self.__test_package_name
+                result.properties['data'] = data
+                result.file_name = filename
+                result.module_name = module_report_name
+                result.start_time = time.time()
+                result.capture_output(False)
+                # Run pre-test setup; if it fails, skip the theory.
+                class_instance: Any = None
+                if await self.__setup(test_module, test_module.__name__, theory.metadata.class_name, class_instance):
+                    try:
+                        class_instance = await theory.execute(test_module, data)
+                        result.is_success = True
+                    except Exception as ex:
+                        result.is_success = False
+                        result.exception = ex
+                else:
+                    # Setup failed — record a failure result.
+                    result.is_success = False
+                result.stop_time = time.time()
+                result.class_name = theory.metadata.class_name
+                result.test_name = theory.metadata.name
+                results.append(result)
+                await self.__teardown(test_module, test_module.__name__, result.class_name, class_instance)
+                result.release_output()
+                self.print_test_result(result)
+                if self.__cli.failfast and not result.is_success:
+                    return
+
+    async def run(self) -> list[TestResult]:
+        results: list[TestResult] = []
+        result: TestResult
+        # TODO: aliasing
+        test_package_path = os.path.join(os.path.abspath(os.curdir), self.__test_package_name).replace('\\', '/')
+        for filename in self.__filenames:
+            ts = time.time()
+            moduleImportName = filename.replace(test_package_path, '').replace('/', '.')
+            if moduleImportName.endswith('.py'):
+                moduleImportName = moduleImportName[:-3]
+            module_report_name = moduleImportName.lstrip('.')
+            try:
+                host_name: str = socket.gethostname()
+                test_module = importlib.import_module(moduleImportName, self.__test_package_name)
+
+                # execute all facts
+                await self.__run_facts(host_name, test_module, filename, module_report_name, results)
+                if self.__cli.failfast and any(e.is_success is False for e in results):
+                    return results
+
+                # execute all theories
+                await self.__run_theories(host_name, test_module, filename, module_report_name, results)
+                if self.__cli.failfast and any(e.is_success is False for e in results):
+                    return results
+
+            except Exception as ex:
+                # module-level failure, report test failure against the module
+                # this is a best-attempt to create output that report readers
+                # can consume to show there was a broad failure in a module.
+                result = TestResult()
+                result.class_name = '*'
+                result.module_name = module_report_name
+                result.test_name = '*'
+                result.start_time = ts
+                result.stop_time = time.time()
+                result.is_success = False
+                result.exception = ex
+                results.append(result)
+                self.print_test_result(result)
+                if self.__cli.failfast:
+                    return results
+        return results

punit-1.7.2/src/punit/setups/Setup.py

@@ -0,0 +1,100 @@
+# SPDX-FileCopyrightText: © 2026 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+import inspect
+from types import BuiltinFunctionType, BuiltinMethodType, FunctionType, MethodType, ModuleType
+from typing import Callable, Coroutine, Union, cast
+
+from ..metadata import CallableMetadata
+
+
+class Setup:
+
+    __metadata: CallableMetadata
+    __scope_type: str  # "module" or "class"
+    __wrapped_target: Union[FunctionType, MethodType, BuiltinFunctionType, BuiltinMethodType, Callable]
+    __target: Union[FunctionType, MethodType, BuiltinFunctionType, BuiltinMethodType, Callable]
+
+    def __init__(self, target: Union[FunctionType, MethodType, BuiltinFunctionType, BuiltinMethodType, Callable]):
+        # For descriptors (staticmethod/classmethod), unwrap to get the raw function
+        if isinstance(target, (staticmethod, classmethod)):
+            self.__wrapped_target = target
+            self.__target = cast(FunctionType, target.__func__)  # type: ignore[arg-type]
+        else:
+            self.__wrapped_target = target
+            self.__target = target
+        self.__metadata = CallableMetadata(self.__target)
+        # Determine scope from class_name: non-empty means class-scoped method
+        if (hasattr(self.__target, '__qualname__') and '.' in self.__target.__qualname__):
+            self.__scope_type = 'class'
+        else:
+            self.__scope_type = 'module'
+
+    @property
+    def metadata(self) -> CallableMetadata:
+        return self.__metadata
+
+    @property
+    def scope_type(self) -> str:
+        return self.__scope_type
+
+    @property
+    def target(self) -> Union[FunctionType, MethodType, BuiltinFunctionType, BuiltinMethodType, Callable]:
+        return self.__wrapped_target
+
+    async def execute(self, module: ModuleType, obj: object | None = None) -> None:
+        """Execute the setup function.
+
+        For module-scoped setups, ``obj`` is ignored.
+        For class-scoped setups on methods, ``obj`` should be an instance
+        of the decorated class; it is used as ``self`` via method binding.
+        """
+        if self.__scope_type == 'module':
+            coro: Coroutine | None = None
+            coro = self.__target()  # type: ignore[call-arg]
+            if inspect.iscoroutine(coro):
+                await coro
+        else:
+            # class-scoped setup method — execute on the provided instance
+            # or create one if none was supplied (defensive fallback).
+            obj_instance = obj
+            if obj_instance is None:
+                cls_name = self.__metadata.class_name
+                if cls_name:
+                    cls = getattr(module, cls_name)  # type: ignore[union-attr]
+                    obj_instance = cls()
+                else:
+                    obj_instance = cast(Callable, self.__target)()
+            if isinstance(self.__wrapped_target, staticmethod):
+                coro = self.__wrapped_target()
+            elif isinstance(self.__wrapped_target, classmethod):
+                qnparts = self.__wrapped_target.__qualname__.split('.')
+                cls = getattr(module, qnparts[-2])
+                args = (cls,)
+                coro = self.__wrapped_target.__func__(*args)
+            else:
+                # regular instance method — bind to the instance
+                bound = getattr(obj_instance, self.__target.__name__)
+                if inspect.iscoroutine(bound):
+                    await bound
+                elif callable(bound):
+                    coro = bound()  # type: ignore[bad-assignment]
+                    if inspect.iscoroutine(coro):  # type: ignore[possibly-undefined]
+                        await coro
+
+
+def setup(target: Callable) -> Callable:
+    from .SetupManager import SetupManager
+    unwrapped = inspect.unwrap(target)
+    if not isinstance(unwrapped, (FunctionType, MethodType, BuiltinFunctionType, BuiltinMethodType)):
+        raise Exception('@setup can only be applied to functions and methods.')
+    if hasattr(unwrapped, '__punit_decorator'):
+        raise Exception(
+            f'@setup and {getattr(unwrapped, "__punit_decorator")} cannot decorate the same function. '
+            f'Function "{unwrapped.__name__}" has already been decorated.'
+        )
+    setattr(unwrapped, '__punit_decorator', '@setup')
+
+    sd: Setup = Setup(target)
+    SetupManager.instance().put(sd)
+    return target

punit-1.7.2/src/punit/setups/SetupManager.py

@@ -0,0 +1,69 @@
+# SPDX-FileCopyrightText: © 2026 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+from __future__ import annotations
+
+from typing import Optional, Tuple
+
+from .Setup import Setup
+
+
+class SetupManager:
+
+    __instance: Optional['SetupManager'] = None
+    # NOTE: dict key is (scope_type, module_name, class_or_empty)
+    __setups: dict[Tuple[str, str, str], Setup]
+    __setup_error_count: int
+
+    def __init__(self) -> None:
+        if SetupManager.__instance is not None:
+            raise Exception('Cannot create more than one instance of SetupManager')  # pragma: no cover
+        self.__setups = {}
+        self.__setup_error_count = 0
+
+    @staticmethod
+    def instance() -> SetupManager:
+        if SetupManager.__instance is None:
+            SetupManager.__instance = SetupManager()
+        return SetupManager.__instance
+
+    @property
+    def setup_error_count(self) -> int:
+        return self.__setup_error_count
+
+    def get(self, scope_type: str, module_name: str, class_name: Optional[str] = None) -> Optional[Setup]:
+        """Look up a setup by (scope_type, module_name, class_name).
+
+        For class-scoped lookups ``class_name`` must match the first segment of
+        the decorated method's ``__qualname__``.  For module-scoped setups
+        pass ``class_name = None`` or empty string — the manager normalises this
+        to ``""``.
+        """
+        key: Tuple[str, str, str]
+        if class_name is None or class_name == '':
+            key = (scope_type, module_name, '')
+        else:
+            key = (scope_type, module_name, class_name)
+
+        return self.__setups.get(key)
+
+    def put(self, sd: Setup) -> None:
+        """Store a setup keyed by (scope_type, module_name, class_or_empty)."""
+        cn = sd.metadata.class_name
+        if cn is not None and len(cn) > 0:
+            key: Tuple[str, str, str] = (sd.scope_type, sd.metadata.module_name, cn)
+        else:
+            key = (sd.scope_type, sd.metadata.module_name, '')
+
+        # Only one setup per scope — last decorator wins if accidentally
+        # applied twice.
+        self.__setups[key] = sd
+
+    def record_error(self) -> None:
+        """Called when a setup function raises an exception."""
+        self.__setup_error_count += 1
+
+    @staticmethod
+    def reset() -> None:
+        """Reset the singleton (used between test modules / suites)."""
+        SetupManager.__instance = None

punit-1.7.2/src/punit/setups/__init__.py

@@ -0,0 +1,11 @@
+# SPDX-FileCopyrightText: © 2026 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+from .Setup import Setup, setup
+from .SetupManager import SetupManager
+
+
+__all__ = [
+    'Setup', 'setup',
+    'SetupManager'
+]

punit-1.7.2/src/punit/teardowns/Teardown.py

@@ -0,0 +1,100 @@
+# SPDX-FileCopyrightText: © 2026 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+import inspect
+from types import BuiltinFunctionType, BuiltinMethodType, FunctionType, MethodType, ModuleType
+from typing import Callable, Coroutine, Union, cast
+
+from ..metadata import CallableMetadata
+
+
+class Teardown:
+
+    __metadata: CallableMetadata
+    __scope_type: str  # "module" or "class"
+    __wrapped_target: Union[FunctionType, MethodType, BuiltinFunctionType, BuiltinMethodType, Callable]
+    __target: Union[FunctionType, MethodType, BuiltinFunctionType, BuiltinMethodType, Callable]
+
+    def __init__(self, target: Union[FunctionType, MethodType, BuiltinFunctionType, BuiltinMethodType, Callable]):
+        # For descriptors (staticmethod/classmethod), unwrap to get the raw function
+        if isinstance(target, (staticmethod, classmethod)):
+            self.__wrapped_target = target
+            self.__target = cast(FunctionType, target.__func__)  # type: ignore[arg-type]
+        else:
+            self.__wrapped_target = target
+            self.__target = target
+        self.__metadata = CallableMetadata(self.__target)
+        # Determine scope from class_name: non-empty means class-scoped method
+        if (hasattr(self.__target, '__qualname__') and '.' in self.__target.__qualname__):
+            self.__scope_type = 'class'
+        else:
+            self.__scope_type = 'module'
+
+    @property
+    def metadata(self) -> CallableMetadata:
+        return self.__metadata
+
+    @property
+    def scope_type(self) -> str:
+        return self.__scope_type
+
+    @property
+    def target(self) -> Union[FunctionType, MethodType, BuiltinFunctionType, BuiltinMethodType, Callable]:
+        return self.__wrapped_target
+
+    async def execute(self, module: ModuleType, obj: object | None = None) -> None:
+        """Execute the teardown function.
+
+        For module-scoped teardowns, ``obj`` is ignored.
+        For class-scoped teardowns on methods, ``obj`` should be an instance
+        of the decorated class; it is used as ``self`` via method binding.
+        """
+        if self.__scope_type == 'module':
+            coro: Coroutine | None = None
+            coro = self.__target()  # type: ignore[call-arg]
+            if inspect.iscoroutine(coro):
+                await coro
+        else:
+            # class-scoped teardown method — execute on the provided instance
+            # or create one if none was supplied (defensive fallback).
+            obj_instance = obj
+            if obj_instance is None:
+                cls_name = self.__metadata.class_name
+                if cls_name:
+                    cls = getattr(module, cls_name)  # type: ignore[union-attr]
+                    obj_instance = cls()
+                else:
+                    obj_instance = cast(Callable, self.__target)()
+            if isinstance(self.__wrapped_target, staticmethod):
+                coro = self.__wrapped_target()
+            elif isinstance(self.__wrapped_target, classmethod):
+                qnparts = self.__wrapped_target.__qualname__.split('.')
+                cls = getattr(module, qnparts[-2])
+                args = (cls,)
+                coro = self.__wrapped_target.__func__(*args)
+            else:
+                # regular instance method — bind to the instance
+                bound = getattr(obj_instance, self.__target.__name__)
+                if inspect.iscoroutine(bound):
+                    await bound
+                elif callable(bound):
+                    coro = bound()  # type: ignore[bad-assignment]
+                    if inspect.iscoroutine(coro):  # type: ignore[possibly-undefined]
+                        await coro
+
+
+def teardown(target: Callable) -> Callable:
+    from .TeardownManager import TeardownManager
+    unwrapped = inspect.unwrap(target)
+    if not isinstance(unwrapped, (FunctionType, MethodType, BuiltinFunctionType, BuiltinMethodType)):
+        raise Exception('@teardown can only be applied to functions and methods.')
+    if hasattr(unwrapped, '__punit_decorator'):
+        raise Exception(
+            f'@teardown and {getattr(unwrapped, "__punit_decorator")} cannot decorate the same function. '
+            f'Function "{unwrapped.__name__}" has already been decorated.'
+        )
+    setattr(unwrapped, '__punit_decorator', '@teardown')
+
+    td: Teardown = Teardown(target)
+    TeardownManager.instance().put(td)
+    return target

punit-1.7.2/src/punit/teardowns/TeardownManager.py

@@ -0,0 +1,69 @@
+# SPDX-FileCopyrightText: © 2026 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+from __future__ import annotations
+
+from typing import Optional, Tuple
+
+from .Teardown import Teardown
+
+
+class TeardownManager:
+
+    __instance: Optional['TeardownManager'] = None
+    # NOTE: dict key is (scope_type, module_name, class_or_empty)
+    __teardowns: dict[Tuple[str, str, str], Teardown]
+    __teardown_error_count: int
+
+    def __init__(self) -> None:
+        if TeardownManager.__instance is not None:
+            raise Exception('Cannot create more than one instance of TeardownManager')  # pragma: no cover
+        self.__teardowns = {}
+        self.__teardown_error_count = 0
+
+    @staticmethod
+    def instance() -> TeardownManager:
+        if TeardownManager.__instance is None:
+            TeardownManager.__instance = TeardownManager()
+        return TeardownManager.__instance
+
+    @property
+    def teardown_error_count(self) -> int:
+        return self.__teardown_error_count
+
+    def get(self, scope_type: str, module_name: str, class_name: Optional[str] = None) -> Optional[Teardown]:
+        """Look up a teardown by (scope_type, module_name, class_name).
+
+        For class-scoped lookups ``class_name`` must match the first segment of
+        the decorated method's ``__qualname__``.  For module-scoped teardowns
+        pass ``class_name = None`` or empty string — the manager normalises this
+        to ``""``.
+        """
+        key: Tuple[str, str, str]
+        if class_name is None or class_name == '':
+            key = (scope_type, module_name, '')
+        else:
+            key = (scope_type, module_name, class_name)
+
+        return self.__teardowns.get(key)
+
+    def put(self, td: Teardown) -> None:
+        """Store a teardown keyed by (scope_type, module_name, class_or_empty)."""
+        cn = td.metadata.class_name
+        if cn is not None and len(cn) > 0:
+            key: Tuple[str, str, str] = (td.scope_type, td.metadata.module_name, cn)
+        else:
+            key = (td.scope_type, td.metadata.module_name, '')
+
+        # Only one teardown per scope — last decorator wins if accidentally
+        # applied twice.
+        self.__teardowns[key] = td
+
+    def record_error(self) -> None:
+        """Called when a teardown function raises an exception."""
+        self.__teardown_error_count += 1
+
+    @staticmethod
+    def reset() -> None:
+        """Reset the singleton (used between test modules / suites)."""
+        TeardownManager.__instance = None

punit-1.7.2/src/punit/teardowns/__init__.py

@@ -0,0 +1,11 @@
+# SPDX-FileCopyrightText: © 2026 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+from .Teardown import Teardown, teardown
+from .TeardownManager import TeardownManager
+
+
+__all__ = [
+    'Teardown', 'teardown',
+    'TeardownManager'
+]

{punit-1.5.3 → punit-1.7.2}/src/punit/theories/Theory.py

@@ -4,7 +4,7 @@
 
 import inspect
 from types import BuiltinFunctionType, BuiltinMethodType, FunctionType, MethodType, ModuleType
-from typing import Callable, Coroutine, Optional, Union, cast
+from typing import Any, Callable, Coroutine, Union, cast
 
 from ..metadata import CallableMetadata
 
@@ -31,13 +31,15 @@ class Theory:
     def target(self) -> Union[FunctionType, MethodType, BuiltinFunctionType, BuiltinMethodType, Callable]:
         return self.__target
 
-    async def execute(self, module: ModuleType, data: tuple) -> None:
+    async def execute(self, module: ModuleType, data: tuple) -> Any | None:
+        class_instance: Any | None = None
         coro: Coroutine | None = None
         if hasattr(self.__target, '__qualname__') and self.__target.__qualname__.find('.') > -1:
             qnparts = self.__target.__qualname__.split('.')
             if isinstance(self.__target, staticmethod):
                 coro = self.__target(*data)
             else:
+                qnparts = [p for p in self.__target.__qualname__.split('.') if p != '<locals>']
                 qntarget = module
                 for qnpart in qnparts[0:-1]:
                     qntarget = getattr(qntarget, qnpart)
@@ -46,19 +48,28 @@ class Theory:
                     coro = self.__target.__func__(*args)
                 else:
                     # every test execution gets a new instance of class
-                    args = (cast(Callable, qntarget)(),) + data
+                    class_instance = cast(Any, cast(Callable, qntarget)())
+                    args = (class_instance,) + data
                     coro = self.__target(*args)
         else:
             self.__test_name = self.__target.__name__
             coro = self.__target(*data)
         if inspect.iscoroutine(coro):
             await coro
+        return class_instance
 
 
 def theory(target: Callable) -> Callable:
     from .TheoryManager import TheoryManager
-    if (not inspect.isfunction(target)) and (not isinstance(target, classmethod)) and (not isinstance(target, staticmethod)):
+    unwrapped = inspect.unwrap(target)
+    if not isinstance(unwrapped, (FunctionType, MethodType, BuiltinFunctionType, BuiltinMethodType)):
         raise Exception('@theory can only be applied to functions and methods.')
+    if hasattr(unwrapped, '__punit_decorator'):
+        raise Exception(
+            f'@theory and {getattr(unwrapped, "__punit_decorator")} cannot decorate the same function. '
+            f'Function "{unwrapped.__name__}" has already been decorated.'
+        )
+    setattr(unwrapped, '__punit_decorator', '@theory')
     theory: Theory = Theory(target)
     TheoryManager.instance().put(theory)
     return target

{punit-1.5.3 → punit-1.7.2}/src/punit/theories/TheoryManager.py

@@ -2,6 +2,8 @@
 # SPDX-License-Identifier: MIT
 ##
 
+from __future__ import annotations
+
 from typing import Callable, Optional
 
 from ..filters.FilterManager import FilterManager
@@ -25,7 +27,7 @@ class TheoryManager:
         self.__datas = {}
 
     @staticmethod
-    def instance() -> 'TheoryManager':
+    def instance() -> TheoryManager:
         if TheoryManager.__instance is None:
             TheoryManager.__instance = TheoryManager()
         return TheoryManager.__instance

{punit-1.5.3 → punit-1.7.2}/src/punit/traits/TraitManager.py

@@ -1,6 +1,7 @@
 # SPDX-FileCopyrightText: © 2026 Shaun Wilson
 # SPDX-License-Identifier: MIT
-##
+
+from __future__ import annotations
 
 from types import FunctionType, MethodType
 from typing import Callable, Optional
@@ -19,7 +20,7 @@ class TraitManager:
         self.__traits = dict[Callable | FunctionType | MethodType, dict[str, Trait]]()
 
     @staticmethod
-    def instance() -> 'TraitManager':
+    def instance() -> TraitManager:
         if TraitManager.__instance is None:
             TraitManager.__instance = TraitManager()
         return TraitManager.__instance

punit-1.5.3/src/punit/runner.py

@@ -1,124 +0,0 @@
-# SPDX-FileCopyrightText: © 2024 Shaun Wilson
-# SPDX-License-Identifier: MIT
-
-import importlib
-import os
-import socket
-import time
-import traceback
-
-from .cli import CommandLineInterface
-from .facts.FactManager import FactManager
-from .metadata.CallableMetadata import CallableMetadata
-from .theories.TheoryManager import TheoryManager
-from .TestResult import TestResult
-
-
-class TestRunner:
-
-    __cli: CommandLineInterface
-    __filenames: list[str]
-    __test_package_name: str
-
-    def __init__(self, test_package_name: str, filenames: list[str], cli: CommandLineInterface):
-        self.__cli = cli
-        self.__filenames = filenames
-        self.__test_package_name = test_package_name
-
-    def print_test_result(self, test_result: TestResult):
-        if self.__cli.quiet:
-            return
-        glyph = '🟩' if test_result.is_success else '🟥'
-        data = test_result.properties.get('data')
-        if data is None:
-            data = ''
-        else:
-            try:
-                data = f'({",".join([str(e) for e in data])})'
-            except Exception:
-                data = '(???)'
-        print(f'{glyph} {test_result.module_name}/{"" if test_result.class_name is None or len(test_result.class_name) == 0 else f"{test_result.class_name}/"}{test_result.test_name}{data} [{test_result.tookPretty}]')
-        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__))}')
-
-    async def run(self) -> list[TestResult]:
-        results: list[TestResult] = []
-        result: TestResult
-        # TODO: aliasing
-        host_name: str = socket.gethostname()
-        test_package_path = os.path.join(os.path.abspath(os.curdir), self.__test_package_name).replace('\\', '/')
-        for filename in self.__filenames:
-            ts = time.time()
-            moduleImportName = filename.replace(test_package_path, '').replace('/', '.')
-            if moduleImportName.endswith('.py'):
-                moduleImportName = moduleImportName[:-3]
-            module_report_name = moduleImportName.lstrip('.')
-            try:
-                testModule = importlib.import_module(moduleImportName, self.__test_package_name)
-                # execute all facts
-                facts = FactManager.instance().get(testModule.__name__)
-                for fact in facts:
-                    result = TestResult()
-                    result.host_name = host_name
-                    result.package_name = self.__test_package_name
-                    result.file_name = filename
-                    result.module_name = module_report_name
-                    result.start_time = time.time()
-                    result.captureOutput(not self.__cli.verbose)
-                    try:
-                        await fact.execute(testModule)
-                        result.is_success = True
-                    except Exception as ex:
-                        result.is_success = False
-                        result.exception = ex
-                    result.releaseOutput()
-                    result.stop_time = time.time()
-                    result.class_name = fact.metadata.class_name
-                    result.test_name = fact.metadata.name
-                    results.append(result)
-                    self.print_test_result(result)
-                    if self.__cli.failfast and not result.is_success:
-                        return results
-                # execute all theories
-                theories = TheoryManager.instance().get(testModule.__name__)
-                for theory in theories:
-                    for data in theory.datas:
-                        result = TestResult()
-                        result.host_name = host_name
-                        result.package_name = self.__test_package_name
-                        result.properties['data'] = data
-                        result.file_name = filename
-                        result.module_name = module_report_name
-                        result.start_time = time.time()
-                        result.captureOutput(not self.__cli.verbose)
-                        try:
-                            await theory.execute(testModule, data)
-                            result.is_success = True
-                        except Exception as ex:
-                            result.is_success = False
-                            result.exception = ex
-                        result.releaseOutput()
-                        result.stop_time = time.time()
-                        result.class_name = theory.metadata.class_name
-                        result.test_name = theory.metadata.name
-                        results.append(result)
-                        self.print_test_result(result)
-                        if self.__cli.failfast and not result.is_success:
-                            return results
-            except Exception as ex:
-                # module-level failure, report test failure against the module
-                # this is a best-attempt to create output that report readers
-                # can consume to show there was a broad failure in a module.
-                result = TestResult()
-                result.class_name = '*'
-                result.module_name = module_report_name
-                result.test_name = '*'
-                result.start_time = ts
-                result.stop_time = time.time()
-                result.is_success = False
-                result.exception = ex
-                results.append(result)
-                self.print_test_result(result)
-                if self.__cli.failfast:
-                    return results
-        return results