Synapse Python Client Documentation

Overview

The synapseclient package provides an interface to Synapse, a collaborative, open-source research platform that allows teams to share data, track analyses, and collaborate, providing support for:

  • integrated presentation of data, code and text

  • fine grained access control

  • provenance tracking

The synapseclient package lets you communicate with the cloud-hosted Synapse service to access data and create shared data analysis projects from within Python scripts or at the interactive Python console. Other Synapse clients exist for R, Java, and the web. The Python client can also be used from the command line.

If you’re just getting started with Synapse, have a look at the Getting Started guides for Synapse.

Next Major Release (3.0.0)

  • Support only pandas >= 1.5

  • Remove support for Python 3.7 due to its end of life.

  • There will be major cosmetic changes to the cli such as removing all camel case or non-standard single dash long command line interface (cli) parameters. Example: command line arguments like -parent will become –parent. Commands that support camel case like –parentId will be changed to –parent-id.

Installation

The synapseclient package is available from PyPI. It can be installed or upgraded with pip. Note that synapseclient requires Python 3, and if you have both Python 2 and Python 3 installations your system, the pip command associated with Python 3 may be named pip3 to distinguish it from a Python 2 associated command. Prefixing the pip installation with sudo may be necessary if you are installing Python into a shared system installation of Python.

(sudo) pip3 install (--upgrade) synapseclient[pandas, pysftp]

The dependencies on pandas and pysftp are optional. The Synapse synapseclient.table feature integrates with Pandas. Support for sftp is required for users of SFTP file storage. Both require native libraries to be compiled or installed separately from prebuilt binaries.

Source code and development versions are available on Github. Installing from source:

git clone git://github.com/Sage-Bionetworks/synapsePythonClient.git
cd synapsePythonClient

You can stay on the master branch to get the latest stable release or check out the develop branch or a tagged revision:

git checkout <branch or tag>
Next, either install the package in the site-packages directory python setup.py install or

python setup.py develop to make the installation follow the head without having to reinstall:

python setup.py <install or develop>

Connecting to Synapse

To use Synapse, you’ll need to register for an account. The Synapse website can authenticate using a Google account, but you’ll need to take the extra step of creating a Synapse personal access token to use the programmatic clients.

Once that’s done, you’ll be able to load the library, create a Synapse object and login:

import synapseclient
syn = synapseclient.Synapse()

syn.login(authToken=<PAT>)

For more information, see:

Imports

Several components of the synapseclient can be imported as needed:

from synapseclient import Activity
from synapseclient import Entity, Project, Folder, File, Link
from synapseclient import Evaluation, Submission, SubmissionStatus
from synapseclient import Wiki

Accessing Data

Synapse identifiers are used to refer to projects and data which are represented by synapseclient.entity objects. For example, the entity syn1899498 represents a tab-delimited file containing a 100 by 4 matrix. Getting the entity retrieves an object that holds metadata describing the matrix, and also downloads the file to a local cache:

entity = syn.get('syn1899498')

View the entity’s metadata in the Python console:

print(entity)

This is one simple way to read in a small matrix:

rows = []
with open(entity.path) as f:
    header = f.readline().split('\t')
    for line in f:
        row = [float(x) for x in line.split('\t')]
        rows.append(row)

View the entity in the browser:

syn.onweb('syn1899498')

Organizing Data in a Project

You can create your own projects and upload your own data sets. Synapse stores entities in a hierarchical or tree structure. Projects are at the top level and must be uniquely named:

import synapseclient
from synapseclient import Project, Folder, File, Link

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

Creating a folder:

data_folder = Folder('Data', parent=project)
data_folder = syn.store(data_folder)

Adding files to the project:

test_entity = File('/path/to/data/file.xyz', description='Fancy new data', parent=data_folder)
test_entity = syn.store(test_entity)

In addition to simple data storage, Synapse entities can be annotated with key/value metadata, described in markdown documents (wikis), and linked together in provenance graphs to create a reproducible record of a data analysis pipeline.

See also:

Annotating Synapse Entities

Annotations are arbitrary metadata attached to Synapse entities, for example:

test_entity.genome_assembly = "hg19"

