Entity

The Entity class is the base class for all entities, including Project, Folder, File, and Link.

Entities are dictionary-like objects in which both object and dictionary notation (entity.foo or entity[‘foo’]) can be used interchangeably.

Imports:

from synapseclient import Project, Folder, File, Link
class synapseclient.entity.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.

Project

class synapseclient.entity.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)

Folder

class synapseclient.entity.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)

File

class synapseclient.entity.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)

Changing File Names

A Synapse File Entity has a name separate from the name of the actual file it represents. When a file is uploaded to Synapse, its filename is fixed, even though the name of the entity can be changed at any time. Synapse provides a way to change this filename and the content-type of the file for future downloads by creating a new version of the file with a modified copy of itself. This can be done with the synapseutils.copy_functions.changeFileMetaData function.

>>> import synapseutils
>>> e = syn.get(synid)
>>> print(os.path.basename(e.path))  ## prints, e.g., "my_file.txt"
>>> e = synapseutils.changeFileMetaData(syn, e, "my_newname_file.txt")

Setting fileNameOverride will not change the name of a copy of the file that’s already downloaded into your local cache. Either rename the local copy manually or remove it from the cache and re-download.:

>>> syn.cache.remove(e.dataFileHandleId)
>>> e = syn.get(e)
>>> print(os.path.basename(e.path))  ## prints "my_newname_file.txt"

Table Schema

class synapseclient.table.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))

Entity View Schema

class synapseclient.table.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]))

DockerRepository

class synapseclient.entity.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

Properties and annotations, implementation details

In Synapse, entities have both properties and annotations. Properties are used by the system, whereas annotations are completely user defined. In the Python client, we try to present this situation as a normal object, with one set of properties.

Printing an entity will show the division between properties and annotations.:

print(entity)

Under the covers, an Entity object has two dictionaries, one for properties and one for annotations. These two namespaces are distinct, so there is a possibility of collisions. It is recommended to avoid defining annotations with names that collide with properties, but this is not enforced.:

## don't do this!
entity.properties['description'] = 'One thing'
entity.annotations['description'] = 'A different thing'

In case of conflict, properties will take precedence.:

print(entity.description)
#> One thing

Some additional ambiguity is entailed in the use of dot notation. Entity objects have their own internal properties which are not persisted to Synapse. As in all Python objects, these properties are held in object.__dict__. For example, this dictionary holds the keys ‘properties’ and ‘annotations’ whose values are both dictionaries themselves.

The rule, for either getting or setting is: first look in the object then look in properties, then look in annotations. If the key is not found in any of these three, a get results in a KeyError and a set results in a new annotation being created. Thus, the following results in a new annotation that will be persisted in Synapse:

entity.foo = 'bar'

To create an object member variable, which will not be persisted in Synapse, this unfortunate notation is required:

entity.__dict__['foo'] = 'bar'

As mentioned previously, name collisions are entirely possible. Keys in the three namespaces can be referred to unambiguously like so:

entity.__dict__['key']

entity.properties.key
entity.properties['key']

entity.annotations.key
entity.annotations['key']

Most of the time, users should be able to ignore these distinctions and treat Entities like normal Python objects. End users should never need to manipulate items in __dict__.

See also: