{"id":28313,"library":"synapseclient","title":"Synapse Python Client","description":"The official Python client for Synapse, a collaborative open-source research platform by Sage Bionetworks. Current version 4.12.0 (requires Python >=3.10, <3.15). Enables programmatic access to data storage, analysis tracking, and collaboration features. Released approximately monthly with breaking changes introduced in major versions (e.g., v4.x dropped Python 3.8 support and shifted to object-oriented models).","status":"active","version":"4.12.0","language":"python","source_language":"en","source_url":"https://github.com/Sage-Bionetworks/synapsePythonClient","tags":["synapse","sage","data repository","collaboration"],"install":[{"cmd":"pip install synapseclient","lang":"bash","label":"Stable"},{"cmd":"pip install synapseclient[pandas]","lang":"bash","label":"With pandas support"}],"dependencies":[],"imports":[{"note":"Direct import only exposes module namespace; must import Synapse class explicitly.","wrong":"import synapseclient","symbol":"Synapse","correct":"from synapseclient import Synapse"},{"note":"Entity submodules like synapseclient.entity are deprecated in favor of top-level imports.","wrong":"from synapseclient.entity import File","symbol":"File","correct":"from synapseclient import File"},{"note":"Schema was moved to top-level in v4.x; old path no longer exists.","wrong":"from synapseclient.models import Schema","symbol":"Schema","correct":"from synapseclient import Schema"}],"quickstart":{"code":"import os\nfrom synapseclient import Synapse, File\n\n# Authenticate using personal access token or credentials\nsyn = Synapse()\nsyn.login(email=os.environ.get('SYNAPSE_EMAIL', ''), password=os.environ.get('SYNAPSE_PASSWORD', ''), rememberMe=True)\n\n# Upload a file\nfile_entity = File('example.txt', parent='syn12345678')\nfile_entity = syn.store(file_entity)\nprint(f'Stored file with ID: {file_entity.id}')\n\n# Query for data\nresults = syn.tableQuery('SELECT * FROM syn12345678')\ndf = results.asDataFrame()","lang":"python","description":"Authenticate, upload a file, and run a table query. Replace 'syn12345678' with a real Synapse ID."},"warnings":[{"fix":"Upgrade Python to 3.10-3.14. Use virtual environment.","message":"Python 3.8 support dropped in v4.4.2. Must use Python >=3.10,<3.15.","severity":"breaking","affected_versions":">=4.4.2"},{"fix":"Check migration guide: https://python-docs.synapse.org/en/stable/reference/migration-v4.html","message":"Many class-based models (e.g., Entity, Evaluation, Submission) have been replaced by object-oriented counterparts in v4.10+ (e.g., `Evaluation -> EvaluationV2`). Old imports may fail.","severity":"breaking","affected_versions":">=4.10.0"},{"fix":"Use `from synapseclient import File, Folder, Project` instead of `from synapseclient.entity import File`.","message":"`synapseclient.entity` submodule is deprecated; import Entity classes from top-level `synapseclient` instead.","severity":"deprecated","affected_versions":">=4.0.0"},{"fix":"Supply email/password or authToken as arguments: `syn.login(email=..., password=...)` or use `SYNAPSE_AUTH_TOKEN` environment variable.","message":"Authentication via `syn.login()` without arguments tries cached credentials; if none, it prompts interactively. In CI, always provide credentials explicitly.","severity":"gotcha","affected_versions":"all"},{"fix":"Call `syn.store(file_entity, forceVersion=False)` and monitor progress with callbacks or after invocation.","message":"When storing large files with `syn.store()`, the method returns immediately but upload continues asynchronously. Use `syn.waitForAsync()` or check `file_entity['_status']` if synchronous behavior needed.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-09T00:00:00.000Z","next_check":"2026-08-07T00:00:00.000Z","problems":[{"fix":"Ensure recent version: `pip install --upgrade synapseclient`. Check Python version; if using Python 3.8, upgrade to >=3.10.","cause":"Wrong import path: using `from synapseclient import Synapse` works but if the package is not installed or old version.","error":"ImportError: cannot import name 'Synapse' from 'synapseclient'"},{"fix":"Set environment variables `SYNAPSE_EMAIL` and `SYNAPSE_PASSWORD` or use a `.synapseConfig` file.","cause":"`syn.login()` called without arguments and no cached credentials found.","error":"synapseclient.exceptions.SynapseNoCredentialsError: No credentials provided"},{"fix":"Verify you have appropriate download/upload permissions. Use `syn.onweb()` to open in browser or ask admin to grant access.","cause":"User token lacks access to the specified Synapse entity (project/file) or wrong permissions.","error":"synapseclient.exceptions.SynapseHTTPError: 403 Forbidden - You do not have permission to access this resource"},{"fix":"Refer to updated Table API: use `syn.tableQuery('SELECT * FROM syn...')` or consult migration docs for changes in 4.11+.","cause":"Using an old API call that changed between v4.x versions.","error":"TypeError: Table.query_sync() got an unexpected keyword argument 'includeEntityEtag'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}