pUnit 1.2.0__py3-none-any.whl

punit/cli.py

@@ -0,0 +1,294 @@
+# SPDX-FileCopyrightText: © Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+import os
+import sys
+from typing import Optional
+from . import __version__
+from .traits import Trait
+
+
+class CommandLineInterface:
+
+    __aliases:dict[str,str]
+    __excludePatterns:list[str]
+    __excludeTraits:list[Trait]
+    __failfast:bool
+    __filterPattern:str
+    __help:bool
+    __includePatterns:list[str]
+    __includeTraits:list[Trait]
+    __no_default_patterns:bool
+    __outputFilename:Optional[str]
+    __quiet:bool
+    __reportFormat:Optional[str]
+    __testPackageName:str|None
+    __verbose:bool
+    __workdir:str|None
+
+    def __init__(self):
+        self.__aliases = dict[str,str]()
+        self.__excludePatterns = []
+        self.__excludeTraits = []
+        self.__failfast = False
+        self.__filterPattern = '*'
+        self.__help = False
+        self.__includePatterns = []
+        self.__includeTraits = []
+        self.__no_default_patterns = False
+        self.__outputFilename = None
+        self.__quiet = False
+        self.__reportFormat = None
+        self.__testPackageName = 'tests'
+        self.__workdir = os.path.curdir
+        self.__verbose = False
+
+    def __parse(self, argv:list[str]) -> 'CommandLineInterface':
+        aliasName:str|None = None
+        extractFilterPattern:bool = False
+        extractExcludePattern:bool = False
+        extractTrait:bool = False
+        extractIncludePattern:bool = False
+        extractAliasName:bool = False
+        extractAliasPath:bool = False
+        extractReportFormat:bool = False
+        extractOutputFilename:bool = False
+        for arg in argv:
+            if extractFilterPattern:
+                self.__filterPattern = arg
+                extractFilterPattern = False
+                continue
+            if extractIncludePattern:
+                self.__includePatterns.append(arg)
+                extractIncludePattern = False
+                continue
+            elif extractTrait:
+                isExclude = arg.startswith('!')
+                arg = arg.lstrip('!')
+                parts = arg.split('=')
+                trait = Trait(parts[0], parts[1]) if len(parts) == 2 else Trait(arg)
+                if isExclude:
+                    self.__excludeTraits.append(trait)
+                else:
+                    self.__includeTraits.append(trait)
+                extractTrait = False
+                continue
+            elif extractExcludePattern:
+                self.__excludePatterns.append(arg)
+                extractExcludePattern = False
+                continue
+            elif extractAliasName:
+                aliasName = arg
+                extractAliasName = False
+                extractAliasPath = True
+                continue
+            elif extractAliasPath and aliasName is not None:
+                extractAliasPath = False
+                self.__aliases[aliasName] = arg
+                continue
+            elif self.__workdir is None:
+                self.__workdir = arg
+                continue
+            elif self.__testPackageName is None:
+                self.__testPackageName = arg
+                continue
+            elif extractReportFormat:
+                extractReportFormat = False
+                self.__reportFormat = arg.lower()
+                match self.__reportFormat:
+                    case 'html' | 'junit':
+                        pass
+                    case _:
+                        print(f'Unsupported value "{arg}" for --report argument, aborting.')
+                        print(f'(valid values are "json" and "junit")')
+                        exit(4)
+                continue
+            elif extractOutputFilename:
+                extractOutputFilename = False
+                self.__outputFilename = arg
+                continue
+            match arg:
+                case '-h' | '--help':
+                    self.__help = True
+                case '-a':
+                    extractAliasName = True
+                case '-f' | '--filter':
+                    extractFilterPattern = True
+                case '-e' | '--exclude':
+                    extractExcludePattern = True
+                case '-z' | '--failfast':
+                    self.__failfast = True
+                case '-p' | '--test-package':
+                    self.__testPackageName = None
+                case '-i' | '--include':
+                    extractIncludePattern = True
+                case '-q' | '--quiet':
+                    self.__quiet = True
+                case '-w' | '--working-directory':
+                    self.__workdir = None
+                case '-v' | '--verbose':
+                    self.__verbose = True
+                case '-n' | '--no-default-patterns':
+                    self.__no_default_patterns = True
+                case '-r' | '--report':
+                    extractReportFormat = True
+                case '-o' | '--output':
+                    extractOutputFilename = True
+                case '-t' | '--trait':
+                    extractTrait = True
+                case _:
+                    continue
+        return self
+
+    @property
+    def aliases(self) -> dict:
+        return self.__aliases
+
+    @property
+    def failfast(self) -> bool:
+        return self.__failfast
+
+    @property
+    def filterPattern(self) -> str:
+        return self.__filterPattern
+
+    @property
+    def excludePatterns(self) -> list[str]:
+        return self.__excludePatterns
+    
+    @property
+    def excludeTraits(self) -> list[Trait]:
+        return self.__excludeTraits
+
+    @property
+    def help(self) -> bool:
+        return self.__help
+
+    @property
+    def includePatterns(self) -> list[str]:
+        return self.__includePatterns
+    
+    @property
+    def includeTraits(self) -> list[Trait]:
+        return self.__includeTraits
+
+    @property
+    def outputFilename(self) -> str|None:
+        return self.__outputFilename
+
+    @property
+    def quiet(self) -> bool:
+        return self.__quiet or (self.__reportFormat is not None and self.__outputFilename is None)
+
+    @property
+    def reportFormat(self) -> str|None:
+        return self.__reportFormat
+
+    @property
+    def testPackageName(self) -> str:
+        return 'tests' if self.__testPackageName is None else self.__testPackageName
+
+    @property
+    def verbose(self) -> bool:
+        return self.__verbose and self.__reportFormat is None 
+
+    @property
+    def workdir(self) -> str:
+        return os.path.curdir if self.__workdir is None else self.__workdir
+
+    def printHelp(self) -> None:
+        self.printVersion()
+        print(
+"""
+Usage: python3 -m punit [-h|--help]
+                        [-q|--quiet] [-v|--verbose]
+                        [-z|--failfast]
+                        [-p|--test-package NAME]
+                        [-i|--include PATTERN]
+                        [-e|--exclude PATTERN]
+                        [-f|--filter PATTERN]
+                        [-t|--trait [!]NAME[=VALUE]]
+                        [-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
+    -z, --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)
+    -f, --filter
+        Only execute tests matching PATTERN
+        Default: '*'
+    -t, --trait [!]NAME[=VALUE]
+        Execute tests with the specified trait, negated by prefixing with '!'.
+        If VALUE is specified, matches tests with the trait having specified value.
+        If VALUE is not specified, matches any test with the trait having any value.
+        Default: No filtering based on traits.        
+    -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.
+"""
+        )
+        exit(0)
+
+    def printSummary(self) -> None:
+        self.printVersion()
+        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:
+            print('Include Patterns:')
+            for pattern in self.__includePatterns:
+                print(f'\t{pattern}')
+        if len(self.__excludePatterns) > 0:
+            print('Exclude Patterns:')
+            for pattern in self.__excludePatterns:
+                print(f'\t{pattern}')
+        print('Filter Pattern:')
+        print(f'\t{self.__filterPattern}')
+    def printVersion(self) -> None:
+        print(f'pUnit {__version__}')
+
+    def validate(self) -> None:
+        if self.__workdir is None or len(self.__workdir.lstrip()) == 0 or self.__workdir.startswith('-'):
+            print(f'Invalid working directory specified: {self.__workdir}')
+            exit(1)
+        elif not os.path.isdir(self.__workdir):
+            print(f'Working directory does not exist: {self.__workdir}')
+            exit(2)
+        self.__workdir = os.path.abspath(self.__workdir)
+        if not self.__no_default_patterns:
+            # if no other patterns specified, default to including all files found in the directory matching `testPackageName`
+            if len(self.__includePatterns) == 0:
+                self.__includePatterns.append(f'/{self.testPackageName}/*.py')
+            # always exclude dot-folders (.git, .venv, etc)
+            self.__excludePatterns.append('/.*')
+            # always exclude dunder files
+            self.__excludePatterns.append('/__*__')
+
+    @staticmethod
+    def parse(argv:list[str] = sys.argv) -> CommandLineInterface:
+        result = CommandLineInterface().__parse(argv)
+        result.validate()
+        return result

