def used(self, target=None, targetVersion=None, wasExecuted=None, url=None, name=None): """ Add a resource used by the activity. This method tries to be as permissive as possible. It accepts a string which might be a synapse ID or a URL, a synapse entity, a UsedEntity or UsedURL dictionary or a list containing any combination of these. In addition, named parameters can be used to specify the fields of either a UsedEntity or a UsedURL. If target and optionally targetVersion are specified, create a UsedEntity. If url and optionally name are specified, create a UsedURL. It is an error to specify both target/targetVersion parameters and url/name parameters in the same call. To add multiple UsedEntities and UsedURLs, make a separate call for each or pass in a list. In case of conflicting settings for wasExecuted both inside an object and with a parameter, the parameter wins. For example, this UsedURL will have wasExecuted set to False:: activity.used({'url':'http://google.com', 'name':'Goog', 'wasExecuted':True}, wasExecuted=False) Entity examples:: activity.used('syn12345') activity.used(entity) activity.used(target=entity, targetVersion=2) activity.used(codeEntity, wasExecuted=True) activity.used({'reference':{'target':'syn12345', 'targetVersion':1}, 'wasExecuted':False}) URL examples:: activity.used('http://mydomain.com/my/awesome/data.RData') activity.used(url='http://mydomain.com/my/awesome/data.RData', name='Awesome Data') activity.used(url='https://github.com/joe_hacker/code_repo', name='Gnarly hacks', wasExecuted=True) activity.used({'url':'https://github.com/joe_hacker/code_repo', 'name':'Gnarly hacks'}, wasExecuted=True) List example:: used( [ 'syn12345', 'syn23456', entity, {'reference':{'target':'syn100009', 'targetVersion':2}, 'wasExecuted':True}, 'http://mydomain.com/my/awesome/data.RData' ] ) """ # -- A list of targets if isinstance(target, list): badargs = _get_any_bad_args(['targetVersion', 'url', 'name'], locals()) _raise_incorrect_used_usage(badargs, 'list of used resources') for item in target: self.used(item, wasExecuted=wasExecuted) return # -- UsedEntity elif is_used_entity(target): badargs = _get_any_bad_args(['targetVersion', 'url', 'name'], locals()) _raise_incorrect_used_usage(badargs, 'dictionary representing a used resource') resource = target if 'concreteType' not in resource: resource['concreteType'] = 'org.sagebionetworks.repo.model.provenance.UsedEntity' # -- Used URL elif is_used_url(target): badargs = _get_any_bad_args(['targetVersion', 'url', 'name'], locals()) _raise_incorrect_used_usage(badargs, 'URL') resource = target if 'concreteType' not in resource: resource['concreteType'] = 'org.sagebionetworks.repo.model.provenance.UsedURL' # -- Synapse Entity elif is_synapse_entity(target): badargs = _get_any_bad_args(['url', 'name'], locals()) _raise_incorrect_used_usage(badargs, 'Synapse entity') reference = {'targetId':target['id']} if 'versionNumber' in target: reference['targetVersionNumber'] = target['versionNumber'] if targetVersion: reference['targetVersionNumber'] = int(targetVersion) resource = {'reference':reference, 'concreteType':'org.sagebionetworks.repo.model.provenance.UsedEntity'} # -- URL parameter elif url: badargs = _get_any_bad_args(['target', 'targetVersion'], locals()) _raise_incorrect_used_usage(badargs, 'URL') resource = {'url':url, 'name':name if name else target, 'concreteType':'org.sagebionetworks.repo.model.provenance.UsedURL'} # -- URL as a string elif is_url(target): badargs = _get_any_bad_args(['targetVersion'], locals()) _raise_incorrect_used_usage(badargs, 'URL') resource = {'url':target, 'name':name if name else target, 'concreteType':'org.sagebionetworks.repo.model.provenance.UsedURL'} # -- Synapse Entity ID (assuming the string is an ID) elif isinstance(target, basestring): badargs = _get_any_bad_args(['url', 'name'], locals()) _raise_incorrect_used_usage(badargs, 'Synapse entity') reference = {'targetId':target} if targetVersion: reference['targetVersionNumber'] = int(targetVersion) resource = {'reference':reference, 'concreteType':'org.sagebionetworks.repo.model.provenance.UsedEntity'} else: raise SynapseError('Unexpected parameters in call to Activity.used().') # Set wasExecuted if wasExecuted is None: # Default to False if 'wasExecuted' not in resource: resource['wasExecuted'] = False else: # wasExecuted parameter overrides setting in an object resource['wasExecuted'] = wasExecuted # Add the used resource to the activity self['used'].append(resource)
def used(self, target=None, targetVersion=None, wasExecuted=None, url=None, name=None): """ Add a resource used by the activity. This method tries to be as permissive as possible. It accepts a string which might be a synapse ID or a URL, a synapse entity, a UsedEntity or UsedURL dictionary or a list containing any combination of these. In addition, named parameters can be used to specify the fields of either a UsedEntity or a UsedURL. If target and optionally targetVersion are specified, create a UsedEntity. If url and optionally name are specified, create a UsedURL. It is an error to specify both target/targetVersion parameters and url/name parameters in the same call. To add multiple UsedEntities and UsedURLs, make a separate call for each or pass in a list. In case of conflicting settings for wasExecuted both inside an object and with a parameter, the parameter wins. For example, this UsedURL will have wasExecuted set to False:: activity.used({'url':'http://google.com', 'name':'Goog', 'wasExecuted':True}, wasExecuted=False) Entity examples:: activity.used('syn12345') activity.used(entity) activity.used(target=entity, targetVersion=2) activity.used(codeEntity, wasExecuted=True) activity.used({'reference':{'target':'syn12345', 'targetVersion':1}, 'wasExecuted':False}) URL examples:: activity.used('http://mydomain.com/my/awesome/data.RData') activity.used(url='http://mydomain.com/my/awesome/data.RData', name='Awesome Data') activity.used(url='https://github.com/joe_hacker/code_repo', name='Gnarly hacks', wasExecuted=True) activity.used({'url':'https://github.com/joe_hacker/code_repo', 'name':'Gnarly hacks'}, wasExecuted=True) List example:: activity.used(['syn12345', 'syn23456', entity, \ {'reference':{'target':'syn100009', 'targetVersion':2}, 'wasExecuted':True}, \ 'http://mydomain.com/my/awesome/data.RData']) """ # -- A list of targets if isinstance(target, list): badargs = _get_any_bad_args(['targetVersion', 'url', 'name'], locals()) _raise_incorrect_used_usage(badargs, 'list of used resources') for item in target: self.used(item, wasExecuted=wasExecuted) return # -- UsedEntity elif is_used_entity(target): badargs = _get_any_bad_args(['targetVersion', 'url', 'name'], locals()) _raise_incorrect_used_usage( badargs, 'dictionary representing a used resource') resource = target if 'concreteType' not in resource: resource[ 'concreteType'] = 'org.sagebionetworks.repo.model.provenance.UsedEntity' # -- Used URL elif is_used_url(target): badargs = _get_any_bad_args(['targetVersion', 'url', 'name'], locals()) _raise_incorrect_used_usage(badargs, 'URL') resource = target if 'concreteType' not in resource: resource[ 'concreteType'] = 'org.sagebionetworks.repo.model.provenance.UsedURL' # -- Synapse Entity elif is_synapse_entity(target): badargs = _get_any_bad_args(['url', 'name'], locals()) _raise_incorrect_used_usage(badargs, 'Synapse entity') reference = {'targetId': target['id']} if 'versionNumber' in target: reference['targetVersionNumber'] = target['versionNumber'] if targetVersion: reference['targetVersionNumber'] = int(targetVersion) resource = { 'reference': reference, 'concreteType': 'org.sagebionetworks.repo.model.provenance.UsedEntity' } # -- URL parameter elif url: badargs = _get_any_bad_args(['target', 'targetVersion'], locals()) _raise_incorrect_used_usage(badargs, 'URL') resource = { 'url': url, 'name': name if name else target, 'concreteType': 'org.sagebionetworks.repo.model.provenance.UsedURL' } # -- URL as a string elif is_url(target): badargs = _get_any_bad_args(['targetVersion'], locals()) _raise_incorrect_used_usage(badargs, 'URL') resource = { 'url': target, 'name': name if name else target, 'concreteType': 'org.sagebionetworks.repo.model.provenance.UsedURL' } # -- Synapse Entity ID (assuming the string is an ID) elif isinstance(target, six.string_types): badargs = _get_any_bad_args(['url', 'name'], locals()) _raise_incorrect_used_usage(badargs, 'Synapse entity') vals = target.split('.') # Handle synapseIds of from syn234.4 if not is_synapse_id(vals[0]): raise ValueError('%s is not a valid Synapse id' % target) if len(vals) == 2: if targetVersion and int(targetVersion) != int(vals[1]): raise ValueError( 'Two conflicting versions for %s were specified' % target) targetVersion = int(vals[1]) reference = {'targetId': vals[0]} if targetVersion: reference['targetVersionNumber'] = int(targetVersion) resource = { 'reference': reference, 'concreteType': 'org.sagebionetworks.repo.model.provenance.UsedEntity' } else: raise SynapseError( 'Unexpected parameters in call to Activity.used().') # Set wasExecuted if wasExecuted is None: # Default to False if 'wasExecuted' not in resource: resource['wasExecuted'] = False else: # wasExecuted parameter overrides setting in an object resource['wasExecuted'] = wasExecuted # Add the used resource to the activity self['used'].append(resource)
def used(self, target=None, targetVersion=None, wasExecuted=None, url=None, name=None): """ Add a resource used by the activity. This method tries to be as permissive as possible. It accepts a string which might be a synapse ID or a URL, a synapse entity, a UsedEntity or UsedURL dictionary or a list containing any combination of these. In addition, named parameters can be used to specify the fields of either a UsedEntity or a UsedURL. If target and optionally targetVersion are specified, create a UsedEntity. If url and optionally name are specified, create a UsedURL. It is an error to specify both target/targetVersion parameters and url/name parameters in the same call. To add multiple UsedEntities and UsedURLs, make a separate call for each or pass in a list. In case of conflicting settings for wasExecuted both inside an object and with a parameter, the parameter wins. For example, this UsedURL will have wasExecuted set to False:: activity.used({'url':'http://google.com', 'name':'Goog', 'wasExecuted':True}, wasExecuted=False) Entity examples:: activity.used('syn12345') activity.used(entity) activity.used(target=entity, targetVersion=2) activity.used(codeEntity, wasExecuted=True) activity.used({'reference':{'target':'syn12345', 'targetVersion':1}, 'wasExecuted':False}) URL examples:: activity.used('http://mydomain.com/my/awesome/data.RData') activity.used(url='http://mydomain.com/my/awesome/data.RData', name='Awesome Data') activity.used(url='https://github.com/joe_hacker/code_repo', name='Gnarly hacks', wasExecuted=True) activity.used({'url':'https://github.com/joe_hacker/code_repo', 'name':'Gnarly hacks'}, wasExecuted=True) List example:: used( [ 'syn12345', 'syn23456', entity, {'reference':{'target':'syn100009', 'targetVersion':2}, 'wasExecuted':True}, 'http://mydomain.com/my/awesome/data.RData' ] ) """ # Check for allowed combinations of parameters and generate specific error message # based on the context. For example, if we specify a URL, it's illegal to specify # a version. def check_for_invalid_parameters(context=None, params={}): err_msg = 'Error in call to Activity.used()' if context == 'list': illegal_params = ('targetVersion', 'url', 'name',) context_msg = 'list of used resources' elif context == 'dict': illegal_params = ('targetVersion', 'url', 'name',) context_msg = 'dictionary representing a used resource' elif context == 'url_param': illegal_params = ('target', 'targetVersion',) context_msg = 'URL' elif context == 'url_string': illegal_params = ('targetVersion',) context_msg = 'URL' elif context == 'entity': illegal_params = ('url', 'name',) context_msg = 'Synapse entity' else: illegal_params = () context_msg = '?' for param in illegal_params: if param in params and params[param] is not None: raise SynapseMalformedEntityError('%s: It is an error to specify the \'%s\' parameter in combination with a %s.' % (err_msg, str(param), context_msg)) # List if isinstance(target, list): check_for_invalid_parameters(context='list', params=locals()) for item in target: self.used(item, wasExecuted=wasExecuted) return # Used Entity elif is_used_entity(target): check_for_invalid_parameters(context='dict', params=locals()) resource = target if 'concreteType' not in resource: resource['concreteType'] = 'org.sagebionetworks.repo.model.provenance.UsedEntity' # Used URL elif is_used_url(target): check_for_invalid_parameters(context='dict', params=locals()) resource = target if 'concreteType' not in resource: resource['concreteType'] = 'org.sagebionetworks.repo.model.provenance.UsedURL' # Synapse Entity elif is_synapse_entity(target): check_for_invalid_parameters(context='entity', params=locals()) reference = {'targetId':target['id']} if 'versionNumber' in target: reference['targetVersionNumber'] = target['versionNumber'] ## if targetVersion is specified as a parameter, it overrides the version in the object if targetVersion: reference['targetVersionNumber'] = int(targetVersion) resource = {'reference':reference, 'concreteType':'org.sagebionetworks.repo.model.provenance.UsedEntity'} # URL parameter elif url: check_for_invalid_parameters(context='url_param', params=locals()) resource = {'url':url, 'name':name if name else target, 'concreteType':'org.sagebionetworks.repo.model.provenance.UsedURL'} # URL as a string elif is_url(target): check_for_invalid_parameters(context='url_string', params=locals()) resource = {'url':target, 'name':name if name else target, 'concreteType':'org.sagebionetworks.repo.model.provenance.UsedURL'} # If it's a string and isn't a URL, assume it's a Synapse Entity ID elif isinstance(target, basestring): check_for_invalid_parameters(context='entity', params=locals()) reference = {'targetId':target} if targetVersion: reference['targetVersionNumber'] = int(targetVersion) resource = {'reference':reference, 'concreteType':'org.sagebionetworks.repo.model.provenance.UsedEntity'} else: raise SynapseError('Unexpected parameters in call to Activity.used().') # Set wasExecuted if wasExecuted is None: # Default to False if 'wasExecuted' not in resource: resource['wasExecuted'] = False else: # wasExecuted parameter overrides setting in an object resource['wasExecuted'] = wasExecuted # Add the used resource to the activity self['used'].append(resource)