punit 0.0.27__py3-none-any.whl

punit/facts/Fact.py

@@ -0,0 +1,68 @@
+# SPDX-FileCopyrightText: © 2024 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+import inspect
+from types import FunctionType, MethodType, ModuleType
+from typing import Any, Callable, Coroutine
+from .FactManager import FactManager
+
+class Fact:
+
+    __className:str
+    __moduleName:str
+    __target:FunctionType|MethodType
+    __testName:str
+
+    def __init__(self, moduleName:str, target:FunctionType|MethodType, className:str = None, testName:str = None):
+        self.__className = className
+        self.__moduleName = moduleName
+        self.__target = target
+        self.__testName = testName
+
+    @property
+    def className(self) -> 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
+
+    async def execute(self, module:ModuleType) -> None:
+        coro:Coroutine = 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(qntarget())
+        else:
+            self.__className = None
+            self.__testName = self.__target.__name__
+            coro = self.__target()
+        if inspect.iscoroutine(coro):
+            await coro
+
+def fact(target:Callable) -> Callable:
+    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,50 @@
+# SPDX-FileCopyrightText: © 2024 Shaun Wilson
+# SPDX-License-Identifier: MIT
+##
+
+import re
+from typing import ForwardRef
+
+Fact = ForwardRef('Fact')
+FactManager = ForwardRef('FactManager')
+
+class FactManager:
+
+    __filterPattern:re.Pattern
+    __instance:'FactManager' = None
+    __modules:dict[str, list[Fact]]
+    
+    def __init__(self):
+        if FactManager.__instance is not None:
+            raise Exception('Cannot create more than one instance of FactManager')
+        self.__filterPattern = None
+        self.__modules = {}
+
+    @staticmethod
+    def instance() -> FactManager:
+        if FactManager.__instance is None:
+            FactManager.__instance = FactManager()
+        return FactManager.__instance
+        
+    @property
+    def filterPattern(self) -> re.Pattern:
+        return self.__filterPattern
+    
+    @filterPattern.setter
+    def filterPattern(self, value:re.Pattern) -> None:
+        self.__filterPattern = value
+
+    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:
+        filterName:str = fact.target.__name__
+        if hasattr(fact.target, '__qualname__'):
+            filterName = fact.target.__qualname__
+        if len(self.__filterPattern.findall(filterName)) > 0:
+            l = self.get(fact.moduleName)
+            l.append(fact)

punit/facts/__init__.py

@@ -0,0 +1,5 @@
+# SPDX-FileCopyrightText: © 2024 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+from .Fact import Fact, fact
+from .FactManager import FactManager

punit/reports/HtmlReportGenerator.py

