punit 0.0.27__tar.gz

punit-0.0.27/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Shaun Wilson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

punit-0.0.27/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.2
+Name: punit
+Version: 0.0.27
+Summary: A modernized unit-test framework for Python.
+Author-email: Shaun Wilson <mrshaunwilson@msn.com>
+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
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+
+`pUnit` is a modernized unit-testing framework for Python, inspired by xUnit.
+
+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).
+
+## Command-Line Usage
+
+Running pUnit with no arguments will perform test auto-discovery and execution:
+
+```bash
+python3 -m punit
+```
+
+By default it will look for tests in the `tests/` directory. You can override this behavior by providing a `--test-package` argument:
+
+```bash
+python3 -m punit --test-package elsewhere
+```
+
+In the above example, test discovery will instead occur in an `elsewhere/` directory.
+
+### Report Generation
+
+`pUnit` can generate "Test Results" reports. Currently supporting HTML and jUnit formats:
+
+```bash
+python3 -m punit --report html
+```
+
+Reports can also be output to a file where they can be lifted as part of a CI/CD pipeline and stored as an artifact or used for other purposes:
+
+```bash
+python3 -m punit --report junit --output results.xml
+```
+
+### Syntax Help
+
+There are more options available, passing a `--help` argument will print help text:
+
+```bash
+python3 -m punit --help
+```
+Outputs:
+```plaintext
+Usage: python3 -m punit [-h|--help]
+                        [-q|--quiet] [-v|--verbose]
+                        [-f|--failfast]
+                        [-p|--test-package NAME]
+                        [-i|--include PATTERN]
+                        [-e|--exclude PATTERN]
+                        [-t|--filter PATTERN]
+                        [-w|--workdir DIRECTORY]
+                        [-n|--no-default-patterns]
+                        [-r|--report {junit|json}]
+                        [-o|--output FILENAME]
+
+Options:
+    -h, --help           Show this help text and exit
+    -q, --quiet          Quiet output
+    -v, --verbose        Verbose output
+    -f, --failfast       Stop on first failure or error
+    -p, --test-package NAME
+        Use NAME as the test package, all tests should
+        be locatable as modules in the named package.
+        Default: 'tests'
+    -i, --include PATTERN
+        Include any tests matching PATTERN
+        Default: '*.py'
+    -e, --exclude PATTERN
+        Exclude any tests matching PATTERN, overriding --include
+        Default: '__*__' (dunder files), '/.*/' (dot-directories)
+    -t, --filter PATTERN
+        Only execute tests matching PATTERN
+        Default: '*'
+    -w, --working-directory DIRECTORY
+        Working directory (defaults to start directory)
+    -n, --no-default-patterns
+        Do not apply any default include/exclude patterns.
+    -r, --report {html|junit}
+        Generate a report to stdout using either an "html"
+        or "junit" format. When generating a report to stdout
+        all other output is suppressed, unless `--output`
+        is also specified.
+    -o, --output FILENAME
+        If `--report` is used, instead of writing to stdout
+        write to FILENAME. In this case `--report` does not
+        suppress any program output.
+```
+
+## Writing Tests
+
+You can write tests as functions, class methods, instance methods, or static methods with all forms offering identical functionality. You can also utilize async/await syntax without any additional overhead.
+
+**pUnit** is based upon the fundamental concepts of `Facts` and `Theories`. These are codified using decorators, aptly named `@fact` and `@theory`. Consider these examples:
+
+```python
+
+from punit import *
+
+@fact
+async def MyLibrary_WhenInitialized_TouchMustReturnTrue:
+    mylib = MyLibrary()
+    mylib.initialize()
+    await asyncio.sleep(1)
+    assert mylib.touch(), "Expecting touch() to return true, because initialize() was called."
+
+class MyTestFixture:
+
+    def calc(number:int|None = None):
+        if number == None:
+            raise Exception('Invalid value "None".')
+        return number * number
+
+    @theory
+    @inlinedata(0, 0)
+    @inlinedata(1, 1)
+    @inlinedata(2, 4)
+    @inlinedata(3, 9)
+    @inlinedata(5, 25)
+    @inlinedata(8, 64)
+    def verifyCalcAssumptions(self, number:int, expected:int) -> None:
+        assert expected == self.calc(number)
+
+    @fact
+    def verifyCalcErrorCondition(self) -> None:
+        from punit.exceptions import raises
+        # assert errors are raised, or not
+        def calc_None():
+            self.calc(None)
+        def calc_1()
+            self.calc(1)
+        assert raises[Exception](calc_None)
+        assert not raises[Exception](calc_1)
+```
+
+Because `pUnit` is a decorative framework you are afforded the utmost freedom in how you structure and implement your tests.
+
+Unlike other testing frameworks, the names you use for functions, classes, and methods is not relevant. There is no requirement to inherit classes from specific abstract/base classes for any particular functionality. There is no requirement that your tests be organized into modules with `__init__.py` files.
+
+You will want to take particular note of the `--exclude` command-line parameter which allows you to restrict what `pUnit` will consider to be a valid test file. While the default behavior will fit 99% of use-cases, you _can_ exercise more control over the discovery process.
+
+## Vision, Future, and LTS
+
+The long-term vision is to provide both imperative and declarative syntaxes for testing while keeping `pUnit` as simple as possible in its implementation.
+
+`pUnit` is a Python 3.12+ package and there are no plans to backport it to earlier versions of Python, however, user contributions to support backward compatibility _will be accepted_ when it makes sense.
+
+As Python progresses so will `pUnit` and SEMVER rules will be respected to provide developers with assurance that a major version of `pUnit` is fit for a particular purpose, thus, if there is ever a breaking change in Python that requires a breaking change in `pUnit` you can expect `pUnit` versioning to reflect this.
+
+In any situation where an undocumented feature may be used maintainers will actively keep watch on deprecation notices and removals, will clearly identify these dependencies in the docs, and most importantly will provide a LTS alternative to any undocumented feature or such features will not be included in `pUnit`.
+
+With respect to long-term support, we will commit to maintaining major versions for 3 years from the date they were superceded by a new major version. This should align well with Python Core Development.
+
+## Contact
+
+You can reach me on [Discord](https://discordapp.com/users/307684202080501761) or [open an Issue on Github](https://github.com/wilson0x4d/punit/issues/new/choose).

punit-0.0.27/README.md

@@ -0,0 +1,155 @@
+`pUnit` is a modernized unit-testing framework for Python, inspired by xUnit.
+
+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).
+
+## Command-Line Usage
+
+Running pUnit with no arguments will perform test auto-discovery and execution:
+
+```bash
+python3 -m punit
+```
+
+By default it will look for tests in the `tests/` directory. You can override this behavior by providing a `--test-package` argument:
+
+```bash
+python3 -m punit --test-package elsewhere
+```
+
+In the above example, test discovery will instead occur in an `elsewhere/` directory.
+
+### Report Generation
+
+`pUnit` can generate "Test Results" reports. Currently supporting HTML and jUnit formats:
+
+```bash
+python3 -m punit --report html
+```
+
+Reports can also be output to a file where they can be lifted as part of a CI/CD pipeline and stored as an artifact or used for other purposes:
+
+```bash
+python3 -m punit --report junit --output results.xml
+```
+
+### Syntax Help
+
+There are more options available, passing a `--help` argument will print help text:
+
+```bash
+python3 -m punit --help
+```
+Outputs:
+```plaintext
+Usage: python3 -m punit [-h|--help]
+                        [-q|--quiet] [-v|--verbose]
+                        [-f|--failfast]
+                        [-p|--test-package NAME]
+                        [-i|--include PATTERN]
+                        [-e|--exclude PATTERN]
+                        [-t|--filter PATTERN]
+                        [-w|--workdir DIRECTORY]
+                        [-n|--no-default-patterns]
+                        [-r|--report {junit|json}]
+                        [-o|--output FILENAME]
+
+Options:
+    -h, --help           Show this help text and exit
+    -q, --quiet          Quiet output
+    -v, --verbose        Verbose output
+    -f, --failfast       Stop on first failure or error
+    -p, --test-package NAME
+        Use NAME as the test package, all tests should
+        be locatable as modules in the named package.
+        Default: 'tests'
+    -i, --include PATTERN
+        Include any tests matching PATTERN
+        Default: '*.py'
+    -e, --exclude PATTERN
+        Exclude any tests matching PATTERN, overriding --include
+        Default: '__*__' (dunder files), '/.*/' (dot-directories)
+    -t, --filter PATTERN
+        Only execute tests matching PATTERN
+        Default: '*'
+    -w, --working-directory DIRECTORY
+        Working directory (defaults to start directory)
+    -n, --no-default-patterns
+        Do not apply any default include/exclude patterns.
+    -r, --report {html|junit}
+        Generate a report to stdout using either an "html"
+        or "junit" format. When generating a report to stdout
+        all other output is suppressed, unless `--output`
+        is also specified.
+    -o, --output FILENAME
+        If `--report` is used, instead of writing to stdout
+        write to FILENAME. In this case `--report` does not
+        suppress any program output.
+```
+
+## Writing Tests
+
+You can write tests as functions, class methods, instance methods, or static methods with all forms offering identical functionality. You can also utilize async/await syntax without any additional overhead.
+
+**pUnit** is based upon the fundamental concepts of `Facts` and `Theories`. These are codified using decorators, aptly named `@fact` and `@theory`. Consider these examples:
+
+```python
+
+from punit import *
+
+@fact
+async def MyLibrary_WhenInitialized_TouchMustReturnTrue:
+    mylib = MyLibrary()
+    mylib.initialize()
+    await asyncio.sleep(1)
+    assert mylib.touch(), "Expecting touch() to return true, because initialize() was called."
+
+class MyTestFixture:
+
+    def calc(number:int|None = None):
+        if number == None:
+            raise Exception('Invalid value "None".')
+        return number * number
+
+    @theory
+    @inlinedata(0, 0)
+    @inlinedata(1, 1)
+    @inlinedata(2, 4)
+    @inlinedata(3, 9)
+    @inlinedata(5, 25)
+    @inlinedata(8, 64)
+    def verifyCalcAssumptions(self, number:int, expected:int) -> None:
+        assert expected == self.calc(number)
+
+    @fact
+    def verifyCalcErrorCondition(self) -> None:
+        from punit.exceptions import raises
+        # assert errors are raised, or not
+        def calc_None():
+            self.calc(None)
+        def calc_1()
+            self.calc(1)
+        assert raises[Exception](calc_None)
+        assert not raises[Exception](calc_1)
+```
+
+Because `pUnit` is a decorative framework you are afforded the utmost freedom in how you structure and implement your tests.
+
+Unlike other testing frameworks, the names you use for functions, classes, and methods is not relevant. There is no requirement to inherit classes from specific abstract/base classes for any particular functionality. There is no requirement that your tests be organized into modules with `__init__.py` files.
+
+You will want to take particular note of the `--exclude` command-line parameter which allows you to restrict what `pUnit` will consider to be a valid test file. While the default behavior will fit 99% of use-cases, you _can_ exercise more control over the discovery process.
+
+## Vision, Future, and LTS
+
+The long-term vision is to provide both imperative and declarative syntaxes for testing while keeping `pUnit` as simple as possible in its implementation.
+
+`pUnit` is a Python 3.12+ package and there are no plans to backport it to earlier versions of Python, however, user contributions to support backward compatibility _will be accepted_ when it makes sense.
+
+As Python progresses so will `pUnit` and SEMVER rules will be respected to provide developers with assurance that a major version of `pUnit` is fit for a particular purpose, thus, if there is ever a breaking change in Python that requires a breaking change in `pUnit` you can expect `pUnit` versioning to reflect this.
+
+In any situation where an undocumented feature may be used maintainers will actively keep watch on deprecation notices and removals, will clearly identify these dependencies in the docs, and most importantly will provide a LTS alternative to any undocumented feature or such features will not be included in `pUnit`.
+
+With respect to long-term support, we will commit to maintaining major versions for 3 years from the date they were superceded by a new major version. This should align well with Python Core Development.
+
+## Contact
+
+You can reach me on [Discord](https://discordapp.com/users/307684202080501761) or [open an Issue on Github](https://github.com/wilson0x4d/punit/issues/new/choose).

punit-0.0.27/punit/TestResult.py

@@ -0,0 +1,180 @@
+# SPDX-FileCopyrightText: © 2024 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+import sys
+from typing import TextIO
+
+class TextIOCapture:
+
+    __quiet:bool
+    output:str = None
+    target:TextIO
+
+    def __init__(self, target:TextIO, quiet:bool = False) -> None:
+        self.__quiet = quiet
+        self.output = None
+        self.target = target
+
+    def write(self, text:str):
+        if self.output is None:
+            self.output = text
+        else:
+            self.output += text
+        if not self.__quiet:
+            self.target.write(text)
+
+class TestResult:
+
+    __className:str
+    __exception:Exception
+    __fileName:str
+    __hostName:str
+    __isSuccess:bool
+    __moduleName:str
+    __packageName:str
+    __properties:dict[str, str]
+    __startTime:float
+    __stderrCapture:TextIOCapture
+    __stdoutCapture:TextIOCapture
+    __stopTime:float
+    __testName:str
+
+    def __init__(self):
+        self.__className = None
+        self.__exception = None
+        self.__fileName = None
+        self.__hostName = None
+        self.__isSuccess = None
+        self.__moduleName = None
+        self.__packageName = None
+        self.__properties = {}
+        self.__startTime = None
+        self.__stderrCapture = None
+        self.__stdoutCapture = None
+        self.__stopTime = None
+        self.__testName = None
+
+    @property
+    def className(self) -> str:
+        return self.__className
+    
+    @className.setter
+    def className(self, value:str) -> None:
+        self.__className = value
+
+    @property
+    def exception(self) -> Exception:
+        return self.__exception
+    
+    @exception.setter
+    def exception(self, value:Exception) -> None:
+        self.__exception = value
+
+    @property
+    def fileName(self) -> str:
+        return self.__fileName
+    
+    @fileName.setter
+    def fileName(self, value:str) -> None:
+        self.__fileName = value
+
+    @property
+    def hostName(self) -> str:
+        return self.__hostName
+    
+    @hostName.setter
+    def hostName(self, value:str) -> None:
+        self.__hostName = value
+
+    @property
+    def isSuccess(self) -> bool:
+        return self.__isSuccess
+    
+    @isSuccess.setter
+    def isSuccess(self, value:bool) -> None:
+        self.__isSuccess = value
+
+    @property
+    def moduleName(self) -> str:
+        return self.__moduleName
+    
+    @moduleName.setter
+    def moduleName(self, value:str) -> None:
+        self.__moduleName = value
+
+    @property
+    def packageName(self) -> str:
+        return self.__packageName
+    
+    @packageName.setter
+    def packageName(self, value:str) -> None:
+        self.__packageName = value
+
+    @property
+    def properties(self) -> dict[str, str]:
+        return self.__properties
+    
+    @properties.setter
+    def properties(self, value:dict[str, str]) -> None:
+        self.__properties = value
+
+    @property
+    def startTime(self) -> float:
+        return self.__startTime
+    
+    @startTime.setter
+    def startTime(self, value:float) -> None:
+        self.__startTime = value
+
+    @property
+    def stderr(self) -> str:
+        return None if self.__stderrCapture is None else self.__stderrCapture.output
+
+    @property
+    def stdout(self) -> str:
+        return None if self.__stdoutCapture is None else self.__stdoutCapture.output
+
+    @property
+    def stopTime(self) -> float:
+        return self.__stopTime
+    
+    @stopTime.setter
+    def stopTime(self, value:float) -> None:
+        self.__stopTime = value
+
+    @property
+    def testName(self) -> str:
+        return self.__testName
+    
+    @testName.setter
+    def testName(self, value:str) -> None:
+        self.__testName = value
+
+    @property
+    def took(self) -> float:
+        return self.__stopTime - self.__startTime
+
+    @property
+    def tookPretty(self) -> str:
+        took = self.took
+        if took >= 1:
+            return f'{took:.1f}'.rstrip('0').rstrip('.') + 's'
+        elif took >= 0.001:
+            return f'{(took*1000):.0f}ms'
+        elif took >= 0.000001:
+            return f'{(took*1000):.3f}'.rstrip('0').rstrip('.') + 'ms'
+        elif took >= 0.000000001:
+            return f'{(took*1000000):.3f}'.rstrip('0').rstrip('.') + 'μs'
+        else:
+            return f'{(took*1000):.3f}'.rstrip('0').rstrip('.') + 'ms'
+
+
+    def captureOutput(self, quiet:bool = False) -> tuple[TextIO, TextIO]:
+        self.__stdoutCapture = TextIOCapture(sys.stdout, quiet)
+        self.__stderrCapture = TextIOCapture(sys.stderr, quiet)
+        sys.stdout = self.__stdoutCapture
+        sys.stderr = self.__stderrCapture
+
+    def releaseOutput(self) -> None:
+        sys.stdout = self.__stdoutCapture.target
+        sys.stderr = self.__stderrCapture.target

punit-0.0.27/punit/__init__.py

@@ -0,0 +1,8 @@
+# SPDX-FileCopyrightText: © 2024 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+__version__ = '0.0.27'
+
+from .assertions import *
+from .facts import *
+from .theories import *

punit-0.0.27/punit/__main__.py

@@ -0,0 +1,55 @@
+# SPDX-FileCopyrightText: © 2024 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+import asyncio
+from .cli import *
+from .discovery import *
+from .reports import HtmlReportGenerator, JUnitReportGenerator
+from .runner import *
+
+async def async_main():
+    ts = time.time()
+    cli = CommandLineInterface.parse()
+    if cli.help:
+        cli.printHelp()
+    elif cli.verbose and not cli.quiet:
+        cli.printSummary()
+    elif not cli.quiet:
+        cli.printVersion()
+    os.chdir(cli.workdir)
+    testModuleDiscovery = TestModuleDiscovery(
+        os.path.join(cli.workdir, cli.testPackageName),
+        cli.includePatterns,
+        cli.excludePatterns,
+        cli)
+    testModuleDiscovery.discover()
+    testRunner = TestRunner(cli.testPackageName, testModuleDiscovery.filenames, cli)
+    results = await testRunner.run()
+    totalTime = time.time() - ts
+    failureCount = 0
+    for result in results:
+        if not result.isSuccess:
+            failureCount += 1
+    if not cli.quiet:
+        print(f'Total: {len(results)}, Failures: {failureCount}, Took: {totalTime:.3f}s')
+    if cli.reportFormat is not None:
+        report:str = None
+        match cli.reportFormat:
+            case 'html':
+                report = HtmlReportGenerator().generate(results)
+            case 'junit':
+                report = JUnitReportGenerator().generate(results)
+        if cli.outputFilename is None:
+            print(report)
+        else:
+            with open(cli.outputFilename, 'wt') as file:
+                file.write(report)
+            print(f'\n("{cli.reportFormat}" report written to: {cli.outputFilename})')
+    if failureCount > 0:
+        exit(119)
+
+def main():
+    asyncio.run(async_main())
+
+if (__name__ == '__main__'):
+    main()

punit-0.0.27/punit/assertions/__init__.py

@@ -0,0 +1,7 @@
+# SPDX-FileCopyrightText: © 2024 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+__all__ = [
+    'collections',
+    'exceptions'
+]

