From 85b50a8ed11cfa6ef1f12bc52e624fec8847e1bb Mon Sep 17 00:00:00 2001 From: Michał Górny Date: Sat, 13 Aug 2011 10:28:44 +0200 Subject: Improve docs. --- pmstestsuite/library/case.py | 85 +++++++++++++++++++++-- pmstestsuite/library/depend_case.py | 6 ++ pmstestsuite/library/standard/dbus_case.py | 36 +++++++--- pmstestsuite/library/standard/ext_cases.py | 2 +- pmstestsuite/library/standard/workdir_fallback.py | 2 +- pmstestsuite/output/cli.py | 2 + pmstestsuite/output/html.py | 2 + pmstestsuite/pm/paludispm.py | 2 +- 8 files changed, 120 insertions(+), 17 deletions(-) diff --git a/pmstestsuite/library/case.py b/pmstestsuite/library/case.py index 00a6cd4..a5817fb 100644 --- a/pmstestsuite/library/case.py +++ b/pmstestsuite/library/case.py @@ -58,42 +58,92 @@ def cleanup_test_case_name(classname): return pn_re.sub('\\1-\\2', classname).lower() class AssertionResult(ABCObject, BoolCompat): + """ + Base class for assertion results. + """ + def __init__(self, name): self._name = name self._undefined = False @property def name(self): + """ + The assertion name. + + @type: str + """ return self._name @property def prefix(self): + """ + The assertion name prefix. + + @type: str + """ return None @property def unprefixed_name(self): + """ + The assertion name without prefix. + + @type: str + """ return self.name @property def undefined(self): + """ + Whether the assertion has undefined result. + + @type: bool + """ return self._undefined @abstractproperty def expected(self): + """ + Expected value. + + @type: any + """ pass @abstractproperty def actual(self): + """ + Actual value. + + @type: any + """ pass @abstractmethod def __bool__(self): + """ + Check whether the assertion succeeds. + + @return: whether the assertion matches + @rtype: bool + """ pass def __str__(self): + """ + Return the stringified assertion description. + + @return: stringified assertion + @rtype: str + """ return '%s == %s' % (self.actual, self.expected) class BoolAssertionResult(AssertionResult): + """ + Assertion for a boolean match. + """ + def __init__(self, name, expect, cond): AssertionResult.__init__(self, name) self._expect = bool(expect) @@ -113,6 +163,10 @@ class BoolAssertionResult(AssertionResult): return self._expect == self._cond class ContainsAssertionResult(AssertionResult): + """ + Assertion checking whether a value is on the list. + """ + def __init__(self, name, needle, container): AssertionResult.__init__(self, name) self._cont = container @@ -135,6 +189,10 @@ class ContainsAssertionResult(AssertionResult): return self._need in self._cont class EqualAssertionResult(AssertionResult): + """ + Assertion checking universal equality. + """ + def __init__(self, name, expect, value): AssertionResult.__init__(self, name) self._expect = expect @@ -152,6 +210,10 @@ class EqualAssertionResult(AssertionResult): return self._expect == self._value class NotEqualAssertionResult(EqualAssertionResult): + """ + Assertion checking universal non-equality. + """ + def __bool__(self): if self._value is None: return False @@ -322,8 +384,8 @@ class TestCase(ABCObject): @param value: the actual value @type value: any - @param expect: the unallowed value - @type expect: any + @param unallowed: the unallowed value + @type unallowed: any @param msg: assertion description @type msg: string @param undefined: whether the result is undefined @@ -463,7 +525,7 @@ class EbuildTestCase(TestCase): return 'pms-test/%s' % self.p def atom(self, pm): - """ Return atom for the test. """ + """ Return an exact-match atom for the test. """ return pm.Atom('=%s' % self.cpv) def _finalize(self): @@ -501,12 +563,22 @@ class EbuildTestCase(TestCase): class EbuildTestCaseEbuildFile(object): """ Lazy ebuild contents evaluator for EbuildTestCase. """ def __init__(self, parent): - """ Instantiate the evaluator for test case . """ + """ + Instantiate the evaluator for test case. + + @param parent: relevant test case + @type parent: L{EbuildTestCase} + """ assert(isinstance(parent, EbuildTestCase)) self._parent = parent def __str__(self): - """ Return the ebuild contents as string. """ + """ + Return the ebuild contents as string. + + @return: ebuild contents + @rtype: str + """ contents = [ebuild_header % (self._parent.eapi, ' '.join(['pms-test'] + self._parent.inherits))] @@ -542,6 +614,9 @@ class EbuildTestCase(TestCase): """ Check the correctness of the result of test execution. By default, checks whether the ebuild was actually merged. + + @param pm: the package manager instance + @type pm: L{PackageManager} """ merged = self.atom(pm) in pm.installed diff --git a/pmstestsuite/library/depend_case.py b/pmstestsuite/library/depend_case.py index fb2881b..bc06aa3 100644 --- a/pmstestsuite/library/depend_case.py +++ b/pmstestsuite/library/depend_case.py @@ -6,6 +6,12 @@ from .case import EbuildTestCase, AssertionResult from .eclass_case import EclassTestCase class DepWrappedAssertion(AssertionResult): + """ + Assertion which have occured in a dependency ebuild. + + It basically wraps the original assertion, adding a prefix. + """ + def __init__(self, assertion, prefix): self._assert = assertion self._prefix = prefix diff --git a/pmstestsuite/library/standard/dbus_case.py b/pmstestsuite/library/standard/dbus_case.py index a76bba4..6bfbd88 100644 --- a/pmstestsuite/library/standard/dbus_case.py +++ b/pmstestsuite/library/standard/dbus_case.py @@ -52,7 +52,10 @@ class RunningTest(dbus.service.Object): def __init__(self, test): """ - Initialize the D-Bus object for test . + Initialize the D-Bus object for the test. + + @param test: the test + @type test: L{TestCase} """ self.test = test self.reset() @@ -73,14 +76,21 @@ class RunningTest(dbus.service.Object): dbus_interface=dbus_interface_name, in_signature='', out_signature='') def test_started(self): - """ Notify the test suite that a particular test has been started. """ + """ + Notify the test suite that a particular test has been started. + """ self.test.dbus_started = True @dbus.service.method( dbus_interface=dbus_interface_name, in_signature='s', out_signature='') def append_output(self, l): - """ Append the line to the test output. """ + """ + Append the string to the test output. + + @param l: result string + @type l: C{dbus.UTF8String} + """ self.test.dbus_output.append(str(l)) class DBusBaseTestCase(object): @@ -92,19 +102,27 @@ class DBusBaseTestCase(object): self._dbusobj = RunningTest(self) def _finalize(self): - """ Finalize the object, ensuring pkg_setup() will be called. """ + """ + Finalize the object, ensuring that C{pkg_setup()} will be called. + """ if self.phase_funcs['pkg_setup']: self.phase_funcs['pkg_setup'].insert(0, 'pms-test-dbus_pkg_setup') def check_dbus_result(self, output, pm): """ - Check whether the sent through D-Bus matches expected test + Check whether the output sent through D-Bus matches expected test output. - Return True if it does, False otherwise. - The default implementation simply checks whether the test was merged - alike EbuildTestCase.check_result(). + alike L{EbuildTestCase.check_result()}. + + @param output: the D-Bus output + @type output: list(str) + @param pm: the package manager instance + @type pm: L{PackageManager} + @return: C{True} if output matches expected test result, C{False} + otherwise + @rtype: bool """ pass @@ -118,7 +136,7 @@ class DBusBaseTestCase(object): self.check_dbus_result(self._pop_dbus_output(), pm) class DBusEbuildTestCase(DBusBaseTestCase, EbuildTestCase): - """ D-Bus capable base test case. """ + """ D-Bus capable ebuild test case. """ def __init__(self, *args, **kwargs): """ Initialize the test case and the D-Bus object for it. """ diff --git a/pmstestsuite/library/standard/ext_cases.py b/pmstestsuite/library/standard/ext_cases.py index 9f0bbf6..94a93cc 100644 --- a/pmstestsuite/library/standard/ext_cases.py +++ b/pmstestsuite/library/standard/ext_cases.py @@ -7,7 +7,7 @@ from .dbus_case import DBusEbuildTestCase class DBusFetchingEbuildTestCase(DBusEbuildTestCase): """ A DBusEbuildTestCase variant with a standarized way of fetching - sources -- to decrease ${DISTDIR} pollution. + sources -- to decrease {${DISTDIR}} pollution. """ def __init__(self, *args, **kwargs): diff --git a/pmstestsuite/library/standard/workdir_fallback.py b/pmstestsuite/library/standard/workdir_fallback.py index 6c96abe..04ce281 100644 --- a/pmstestsuite/library/standard/workdir_fallback.py +++ b/pmstestsuite/library/standard/workdir_fallback.py @@ -19,7 +19,7 @@ class WorkdirFallbackTest(DBusFetchingEbuildTestCase): } phase_funcs = { 'src_unpack': [ - 'echo $A' + 'echo ${A}' ], 'src_compile': [ ':' diff --git a/pmstestsuite/output/cli.py b/pmstestsuite/output/cli.py index c11e0be..d07fbfa 100644 --- a/pmstestsuite/output/cli.py +++ b/pmstestsuite/output/cli.py @@ -5,6 +5,8 @@ from . import OutputModule class CLIOutput(OutputModule): + """ Command-line output module. """ + name = 'cli' def __call__(self, allresults, verbose = False): diff --git a/pmstestsuite/output/html.py b/pmstestsuite/output/html.py index 1e497b1..71ea2ac 100644 --- a/pmstestsuite/output/html.py +++ b/pmstestsuite/output/html.py @@ -9,6 +9,8 @@ from abc import abstractmethod from . import OutputModule class HTMLOutput(OutputModule): + """ HTML output module. """ + name = 'html' def __init__(self, path = None): diff --git a/pmstestsuite/pm/paludispm.py b/pmstestsuite/pm/paludispm.py index 3fbcfee..a77a7bc 100644 --- a/pmstestsuite/pm/paludispm.py +++ b/pmstestsuite/pm/paludispm.py @@ -17,7 +17,7 @@ class PaludisPM(_PaludisPM, PackageManager): """ A class implementing the interfaces to the Paludis PM. - Requires Paludis with USE=python. + Requires Paludis with C{USE=python}. """ name = 'paludis' -- cgit v1.2.3-65-gdbad