punit/discovery/TestModuleDiscovery.py

@@ -0,0 +1,113 @@
+# SPDX-FileCopyrightText: © Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+import os
+import re
+
+from ..facts import FactManager
+from ..theories import TheoryManager
+from ..cli import CommandLineInterface
+from ..traits import Trait
+
+class TestModuleDiscovery:
+
+    __cli:CommandLineInterface
+    __excludePatterns:list[re.Pattern]
+    __excludeTraits:list[Trait]
+    __filenames:list[str]
+    __filterPattern:re.Pattern
+    __includePatterns:list[re.Pattern]
+    __includeTraits:list[Trait]
+    __workdir:str
+
+    def __init__(self, workdir:str, includePatterns:list[str], excludePatterns:list[str], cli:CommandLineInterface):
+        self.__cli = cli
+        self.__excludePatterns = []
+        if excludePatterns is not None:
+            for pattern in excludePatterns:
+                self.__excludePatterns.append(
+                    re.compile(
+                        self.__convertPatternToRegex(pattern),
+                        re.IGNORECASE))
+        self.__filenames = []
+        self.__filterPattern = re.compile(self.__convertPatternToRegex(cli.filterPattern))        
+        self.__includePatterns = []
+        self.__excludeTraits = cli.excludeTraits
+        self.__includeTraits = cli.includeTraits
+        if includePatterns is not None:
+            for pattern in includePatterns:
+                self.__includePatterns.append(
+                    re.compile(
+                        self.__convertPatternToRegex(pattern),
+                        re.IGNORECASE))
+        self.__workdir = workdir
+
+    def __convertPatternToRegex(self, pattern:str):
+        result = re.escape(pattern)\
+            .replace('\\\\', '/')\
+            .replace('\\*', r'.+')\
+            .replace('?', '.')
+        return result
+
+    def __testAnyInclude(self, input:str) -> bool:
+        for pat in self.__includePatterns:
+            if len(pat.findall(input)) > 0:
+                return True
+        return False
+
+    def __testAnyExclude(self, input:str) -> bool:
+        for pat in self.__excludePatterns:
+            if len(pat.findall(input)) > 0:
+                return True
+        return False
+
+    def __walkDirectory(self, path:str) -> list[str]:
+        filenames = []
+        if os.path.isdir(path):
+            for dname, dlist, flist in os.walk(path, topdown=True):
+                if self.__cli.verbose:
+                    print(f'.. discovery for: {dname}')
+                dname2 = dname.replace('\\', '/')
+                if self.__testAnyExclude(dname2):
+                    # directory is excluded, prune all children
+                    if self.__cli.verbose:
+                        print(f'Excluded: {dname}')
+                    while len(dlist) > 0:
+                        del dlist[0]
+                    while len(flist) > 0:
+                        del flist[0]
+                # determine if any individual subdirs should be pruned
+                dlnames = dlist.copy()
+                for dlname in dlnames:
+                    dlname2 = dlname.replace('\\', '/')
+                    if self.__testAnyExclude(dlname2):
+                        if self.__cli.verbose:
+                            print(f'Excluded: {dlname}')
+                        dlist.remove(dlname)
+                # determine if any individual files should be pruned
+                for fname in flist:
+                    fname2 = os.path.join(dname, fname).replace('\\', '/')
+                    if self.__testAnyInclude(fname2) and not self.__testAnyExclude(fname2):
+                        if fname.endswith('.py'):
+                            if self.__cli.verbose:
+                                print(f'Included: {fname}')
+                            filenames.append(fname2)
+        return filenames
+
+    @property
+    def filenames(self) -> list[str]:
+        return self.__filenames
+        
+    def discover(self) -> list[str]:
+        FactManager.instance().excludeTraits = self.__excludeTraits
+        FactManager.instance().filterPattern = self.__filterPattern
+        FactManager.instance().includeTraits = self.__includeTraits
+        TheoryManager.instance().excludeTraits = self.__excludeTraits
+        TheoryManager.instance().filterPattern = self.__filterPattern
+        TheoryManager.instance().includeTraits = self.__includeTraits
+        if self.__cli.verbose:
+            print(f'.. starting test discovery')
+        self.__filenames = self.__walkDirectory(self.__workdir)
+        if self.__cli.verbose:
+            print('.. finished test discovery.')
+        return self.__filenames

