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/jkiang/.synapseConfig', requests_session=None, cache_root_dir=None, silent=None)

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

:param requests_session a custom requests.Session object that this Synapse instance will use

when making http requests

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

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

create_external_s3_file_handle(bucket_name, s3_file_key, file_path, *, parent=None, storage_location_id=None, mimetype=None)

Create an external S3 file handle for e.g. a file that has been uploaded directly to an external S3 storage location.

Parameters

  • bucket_name – Name of the S3 bucket

  • s3_file_key – S3 key of the uploaded object

  • file_path – Local path of the uploaded file

  • parent – Parent entity to create the file handle in, the file handle will be created in the default storage location of the parent. Mutually exclusive with storage_location_id

  • storage_location_id – Explicit storage location id to create the file handle in, mutually exclusive with parent

  • mimetype – Mimetype of the file, if known

create_s3_storage_location(*, parent=None, folder_name=None, folder=None, bucket_name=None, base_key=None, sts_enabled=False)

Create a storage location in the given parent, either in the given folder or by creating a new folder in that parent with the given name. This will both create a StorageLocationSetting, and a ProjectSetting together, optionally creating a new folder in which to locate it, and optionally enabling this storage location for access via STS. If enabling an existing folder for STS, it must be empty.

Parameters

  • parent – The parent in which to locate the storage location (mutually exclusive with folder)

  • folder_name – The name of a new folder to create (mutually exclusive with folder)

  • folder – The existing folder in which to create the storage location (mutually exclusive with folder_name)

  • bucket_name – The name of an S3 bucket, if this is an external storage location, if None will use Synapse S3 storage

  • base_key – The base key of within the bucket, None to use the bucket root, only applicable if bucket_name is passed

  • sts_enabled – Whether this storage location should be STS enabled

Returns

a 3-tuple of the synapse Folder, a the storage location setting, and the project setting dictionaries

create_snapshot_version(table: Union[synapseclient.table.EntityViewSchema, synapseclient.table.Schema, str, synapseclient.table.SubmissionViewSchema], comment: Optional[str] = None, label: Optional[str] = None, activity: Optional[Union[synapseclient.activity.Activity, str]] = None, wait: bool = True) → int

Create a new Table Version or a new View version.

Parameters

  • table – The schema of the Table/View, or its ID.

  • comment – Optional snapshot comment.

  • label – Optional snapshot label.

  • activity – Optional activity ID applied to snapshot version.

  • wait – True if this method should return the snapshot version after waiting for any necessary asynchronous table updates to complete. If False this method will return as soon as any updates are initiated.

Returns

the snapshot version number if wait=True, None if wait=False

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.

deleteProvenance(entity)

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

Parameters

entity – An Entity or Synapse ID to modify

downloadTableColumns(table, columns, downloadLocation=None, **kwargs)

Bulk download of table-associated files.

Parameters

  • table – table query result

  • columns – a list of column names as strings

  • downloadLocation – directory into which to download the files

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()
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)

Deprecated since version 2.1.0.

deprecated and replaced with get_annotations()

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 RawConfigParser populated with properties from the user’s configuration file.

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 or a Team object 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.

get_annotations(entity: Union[str, synapseclient.entity.Entity], version: Optional[Union[str, int]] = None) → synapseclient.annotations.Annotations

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 synapseclient.annotations.Annotations object, a dict that also has id and etag attributes

Return type

synapseclient.annotations.Annotations

get_membership_status(userid, team)

Retrieve a user’s Team Membership Status bundle. https://docs.synapse.org/rest/GET/team/id/member/principalId/membershipStatus.html

Parameters
Returns

dict of TeamMembershipStatus

get_sts_storage_token(entity, permission, *, output_format='json', min_remaining_life=None)

Get STS credentials for the given entity_id and permission, outputting it in the given format

Parameters

  • entity – the entity or entity id whose credentials are being returned

  • permission – one of ‘read_only’ or ‘read_write’

  • output_format – one of ‘json’, ‘boto’, ‘shell’, ‘bash’, ‘cmd’, ‘powershell’ json: the dictionary returned from the Synapse STS API including expiration boto: a dictionary compatible with a boto session (aws_access_key_id, etc) shell: output commands for exporting credentials appropriate for the detected shell bash: output commands for exporting credentials into a bash shell cmd: output commands for exporting credentials into a windows cmd shell powershell: output commands for exporting credentials into a windows powershell

  • min_remaining_life – the minimum allowable remaining life on a cached token to return. if a cached token has left than this amount of time left a fresh token will be fetched

get_team_open_invitations(team)

Retrieve the open requests submitted to a Team https://docs.synapse.org/rest/GET/team/id/openInvitation.html

Parameters

team – A synapseclient.team.Team object or a team’s ID.

Returns

