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)