punit/discovery/__init__.py

@@ -0,0 +1,9 @@
+# SPDX-FileCopyrightText: © Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+from .TestModuleDiscovery import TestModuleDiscovery
+
+
+__all__ = [
+    'TestModuleDiscovery'
+]

punit/facts/Fact.py

@@ -0,0 +1,82 @@
+# SPDX-FileCopyrightText: © Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+import inspect
+from types import FunctionType, MethodType, ModuleType
+from typing import Callable, Coroutine, Optional, cast
+
+from ..traits.Trait import Trait
+
+
+class Fact:
+
+    __className:Optional[str]
+    __moduleName:str
+    __target:FunctionType|MethodType
+    __testName:Optional[str]
+    __traits:list[Trait]
+
+    def __init__(self, moduleName:str, target:FunctionType|MethodType|Callable, className:Optional[str] = None, testName:Optional[str] = None):
+        self.__className = className
+        self.__moduleName = moduleName
+        self.__target = target
+        self.__testName = testName
+        self.__traits = []
+
+    @property
+    def className(self) -> Optional[str]:
+        return self.__className
+
+    @property
+    def moduleName(self) -> str:
+        return self.__moduleName
+
+    @property
+    def target(self) -> FunctionType|MethodType:
+        return self.__target
+
+    @property
+    def testName(self) -> str:
+        return self.__testName if self.__testName is not None else self.__target.__qualname__.split('.')[-1]
+    
+    @property
+    def filterName(self) -> str:
+        return f'{self.moduleName}/{"" if self.className is None or len(self.className) == 0 else f"{self.className}/"}{self.testName}'
+
+    @property
+    def traits(self) -> list[Trait]:
+        return self.__traits
+
+    async def execute(self, module:ModuleType) -> 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()
+                self.__className = '.'.join(qnparts[0:-1])
+                self.__testName = qnparts[-1]
+            else:
+                qntarget = module
+                self.__className = '.'.join(qnparts[0:-1])
+                self.__testName = qnparts[-1]
+                for qnpart in qnparts[0:-1]:
+                    qntarget = getattr(qntarget, qnpart)
+                if isinstance(self.__target, classmethod):
+                    coro = self.__target.__func__(qntarget)
+                else:
+                    coro = self.__target(cast(Callable,qntarget)())
+        else:
+            self.__className = None
+            self.__testName = self.__target.__name__
+            coro = self.__target()
+        if inspect.iscoroutine(coro):
+            await coro
+
+
+def fact(target:Callable) -> Callable:
+    from .FactManager import FactManager
+    if (not inspect.isfunction(target)) and (not isinstance(target, classmethod)) and (not isinstance(target, staticmethod)):
+        raise Exception('@fact can only be applied to functions and methods.')
+    fact:Fact = Fact(target.__module__, target)
+    FactManager.instance().put(fact)
+    return target

