Synapse Client

The Synapse object encapsulates a connection to the Synapse service and is used for building projects, uploading and retrieving data, and recording provenance of data analysis.

Login

client.login(*args, **kwargs)

Convenience method to create a Synapse object and login.

See synapseclient.Synapse.login() for arguments and usage.

Example:

import synapseclient
syn = synapseclient.login()

Synapse

class synapseclient.Synapse(repoEndpoint=None, authEndpoint=None, fileHandleEndpoint=None, portalEndpoint=None, debug=False, skip_checks=False, configPath=u'/Users/CBare/.synapseConfig')

Constructs a Python client object for the Synapse repository service

Parameters:
  • repoEndpoint – Location of Synapse repository
  • authEndpoint – Location of authentication service
  • fileHandleEndpoint – Location of file service
  • portalEndpoint – Location of the website
  • serviceTimeoutSeconds – Wait time before timeout (currently unused)
  • debug – Print debugging messages if True
  • skip_checks – Skip version and endpoint checks
  • configPath – Path to config File with setting for Synapse defaults to ~/.synapseConfig

Typically, no parameters are needed:

import synapseclient
syn = synapseclient.Synapse()

See:

chunkedQuery(queryStr)

Query for Synapse Entities. More robust than synapseclient.Synapse.query(). See the query language documentation.

Returns:An iterator that will break up large queries into managable pieces.

Example:

results = syn.chunkedQuery("select id, name from entity where entity.parentId=='syn449742'")
for res in results:
    print(res['entity.id'])
createEntity(entity, used=None, executed=None, **kwargs)

Deprecated

Use synapseclient.Synapse.store()

delete(obj, version=None)

Removes an object from Synapse.

Parameters:
  • obj – An existing object stored on Synapse such as Evaluation, File, Project, WikiPage etc
  • version – For entities, specify a particular version to delete.
deleteEntity(entity)

Deprecated

Use synapseclient.Synapse.delete()

deleteProvenance(entity)

Removes provenance information from an Entity and deletes the associated Activity.

Parameters:entity – An Entity or Synapse ID to modify
downloadEntity(entity, version=None)

Deprecated

Use synapseclient.Synapse.get()

downloadTableColumns(table, columns)

Bulk download of table-associated files.

Parameters:
  • table – table query result
  • column – a list of column names as strings
Returns:

a dictionary from file handle ID to path in the local file system.

For example, consider a Synapse table whose ID is “syn12345” with two columns of type File named ‘foo’ and ‘bar’. The associated files are JSON encoded, so we might retrieve the files from Synapse and load for the second 100 of those rows as shown here:

import json

results = syn.tableQuery('SELECT * FROM syn12345 LIMIT 100 OFFSET 100')
file_map = syn.downloadTableColumns(results, ['foo', 'bar'])

for file_handle_id, path in file_map.items():
    with open(path) as f:
        data[file_handle_id] = f.read()
downloadTableFile(table, column, downloadLocation=None, rowId=None, versionNumber=None, rowIdAndVersion=None, ifcollision=u'keep.both')

Downloads a file associated with a row in a Synapse table.

Parameters:
  • table – schema object, table query result or synapse ID
  • rowId – row number that holds the file handle
  • versionNumber – version number of the row that holds the file handle
  • rowIdAndVersion – row number and version in one string, “101_2” for version 2 of row 101
  • column – a Column object, the ID of a column or its name
  • downloadLocation – location in local file system to download the file
  • ifcollision – Determines how to handle file collisions. May be “overwrite.local”, “keep.local”, or “keep.both”. Defaults to “keep.both”.
Returns:

a dictionary with ‘path’.

Example:

file_info = syn.downloadTableFile(table, rowId=1, versionNumber=1, column="cover_art", downloadLocation=".")
print(file_info['path'])
get(entity, **kwargs)

Gets a Synapse entity from the repository service.

Parameters:
  • entity – A Synapse ID, a Synapse Entity object, a plain dictionary in which ‘id’ maps to a Synapse ID or a local file that is stored in Synapse (found by hash of file)
  • version – The specific version to get. Defaults to the most recent version.
  • downloadFile – Whether associated files(s) should be downloaded. Defaults to True
  • downloadLocation – Directory where to download the Synapse File Entity. Defaults to the local cache.
  • followLink – Whether the link returns the target Entity. Defaults to True
  • ifcollision – Determines how to handle file collisions. May be “overwrite.local”, “keep.local”, or “keep.both”. Defaults to “keep.both”.
  • limitSearch – a Synanpse ID used to limit the search in Synapse if entity is specified as a local file. That is, if the file is stored in multiple locations in Synapse only the ones in the specified folder/project will be returned.