See:

Provenance

Synapse provides tools for tracking ‘provenance’, or the transformation of raw data into processed results, by linking derived data objects to source data and the code used to perform the transformation.

See:

Tables

Tables can be built up by adding sets of rows that follow a user-defined schema and queried using a SQL-like syntax.

See:

Wikis

Wiki pages can be attached to an Synapse entity (i.e. project, folder, file, etc). Text and graphics can be composed in markdown and rendered in the web view of the object.

See:

Evaluations

An evaluation is a Synapse construct useful for building processing pipelines and for scoring predictive modelling and data analysis challenges.

See:

Access Control

By default, data sets in Synapse are private to your user account, but they can easily be shared with specific users, groups, or the public.

See:

Accessing the API Directly

These methods enable access to the Synapse REST(ish) API taking care of details like endpoints and authentication. See the REST API documentation.

See:

Synapse Utilities

There is a companion module called synapseutils that provide higher level functionality such as recursive copying of content, syncing with Synapse and additional query functionality.

See: - synapseutils

More Information

For more information see the Synapse User Guide. These Python API docs are browsable online at https://python-docs.synapse.org/.

Getting Updates

To get information about new versions of the client, see: synapseclient.check_for_updates().

class synapseclient.Activity(name=None, description=None, used=None, executed=None, data={})

Represents the provenance of a Synapse Entity.

Parameters

  • name – name of the Activity

  • description – a short text description of the Activity

  • used –

    Either a list of:

    • reference objects (e.g. [{'targetId':'syn123456', 'targetVersionNumber':1}])

    • a list of Synapse Entities or Entity IDs

    • a list of URL’s

  • executed – A code resource that was executed to generate the Entity.

  • data – A dictionary representation of an Activity, with fields ‘name’, ‘description’ and ‘used’ (a list of reference objects)

See also: The W3C’s provenance ontology

executed(target=None, targetVersion=None, url=None, name=None)

Add a code resource that was executed during the activity. See synapseclient.activity.Activity.used()

used(target=None, targetVersion=None, wasExecuted=None, url=None, name=None)

Add a resource used by the activity.

This method tries to be as permissive as possible. It accepts a string which might be a synapse ID or a URL, a synapse entity, a UsedEntity or UsedURL dictionary or a list containing any combination of these.

In addition, named parameters can be used to specify the fields of either a UsedEntity or a UsedURL. If target and optionally targetVersion are specified, create a UsedEntity. If url and optionally name are specified, create a UsedURL.

It is an error to specify both target/targetVersion parameters and url/name parameters in the same call. To add multiple UsedEntities and UsedURLs, make a separate call for each or pass in a list.

In case of conflicting settings for wasExecuted both inside an object and with a parameter, the parameter wins. For example, this UsedURL will have wasExecuted set to False:

activity.used({'url':'http://google.com', 'name':'Goog', 'wasExecuted':True}, wasExecuted=False)

Entity examples:

activity.used('syn12345')
activity.used(entity)
activity.used(target=entity, targetVersion=2)
activity.used(codeEntity, wasExecuted=True)
activity.used({'reference':{'target':'syn12345', 'targetVersion':1}, 'wasExecuted':False})

URL examples:

activity.used('http://mydomain.com/my/awesome/data.RData')
activity.used(url='http://mydomain.com/my/awesome/data.RData', name='Awesome Data')
activity.used(url='https://github.com/joe_hacker/code_repo', name='Gnarly hacks', wasExecuted=True)
activity.used({'url':'https://github.com/joe_hacker/code_repo', 'name':'Gnarly hacks'}, wasExecuted=True)

List example:

activity.used(['syn12345', 'syn23456', entity,                           {'reference':{'target':'syn100009', 'targetVersion':2}, 'wasExecuted':True},                           'http://mydomain.com/my/awesome/data.RData'])
class synapseclient.Annotations(id: Union[str, int, synapseclient.entity.Entity], etag: str, values: Optional[Dict] = None, **kwargs)

Represent Synapse Entity annotations as a flat dictionary with the system assigned properties id, etag as object attributes.

class synapseclient.Column(**kwargs)

