synapse-python-client

Synapse Python Client Skill

Overview

The Synapse Python client (synapseclient) is the official Python SDK and CLI for Synapse (synapse.org), a collaborative biomedical data sharing platform by Sage Bionetworks. The modern synapseclient.models API provides async-first dataclass models with auto-generated sync wrappers.

Installation

pip install synapseclient

# With optional extras
pip install "synapseclient[boto3,pandas,pysftp,curator]"

Requires: Python 3.10 - 3.14

Authentication

import synapseclient

# Personal access token (preferred)
synapseclient.login(authToken="your_token")

# From ~/.synapseConfig [default] profile
synapseclient.login()

# From environment variable SYNAPSE_AUTH_TOKEN
synapseclient.login()

# Select a named profile from ~/.synapseConfig
# Set SYNAPSE_PROFILE=myprofile or pass profile="myprofile"
synapseclient.login(profile="myprofile")

Auth priority chain: login args > config file (~/.synapseConfig) > SYNAPSE_AUTH_TOKEN env var > AWS SSM (via SYNAPSE_TOKEN_AWS_SSM_PARAMETER_NAME).

Core Concepts

• Entity: Base class for Synapse objects (Projects, Folders, Files, Tables, Datasets, etc.)
• Synapse ID: Format syn123456 - unique identifier for every entity
• Async-first: All model methods are async with _async suffix. The @async_to_sync decorator auto-generates sync wrappers (without the suffix)
• Dataclass models: All models are @dataclass classes (NOT Pydantic)

Sync vs Async Usage

Sync (default for scripts)

from synapseclient.models import File
file = File(id="syn123456").get()           # sync wrapper
file.store()                                 # sync wrapper

Async (for heavy I/O, parallel operations)

import asyncio
from synapseclient.models import File

async def main():
    file = await File(id="syn123456").get_async()
    await file.store_async()

    # Parallel uploads
    files = [File(path=p, parent_id="syn123") for p in paths]
    await asyncio.gather(*(f.store_async() for f in files))

asyncio.run(main())