whatArgs(apiMethodName) implemented lczub#8

Author: Luiko Czub

Diff for: example/TestLinkExample.py

@@ -88,16 +88,21 @@
 NEWTESTSUITE_AA="AA - Second Level"
 NEWTESTCASE_AA="TESTCASE_AA"
 NEWTESTCASE_B="TESTCASE_B"
-NEWBUILD="Build v0.4.5"
+NEWBUILD='%s v%s' % (myTestLink.__class__.__name__ , myTestLink.__version__)
 
 NEWATTACHMENT_PY= os.path.realpath(__file__)
 this_file_dirname=os.path.dirname(NEWATTACHMENT_PY)
 NEWATTACHMENT_PNG=os.path.join(this_file_dirname, 'PyGreat.png')
 
+# example asking the api client about methods arguments
+print myTestLink.whatArgs('createTestCase')
+
+
 # -- Start CHANGE v0.4.5 -- 
 # if myTestLink.checkDevKey() != True:
 #     print "Error with the devKey."      
 #     sys.exit(-1)
+
 # example handling Response Error Codes
 # first check an invalid devKey and than the own one
 try:

Diff for: example/TestLinkExampleGenericApi.py

@@ -78,12 +78,16 @@
 NEWTESTSUITE_AA="AA - Second Level"
 NEWTESTCASE_AA="TESTCASE_AA"
 NEWTESTCASE_B="TESTCASE_B"
-NEWBUILD="Build v0.4.5"
+NEWBUILD='%s v%s' % (myTestLink.__class__.__name__ , myTestLink.__version__)
 
 NEWATTACHMENT_PY= os.path.realpath(__file__)
 this_file_dirname=os.path.dirname(NEWATTACHMENT_PY)
 NEWATTACHMENT_PNG=os.path.join(this_file_dirname, 'PyGreat.png')
 
+# example asking the api client about methods arguments
+print myTestLink.whatArgs('createTestCase')
+
+
 # example handling Response Error Codes
 # first check an invalid devKey and than the own one
 try:

Diff for: src/testlink/testlinkapigeneric.py

@@ -20,7 +20,7 @@
 import xmlrpclib
 import testlinkerrors
 from .testlinkhelper import TestLinkHelper, VERSION
-from .testlinkargs import getMethodsWithPositionalArgs
+from .testlinkargs import getMethodsWithPositionalArgs, getArgsForMethod
 from .testlinkdecorators import decoApiCallAddAttachment,\
 decoApiCallAddDevKey, decoApiCallWithoutArgs, \
 decoMakerApiCallReplaceTLResponseError, decoMakerApiCallWithArgs 
@@ -1086,6 +1086,65 @@ def _checkResponse(self, response, methodNameAPI, argsOptional):
     #  ADDITIONNAL FUNCTIONS
     #                                   
 
+    def whatArgs(self, methodNameAPI):
+        """ returns for METHODNAME a description with 
+            - positional, optional and other (non api) mandatory args
+            - methods doc/help string
+        """
+        
+        # collect arg names 
+        posArgNames = self._positionalArgNames.get(methodNameAPI, [])
+        otherArgs = ([],[])
+        registeredApiMethod = True
+        try:
+            otherArgs = getArgsForMethod(methodNameAPI, posArgNames)
+        except testlinkerrors.TLArgError:
+            # no API args registered for methodName 
+            registeredApiMethod = False
+        optArgNames=otherArgs[0]
+        manArgNames=otherArgs[1]
+            
+        # get method doc string
+        ownMethod = True
+        docString = None
+        argSeparator = ''
+        try:
+            apiMethod = self.__getattribute__(methodNameAPI)
+            docString = apiMethod.__doc__
+        except AttributeError:
+            # no real method defined for methodNameAPI
+            ownMethod = False
+            
+        # now we start to build the description
+        # first the method name
+        methDescr = ''
+        if not ownMethod:
+            methDescr = "callServerWithPosArgs('%s'" % methodNameAPI
+            argSeparator = ', '
+            if not optArgNames:
+                optArgNames = ['apiArg']
+        else:
+            methDescr = "%s(" % methodNameAPI
+
+        # description pos and mandatory args
+        manArgNames.extend(posArgNames) 
+        if manArgNames:
+            tmp_l = ['<%s>' % x for x in manArgNames]
+            methDescr += '%s%s' % (argSeparator, ", ".join(tmp_l))
+            argSeparator = ', '
+        # description optional args
+        if optArgNames:
+            tmp_l = ['%s=<%s>' % (x,x) for x in optArgNames]
+            methDescr += '%s[%s]' % (argSeparator, "], [".join(tmp_l))
+            
+        # closing the method call
+        methDescr += ")" 
+
+        # now append methods docstring
+        if docString:
+            methDescr += "\n%s" % docString 
+                        
+        return methDescr
 
     def __str__(self):
         message = """

Diff for: src/testlink/testlinkargs.py

@@ -29,7 +29,7 @@
 #
 # definitions structure is
 # key(apiMethodeName) = ( [default positional apiArgs], [all apiArgs], 
-#                         [other mandatory Args] )
+#                         [other mandatory non api Args] )
 # [all apiArgs] includes all positional and optional args without other 
 #  mandatory Args
 _apiMethodsArgs = {}
@@ -53,12 +53,10 @@ def registerMethod(methodName, apiArgsPositional=[], apiArgsOptional=[],
 
         definitions structure is
         key(apiMethodeName) = ( [default positional apiArgs], [all apiArgs], 
-                                 [other mandatory Args] )
+                                 [other mandatory non api Args] )
        [all apiArgs] includes all positional and optional args without other 
        mandatory Args  """ 
 
-    print 'register args for', methodName
-       
     if methodName in _apiMethodsArgs:
         raise TLArgError('apiMethod %s already registered!' % methodName)
 
@@ -76,6 +74,13 @@ def registerArgOptional(methodName, argName):
     if not argName in allArgs:
         allArgs.append(argName)
 
+def registerArgNonApi(methodName, argName):
+    """ Update _apiMethodsArgs[methodName] with additional non api argument """ 
+       
+    nonApiArgs = _getMethodsArgDefinition(methodName)[2]
+    if not argName in nonApiArgs:
+        nonApiArgs.append(argName)
+    
 
 def getMethodsWithPositionalArgs():
     """ returns a dictionary with method names and there positional args """
@@ -86,6 +91,26 @@ def getMethodsWithPositionalArgs():
             positionalArgNames[mname] = argdef[0][:]
     return positionalArgNames
 
-def getApiArgsForMethod(methodName):
-    """ returns list with all argument name api methodName """
-    return _getMethodsArgDefinition(methodName)[1][:]
+# def getApiArgsForMethod(methodName):
+#     """ returns list with all api argument name for METHODNAME """
+#     return _getMethodsArgDefinition(methodName)[1][:]
+
+def getArgsForMethod(methodName, knownArgNames=[]):
+    """ returns for METHODNAME additional arg names as a tuple with two lists 
+        a) optional api arguments, not listed in knownArgNames
+        b) additional mandatory non api arguments 
+        
+        raise TLArgError, if METHODNAME is not registered """ 
+    
+    # argument definitions in _apiMethodsArgs 
+    argDef = _getMethodsArgDefinition(methodName)
+    
+    # find missing optional arg names
+    apiArgsAll = argDef[1]
+    apiArgs = [x for x in apiArgsAll if x not in knownArgNames]
+    
+    # other mandatory arg names
+    manArgs = argDef[2][:]
+    
+    return (apiArgs, manArgs)
+    

Diff for: src/testlink/testlinkdecorators.py

@@ -18,7 +18,7 @@
 # ------------------------------------------------------------------------
 
 from functools import wraps