Defines a column to be used in a table synapseclient.table.Schema synapseclient.table.EntityViewSchema.

Variables

id – An immutable ID issued by the platform

Parameters

  • columnType (string) – The column type determines the type of data that can be stored in a column. It can be any of: “STRING”, “DOUBLE”, “INTEGER”, “BOOLEAN”, “DATE”, “FILEHANDLEID”, “ENTITYID”, “LINK”, “LARGETEXT”, “USERID”. For more information, please see: https://docs.synapse.org/rest/org/sagebionetworks/repo/model/table/ColumnType.html

  • maximumSize (integer) – A parameter for columnTypes with a maximum size. For example, ColumnType.STRINGs have a default maximum size of 50 characters, but can be set to a maximumSize of 1 to 1000 characters.

  • maximumListLength (integer) – Required if using a columnType with a “_LIST” suffix. Describes the maximum number of values that will appear in that list. Value range 1-100 inclusive. Default 100

  • name (string) – The display name of the column

  • enumValues (array of strings) – Columns type of STRING can be constrained to an enumeration values set on this list.

  • defaultValue (string) – The default value for this column. Columns of type FILEHANDLEID and ENTITYID are not allowed to have default values.

class synapseclient.Dataset(*args, **kwargs)

A Dataset is an synapseclient.entity.Entity that defines a flat list of entities as a tableview (a.k.a. a “dataset”).

Parameters

  • name – The name for the Dataset object

  • description – User readable description of the schema

  • columns – A list of Column objects or their IDs

  • parent – The Synapse Project to which this Dataset belongs

  • properties – A map of Synapse properties

  • annotations – A map of user defined annotations

  • dataset_items – A list of items characterized by entityId and versionNumber

  • folder – A list of Folder IDs

  • local_state – Internal use only

Example:

from synapseclient import Dataset

# Create a Dataset with pre-defined DatasetItems. Default Dataset columns
# are used if no schema is provided.
dataset_items = [
    {'entityId': "syn000", 'versionNumber': 1},
    {...},
]
dataset = syn.store(Dataset(
    name="My Dataset",
    parent=project,
    dataset_items=dataset_items))

# Add/remove specific Synapse IDs to/from the Dataset
dataset.add_item({'entityId': "syn111", 'versionNumber': 1})
dataset.remove_item("syn000")
dataset = syn.store(dataset)

# Add a list of Synapse IDs to the Dataset
new_items = [
    {'entityId': "syn222", 'versionNumber': 2},
    {'entityId': "syn333", 'versionNumber': 1}
]
dataset.add_items(new_items)
dataset = syn.store(dataset)

Folders can easily be added recursively to a dataset, that is, all files within the folder (including sub-folders) will be added. Note that using the following methods will add files with the latest version number ONLY. If another version number is desired, use :py:classmethod:`synapseclient.table.add_item` or :py:classmethod:`synapseclient.table.add_items`.

Example:

# Add a single Folder to the Dataset
dataset.add_folder("syn123")

# Add a list of Folders, overwriting any existing files in the dataset
dataset.add_folders(["syn456", "syn789"], force=True)

dataset = syn.store(dataset)

empty() can be used to truncate a dataset, that is, remove all current items from the set.

Example:

dataset.empty()
dataset = syn.store(dataset)

To get the number of entities in the dataset, use len().

Example:

print(f"{dataset.name} has {len(dataset)} items.")

To create a snapshot version of the Dataset, use :py:classmethod:`synapseclient.client.create_snapshot_version`.

Example:

syn = synapseclient.login()
syn.create_snapshot_version(
    dataset.id,
    label="v1.0",
    comment="This is version 1")
add_folder(folder: str, force: bool = True)
Parameters

  • folder – a single Synapse Folder ID

  • force – force add items from folder

add_folders(folders: List[str], force: bool = True)
Parameters

  • folders – a list of Synapse Folder IDs

  • force – force add items from folders

add_item(dataset_item: Dict[str, str], force: bool = True)
Parameters

  • dataset_item – a single dataset item

  • force – force add item

add_items(dataset_items: List[Dict[str, str]], force: bool = True)
Parameters

  • dataset_items – a list of dataset items

  • force – force add items