@@ -0,0 +1,92 @@
+# SPDX-FileCopyrightText: © 2024 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+import traceback
+from ..TestResult import TestResult
+
+class HtmlReportGenerator:
+
+    def __init__(self):
+        pass
+
+    def generate(self, testResults:list[TestResult]) -> str:
+        failureCount = 0
+        totalCount = 0
+        for testResult in testResults:
+            totalCount += 1
+            if not testResult.isSuccess:
+                failureCount += 1
+        testResults = testResults.copy()
+        testResults.sort(key=lambda e : e.moduleName)
+        lines = []
+        lines.append('<html>')
+        lines.append('<head><title>Test Results</title></head>')
+        lines.append('<body>')
+        lines.append("""
+                     <style>
+                     body { font-family: sans-serif }
+                     .testresults-summary { border-bottom:solid 3px steelblue; font-size: 2em; display: flex; flex-direction: row; justify-content: center }
+                     .testresults-summary div { flex-grow: 1 }
+                     .testresults-summary .pass { color: green; }
+                     .testresults-summary .fail { color: red; }
+                     .module-name { font-style: italic }
+                     .testresult { background-color: #EEE; margin-bottom: 2em; padding: 1em }
+                     .testresult-pass { border: solid 1px green }
+                     .testresult-fail { border: solid 1px red }
+                     .testresult .test-time { border: solid 1px black; padding: 0.3em }
+                     .percent-pass { color: green }
+                     .percent-fail { color: red }
+                     .testresult-body { margin: 1em; border: solid 1px silver; background-color: #FFF  }
+                     .testresult-error { border-left: solid 3px red; font-family: monospace; padding: 0.8em }
+                     .testresult-stdout { font-family: monospace; max-height: 10em; overflow: auto; padding: 0.8em }
+                     .testresult-stderr { font-family: monospace; max-height: 10em; overflow: auto; padding: 0.8em }
+                     .test-time-pass { background-color: #EFE }
+                     .test-time-fail { background-color: #FEE }
+                     </style>
+                     """)
+        
+        lines.append('<div class="testresults-summary">')
+        lines.append('<div>&nbsp;</div>')
+        lines.append(f'<div>Total Executed: <span class="pass">{totalCount-failureCount}</span></div>')
+        if failureCount > 0:
+            lines.append('<div>&nbsp;</div>')
+            lines.append(f'<div>Total Failed: <span class="fail">{failureCount}</span></div>')
+        lines.append('<div>&nbsp;</div>')
+        percentstyle = 'pass' if failureCount == 0 else 'fail'
+        lines.append(f'<div class="passfail-percent">Pass/Fail&nbsp;<span class="percent-{percentstyle}">{100-((failureCount/totalCount)*100):.1f}%</span></div>')
+        lines.append('<div>&nbsp;</div>')
+        lines.append('</div>')
+        currentModuleName = None
+        for testResult in testResults:
+            if currentModuleName != testResult.moduleName:
+                if currentModuleName is not None:
+                    lines.append('</div>')
+                lines.append('<div class="testresults-module">')
+                lines.append(f'<h2 class="module-name">{testResult.packageName}/{testResult.moduleName}</h2>')
+                currentModuleName = testResult.moduleName                
+            passfailstyle = '-pass' if testResult.isSuccess else '-fail'
+            passfailglyph = '🟩' if testResult.isSuccess else '🟥'
+            lines.append(f'<div class="testresult testresult{passfailstyle}">')
+            lines.append('<div class="testresult-heading">')
+            lines.append(f'<span class="glyph glyph{passfailstyle}">{passfailglyph}</span>')
+            lines.append(f'<span class="test-class">{"" if testResult.className is None else testResult.className}</span>')
+            lines.append(f'<span class="test-name">{testResult.testName}</span>')
+            lines.append(f'<span class="test-time test-time{passfailstyle}">{testResult.tookPretty}</span>')
+            lines.append('</div>')
+            if not testResult.isSuccess or testResult.stdout is not None or testResult.stderr is not None:
+                lines.append('<div class="testresult-body">')
+                if not testResult.isSuccess:
+                    lines.append('<div class="testresult-error">')
+                    if len(f'{testResult.exception}') > 0:
+                        lines.append(f'Error:<br/>&nbsp;&nbsp;{testResult.exception}<br/>')
+                    lines.append(f'Traceback:<br/>{"".join(traceback.format_tb(testResult.exception.__traceback__)).replace('\n', '<br/>').replace(' ', '&nbsp;')}')
+                    lines.append('</pre></div>')
+                if testResult.stdout is not None:
+                    lines.append(f'<div class="testresult-stdout"><pre>{testResult.stdout}</pre></div>')
+                if testResult.stderr is not None:
+                    lines.append(f'<div class="testresult-stderr"><pre>{testResult.stderr}</pre></div>')
+                lines.append('</div>')
+            lines.append('</div>')
+        lines.append('</body>')
+        lines.append('</html>')
+        return '\n'.join(lines)

punit/reports/JUnitReportGenerator.py