punit/facts/FactManager.py

@@ -0,0 +1,94 @@
+# SPDX-FileCopyrightText: © Shaun Wilson
+# SPDX-License-Identifier: MIT
+##
+
+import re
+from typing import Callable, Optional
+
+from .Fact import Fact
+from ..traits.Trait import Trait
+
+
+class FactManager:
+
+    __excludeTraits:list[Trait]    
+    __filterPattern:Optional[re.Pattern]
+    __instance:'FactManager'|None = None
+    __includeTraits:list[Trait]
+    __modules:dict[str, list[Fact]]
+    __traits:dict[Callable, list[Trait]]
+    
+    def __init__(self):
+        if FactManager.__instance is not None:
+            raise Exception('Cannot create more than one instance of FactManager')
+        self.__filterPattern = None
+        self.__modules = {}
+        self.__traits = {}
+
+    @staticmethod
+    def instance() -> FactManager:
+        if FactManager.__instance is None:
+            FactManager.__instance = FactManager()
+        return FactManager.__instance
+    
+    @property
+    def excludeTraits(self) -> list[Trait]:
+        return [] if self.__excludeTraits is None else self.__excludeTraits
+
+    @excludeTraits.setter
+    def excludeTraits(self, value:list[Trait]) -> None:
+        self.__excludeTraits = value
+
+    @property
+    def filterPattern(self) -> Optional[re.Pattern]:
+        return self.__filterPattern
+    
+    @filterPattern.setter
+    def filterPattern(self, value:re.Pattern) -> None:
+        self.__filterPattern = value
+
+    @property
+    def includeTraits(self) -> list[Trait]:
+        return [] if self.__includeTraits is None else self.__includeTraits
+    
+    @includeTraits.setter
+    def includeTraits(self, value:list[Trait]) -> None:
+        self.__includeTraits = value
+
+    def __excludeByTraits(self, fact:Fact) -> bool:
+        if self.__excludeTraits is not None and len(self.__excludeTraits) > 0:
+            for trait in self.__excludeTraits:
+                for L_trait in fact.traits:
+                    if trait.name == L_trait.name and (trait.value is None or (trait.value == L_trait.value)):
+                        return True
+        if self.__includeTraits is not None and len(self.__includeTraits) > 0:
+            for trait in self.__includeTraits:
+                for L_trait in fact.traits:
+                    if trait.name == L_trait.name and (trait.value is None or (trait.value == L_trait.value)):
+                        return False
+            return True
+        return False
+
+    def get(self, moduleName:str) -> list[Fact]:
+        l = self.__modules.get(moduleName)
+        if l is None:
+            l = []
+            self.__modules[moduleName] = l
+        return l
+
+    def put(self, fact:Fact) -> None:
+        if self.__filterPattern is None or len(self.__filterPattern.findall(fact.filterName)) > 0:
+            l = self.get(fact.moduleName)
+            t = self.__traits.get(fact.target)
+            if t is not None:
+                for trait in t:
+                    fact.traits.append(trait)
+            if not self.__excludeByTraits(fact):
+                l.append(fact)
+
+    def withTrait(self, target:Callable, trait:Trait) -> None:
+        t = self.__traits.get(target)
+        if t is None:
+            t = []
+            self.__traits[target] = t
+        t.append(trait)

punit/facts/__init__.py

@@ -0,0 +1,11 @@
+# SPDX-FileCopyrightText: © Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+from .Fact import Fact, fact
+from .FactManager import FactManager
+
+
+__all__ = [
+    'Fact', 'fact',
+    'FactManager'
+]