Returns:

A new Synapse Entity object of the appropriate type

Example:

 ## download file into cache
 entity = syn.get('syn1906479')
 print(entity.name)
 print(entity.path)

 ## download file into current working directory
 entity = syn.get('syn1906479', downloadLocation='.')
 print(entity.name)
 print(entity.path)

## Determine the provenance of a localy stored file as indicated in Synapse
entity = syn.get('/path/to/file.txt', limitSearch='syn12312')
print(syn.getProvenance(entity))
getAnnotations(entity, version=None)

Retrieve annotations for an Entity from the Synapse Repository as a Python dict.

Note that collapsing annotations from the native Synapse format to a Python dict may involve some loss of information. See _getRawAnnotations() to get annotations in the native format.

Parameters:
  • entity – An Entity or Synapse ID to lookup
  • version – The version of the Entity to retrieve.
Returns:

A dictionary

getColumn(id)

Gets a Column object from Synapse by ID.

See: synapseclient.table.Column

Example:

column = syn.getColumn(123)
getColumns(x, limit=100, offset=0)

Get all columns defined in Synapse, those corresponding to a set of column headers or those whose names start with a given prefix.

Parameters:x – a list of column headers, a Schema, a TableSchema’s Synapse ID, or a string prefix
Return:a generator of Column objects
getConfigFile(configPath)

Returns a ConfigParser populated with properties from the user’s configuration file.

getEntity(entity, version=None)

Deprecated

Use synapseclient.Synapse.get()

getEvaluation(id)

Gets an Evaluation object from Synapse.

See: synapseclient.evaluation

Example:

evaluation = syn.getEvalutation(2005090)
getEvaluationByContentSource(entity)

Returns a generator over evaluations that derive their content from the given entity

getEvaluationByName(name)

Gets an Evaluation object from Synapse.

See: synapseclient.evaluation

getPermissions(entity, principalId=None)

Get the permissions that a user or group has on an Entity.

Parameters:
  • entity – An Entity or Synapse ID to lookup
  • principalId – Identifier of a user or group (defaults to PUBLIC users)
Returns:

An array containing some combination of [‘READ’, ‘CREATE’, ‘UPDATE’, ‘DELETE’, ‘CHANGE_PERMISSIONS’, ‘DOWNLOAD’, ‘PARTICIPATE’] or an empty array

getProvenance(entity, version=None)

Retrieve provenance information for a Synapse Entity.

Parameters:
  • entity – An Entity or Synapse ID to lookup
  • version – The version of the Entity to retrieve. Gets the most recent version if omitted
Returns:

An Activity object or raises exception if no provenance record exists

getSubmission(id, **kwargs)

Gets a synapseclient.evaluation.Submission object.

See: synapseclient.Synapse.get() for information
on the downloadFile, downloadLocation, and ifcollision parameters
getSubmissionBundles(evaluation, status=None, myOwn=False, limit=100, offset=0)
Parameters:
  • evaluation – Evaluation to get submissions from.
  • status – Optionally filter submissions for a specific status. One of {OPEN, CLOSED, SCORED, INVALID}
  • myOwn – Determines if only your Submissions should be fetched. Defaults to False (all Submissions)
  • limit – Limits the number of submissions coming back from the service in a single response.
  • offset – Start iterating at a submission offset from the first submission.
Returns:

A generator over tuples containing a synapseclient.evaluation.Submission and a synapseclient.evaluation.SubmissionStatus.

Example:

for submission, status in syn.getSubmissionBundles(evaluation):
    print(submission.name, \
          submission.submitterAlias, \
          status.status, \
          status.score)

This may later be changed to return objects, pending some thought on how submissions along with related status and annotations should be represented in the clients.

See: synapseclient.evaluation

getSubmissionStatus(submission)

Downloads the status of a Submission.