has_item(item_id)
Parameters

item_id – a single dataset item Synapse ID

remove_item(item_id: str)
Parameters

item_id – a single dataset item Synapse ID

class synapseclient.DockerRepository(*args, **kwargs)

A Docker repository is a lightweight virtual machine image.

NOTE: store()-ing a DockerRepository created in the Python client will always result in it being treated as a reference to an external Docker repository that is not managed by synapse. To upload a docker image that is managed by Synapse please use the official Docker client and read

http://docs.synapse.org/articles/docker.html for instructions on uploading a Docker Image to Synapse

Parameters

  • repositoryName – the name of the Docker Repository. Usually in the format: [host[:port]/]path. If host is not set, it will default to that of DockerHub. port can only be specified if the host is also specified.

  • parent – the parent project for the Docker repository

  • properties – A map of Synapse properties

  • annotations – A map of user defined annotations

  • local_state – Internal use only

Returns

an object of type synapseclient.entity.DockerRepository

class synapseclient.Entity(*args, **kwargs)

A Synapse entity is an object that has metadata, access control, and potentially a file. It can represent data, source code, or a folder that contains other entities.

Entities should typically be created using the constructors for specific subclasses such as Project, Folder or File.

classmethod create(properties=None, annotations=None, local_state=None)

Create an Entity or a subclass given dictionaries of properties and annotations, as might be received from the Synapse Repository.

Parameters

  • properties –

    A map of Synapse properties

    If ‘concreteType’ is defined in properties, we create the proper subclass of Entity. If not, give back the type whose constructor was called:

    If passed an Entity as input, create a new Entity using the input entity as a prototype.

  • annotations – A map of user defined annotations

  • local_state – Internal use only

has_key(key)

Is the given key a property or annotation?

keys()

Returns a set of property and annotation keys

local_state(state=None)

Set or get the object’s internal state, excluding properties, or annotations.

Parameters

state – A dictionary

class synapseclient.EntityViewSchema(*args, **kwargs)

A EntityViewSchema is a synapseclient.entity.Entity that displays all files/projects (depending on user choice) within a given set of scopes

Parameters

  • name – the name of the Entity View Table object

  • columns – a list of Column objects or their IDs. These are optional.

  • parent – the project in Synapse to which this table belongs

  • scopes – a list of Projects/Folders or their ids

  • type – This field is deprecated. Please use includeEntityTypes

  • includeEntityTypes –

    a list of entity types to include in the view. Supported entity types are:

    EntityViewType.FILE, EntityViewType.PROJECT, EntityViewType.TABLE, EntityViewType.FOLDER, EntityViewType.VIEW, EntityViewType.DOCKER

    If none is provided, the view will default to include EntityViewType.FILE.

  • addDefaultViewColumns – If true, adds all default columns (e.g. name, createdOn, modifiedBy etc.) Defaults to True. The default columns will be added after a call to synapseclient.Synapse.store().

  • addAnnotationColumns – If true, adds columns for all annotation keys defined across all Entities in the EntityViewSchema’s scope. Defaults to True. The annotation columns will be added after a call to synapseclient.Synapse.store().

  • ignoredAnnotationColumnNames – A list of strings representing annotation names. When addAnnotationColumns is True, the names in this list will not be automatically added as columns to the EntityViewSchema if they exist in any of the defined scopes.

  • properties – A map of Synapse properties

  • annotations – A map of user defined annotations

  • local_state – Internal use only

Example:

from synapseclient import EntityViewType

project_or_folder = syn.get("syn123")
schema = syn.store(EntityViewSchema(name='MyTable', parent=project, scopes=[project_or_folder_id, 'syn123'],
 includeEntityTypes=[EntityViewType.FILE]))
set_entity_types(includeEntityTypes)
Parameters

includeEntityTypes –

a list of entity types to include in the view. This list will replace the previous settings. Supported entity types are:

EntityViewType.FILE, EntityViewType.PROJECT, EntityViewType.TABLE, EntityViewType.FOLDER, EntityViewType.VIEW, EntityViewType.DOCKER

class synapseclient.EntityViewType(value)

An enumeration.

class synapseclient.Evaluation(**kwargs)

An Evaluation Submission queue, allowing submissions, retrieval and scoring.

Parameters

  • name – Name of the evaluation

  • description – A short description of the evaluation

  • contentSource – Synapse Project associated with the evaluation

  • submissionReceiptMessage – Message to display to users upon submission

  • submissionInstructionsMessage – Message to display to users detailing acceptable formatting for submissions.

To create an Evaluation and store it in Synapse:

evaluation = syn.store(Evaluation(
    name="Q1 Final",
    description="Predict progression of MMSE scores for final scoring",
    contentSource="syn2290704"))

The contentSource field links the evaluation to its synapseclient.entity.Project. (Or, really, any synapse ID, but sticking to projects is a good idea.)

Evaluations can be retrieved from Synapse by ID:

evaluation = syn.getEvaluation(1901877)

…by the Synapse ID of the content source (associated entity):

evaluation = syn.getEvaluationByContentSource('syn12345')

…or by the name of the evaluation:

evaluation = syn.getEvaluationByName('Foo Challenge Question 1')
class synapseclient.File(*args, **kwargs)

Represents a file in Synapse.

When a File object is stored, the associated local file or its URL will be stored in Synapse. A File must have a path (or URL) and a parent.

Parameters

  • path – Location to be represented by this File

  • name – Name of the file in Synapse, not to be confused with the name within the path

  • parent – Project or Folder where this File is stored

  • synapseStore – Whether the File should be uploaded or if only the path should be stored when synapseclient.Synapse.store() is called on the File object. Defaults to True (file should be uploaded)

  • contentType – Manually specify Content-type header, for example “application/png” or “application/json; charset=UTF-8”

  • dataFileHandleId – Defining an existing dataFileHandleId will use the existing dataFileHandleId The creator of the file must also be the owner of the dataFileHandleId to have permission to store the file

  • properties – A map of Synapse properties

  • annotations – A map of user defined annotations

  • local_state – Internal use only

Example:

data = File('/path/to/file/data.xyz', parent=folder)
data = syn.store(data)
class synapseclient.Folder(*args, **kwargs)

Represents a folder in Synapse.

Folders must have a name and a parent and can optionally have annotations.

Parameters

  • name – The name of the folder

  • parent – The parent project or folder

  • properties – A map of Synapse properties

  • annotations – A map of user defined annotations

  • local_state – Internal use only

Example:

folder = Folder('my data', parent=project)
folder = syn.store(folder)

Represents a link in Synapse.

Links must have a target ID and a parent. When you do synapseclient.Synapse.get() on a Link object, the Link object is returned. If the target is desired, specify followLink=True in synapseclient.Synapse.get.

Parameters

  • targetId – The ID of the entity to be linked

  • targetVersion – The version of the entity to be linked

  • parent – The parent project or folder

  • properties – A map of Synapse properties

  • annotations – A map of user defined annotations

  • local_state – Internal use only

Example:

link = Link('targetID', parent=folder)
link = syn.store(link)
class synapseclient.MaterializedViewSchema(*args, **kwargs)

A MaterializedViewSchema is an synapseclient.entity.Entity that defines a set of columns in a materialized view along with the SQL statement.

Parameters

  • name – the name for the Materialized View Schema object

  • description – User readable description of the schema

  • definingSQL – The synapse SQL statement that defines the data in the materialized view. The SQL may contain JOIN clauses on multiple tables.

  • columns – a list of Column objects or their IDs

  • parent – the project in Synapse to which this Materialized View belongs

  • properties – A map of Synapse properties

  • annotations – A map of user defined annotations

  • local_state – Internal use only

Example:

defining_sql = "SELECT * FROM syn111 F JOIN syn2222 P on (F.patient_id = P.patient_id)"

schema = syn.store(MaterializedViewSchema(name='MyTable', parent=project, definingSQL=defining_sql))
class synapseclient.PartialRowset(schema, rows)

A set of Partial Rows used for updating cells of a table. PartialRowsets allow you to push only the individual cells you wish to change instead of pushing entire rows with many unchanged cells.

Example::

#### the following code will change cells in a hypothetical table, syn123: #### these same steps will also work for using EntityView tables to change Entity annotations # # fooCol | barCol fooCol | barCol # —————– =======> ———————- # foo1 | bar1 foo foo1 | bar1 # foo2 | bar2 foo2 | bar bar 2

query_results = syn.tableQuery(“SELECT * FROM syn123”)

# The easiest way to know the rowId of the row you wish to change # is by converting the table to a pandas DataFrame with rowIdAndVersionInIndex=False df = query_results.asDataFrame(rowIdAndVersionInIndex=False)

partial_changes = {df[‘ROW_ID’][0]: {‘fooCol’: ‘foo foo 1’},

df[‘ROW_ID’][1]: {‘barCol’: ‘bar bar 2’}}

# you will need to pass in your original query result as an argument # so that we can perform column id translation and etag retrieval on your behalf: partial_rowset = PartialRowset.from_mapping(partial_changes, query_results) syn.store(partial_rowset)

Parameters

  • schema – The Schema of the table to update or its tableId as a string

  • rows – A list of PartialRows

classmethod from_mapping(mapping, originalQueryResult)

Creates a PartialRowset :param mapping: A mapping of mappings in the structure: {ROW_ID : {COLUMN_NAME: NEW_COL_VALUE}} :param originalQueryResult: :return: a PartialRowSet that can be syn.store()-ed to apply the changes

class synapseclient.Project(*args, **kwargs)

Represents a project in Synapse.

Projects in Synapse must be uniquely named. Trying to create a project with a name that’s already taken, say ‘My project’, will result in an error

Parameters

  • name – The name of the project

  • properties – A map of Synapse properties

  • annotations – A map of user defined annotations

  • local_state – Internal use only

Example:

project = Project('Foobarbat project')
project = syn.store(project)
class synapseclient.Row(values, rowId=None, versionNumber=None, etag=None, **kwargs)

A row in a Table.

Parameters

  • values – A list of values

  • rowId – The immutable ID issued to a new row

  • versionNumber – The version number of this row. Each row version is immutable, so when a row is updated a new version is created.

class synapseclient.RowSet(columns=None, schema=None, **kwargs)

A Synapse object of type org.sagebionetworks.repo.model.table.RowSet.

Parameters

  • schema – A synapseclient.table.Schema object that will be used to set the tableId

  • headers (array of SelectColumns) – The list of SelectColumn objects that describe the fields in each row.

  • columns – An alternative to ‘headers’, a list of column objects that describe the fields in each row.

  • tableId (string) – The ID of the TableEntity that owns these rows

  • rows (array of rows) – The synapseclient.table.Row s of this set. The index of each row value aligns with the index of each header.

Variables

etag – Any RowSet returned from Synapse will contain the current etag of the change set. To update any rows from a RowSet the etag must be provided with the POST.

class synapseclient.Schema(*args, **kwargs)

A Schema is an synapseclient.entity.Entity that defines a set of columns in a table.

Parameters

  • name – the name for the Table Schema object

  • description – User readable description of the schema

  • columns – a list of Column objects or their IDs

  • parent – the project in Synapse to which this table belongs

  • properties – A map of Synapse properties

  • annotations – A map of user defined annotations

  • local_state – Internal use only

Example:

cols = [Column(name='Isotope', columnType='STRING'),
        Column(name='Atomic Mass', columnType='INTEGER'),
        Column(name='Halflife', columnType='DOUBLE'),
        Column(name='Discovered', columnType='DATE')]

schema = syn.store(Schema(name='MyTable', columns=cols, parent=project))
class synapseclient.Submission(**kwargs)

Builds an Synapse submission object.

Parameters

  • name – Name of submission

  • entityId – Synapse ID of the Entity to submit

  • evaluationId – ID of the Evaluation to which the Entity is to be submitted

  • versionNumber – Version number of the submitted Entity

  • submitterAlias – A pseudonym or team name for a challenge entry

class synapseclient.SubmissionStatus(id, etag, **kwargs)

Builds an Synapse submission status object. https://rest-docs.synapse.org/rest/org/sagebionetworks/evaluation/model/SubmissionStatus.html

Parameters
json(ensure_ascii=True)

Overloaded json function, turning submissionAnnotations into synapse style annotations

class synapseclient.SubmissionViewSchema(*args, **kwargs)

A SubmissionViewSchema is a synapseclient.entity.Entity that displays all files/projects (depending on user choice) within a given set of scopes

Parameters

  • name – the name of the Entity View Table object

  • columns – a list of Column objects or their IDs. These are optional.

  • parent – the project in Synapse to which this table belongs

  • scopes – a list of Evaluation Queues or their ids

  • addDefaultViewColumns – If true, adds all default columns (e.g. name, createdOn, modifiedBy etc.) Defaults to True. The default columns will be added after a call to synapseclient.Synapse.store().

  • addAnnotationColumns – If true, adds columns for all annotation keys defined across all Entities in the SubmissionViewSchema’s scope. Defaults to True. The annotation columns will be added after a call to synapseclient.Synapse.store().

  • ignoredAnnotationColumnNames – A list of strings representing annotation names. When addAnnotationColumns is True, the names in this list will not be automatically added as columns to the SubmissionViewSchema if they exist in any of the defined scopes.

  • properties – A map of Synapse properties

  • annotations – A map of user defined annotations

  • local_state – Internal use only

Example::

from synapseclient import SubmissionViewSchema

project = syn.get(“syn123”) schema = syn.store(SubmissionViewSchema(name=’My Submission View’, parent=project, scopes=[‘9614543’]))

class synapseclient.Synapse(repoEndpoint=None, authEndpoint=None, fileHandleEndpoint=None, portalEndpoint=None, debug=None, skip_checks=False, configPath='/Users/tyu/.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:

clear_download_list()

Clear all files from download list

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, synapseclient.table.Dataset], 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, new View version, or new Dataset 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', 'submissionview', 'dataset', 'materializedview'], 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:

  • synapseutils.walk()

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.

Parameters

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_download_list(downloadLocation: Optional[str] = None) → str

Download all files from your Synapse download list

Parameters

downloadLocation – Directory to download files to.

Returns

manifest file with file paths

get_download_list_manifest()

Get the path of the download list manifest file

Returns

path of download list manifest file

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 (WILL BE DEPRECATED)

  • email/username and apiKey (Base64 encoded string) (WILL BE DEPRECATED)

  • 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 – !!WILL BE DEPRECATED!! password. Please use authToken (Synapse personal access token)

  • apiKey – !!WILL BE DEPRECATED!! 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

remove_from_download_list(list_of_files: List[Dict]) → int

Remove a batch of files from download list

Param

array of files in the format of a mapping {fileEntityId: synid, versionNumber: version}

Returns

Number of files removed from download list

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

Parameters

  • entity – a Project or Folder to which the StorageLocationSetting is set

  • 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 – (DEPRECATED)

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

synapseclient.Table(schema, values, **kwargs)

Combine a table schema and a set of values into some type of Table object depending on what type of values are given.

Parameters

  • schema – a table Schema object or Synapse Id of Table.

  • values –

    an object that holds the content of the tables - a RowSet - a list of lists (or tuples) where each element is a row - a string holding the path to a CSV file - a Pandas DataFrame - a dict which will be wrapped by a Pandas DataFrame

Returns

a Table object suitable for storing

Usually, the immediate next step after creating a Table object is to store it:

table = syn.store(Table(schema, values))

End users should not need to know the details of these Table subclasses:

  • TableAbstractBaseClass

  • RowSetTable

  • TableQueryResult

  • CsvFileTable

class synapseclient.Team(**kwargs)

Represents a Synapse Team. User definable fields are:

Parameters

  • icon – fileHandleId for icon image of the Team

  • description – A short description of this Team.

  • name – The name of the Team.

  • canPublicJoin – true for teams which members can join without an invitation or approval

class synapseclient.TeamMember(**kwargs)
Contains information about a user’s membership in a Team. In practice the constructor is not called directly by

the client.

Parameters

  • teamId – the ID of the team

  • member – An object of type org.sagebionetworks.repo.model.UserGroupHeader describing the member

  • isAdmin – Whether the given member is an administrator of the team