generator of MembershipRequest

invalidateAPIKey()

Invalidates authentication across all clients.

invite_to_team(team, user=None, inviteeEmail=None, message=None, force=False)

Invite user to a Synapse team via Synapse username or email (choose one or the other)

Parameters

  • syn – Synapse object

  • team – A synapseclient.team.Team object or a team’s ID.

  • user – Synapse username or profile id of user

  • inviteeEmail – Email of user

  • message – Additional message for the user getting invited to the team. Default to None.

  • force – If an open invitation exists for the invitee, the old invite will be cancelled. Default to False.

Returns

MembershipInvitation or None if user is already a member

is_certified(user: Union[str, int]) → bool

Determines whether a Synapse user is a certified user.

Params user

Synapse username or Id

Returns

True if the Synapse user is certified

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

Valid combinations of login() arguments:

  • email/username and password

  • email/username and apiKey (Base64 encoded string)

  • authToken

  • 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. User’s personal access token from environment the variable: SYNAPSE_AUTH_TOKEN

  2. .synapseConfig file (in user home folder unless configured otherwise)

  3. 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.

  • authToken – A bearer authorization token, e.g. a personal access token, can be used in lieu of a password or apiKey

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={}, requests_session=None, **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

  • requests_session – an external requests.session object to use when making this specific call

  • kwargs – Any other arguments taken by a requests method

restGET(uri, endpoint=None, headers=None, retryPolicy={}, requests_session=None, **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

  • requests_session – an external requests.Session object to use when making this specific call

  • kwargs –

    Any other arguments taken by a requests method

Returns

JSON encoding of response

restPOST(uri, body, endpoint=None, headers=None, retryPolicy={}, requests_session=None, **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

  • requests_session – an external requests.Session object to use when making this specific call

  • kwargs –

    Any other arguments taken by a requests method

Returns

JSON encoding of response

restPUT(uri, body=None, endpoint=None, headers=None, retryPolicy={}, requests_session=None, **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

  • requests_session – an external requests.session object to use when making this specific call

  • 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

send_membership_invitation(teamId, inviteeId=None, inviteeEmail=None, message=None)

Create a membership invitation and send an email notification to the invitee.

Parameters

  • teamId – Synapse teamId

  • inviteeId – Synapse username or profile id of user

  • inviteeEmail – Email of user

  • message – Additional message for the user getting invited to the team. Default to None.

Returns

MembershipInvitation

setAnnotations(entity, annotations=None, **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

Deprecated since version 2.1.0: deprecated and replaced with set_annotations() This method is UNSAFE and may overwrite existing annotations without confirming that you have retrieved and updated the latest annotations

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

set_annotations(annotations: synapseclient.annotations.Annotations)

Store annotations for an Entity in the Synapse Repository.

Parameters

annotations – A synapseclient.annotations.Annotations of annotation names and values, with the id and etag attribute set

Returns

the updated synapseclient.annotations.Annotations for the entity

Example:

annos = syn.get_annotations('syn123')

# annos will contain the id and etag associated with the entity upon retrieval
print(annos.id)
# syn123
print(annos.etag)
# 7bdb83e9-a50a-46e4-987a-4962559f090f   (Usually some UUID in the form of a string)

# returned annos object from get_annotations() can be used as if it were a dict

# set key 'foo' to have value of 'bar' and 'baz'
annos['foo'] = ['bar', 'baz']

# single values will automatically be wrapped in a list once stored
annos['qwerty'] = 'asdf'

# store the annotations
annos = syn.set_annotations(annos)

print(annos)
# {'foo':['bar','baz], 'qwerty':['asdf']}
store(obj, *, createOrUpdate=True, forceVersion=True, versionLabel=None, isRestricted=False, activity=None, used=None, executed=None, activityName=None, activityDescription=None)

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, dockerTag='latest')

Submit an Entity for evaluation.

Parameters

  • evaluation – Evaluation queue to submit to

  • entity – The Entity containing the Submission

  • name – A name for this submission. In the absent of this parameter, the entity name will be used.

  • team – (optional) A Team object, ID or name of a Team that is registered for the challenge

  • silent – Set to True to suppress output.

  • submitterAlias – (optional) A nickname, possibly for display in leaderboards in place of the submitter’s name

  • teamName – (deprecated) A synonym for submitterAlias

  • dockerTag – (optional) The Docker tag must be specified if the entity is a DockerRepository. Defaults to “latest”.

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(123)
entity = syn.get('syn456')
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

  • downloadLocation – directory path to download the CSV file to

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:

# Sets the max timeout to 5 minutes.
syn.table_query_timeout = 300
updateActivity(activity)

Modifies an existing Activity.

Parameters

activity – The Activity to be updated.

Returns

An updated Activity object

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. 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

More information

See also the Synapse API documentation.