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(**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=None, skip_checks=False, configPath='/Users/kimyenladia/.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:

createColumns(columns)

Creates a batch of synapseclient.table.Column s within a single request.

Parameters:columns – a list of synapseclient.table.Column objects
Returns:a list of synapseclient.table.Column objects that have been created in Synapse
createEntity(entity, used=None, executed=None, **kwargs)

Use synapseclient.Synapse.store()

Deprecated since version 1.9.0: This will be removed in 2.0. Please use store() instead.

createStorageLocationSetting(storage_type, **kwargs)

Creates an IMMUTABLE storage location based on the specified type.

For each storage_type, the following kwargs should be specified: ExternalObjectStorage: (S3-like (e.g. AWS S3 or Openstack) bucket not accessed by Synapse) - endpointUrl: endpoint URL of the S3 service (for example: ‘https://s3.amazonaws.com’) - bucket: the name of the bucket to use ExternalS3Storage: (Amazon S3 bucket accessed by Synapse) - bucket: the name of the bucket to use ExternalStorage: (SFTP or FTP storage location not accessed by Synapse) - url: the base URL for uploading to the external destination - supportsSubfolders(optional): does the destination support creating subfolders under the base url

(default: false)

ProxyStorage: (a proxy server that controls access to a storage) - secretKey: The encryption key used to sign all pre-signed URLs used to communicate with the proxy. - proxyUrl: The HTTPS URL of the proxy used for upload and download.

Optional kwargs for ALL types: - banner: The optional banner to show every time a file is uploaded - description: The description to show the user when the user has to choose which upload destination to use

Parameters:
  • storage_type – the type of the StorageLocationSetting to create
  • kwargs – fields necessary for creation of the specified storage_type
Returns:

a dict of the created StorageLocationSetting

delete(obj, version=None)

Removes an object from Synapse.

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

Use synapseclient.Synapse.delete()

Deprecated since version 1.9.0: This will be removed in 2.0. Please use delete() instead.

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)

Use synapseclient.Synapse.get()

Deprecated since version 1.9.0: This will be removed in 2.0. Please use get() instead.

downloadTableColumns(table, columns, **kwargs)

Bulk download of table-associated files.

Parameters:
  • table – table query result
  • columns – 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 FILEHANDLEID 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='keep.both')

Deprecated since version 1.9.0: This will be removed in 2.0. please use downloadTableColumns() instead

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:

file path (as a string) to the downloaded file.

Example:

file_path = syn.downloadTableFile(table, rowId=1, versionNumber=1, column="cover_art", downloadLocation=".")
print(file_path)
findEntityId(name, parent=None)

Find an Entity given its name and parent.

Parameters:
  • name – name of the entity to find
  • parent – An Entity object or the Id of an entity as a string. Omit if searching for a Project by name
Returns:

the Entity ID or None if not found

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 the file MD5)
  • 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 False
  • 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 locally 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

getChildren(parent, includeTypes=['folder', 'file', 'table', 'link', 'entityview', 'dockerrepo'], sortBy='NAME', sortDirection='ASC')

Retrieves all of the entities stored within a parent such as folder or project.

Parameters:
  • parent – An id or an object of a Synapse container or None to retrieve all projects
  • includeTypes – Must be a list of entity types (ie. [“folder”,”file”]) which can be found here: http://docs.synapse.org/rest/org/sagebionetworks/repo/model/EntityType.html
  • sortBy – How results should be sorted. Can be NAME, or CREATED_ON
  • sortDirection – The direction of the result sort. Can be ASC, or DESC
Returns:

An iterator that shows all the children of the container.

Also see:

getColumn(id)

Gets a Column object from Synapse by ID.

See: synapseclient.table.Column

Parameters:id – the ID of the column to retrieve
Returns:an object of type synapseclient.table.Column

Example:

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

Get the columns defined in Synapse either (1) corresponding to a set of column headers, (2) those for a given schema, or (3) those whose names start with a given prefix.

Parameters:
  • x – a list of column headers, a Table Entity object (Schema/EntityViewSchema), a Table’s Synapse ID, or a string prefix
  • limit – maximum number of columns to return (pagination parameter)
  • offset – the index of the first column to return (pagination parameter)
Returns:

a generator of Column objects

getConfigFile(configPath)

Retrieves the client configuration information.

Parameters:configPath – Path to configuration file on local file system
Returns:a ConfigParser populated with properties from the user’s configuration file.
getEntity(entity, version=None)

Use synapseclient.Synapse.get()

Deprecated since version 1.9.0: This will be removed in 2.0. Please use get() instead.

getEvaluation(id)

Gets an Evaluation object from Synapse.