class synapseclient.UserGroupHeader(**kwargs)

Select metadata about a Synapse principal. In practice the constructor is not called directly by the client.

Parameters

  • ownerId – A foreign key to the ID of the ‘principal’ object for the user.

  • firstName – First Name

  • lastName – Last Name

  • userName – A name chosen by the user that uniquely identifies them.

  • email – User’s current email address

  • isIndividual – True if this is a user, false if it is a group

class synapseclient.UserProfile(**kwargs)

Information about a Synapse user. In practice the constructor is not called directly by the client.

Parameters

  • ownerId – A foreign key to the ID of the ‘principal’ object for the user.

  • uri – The Uniform Resource Identifier (URI) for this entity.

  • etag – Synapse employs an Optimistic Concurrency Control (OCC) scheme to handle concurrent updates. Since the E-Tag changes every time an entity is updated it is used to detect when a client’s current representation of an entity is out-of-date.

  • firstName – This person’s given name (forename)

  • lastName – This person’s family name (surname)

  • emails – The list of user email addresses registered to this user.

  • userName – A name chosen by the user that uniquely identifies them.

  • summary – A summary description about this person

  • position – This person’s current position title

  • location – This person’s location

  • industry – “The industry/discipline that this person is associated with

  • company – This person’s current affiliation

  • profilePicureFileHandleId – The File Handle ID of the user’s profile picture.

  • url – A link to more information about this person

  • notificationSettings – An object of type org.sagebionetworks.repo.model.message.Settings containing the user’s preferences regarding when email notifications should be sent

class synapseclient.Wiki(**kwargs)

Represents a wiki page in Synapse with content specified in markdown.

Parameters

  • title – Title of the Wiki

  • owner – Parent Entity that the Wiki will belong to

  • markdown – Content of the Wiki (cannot be defined if markdownFile is defined)

  • markdownFile – Path to file which contains the Content of Wiki (cannot be defined if markdown is defined)

  • attachments – List of paths to files to attach

  • fileHandles – List of file handle IDs representing files to be attached

  • parentWikiId – (optional) For sub-pages, specify parent wiki page

deleteURI()

For internal use.

getURI()

For internal use.

json()

Returns the JSON representation of the Wiki object.

postURI()

For internal use.

putURI()

For internal use.

update_markdown(markdown=None, markdown_file=None)

Updates the wiki’s markdown. Specify only one of markdown or markdown_file :param markdown: text that will become the markdown :param markdown_file: path to a file. Its contents will be the markdown

synapseclient.as_table_columns(values)

Return a list of Synapse table Column objects that correspond to the columns in the given values.

Params values

an object that holds the content of the tables - a string holding the path to a CSV file, a filehandle, or StringIO containing valid csv content - a Pandas DataFrame

Returns

A list of Synapse table Column objects

Example:

import pandas as pd

df = pd.DataFrame(dict(a=[1, 2, 3], b=["c", "d", "e"]))
cols = as_table_columns(df)
synapseclient.build_table(name, parent, values)

Build a Table object

Parameters

  • name – the name for the Table Schema object

  • parent – the project in Synapse to which this table belongs

  • values –

    an object that holds the content of the tables - a string holding the path to a CSV file - a Pandas DataFrame

Returns

a Table object suitable for storing

Example:

path = "/path/to/file.csv"
table = build_table("simple_table", "syn123", path)
table = syn.store(table)

import pandas as pd

df = pd.DataFrame(dict(a=[1, 2, 3], b=["c", "d", "e"]))
table = build_table("simple_table", "syn123", df)
table = syn.store(table)
synapseclient.check_for_updates()

Check for the existence of newer versions of the client, reporting both current release version and development version.

For help installing development versions of the client, see the docs for synapseclient or the README.md.

synapseclient.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()
synapseclient.release_notes(version_url=None)

Print release notes for the installed version of the client or latest release or development version if version_url is supplied.

Parameters

version_url –

Defaults to None, meaning release notes for the installed version. Alternatives are:

  • synapseclient.version_check._VERSION_URL

  • synapseclient.version_check._DEV_VERSION_URL