Parameters:submission – The Submission to lookup
Returns:A synapseclient.evaluation.SubmissionStatus object
getSubmissions(evaluation, status=None, myOwn=False, limit=100, offset=0)
Parameters:
  • evaluation – Evaluation to get submissions from.
  • status – Optionally filter submissions for a specific status. One of {OPEN, CLOSED, SCORED,INVALID,VALIDATED, EVALUATION_IN_PROGRESS,RECEIVED, REJECTED, ACCEPTED}
  • myOwn – Determines if only your Submissions should be fetched. Defaults to False (all Submissions)
  • limit – Limits the number of submissions in a single response. Because this method returns a generator and repeatedly fetches submissions, this arguement is limiting the size of a single request and NOT the number of sub- missions returned in total.
  • offset – Start iterating at a submission offset from the first submission.
Returns:

A generator over synapseclient.evaluation.Submission objects for an Evaluation

Example:

for submission in syn.getSubmissions(1234567):
    print(submission['entityId'])

See: synapseclient.evaluation

getTableColumns(table, limit=100, offset=0)

Retrieve the column models used in the given table schema.

getTeam(id)

Finds a team with a given ID or name.

getTeamMembers(team)
Parameters:team – A Team object or a team’s ID.
Returns:a generator over TeamMember objects.
getUserProfile(*args, **kwargs)

Get the details about a Synapse user. Retrieves information on the current user if ‘id’ is omitted.

Parameters:
  • id – The ‘userId’ (aka ‘ownerId’) of a user or the userName
  • sessionToken – The session token to use to find the user profile
  • refresh – If set to True will always fetch the data from Synape otherwise will used cached information
Returns:

JSON-object

Example:

my_profile = syn.getUserProfile()

freds_profile = syn.getUserProfile('fredcommo')
getWiki(owner, subpageId=None, version=None)

Get a synapseclient.wiki.Wiki object from Synapse. Uses wiki2 API which supports versioning.

getWikiHeaders(owner)

Retrieves the header of all Wiki’s belonging to the owner.

Parameters:owner – An Evaluation or Entity
Returns:A list of Objects with three fields: id, title and parentId.
invalidateAPIKey()

Invalidates authentication across all clients.

loadEntity(entity)

Deprecated

Use synapseclient.Synapse.get()

login(email=None, password=None, apiKey=None, sessionToken=None, rememberMe=False, silent=False, forced=False)

Authenticates the user using the given credentials (in order of preference):

  • supplied synapse user name (or email) and password
  • supplied email and API key (base 64 encoded)
  • supplied session token
  • supplied email and cached API key
  • most recent cached email and API key
  • email in the configuration file and cached API key
  • email and API key in the configuration file
  • email and password in the configuraton file
  • session token in the configuration file
Parameters:
  • email – Synapse user name (or an email address associated with a Synapse account)
  • password – password
  • apiKey – Base64 encoded Synapse API key
  • rememberMe – Whether the authentication information should be cached locally for usage across sessions and clients.
  • silent – Defaults to False. Suppresses the “Welcome ...!” message.
  • forced – Defaults to False. Bypass the credential cache if set.

Example:

syn.login('me@somewhere.com', 'secret-password', rememberMe=True)
#> Welcome, Me!

After logging in with the rememberMe flag set, an API key will be cached and used to authenticate for future logins:

syn.login()
#> Welcome, Me!
logout(forgetMe=False)

Removes authentication information from the Synapse client.

Parameters:forgetMe – Set as True to clear any local storage of authentication information. See the flag “rememberMe” in synapseclient.Synapse.login().
md5Query(md5)

Find the Entities with attached file(s) with the given MD5 hash.

Parameters:md5 – The MD5 to query for (hexadecimal string)
Returns:A list of Entity headers
onweb(entity, subpageId=None)

Opens up a browser window to the entity page or wiki-subpage.

Parameters:
  • entity – Either an Entity or a Synapse ID
  • subpageId – (Optional) ID of one of the wiki’s sub-pages
printEntity(entity, ensure_ascii=True)

Pretty prints an Entity.

query(queryStr)

Query for Synapse entities. To be replaced with synapseclient.Synapse.chunkedQuery() in the future. See the query language documentation.

Returns:A JSON object containing an array of query results

Example:

syn.query("select id, name from entity where entity.parentId=='syn449742'")

See also: synapseclient.Synapse.chunkedQuery()

restDELETE(uri, endpoint=None, headers=None, retryPolicy={}, **kwargs)

Performs a REST DELETE operation to the Synapse server.

