From 3b985151832b1790badaf228604cb9f68e9a4191 Mon Sep 17 00:00:00 2001 From: Thomas Yu Date: Fri, 13 Mar 2026 10:14:16 -0700 Subject: [PATCH 1/4] SYNPY-1508: add tutorial for downloading files by Synapse ID concurrently Co-Authored-By: Claude Sonnet 4.6 --- docs/tutorials/python/download_file.md | 66 +++++++++++++++++++ .../python/tutorial_scripts/download_file.py | 43 ++++++++++++ docs/tutorials/python_client.md | 1 + mkdocs.yml | 1 + 4 files changed, 111 insertions(+) create mode 100644 docs/tutorials/python/download_file.md create mode 100644 docs/tutorials/python/tutorial_scripts/download_file.py diff --git a/docs/tutorials/python/download_file.md b/docs/tutorials/python/download_file.md new file mode 100644 index 000000000..da796ada9 --- /dev/null +++ b/docs/tutorials/python/download_file.md @@ -0,0 +1,66 @@ +[](){ #tutorial-downloading-a-file } +# Downloading files by Synapse ID + +This tutorial shows how to download any set of files from Synapse using their +Synapse IDs. Rather than syncing an entire project or folder, this approach lets +you target exactly the files you need and download them **concurrently** — even +directing each file to a different local directory. + + +## Tutorial Purpose +In this tutorial you will: + +1. Build a mapping of Synapse IDs to local download directories +1. Download all files concurrently using the async API + + +## Prerequisites +* Make sure that you have completed the following tutorials: + * [Folder](./folder.md) + * [File](./file.md) +* The target directories (`~/temp/subdir1`, etc.) must exist before running the + script. Create them or replace them with directories of your choice. + + +## 1. Build a mapping of Synapse IDs to download directories + +Create a dictionary that maps each Synapse ID to the local path where that file +should be saved. Files can be directed to different directories as needed. + +```python +{!docs/tutorials/python/tutorial_scripts/download_file.py!lines=13-30} +``` + + +## 2. Download all files concurrently + +Use `File.get_async()` together with `asyncio.gather` to kick off every download +at the same time and wait for them all to finish. + +```python +{!docs/tutorials/python/tutorial_scripts/download_file.py!lines=33-42} +``` + +
+ After all downloads finish you'll see output like: +``` +Retrieved 12 files +``` +
+ + +## Source code for this tutorial + +
+ Click to show me + +```python +{!docs/tutorials/python/tutorial_scripts/download_file.py!} +``` +
+ +## References used in this tutorial + +- [File][synapseclient.models.File] +- [File.get_async][synapseclient.models.File.get_async] +- [syn.login][synapseclient.Synapse.login] diff --git a/docs/tutorials/python/tutorial_scripts/download_file.py b/docs/tutorials/python/tutorial_scripts/download_file.py new file mode 100644 index 000000000..ce885443d --- /dev/null +++ b/docs/tutorials/python/tutorial_scripts/download_file.py @@ -0,0 +1,43 @@ +""" +Here is where you'll find the code for the downloading a file tutorial. +""" + +import asyncio + +from synapseclient import Synapse +from synapseclient.models import File + +syn = Synapse() +syn.login() + +# A mapping of Synapse IDs to the local directory each file should be downloaded to. +# Files can be directed to different directories as needed. +SYN_IDS_AND_PATHS = { + "syn60584250": "~/temp/subdir1", + "syn60584256": "~/temp/subdir1", + "syn60584248": "~/temp/subdir1", + "syn60584252": "~/temp/subdir1", + "syn60584258": "~/temp/subdir1", + "syn60584260": "~/temp/subdir1", + "syn60584257": "~/temp/subdir1", + "syn60584251": "~/temp/subdir1", + "syn60584253": "~/temp/subdir1", + "syn60584390": "~/temp/subdir1", + "syn60584405": "~/temp/subdir2", + "syn60584400": "~/temp/subdir3", +} + + +async def main(): + # Build a list of concurrent download tasks — one per Synapse ID + tasks = [] + for syn_id, path in SYN_IDS_AND_PATHS.items(): + tasks.append(File(id=syn_id, path=path).get_async()) + + # Download all files concurrently and wait for every one to finish + results = await asyncio.gather(*tasks) + + print(f"Retrieved {len(results)} files") + + +asyncio.run(main()) diff --git a/docs/tutorials/python_client.md b/docs/tutorials/python_client.md index e1f912c44..ac6271e3f 100644 --- a/docs/tutorials/python_client.md +++ b/docs/tutorials/python_client.md @@ -30,6 +30,7 @@ By the end of these tutorials you'll have: - A [Team](./python/team.md) created with one or more members - Methods to [upload data in bulk](./python/upload_data_in_bulk.md) - Methods to [download data in bulk](./python/download_data_in_bulk.md) +- Methods to [download files by Synapse ID](./python/download_file.md) - Methods to [move files and folders](./python/move_files_and_folders.md) - Methods to [migrate data to other storage locations](./python/migrate_data_to_other_storage_locations.md) diff --git a/mkdocs.yml b/mkdocs.yml index eda90ac08..62aa876a8 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -45,6 +45,7 @@ nav: # - Team: tutorials/python/team.md - Upload data in bulk: tutorials/python/upload_data_in_bulk.md - Download data in bulk: tutorials/python/download_data_in_bulk.md + - Download files by Synapse ID: tutorials/python/download_file.md # - Creating JSON Schema: tutorials/python/schema_operations.md - Working with JSON Schema: tutorials/python/json_schema.md # - Move Files and Folders: tutorials/python/move_files_and_folders.md From 1c0a37219066d17d48b0a63ff3fa360759991fa6 Mon Sep 17 00:00:00 2001 From: Thomas Yu Date: Wed, 1 Apr 2026 12:53:52 -0700 Subject: [PATCH 2/4] Update download data tutorial --- .../python/{download_file.md => download_data_by_synid.md} | 6 +++--- .../{download_file.py => download_data_by_synid.py} | 2 +- mkdocs.yml | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) rename docs/tutorials/python/{download_file.md => download_data_by_synid.md} (89%) rename docs/tutorials/python/tutorial_scripts/{download_file.py => download_data_by_synid.py} (92%) diff --git a/docs/tutorials/python/download_file.md b/docs/tutorials/python/download_data_by_synid.md similarity index 89% rename from docs/tutorials/python/download_file.md rename to docs/tutorials/python/download_data_by_synid.md index da796ada9..c3e09b442 100644 --- a/docs/tutorials/python/download_file.md +++ b/docs/tutorials/python/download_data_by_synid.md @@ -1,5 +1,5 @@ [](){ #tutorial-downloading-a-file } -# Downloading files by Synapse ID +# Downloading data by Synapse ID This tutorial shows how to download any set of files from Synapse using their Synapse IDs. Rather than syncing an entire project or folder, this approach lets @@ -28,7 +28,7 @@ Create a dictionary that maps each Synapse ID to the local path where that file should be saved. Files can be directed to different directories as needed. ```python -{!docs/tutorials/python/tutorial_scripts/download_file.py!lines=13-30} +{!docs/tutorials/python/tutorial_scripts/download_data_by_synid.py!lines=13-30} ``` @@ -38,7 +38,7 @@ Use `File.get_async()` together with `asyncio.gather` to kick off every download at the same time and wait for them all to finish. ```python -{!docs/tutorials/python/tutorial_scripts/download_file.py!lines=33-42} +{!docs/tutorials/python/tutorial_scripts/download_data_by_synid.py!lines=31-43} ```
diff --git a/docs/tutorials/python/tutorial_scripts/download_file.py b/docs/tutorials/python/tutorial_scripts/download_data_by_synid.py similarity index 92% rename from docs/tutorials/python/tutorial_scripts/download_file.py rename to docs/tutorials/python/tutorial_scripts/download_data_by_synid.py index ce885443d..14566241b 100644 --- a/docs/tutorials/python/tutorial_scripts/download_file.py +++ b/docs/tutorials/python/tutorial_scripts/download_data_by_synid.py @@ -1,5 +1,5 @@ """ -Here is where you'll find the code for the downloading a file tutorial. +Here is where you'll find the code for the downloading files by synapse ids tutorial. """ import asyncio diff --git a/mkdocs.yml b/mkdocs.yml index 62aa876a8..c7e743ed9 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -45,7 +45,7 @@ nav: # - Team: tutorials/python/team.md - Upload data in bulk: tutorials/python/upload_data_in_bulk.md - Download data in bulk: tutorials/python/download_data_in_bulk.md - - Download files by Synapse ID: tutorials/python/download_file.md + - Download data by Synapse ID: tutorials/python/download_data_by_synid.md # - Creating JSON Schema: tutorials/python/schema_operations.md - Working with JSON Schema: tutorials/python/json_schema.md # - Move Files and Folders: tutorials/python/move_files_and_folders.md From c7b60b38d96e4ceb6cf6d2ed58408d7b4f1321ef Mon Sep 17 00:00:00 2001 From: Thomas Yu Date: Wed, 1 Apr 2026 12:55:45 -0700 Subject: [PATCH 3/4] update tutorial doc --- docs/tutorials/python_client.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/python_client.md b/docs/tutorials/python_client.md index ac6271e3f..ef15e1b79 100644 --- a/docs/tutorials/python_client.md +++ b/docs/tutorials/python_client.md @@ -30,7 +30,7 @@ By the end of these tutorials you'll have: - A [Team](./python/team.md) created with one or more members - Methods to [upload data in bulk](./python/upload_data_in_bulk.md) - Methods to [download data in bulk](./python/download_data_in_bulk.md) -- Methods to [download files by Synapse ID](./python/download_file.md) +- Methods to [download files by Synapse ID](./python/download_data_by_synid.md) - Methods to [move files and folders](./python/move_files_and_folders.md) - Methods to [migrate data to other storage locations](./python/migrate_data_to_other_storage_locations.md) From eb8b4108e4c45f18e05172f8b911e61b55e2f46d Mon Sep 17 00:00:00 2001 From: Thomas Yu Date: Wed, 1 Apr 2026 12:57:19 -0700 Subject: [PATCH 4/4] Update script name --- docs/tutorials/python/download_data_by_synid.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/python/download_data_by_synid.md b/docs/tutorials/python/download_data_by_synid.md index c3e09b442..dd3790dfc 100644 --- a/docs/tutorials/python/download_data_by_synid.md +++ b/docs/tutorials/python/download_data_by_synid.md @@ -55,7 +55,7 @@ Retrieved 12 files Click to show me ```python -{!docs/tutorials/python/tutorial_scripts/download_file.py!} +{!docs/tutorials/python/tutorial_scripts/download_data_by_synid.py!} ```