"""
	EBeyeWSWrapper

	Basic wrapper around the eb-eye web services to hide the structures used by SOAPPy.
	
	WSDL : http://www.ebi.ac.uk/ebisearch/service.ebi?wsdl
	Doc  : http://www.ebi.ac.uk/Tools/webservices/
"""

from SOAPpy import WSDL


class EBeyeWSWrapper:
	
	# ==  Private methods  ======================================================
	
	def __init__(self, wsdlUrl):
		self.url   = wsdlUrl
		self.proxy = WSDL.Proxy(self.url)


	def __getStringArray(self, wsResult):
		if isinstance(wsResult,str):
			return []
		else:
			return wsResult.string

	def __getArrayOfStringArray(self, wsResult):
		return [self.__getStringArray(x) for x in wsResult._getItemAsList('ArrayOfString')]
	

	# ==  Public methods  =======================================================
	
	def setDebug(self, debug):
		self.proxy.soapproxy.config.dumpSOAPOut = debug
		self.proxy.soapproxy.config.dumpSOAPIn  = debug
	
	def listDomains(self):
		""" Returns a list of all the domain identifiers which can be used in a query.
		
		Return:
			 List of domain identifiers (strings).
		"""
		domains = self.proxy.listDomains()
		return domains.string


	def getNumberOfResults(self, domain, query):
		""" Executes a query and returns the number of results found. 
		
		Parameters:
			domain (string) The id of the domain to search into (must be one of the 
			                domains returned by the listDomains() method)
			query (string)  The terms to look for.
		Return:
			Number of results (int).
		"""
		return int(self.proxy.getNumberOfResults(domain, query))


	def getResultsIds(self, domain, query, start, size):
		""" Executes a query and returns the list of identifiers for the entries found.
		
		Parameters:
			domain (string) The id of the domain to search into (must be one of the 
			                domains returned by the listDomains() method).
			query (string)  The terms to look for.
			start (int)     The index of the first entry in the results list to be returned.
			size  (int)     The number of entries to be returned (limit: 100).
		Return:
			List of identifiers (strings).
		"""
		return self.__getStringArray(self.proxy.getResultsIds(domain, query, start, size))
		
		
	def getAllResultsIds(self, domain, query):
		""" Executes a query and returns the list of all the identifiers for the entries found.
		
		Parameters:
			domain (string) The id of the domain to search into (must be one of the domains
			                returned by the listDomains() method).
			query (string)  The terms to look for.
		Return:
			List of identifiers (strings).
		"""
		return self.__getStringArray(self.proxy.getAllResultsIds(domain, query))
		
		
	def listFields(self, domain):
		""" Returns the list of fields that can be retrieved for a particular domain.
		
		Parameters:
			domain (string) The domain identifier (must be one of the domains returned 
			                by the listDomains() method).
		Return:
			List of fields (strings)
		"""
		return self.__getStringArray(self.proxy.listFields(domain))
	
	
	def getResults(self, domain, query, fields, start, size):
		""" Executes a query and returns a list of results. Each result contains the
		    values for each field specified in the 'fields' argument in the same order
			 as they appear in the 'fields' list.

		Parameters:
			domain (string) The id of the domain to search into (must be one of the domains
			                returned by the listDomains() method).
			query (string)  The terms to look for.
			fields (array of strings) A list of fields which data will be included in the results
			start (int)     The index of the first entry in the results list to be returned
			size (int)      The number of entries to be returned (limit: 100).
		Return:
			An array of arrays of strings (['field1', 'field2', ...], ['field1', 'field2', ...], ...] )
		"""
		return self.__getArrayOfStringArray(self.proxy.getResults(domain, query, fields, start, size))
		
		
	def getEntry(self, domain, entry, fields):
		""" Search for a particular entry in a domain and returns the values for some 
		   of the fields of this entry. 
		    The result contains the values for each field specified in the 'fields' 
			 argument in the same order as they appear in the 'fields' list.
		    
		Parameters:
			domain (string)          The id of the domain to search into (must be one of the domains returned by the listDomains() method).
			entry  (string)          The entry identifier.
			fields (list of strings) A list of fields which data will be included in the results
		Return:
			list of the fields' values (strings).
		    	
		"""
		return self.__getStringArray(self.proxy.getEntry(domain, entry, fields))
		
		
	def getEntries(self, domain, entries, fields):
		""" Search for entries in a domain and returns the values for some of the 
		    fields of these entries. The result contains the values for each field 
			 specified in the 'fields' argument in the same order as they appear in 
			 the 'fields' list.
		
		Parameters:
			domain  (string)           The id of the domain to search into (must be
			                           one of the domains returned by the listDomains() method)
			entries (array of strings) The list of entry identifiers.
			fields  (array of string)  A list of fields which data will be included in the results.
		Return:
			An array of arrays of strings.
		"""
		return self.__getArrayOfStringArray(self.proxy.getEntries(domain, entries, fields))	
	
		
	def getEntryFieldUrls(self, domain, entry, fields):
		""" Search for a particular entry in a domain and returns the urls configured 
		    for some of the fields of this entry. The result contains the urls for each 
			 field specified in the 'fields' argument in the same order as they appear 
			 in the 'fields' list.
			 
		Parameters:
			domain (string) The id of the domain to search into (must be one of the 
			                domains returned by the listDomains() method).
			entry (string)  The entry identifier.
			fields (array of strings) A list of fields which corresponding urls will 
			                          be included in the results.
		Return:
			List of urls
		"""
		return self.__getStringArray(self.proxy.getEntryFieldUrls(domain, entry, fields))
	
		
	def getEntriesFieldUrls(self, domain, entries, fields):
			""" Search for a list of entries in a domain and returns the urls configured 
			    for some of the fields of these entries. Each result contains the url for 
				 each field specified in the 'fields' argument in the same order as they 
				 appear in the 'fields' list.
				 
			Parameters:
				domain (string)            The id of the domain to search into (must be 
				                           one of the domains returned by the listDomains() method).
				entries (array of strings) The list of entry identifiers.
				fields  (array of strings) A list of fields which corresponding urls will 
				                           be included in the results
			Return:
				An array of arrays of strings.
			"""
			return self.__getArrayOfStringArray(self.proxy.getEntriesFieldUrls(domain, entries, fields))
		
		
	def getDomainsReferencedInDomain(self, domain):
		""" Returns the list of domains with entries referenced in a particular domain.
		    These domains are indexed in the EB-eye.
		
		Parameter:
			domain (string) The domain identifier (must be one of the domains returned 
			by the listDomains() method)
		Return:
			The list of domains
		"""    
		return self.__getStringArray(self.proxy.getDomainsReferencedInDomain(domain))
	
	
	def getDomainsReferencedInEntry(self, domain, entry):
		""" Returns the list of domains with entries referenced in a particular domain entry. 
		    These domains are indexed in the EB-eye.
		
		Parameters:
			domain (string) The domain identifier (must be one of the domains returned 
			                by the listDomains() method).
			entry (string)  The entry identifier.
		Return:	
			The list of domains
		"""
		return self.__getStringArray(self.proxy.getDomainsReferencedInEntry(domain, entry))
		
		
	def listAdditionalReferenceFields(self, domain):
		""" Returns the list of fields corresponding to databases referenced in the 
		    domain but not included as a domain in the EB-eye.
		    
		Parameters:
			domain (string) The domain identifier (must be one of the domains returned 
			                by the listDomains() method).
		Return:
			The list of fields
		"""
		return self.__getStringArray(self.proxy.listAdditionalReferenceFields(domain))
		
		
	def getReferencedEntries(self, domain, entry, referencedDomain):
		""" Returns the list of referenced entry identifiers from a domain referenced 
		    in a particular domain entry.
		    
		Parameters:
			domain (string) The domain identifier (must be one of the domains returned 
			                by the listDomains() method).
			entry (string)  The entry identifier.
			referencedDomain (string) The identifier for the domain referenced in the 
			                        entry (must be one of the domains returned by the 
											getDomainsReferencedInEntry(domain, entry) method).
		Return:
			The list of referenced entry identifiers.
		"""
		return self.__getStringArray(self.proxy.getReferencedEntries(domain, entry, referencedDomain))
		
		
	def getReferencedEntriesSet(self, domain, entries, referencedDomain, fields):
		""" Returns the list of referenced entries from a domain referenced in a set of entries. 
		    The result will be returned as a list of objects, each representing an entry reference.
		 
		Parameters:
			domain (string)           The domain identifier (must be one of the domains 
			                          returned by the listDomains() method).
			entries (array of string) The entry identifiers.
			referencedDomain (string) The identifier for the domain referenced in the entry
			                          (must be one of the domains returned by the 
											  getDomainsReferencedInEntry(domain, entry) method).
			fields (array of strings) A list of fields which data will be included in the results.
		Return:
			A dictionary : {entryId1:[ [fields],[fields],...], entryId2:[ [fields],[fields],...]}
		"""
		result = self.proxy.getReferencedEntriesSet(domain, entries, referencedDomain, fields)
		dict   = {}
		for ids in  result['EntryReferences']:
			dict[ids['entry']] = self.__getArrayOfStringArray(ids['references'])
		
		return dict		 

		
	def getReferencedEntriesFlatSet(self, domain, entries, referencedDomain, fields):
		""" Returns the list of referenced entries from a domain referenced in a set 
		    of entries. The result will be returned as a flat table corresponding to
			the list of results where, for each result, the first value is the original 
			entry identifier and the other values correspond to the fields values.
			
		Parameters:
			domain (string)            The domain identifier (must be one of the domains 
			                           returned by the listDomains() method).
			entries (array of strings) The entry identifiers
			referencedDomain (string)  The identifier for the domain referenced in the entry 
			                           (must be one of the domains returned by the 
												getDomainsReferencedInEntry(domain, entry) method).
			fields (array of strings)  A list of fields which data will be included in the results.
		Return:
			The list of referenced entries : [ [entryId1, field1, field2, ...], [entryId2, field1, field2, ...]
		"""
		return self.__getArrayOfStringArray(self.proxy.getReferencedEntriesFlatSet(domain, entries, referencedDomain, fields))