punit-0.0.27/punit/assertions/collections.py

@@ -0,0 +1,18 @@
+# SPDX-FileCopyrightText: © 2024 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+from typing import Any, Sequence
+
+def areSame(a:Sequence[Any], b:Sequence[Any]) -> bool:
+    if a is b:
+        return True
+    elif a is None and b is not None:
+        return False
+    elif a is not None and b is None:
+        return False
+    elif len(a) != len(b):        
+        return False
+    for i in range(len(a)):
+        if not a[i] == b[i]:
+            return False
+    return True

punit-0.0.27/punit/assertions/exceptions.py

@@ -0,0 +1,33 @@
+# SPDX-FileCopyrightText: © 2024 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+from typing import Callable, get_args
+
+def isNoneOrWhiteSpace(input:str):
+    return input is None or len(input.lstrip()) == 0
+
+def isNoneOrEmpty(input:str):
+    return input is None or len(input) == 0
+
+class raises[TError:Exception]:
+    
+    __action:Callable
+    __exact:bool
+    __expect:TError
+
+    def __init__(self, action:Callable, *, exact:bool = False, expect:TError = 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:
+                expected = get_args(self.__orig_class__)[0]
+            if self.__exact:
+                return type(ex) is expected
+            else:
+                return issubclass(type(ex), expected)