-from .testlinkargs import registerMethod, registerArgOptional
+from .testlinkargs import registerMethod, registerArgOptional, registerArgNonApi
 from .testlinkerrors import TLResponseError
 
 __doc__ = """ This internal module defines the decorator functions, which are 
@@ -144,6 +144,8 @@ def decoApiCallAddAttachment(methodAPI):
     """ Decorator to expand parameter list with devKey and attachmentfile
         attachmentfile  is a python file descriptor pointing to the file
     """  
+    registerArgOptional(methodAPI.__name__, 'devKey')
+    registerArgNonApi(methodAPI.__name__, 'attachmentfile')
     @wraps(methodAPI)  
     def wrapperAddAttachment(self, attachmentfile, *argsPositional, **argsOptional):
         if not ('devKey' in argsOptional):

Diff for: test/utest/testlinkapigeneric_offline_test.py

@@ -187,6 +187,28 @@ def test_checkResponse_dictionaryResponse(self):
         self.api._checkResponse(response, 'DummyMethod', 
                                 {'Uno' : 1, 'due' :2, 'tre' : 3})
 
+    def test_whatArgs_noArgs(self):
+        response = self.api.whatArgs('sayHello')
+        self.assertRegexpMatches(response, 'sayHello().*')
+        
+    def test_whatArgs_onlyOptionalArgs(self):
+        response = self.api.whatArgs('getTestCaseAttachments')
+        self.assertRegexpMatches(response, 'getTestCaseAttachments\(\[.*=<.*>\].*\).*')
+        
+    def test_whatArgs_OptionalAndPositionalArgs(self):
+        response = self.api.whatArgs('createBuild')
+        self.assertRegexpMatches(response, 'createBuild\(<.*>.*\).*')
+
+    def test_whatArgs_MandatoryArgs(self):
+        response = self.api.whatArgs('uploadExecutionAttachment')
+        self.assertRegexpMatches(response, 
+                    'uploadExecutionAttachment\(<attachmentfile>, <.*>.*\).*')
+
+    def test_whatArgs_unknownMethods(self):
+        response = self.api.whatArgs('apiUnknown')
+        self.assertRegexpMatches(response, 
+                "callServerWithPosArgs\('apiUnknown', \[apiArg=<apiArg>\]\)")
+        
     def test_noWrapperName_apiMethods(self):
         " decorator test: API Methods internal function name should be unchanged "
 
@@ -198,6 +220,8 @@ def test_noWrapperName_apiMethods(self):
         self.assertEqual('createBuild', self.api.createBuild.__name__)
         # apiMethod with decorator @decoMakerApiCallReplaceTLResponseError()
         self.assertEqual('getProjectTestPlans', self.api.getProjectTestPlans.__name__)
+        # apiMethod with decorator @decoApiCallAddAttachment
+        self.assertEqual('uploadExecutionAttachment', self.api.uploadExecutionAttachment.__name__)
 
     def test_ping(self):
         self.api.loadScenario(SCENARIO_A)

Diff for: test/utest/testlinkargstest.py

@@ -36,7 +36,12 @@ def setUp(self):
         self.mut = testlinkargs
         # reset the args cache
         self.mut._resetRegister()
+        # api simulation
+        self.api = self 
 
+    def tearDown(self):
+        # reset the args cache
+        self.mut._resetRegister()
 
     def test__resetRegister(self):
         self.mut._apiMethodsArgs['BigBird'] = 'not a Small Bird'
@@ -97,11 +102,39 @@ def test_registerArgOptional_ErrorUnknownMethod(self):
                                      'DummyMethod not registered'):
             self.mut.registerArgOptional('DummyMethod', 'sei')
 
-    def test_getApiArgsForMethod(self):
+    def test_registerArgNonApi(self):
+        self.mut.registerMethod('DummyMethod', ['Uno', 'due', 'tre'],  
+                                ['quad','tre'], ['cinque'])
+        self.mut.registerArgNonApi('DummyMethod', 'sei')
+        a_def = self.mut._apiMethodsArgs['DummyMethod']
+        self.assertEqual((['Uno', 'due', 'tre'], 
+                          ['Uno', 'due', 'tre', 'quad'],
+                          ['cinque', 'sei']), a_def )
+        
+    def test_getArgsForMethod_onlyOptionalArgs(self):
+        self.mut.registerMethod('DummyMethod', ['Uno', 'due', 'tre'],  
+                                ['quad','tre'])
+        response = self.mut.getArgsForMethod('DummyMethod')
+        self.assertEqual(response, (['Uno', 'due', 'tre', 'quad'], []) )
+        
+    def test_getArgsForMethod_OptionalAndPositionalArgs(self):
+        self.mut.registerMethod('DummyMethod', ['Uno', 'due', 'tre'],  
+                                ['quad','tre']) 
+        response = self.mut.getArgsForMethod('DummyMethod', ['Uno', 'quad'])
+        self.assertEqual(response, (['due', 'tre'], []) )
+
+    def test_getArgsForMethod_nonApiArgs(self):
         self.mut.registerMethod('DummyMethod', ['Uno', 'due', 'tre'],  
                                 ['quad','tre'], ['cinque'])
-        allArgs = self.mut.getApiArgsForMethod('DummyMethod')
-        self.assertEqual(['Uno', 'due', 'tre', 'quad'], allArgs )
+        response = self.mut.getArgsForMethod('DummyMethod', 
+                                             ['Uno', 'due', 'tre'])
+        self.assertEqual(response,  (['quad'], ['cinque']) )
+
+    def test_getArgsForMethod_unknownMethods(self):
+        with self.assertRaisesRegexp(testlinkargs.TLArgError, 
+                                     'unknownMethod not registered'):
+            self.mut.getArgsForMethod('unknownMethod')
+        
 
 if __name__ == "__main__":
     #import sys;sys.argv = ['', 'Test.testName']

Diff for: test/utest/testlinkdecoratorstest.py

@@ -22,7 +22,7 @@
 
 import unittest
 from testlink.testlinkerrors import TLResponseError
-from testlink.testlinkargs import registerMethod, getApiArgsForMethod
+from testlink.testlinkargs import registerMethod, getArgsForMethod
 from testlink.testlinkdecorators import decoApiCallAddAttachment,\
 decoApiCallAddDevKey, decoApiCallWithoutArgs, \
 decoMakerApiCallReplaceTLResponseError, decoMakerApiCallWithArgs 
@@ -34,6 +34,13 @@ class testlinkdecoratorsTestCase(unittest.TestCase):
     devKey = '007'
     def setUp(self):
         self.api = self
+        
+    def _getAttachmentArgs(self, attachmentfile):
+        # simulation of TestlinkAPIGeneric._getAttachmentArgs()
+        # needed in test_decoApiCallAddAttachment
+        return {'filename': 'name %s' % attachmentfile,
+                'filetype': 'type %s' % attachmentfile,
+                'content' : 'content %s' % attachmentfile}
 
 #     def tearDown(self):
 #         pass
@@ -60,7 +67,6 @@ def DummyMethod(a_api):
             pass
 
         posArgs = getMethodsWithPositionalArgs()
-        print posArgs
         self.assertEqual(['Uno', 'due', 'tre'], posArgs['DummyMethod'])
 
     def test_noWrapperName_decoApiCallWithArgs(self):
@@ -84,8 +90,8 @@ def a_func(a_api, *argsPositional, **argsOptional):
             return argsPositional, argsOptional
 
         # check method argument definition
-        allArgs = getApiArgsForMethod('a_func')
-        self.assertEqual(['devKey'], allArgs)
+        allArgs = getArgsForMethod('a_func')
+        self.assertEqual((['devKey'], []), allArgs)
         # check call arguments
         response = a_func(self.api)
         self.assertEqual({'devKey' : self.api.devKey}, response[1])
@@ -158,9 +164,27 @@ def orig_funcname4(a_api, *argsPositional, **argsOptional):
         self.assertEqual('orig doc string', orig_funcname4.__doc__)
         self.assertEqual('testlinkdecoratorstest', orig_funcname4.__module__)
 
+    def test_decoApiCallAddAttachment(self):
+        " decorator test: argsOptional should be extended attachment file infos"
+        
+        registerMethod('func_addAttachment')
+        @decoApiCallAddAttachment
+        def func_addAttachment(a_api, *argsPositional, **argsOptional):
+            return argsPositional, argsOptional
+        
+        # check method argument definition
+        allArgs = getArgsForMethod('func_addAttachment')
+        self.assertEqual((['devKey'], ['attachmentfile']), allArgs)
+        # check call arguments
+        response = func_addAttachment(self.api, 'a_file')
+        self.assertEqual({'devKey' : self.api.devKey, 'filename': 'name a_file',
+                    'filetype': 'type a_file', 'content' : 'content a_file'}, 
+                         response[1])
+        
     def test_noWrapperName_decoApiCallAddAttachment(self):
         " decorator test: original function name should be unchanged "
 
+        registerMethod('orig_funcname5')
         @decoApiCallAddAttachment
         def orig_funcname5(a_api):
             "orig doc string"