@@ -0,0 +1,185 @@
+# SPDX-FileCopyrightText: © 2024 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+import datetime
+import xml.etree.ElementTree as et
+from xml.sax.saxutils import escape
+from ..TestResult import TestResult
+
+class JUnitError:
+    message:str = None
+    type:str = None
+
+
+class JUnitTestCase:
+    # attrs
+    classname:str = None
+    disabled:bool = None
+    name:str = None
+    time:float = None
+    # eles
+    error:JUnitError = None
+    failure:JUnitError = None
+    stdout:str = None
+    stderr:str = None
+    skipped:bool = None
+    def __init__(self, testResult:TestResult) -> None:
+        self.disabled = False
+        self.classname = testResult.moduleName if testResult.className is None else f'{testResult.moduleName}.{testResult.className}'
+        self.time = testResult.took
+        data = testResult.properties.get('data')
+        if data is not None and len(data) > 0:
+            data = f'({",".join([str(e) for e in data])})'
+        else:
+            data = ''
+        self.name = f'{testResult.testName}{data}'
+        if not testResult.isSuccess:
+            exc_type = type(testResult.exception)
+            error = JUnitError()
+            error.message = f'{testResult.exception}'
+            error.type = getattr(exc_type, '__name__') if not hasattr(exc_type, '__qualname__') else getattr(exc_type, '__qualname__')
+            if issubclass(exc_type, AssertionError):
+                self.failure = error
+            else:
+                self.error = error
+        self.stdout = None if testResult.stdout is None else escape(testResult.stdout)
+        self.stderr = None if testResult.stderr is None else escape(testResult.stderr)
+        self.skipped = False
+
+
+class JUnitTestSuite:
+    # attrs
+    name:str = None
+    hostname:str = None
+    id:int = None
+    name:str = None
+    package:str = None
+    timestamp:datetime.datetime = None
+    # eles
+    testCases:list[JUnitTestCase] = None
+
+    @property
+    def disabled(self) -> int:
+        result:int = 0
+        for testCase in self.testCases:
+            if testCase.disabled == True:
+                result += 1
+        return result
+
+    @property
+    def errors(self) -> int:
+        result:int = 0
+        for testCase in self.testCases:
+            if testCase.error is not None:
+                result += 1
+        return result
+
+    @property
+    def failures(self) -> int:
+        result:int = 0
+        for testCase in self.testCases:
+            if testCase.failure is not None:
+                result += 1
+        return result
+
+    @property
+    def skipped(self) -> int:
+        result:int = 0
+        for testCase in self.testCases:
+            if testCase.skipped:
+                result += 1
+        return result
+
+    @property
+    def tests(self) -> float:
+        return len(self.testCases)
+
+    @property
+    def time(self) -> float:
+        result:float = 0.0
+        for testCase in self.testCases:
+            result += testCase.time
+        return result
+
+
+class JUnitReportGenerator:
+
+    def __init__(self):
+        pass
+
+    def generate(self, testResults:list[TestResult]) -> str:
+        # transform to intermediary model
+        testSuites:dict[str, JUnitTestSuite] = {}
+        ts = 0
+        for testResult in testResults:
+            if ts < testResult.stopTime:
+                ts = testResult.stopTime
+            testSuite = testSuites.get(testResult.moduleName)
+            if testSuite is None:
+                testSuite = JUnitTestSuite()
+                testSuite.name = testResult.moduleName
+                testSuite.id = len(testSuites)
+                testSuite.hostname = testResult.hostName
+                testSuite.package = testResult.packageName
+                testSuite.testCases = []
+                testSuites[testResult.moduleName] = testSuite
+            testSuite.testCases.append(JUnitTestCase(testResult))
+            testSuite.timestamp = datetime.datetime.fromtimestamp(ts)
+        # materialize as xml
+        totalDisabledCount = 0
+        totalErrorCount = 0
+        totalFailureCount = 0
+        totalTestCount = 0
+        totalTime = 0
+        testSuitesEle:et.Element = et.Element('testsuites')
+        for testSuiteName in testSuites:
+            testSuite:JUnitTestSuite = testSuites[testSuiteName]
+            totalTime += testSuite.time
+            totalDisabledCount += testSuite.disabled
+            totalErrorCount += testSuite.errors
+            totalFailureCount += testSuite.failures
+            totalTestCount += testSuite.tests
+            testSuiteEle = et.SubElement(testSuitesEle, 'testsuite')
+            testSuiteEle.attrib['disabled'] = str(testSuite.disabled)
+            testSuiteEle.attrib['errors'] = str(testSuite.errors)
+            testSuiteEle.attrib['failures'] = str(testSuite.failures)
+            testSuiteEle.attrib['id'] = str(testSuite.id)
+            testSuiteEle.attrib['name'] = str(testSuite.name)
+            testSuiteEle.attrib['package'] = str(testSuite.package)
+            testSuiteEle.attrib['timestamp'] = str(testSuite.timestamp)
+            testSuiteEle.attrib['hostname'] = str(testSuite.hostname)
+            testSuiteEle.attrib['tests'] = str(testSuite.tests)
+            testSuiteEle.attrib['time'] = f'{testSuite.time:.6f}'.rstrip('0').rstrip('.')
+            for testCase in testSuite.testCases:
+                testCaseEle = et.SubElement(testSuiteEle, 'testcase')
+                testCaseEle.attrib['name'] = testCase.name
+                if testCase.classname is not None:
+                    testCaseEle.attrib['classname'] = testCase.classname
+                testCaseEle.attrib['time'] = f'{testCase.time:.6f}'.rstrip('0').rstrip('.')
+                if testCase.skipped:
+                    et.SubElement(testCaseEle, 'skipped')
+                if testCase.error is not None:
+                    ele = et.SubElement(testCaseEle, 'error')
+                    if testCase.error.type is not None:
+                        ele.attrib['type'] = testCase.error.type
+                    if testCase.error.message is not None:
+                        ele.attrib['message'] = testCase.error.message
+                if testCase.failure is not None:
+                    ele = et.SubElement(testCaseEle, 'failure')
+                    if testCase.failure.type is not None:
+                        ele.attrib['type'] = testCase.failure.type
+                    if testCase.failure.message is not None:
+                        ele.attrib['message'] = testCase.failure.message
+                if testCase.stdout is not None:
+                    ele = et.SubElement(testCaseEle, 'system-out')
+                    ele.text = testCase.stdout
+                if testCase.stderr is not None:
+                    ele = et.SubElement(testCaseEle, 'system-err')
+                    ele.text = testCase.stderr
+        testSuitesEle.attrib['disabled'] = str(totalDisabledCount)
+        testSuitesEle.attrib['errors'] = str(totalErrorCount)
+        testSuitesEle.attrib['failures'] = str(totalErrorCount)
+        testSuitesEle.attrib['tests'] = str(totalTestCount)
+        testSuitesEle.attrib['time'] = f'{totalTime:.6f}'.rstrip('0').rstrip('.')
+        et.indent(testSuitesEle, space="    ")
+        return f'<?xml version="1.0" encoding="UTF-8"?>\n{et.tostring(testSuitesEle).decode()}\n'

punit/reports/__init__.py

@@ -0,0 +1,5 @@
+# SPDX-FileCopyrightText: © 2024 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+from .HtmlReportGenerator import HtmlReportGenerator
+from .JUnitReportGenerator import JUnitReportGenerator

punit/runner.py

@@ -0,0 +1,118 @@
+# 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 .theories.TheoryManager import TheoryManager
+from .TestResult import TestResult
+
+class TestRunner:
+
+    __cli:CommandLineInterface
+    __filenames:list[str]
+    __testPackageName:str
+    
+    def __init__(self, testPackageName:str, filenames:list[str], cli:CommandLineInterface):
+        self.__cli = cli
+        self.__filenames = filenames
+        self.__testPackageName = testPackageName
+
+    def printTestResult(self, testResult:TestResult):
+        if self.__cli.quiet:
+            return
+        glyph = '🟩' if testResult.isSuccess else '🟥'
+        data = testResult.properties.get('data')
+        if data is None:
+            data = ''
+        else:
+            try:
+                data = f'({",".join([str(e) for e in data])})'
+            except:
+                data = '(???)'
+        print(f'{glyph} {testResult.moduleName}/{"" if testResult.className is None or len(testResult.className) == 0 else f"{testResult.className}/"}{testResult.testName}{data} [{testResult.tookPretty}]')
+        if self.__cli.verbose and (not testResult.isSuccess) and testResult.exception is not None:
+            print(f'Test File:\n    {testResult.fileName}\nError:\n    {testResult.exception}\n    Traceback:\n{"".join(traceback.format_tb(testResult.exception.__traceback__))}')
+
+    async def run(self) -> list[TestResult]:
+        results:list[TestResult] = []
+        # TODO: aliasing
+        hostName:str = socket.gethostname()
+        testPackagePath = os.path.join(os.path.abspath(os.curdir), self.__testPackageName).replace('\\', '/')
+        for filename in self.__filenames:
+            ts = time.time()
+            moduleImportName = filename.replace(testPackagePath, '').replace('/', '.').replace('.py', '')
+            moduleReportName = moduleImportName.lstrip('.')
+            try:
+                testModule = importlib.import_module(moduleImportName, self.__testPackageName)
+                # execute all facts
+                facts = FactManager.instance().get(testModule.__name__)
+                for fact in facts:
+                    result:TestResult = TestResult()
+                    result.hostName = hostName
+                    result.packageName = self.__testPackageName
+                    result.fileName = filename
+                    result.moduleName = moduleReportName
+                    result.startTime = time.time()
+                    result.captureOutput(not self.__cli.verbose)
+                    try:
+                        await fact.execute(testModule)
+                        result.isSuccess = True
+                    except Exception as ex:
+                        result.isSuccess = False
+                        result.exception = ex
+                    result.releaseOutput()
+                    result.stopTime = time.time()
+                    result.className = fact.className
+                    result.testName = fact.testName
+                    results.append(result)
+                    self.printTestResult(result)
+                    if self.__cli.failfast and not result.isSuccess:
+                        return results
+                # execute all theories
+                theories = TheoryManager.instance().get(testModule.__name__)
+                for theory in theories:
+                    for data in theory.datas:
+                        result:TestResult = TestResult()
+                        result.hostName = hostName
+                        result.packageName = self.__testPackageName
+                        result.properties['data'] = data
+                        result.fileName = filename
+                        result.moduleName = moduleReportName
+                        result.startTime = time.time()
+                        result.captureOutput(not self.__cli.verbose)
+                        try:
+                            await theory.execute(testModule, data)
+                            result.isSuccess = True
+                        except Exception as ex:
+                            result.isSuccess = False
+                            result.exception = ex
+                        result.releaseOutput()
+                        result.stopTime = time.time()
+                        result.className = theory.className
+                        result.testName = theory.testName
+                        results.append(result)
+                        self.printTestResult(result)
+                        if self.__cli.failfast and not result.isSuccess:
+                            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.className = '*'
+                result.moduleName = moduleReportName
+                result.testName = '*'
+                result.startTime = ts
+                result.stopTime = time.time()
+                result.isSuccess = False
+                result.exception = ex
+                results.append(result)
+                self.printTestResult(result)
+                if self.__cli.failfast:
+                    return results
+        return results