Parameters:
  • uri – URI of resource to be deleted
  • endpoint – Server endpoint, defaults to self.repoEndpoint
  • headers – Dictionary of headers to use rather than the API-key-signed default set of headers
  • kwargs – Any other arguments taken by a requests method
restGET(uri, endpoint=None, headers=None, retryPolicy={}, **kwargs)

Performs a REST GET operation to the Synapse server.

Parameters:
  • uri – URI on which get is performed
  • endpoint – Server endpoint, defaults to self.repoEndpoint
  • headers – Dictionary of headers to use rather than the API-key-signed default set of headers
  • kwargs

    Any other arguments taken by a requests method

Returns:

JSON encoding of response

restPOST(uri, body, endpoint=None, headers=None, retryPolicy={}, **kwargs)

Performs a REST POST operation to the Synapse server.

Parameters:
  • uri – URI on which get is performed
  • endpoint – Server endpoint, defaults to self.repoEndpoint
  • body – The payload to be delivered
  • headers – Dictionary of headers to use rather than the API-key-signed default set of headers
  • kwargs

    Any other arguments taken by a requests method

Returns:

JSON encoding of response

restPUT(uri, body=None, endpoint=None, headers=None, retryPolicy={}, **kwargs)

Performs a REST PUT operation to the Synapse server.

Parameters:
  • uri – URI on which get is performed
  • endpoint – Server endpoint, defaults to self.repoEndpoint
  • body – The payload to be delivered
  • headers – Dictionary of headers to use rather than the API-key-signed default set of headers
  • kwargs

    Any other arguments taken by a requests method

Returns:

JSON encoding of response

sendMessage(userIds, messageSubject, messageBody, contentType=u'text/plain')

send a message via Synapse.

Parameters:
  • userIds – A list of user IDs to which the message is to be sent
  • messageSubject – The subject for the message
  • messageBody – The body of the message
  • contentType – optional contentType of message body (default=”text/plain”) Should be one of “text/plain” or “text/html”
Returns:

The metadata of the created message

setAnnotations(entity, annotations={}, **kwargs)

Store annotations for an Entity in the Synapse Repository.

Parameters:
  • entity – An Entity or Synapse ID to update annotations of
  • annotations – A dictionary in Synapse format or a Python format
  • kwargs – Any additional entries to be added to the annotations dictionary
Returns:

A dictionary

setEndpoints(repoEndpoint=None, authEndpoint=None, fileHandleEndpoint=None, portalEndpoint=None, skip_checks=False)

Sets the locations for each of the Synapse services (mostly useful for testing).

Parameters:
  • repoEndpoint – Location of synapse repository
  • authEndpoint – Location of authentication service
  • fileHandleEndpoint – Location of file service
  • portalEndpoint – Location of the website
  • skip_checks – Skip version and endpoint checks

To switch between staging and production endpoints:

syn.setEndpoints(**synapseclient.client.STAGING_ENDPOINTS)
syn.setEndpoints(**synapseclient.client.PRODUCTION_ENDPOINTS)
setPermissions(entity, principalId=None, accessType=[u'READ'], modify_benefactor=False, warn_if_inherits=True, overwrite=True)

Sets permission that a user or group has on an Entity. An Entity may have its own ACL or inherit its ACL from a benefactor.

Parameters:
  • entity – An Entity or Synapse ID to modify
  • principalId – Identifier of a user or group
  • accessType – Type of permission to be granted
  • modify_benefactor – Set as True when modifying a benefactor’s ACL
  • warn_if_inherits – Set as False, when creating a new ACL. Trying to modify the ACL of an Entity that inherits its ACL will result in a warning
  • overwrite – By default this function overwrites existing permissions for the specified user. Set this flag to False to add new permissions nondestructively.
Returns:

an Access Control List object

Valid access types are: CREATE, READ, UPDATE, DELETE, CHANGE_PERMISSIONS, DOWNLOAD, PARTICIPATE, SUBMIT

setProvenance(entity, activity)

Stores a record of the code and data used to derive a Synapse entity.

Parameters:
Returns:

An updated synapseclient.activity.Activity object

store(obj, **kwargs)

Creates a new Entity or updates an existing Entity, uploading any files in the process.