Parameters:id – The ID of the synapseclient.evaluation.Evaluation to return.
Returns:an synapseclient.evaluation.Evaluation object

See: synapseclient.evaluation

Example:

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

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

Parameters:entity – The synapseclient.entity.Project whose Evaluations are to be fetched.
Returns:a Generator over the synapseclient.evaluation.Evaluation objects for the given synapseclient.entity.Project
getEvaluationByName(name)

Gets an Evaluation object from Synapse.

Parameters:name – The name of the synapseclient.evaluation.Evaluation to return.
Returns:an synapseclient.evaluation.Evaluation object

See: synapseclient.evaluation

getMyStorageLocationSetting(storage_location_id)

Get a StorageLocationSetting by its id. :param storage_location_id: id of the StorageLocationSetting to retrieve.

The corresponding StorageLocationSetting must have been created by this user.
Returns:a dict describing the StorageLocationSetting retrieved by its id
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’] or an empty array

getProjectSetting(project, setting_type)

Gets the ProjectSetting for a project.

Parameters:
  • project – Project entity or its id as a string
  • setting_type – type of setting. Choose from: {‘upload’, ‘external_sync’, ‘requester_pays’}
Returns:

The ProjectSetting as a dict or None if no settings of the specified type exist.

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 by its id.

Parameters:id – The id of the submission to retrieve
Returns: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=20, offset=0)

Retrieve submission bundles (submission and submissions status) for an evaluation queue, optionally filtered by submission status and/or owner.

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=20, 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 argument 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)

Retrieve the column models used in the given table schema.

Parameters:table – the schema of the Table whose columns are to be retrieved
Returns:a Generator over the Table’s columns
getTeam(id)

Finds a team with a given ID or name.

Parameters:id – The ID or name of the team to retrieve
Returns:An object of type synapseclient.team.Team
getTeamMembers(team)

Lists the members of the given team.

Parameters:team – A synapseclient.team.Team object or a team’s ID.
Returns:a generator over synapseclient.team.TeamMember objects.
getUserProfile(id=None, sessionToken=None, refresh=False)

Get the details about a Synapse user. Retrieves information on the current user if ‘id’ is omitted. :param id: The ‘userId’ (aka ‘ownerId’) of a user or the userName :param sessionToken: The session token to use to find the user profile :param refresh: If set to True will always fetch the data from Synape otherwise will use cached information :returns: The user profile for the user of interest.

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.

Parameters:
  • owner – The entity to which the Wiki is attached
  • subpageId – The id of the specific sub-page or None to get the root Wiki page
  • version – The version of the page to retrieve or None to retrieve the latest
Returns:

a synapseclient.wiki.Wiki object

getWikiAttachments(wiki)

Retrieve the attachments to a wiki page.

Parameters:wiki – the Wiki object for which the attachments are to be returned.
Returns:A list of file handles for the files attached to the Wiki.
getWikiHeaders(owner)

Retrieves the headers of all Wikis belonging to the owner (the entity to which the Wiki is attached).

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

Invalidates authentication across all clients.

loadEntity(entity)

Use synapseclient.Synapse.get()

Deprecated since version 1.9.0: This will be removed in 2.0. Please use get() instead.

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

Valid combinations of login() arguments:

  • email/username and password
  • email/username and apiKey (Base64 encoded string)
  • sessionToken (DEPRECATED)
If no login arguments are provided or only username is provided, login() will attempt to log in using
information from these sources (in order of preference):
  1. .synapseConfig file (in user home folder unless configured otherwise)
  2. cached credentials from previous login() where rememberMe=True was passed as a parameter
Parameters:
  • email – Synapse user name (or an email address associated with a Synapse account)
  • password – password
  • apiKey – Base64 encoded Synapse API key
  • sessionToken!!DEPRECATED FIELD!! User’s current session token. Using this field will ignore the following fields: email, password, apiKey
  • rememberMe – Whether the authentication information should be cached in your operating system’s credential storage.

GNOME Keyring (recommended) or KWallet is recommended to be installed for credential storage on Linux systems. If it is not installed/setup, credentials will be stored as PLAIN-TEXT file with read and write permissions for the current user only (chmod 600). On Windows and Mac OS, a default credentials storage exists so it will be preferred over the plain-text file. To install GNOME Keyring on Ubuntu:

sudo apt-get install gnome-keyring

sudo apt-get install python-dbus  #(for Python 2 installed via apt-get)
OR
sudo apt-get install python3-dbus #(for Python 3 installed via apt-get)
OR
sudo apt-get install libdbus-glib-1-dev #(for custom installation of Python or vitualenv)
sudo pip install dbus-python #(may take a while to compile C code)

If you are on a headless Linux session (e.g. connecting via SSH), please run the following commands before running your Python session:

dbus-run-session -- bash #(replace 'bash' with 'sh' if bash is unavailable)
echo -n "REPLACE_WITH_YOUR_KEYRING_PASSWORD"|gnome-keyring-daemon -- unlock
Parameters:
  • silent – Defaults to False. Suppresses the “Welcome …!” message.
  • forced – Defaults to False. Bypass the credential cache if set.

Example:

syn.login('my-username', '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 which have attached file(s) which have the given MD5 hash.

Parameters:md5 – The MD5 to query for (hexadecimal string)
Returns:A list of Entity headers
move(entity, new_parent)

Move a Synapse entity to a new container.

Parameters:
  • entity – A Synapse ID, a Synapse Entity object, or a local file that is stored in Synapse
  • new_parent – The new parent container (Folder or Project) to which the entity should be moved.
Returns:

The Synapse Entity object that has been moved.

Example:

entity = syn.move('syn456', 'syn123')
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.

Parameters:
  • entity – The entity to be printed.
  • ensure_ascii – If True, escapes all non-ASCII characters
restDELETE(uri, endpoint=None, headers=None, retryPolicy={}, **kwargs)

Sends an HTTP DELETE request 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)

Sends an HTTP GET request 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)

Sends an HTTP POST request 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)

Sends an HTTP PUT request 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='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 – The Entity or Synapse Entity ID whose annotations are to be updated
  • annotations – A dictionary of annotation names and values
  • kwargs – annotation names and values
Returns:

the updated annotations for the entity

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=['READ', 'DOWNLOAD'], 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. One or more of CREATE, READ, DOWNLOAD, UPDATE, DELETE, CHANGE_PERMISSIONS
  • 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 non-destructively.
Returns:

an Access Control List object

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

setStorageLocation(entity, storage_location_id)

Sets the storage location for a Project or Folder :param entity: a Project or Folder to which the StorageLocationSetting is set :param storage_location_id: a StorageLocation id or a list of StorageLocation ids. Pass in None for the default

Synapse storage.
Returns:The created or updated settings as a dict
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 (can also be a list of these)
  • executed – The Entity, Synapse ID, or URL representing code executed to create the object (can also be a list of these)
  • 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 queue 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
  • silent – Suppress output.
  • 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='csv', **kwargs)

Query a Synapse Table.

Parameters:
  • query – query string in a SQL-like syntax, for example “SELECT * from syn12345”
  • resultsAs – select whether results are returned as a CSV file (“csv”) or incrementally downloaded as sets of rows (“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
Returns:

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

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.

Parameters:activity – The Activity to be updated.
Returns:An updated Activity object
updateEntity(entity, used=None, executed=None, incrementVersion=False, versionLabel=None, **kwargs)

Use synapseclient.Synapse.store()

Deprecated since version 1.9.0: This will be removed in 2.0. Please use store() instead.

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

Use synapseclient.Synapse.store()

Deprecated since version 1.9.0: This will be removed in 2.0. Please use store() instead.

uploadFileHandle(path, parent, synapseStore=True, mimetype=None, md5=None, file_size=None)

Uploads the file in the provided path (if necessary) to a storage location based on project settings.

Deprecated since version 1.9.0: This will be removed in 2.0.

Returns a new FileHandle as a dict to represent the stored file.

Parameters:
  • parent – parent of the entity to which we upload.
  • path – file path to the file being uploaded
  • synapseStore – If False, will not upload the file, but instead create an ExternalFileHandle that references the file on the local machine. If True, will upload the file based on StorageLocation determined by the entity_parent_id
  • mimetype – The MIME type metadata for the uploaded file
  • md5 – The MD5 checksum for the file, if known. Otherwise if the file is a local file, it will be calculated automatically.
  • file_size – The size the file, if known. Otherwise if the file is a local file, it will be calculated automatically.
  • file_type – The MIME type the file, if known. Otherwise if the file is a local file, it will be calculated automatically.
Returns:

a dict of a new FileHandle as a dict that represents the uploaded file

uploadSynapseManagedFileHandle(path, storageLocationId=None, mimetype=None)

Deprecated since version 1.9.0: This will be removed in 2.0.

Uploads a file to a Synapse managed S3 storage. This is the preferred function for uploading files to Tables :param path: path to the file :param storageLocationId: storageLocationId of a S3 storage location. pass in a value if you wish to use an

ExternalS3StorageLocation
Parameters:mimetype – MIME type of the file, if known.
Returns:file handle dict associated with the uploaded file

More information

See also the Synapse API documentation.