punit/theories/Theory.py

@@ -0,0 +1,84 @@
+# SPDX-FileCopyrightText: © 2024 Shaun Wilson
+# SPDX-License-Identifier: MIT
+##
+
+import inspect
+from types import FunctionType, MethodType, ModuleType
+from typing import Any, Callable, Coroutine
+from .TheoryManager import TheoryManager
+
+class Theory:
+
+    __className:str
+    __datas:list[tuple]
+    __moduleName:str
+    __target:FunctionType|MethodType
+    __testName:str
+
+    def __init__(self, moduleName:str, target:FunctionType|MethodType, className:str = None, testName:str = None):
+        self.__className = className
+        self.__datas = []
+        self.__moduleName = moduleName
+        self.__target = target
+        self.__testName = testName
+
+    @property
+    def className(self) -> str:
+        return self.__className
+
+    @property
+    def datas(self) -> list[tuple]:
+        return self.__datas
+
+    @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
+
+    async def execute(self, module:ModuleType, data:tuple) -> None:
+        coro:Coroutine = 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)
+                self.__className = '.'.join(qnparts[0:-1])
+                self.__testName = qnparts[-1]
+            else:
+                qntarget = module
+                self.__testName = qnparts[-1]
+                self.__className = '.'.join(qnparts[0:-1])
+                for qnpart in qnparts[0:-1]:
+                    qntarget = getattr(qntarget, qnpart)
+                if isinstance(self.__target, classmethod):
+                    args = (qntarget,) + data
+                    coro = self.__target.__func__(*args)
+                else:
+                    args = (qntarget(),) + data
+                    coro = self.__target(*args)
+        else:
+            self.__className = None
+            self.__testName = self.__target.__name__
+            coro = self.__target(*data)
+        if inspect.iscoroutine(coro):
+            await coro
+
+def theory(target:Callable) -> Callable:
+    if (not inspect.isfunction(target)) and (not isinstance(target, classmethod)) and (not isinstance(target, staticmethod)):
+        raise Exception('@theory can only be applied to functions and methods.')
+    theory:Theory = Theory(target.__module__, target)
+    TheoryManager.instance().put(theory)
+    return target
+
+def inlinedata(*args) -> Callable:
+    def wrapper(target:Callable) -> Callable:
+        if args is not None and len(args) > 0:
+            TheoryManager.instance().withData(target, args)
+        return target
+    return wrapper

punit/theories/TheoryManager.py

@@ -0,0 +1,67 @@
+# SPDX-FileCopyrightText: © 2024 Shaun Wilson
+# SPDX-License-Identifier: MIT
+##
+
+import re
+from typing import Callable, ForwardRef
+
+Theory = ForwardRef('Theory')
+TheoryManager = ForwardRef('TheoryManager')
+
+class TheoryManager:
+
+    __filterPattern:re.Pattern
+    __instance:'TheoryManager' = None
+    __modules:dict[str, list[Theory]]
+    __datas:dict[Callable, list[tuple]]
+    
+    def __init__(self):
+        if TheoryManager.__instance is not None:
+            raise Exception('Cannot create more than one instance of TheoryManager')
+        self.__filterPattern = None
+        self.__modules = {}
+        self.__datas = {}
+
+    @staticmethod
+    def instance() -> TheoryManager:
+        if TheoryManager.__instance is None:
+            TheoryManager.__instance = TheoryManager()
+        return TheoryManager.__instance
+        
+    @property
+    def filterPattern(self) -> re.Pattern:
+        return self.__filterPattern
+    
+    @filterPattern.setter
+    def filterPattern(self, value:re.Pattern) -> None:
+        self.__filterPattern = value
+
+    def get(self, moduleName:str) -> list[Theory]:
+        l = self.__modules.get(moduleName)
+        if l is None:
+            l = []
+            self.__modules[moduleName] = l
+        return l
+
+    def put(self, theory:Theory) -> None:
+        filterName:str = theory.target.__name__
+        if hasattr(theory.target, '__qualname__'):
+            filterName = theory.target.__qualname__
+        if len(self.__filterPattern.findall(filterName)) > 0:
+            l = self.get(theory.moduleName)
+            d = self.__datas.get(theory.target)
+            if d is not None:
+                d.reverse()
+                for data in d:
+                    theory.datas.append(data)
+            l.append(theory)
+
+    def withData(self, target:Callable, data:tuple) -> None:
+        # TODO: data acquisition should be deferred until put() since that is where filterPattern
+        # is applied, but for current implementation `@inlinedata()` is not affected. more advanced
+        # data decorators may benefit from deferral (for example, data coming from an API or DB.)
+        d = self.__datas.get(target)
+        if d is None:
+            d = []
+            self.__datas[target] = d
+        d.append(data)