Parameters:
  • obj – A Synapse Entity, Evaluation, or Wiki
  • used – The Entity, Synapse ID, or URL used to create the object
  • executed – The Entity, Synapse ID, or URL representing code executed to create the object
  • activity – Activity object specifying the user’s provenance
  • activityName – Activity name to be used in conjunction with used and executed.
  • activityDescription – Activity description to be used in conjunction with used and executed.
  • createOrUpdate – Indicates whether the method should automatically perform an update if the ‘obj’ conflicts with an existing Synapse object. Defaults to True.
  • forceVersion – Indicates whether the method should increment the version of the object even if nothing has changed. Defaults to True.
  • versionLabel – Arbitrary string used to label the version.
  • isRestricted – If set to true, an email will be sent to the Synapse access control team to start the process of adding terms-of-use or review board approval for this entity. You will be contacted with regards to the specific data being restricted and the requirements of access.
Returns:

A Synapse Entity, Evaluation, or Wiki

Example:

from synapseclient import Project

project = Project('My uniquely named project')
project = syn.store(project)

Adding files with provenance:

from synapseclient import File, Activity

## A synapse entity *syn1906480* contains data
## entity *syn1917825* contains code
activity = Activity(
    'Fancy Processing',
    description='No seriously, really fancy processing',
    used=['syn1906480', 'http://data_r_us.com/fancy/data.txt'],
    executed='syn1917825')

test_entity = File('/path/to/data/file.xyz', description='Fancy new data', parent=project)
test_entity = syn.store(test_entity, activity=activity)
submit(evaluation, entity, name=None, team=None, silent=False, submitterAlias=None, teamName=None)

Submit an Entity for evaluation.

Parameters:
  • evaluation – Evaluation board to submit to
  • entity – The Entity containing the Submission
  • name – A name for this submission
  • team – (optional) A Team object or name of a Team that is registered for the challenge
  • submitterAlias – (optional) A nickname, possibly for display in leaderboards in place of the submitter’s name
  • teamName – (deprecated) A synonym for submitterAlias
Returns:

A synapseclient.evaluation.Submission object

In the case of challenges, a team can optionally be provided to give credit to members of the team that contributed to the submission. The team must be registered for the challenge with which the given evaluation is associated. The caller must be a member of the submitting team.

Example:

evaluation = syn.getEvaluation(12345)
entity = syn.get('syn12345')
submission = syn.submit(evaluation, entity, name='Our Final Answer', team='Blue Team')
tableQuery(query, resultsAs=u'csv', **kwargs)

Query a Synapse Table.

Parameters:
  • query

    query string in a SQL-like syntax:

    SELECT * from syn12345

  • resultsAs – select whether results are returned as a CSV file (“csv”) or incrementally downloaded as sets of rows (“rowset”).
Returns:

A Table object that serves as a wrapper around a CSV file (or generator over Row objects if resultsAs=”rowset”).

You can receive query results either as a generator over rows or as a CSV file. For smallish tables, either method will work equally well. Use of a “rowset” generator allows rows to be processed one at a time and processing may be stopped before downloading the entire table.

Optional keyword arguments differ for the two return types. For the “rowset” option,

Parameters:
  • limit – specify the maximum number of rows to be returned, defaults to None
  • offset – don’t return the first n rows, defaults to None
  • isConsistent – defaults to True. If set to False, return results based on current state of the index without waiting for pending writes to complete. Only use this if you know what you’re doing.

For CSV files, there are several parameters to control the format of the resulting file:

Parameters:
  • quoteCharacter – default double quote
  • escapeCharacter – default backslash
  • lineEnd – defaults to os.linesep
  • separator – defaults to comma
  • header – True by default
  • includeRowIdAndRowVersion – True by default
NOTE: When performing queries on frequently updated tables,

the table can be inaccessible for a period leading to a timeout of the query. Since the results are guaranteed to eventually be returned you can change the max timeout by setting the table_query_timeout variable of the Synapse object:

syn.table_query_timeout = 300 #Sets the max timeout to 5 minutes.

updateActivity(activity)

Modifies an existing Activity.

Returns:An updated Activity object
updateEntity(entity, used=None, executed=None, incrementVersion=False, versionLabel=None, **kwargs)

Deprecated

Use synapseclient.Synapse.store()

uploadFile(entity, filename=None, used=None, executed=None)

Deprecated

Use synapseclient.Synapse.store()

More information

See also the Synapse API documentation.