DreamLake

Download Files

dl.download is one function that handles four cases. It looks at the kind of the resolved node and picks the right strategy.

A single file by path

Inside a Prefix context:

python
import dreamlake as dl

with dl.Prefix(project="robotics@alice", prefix="/session-100"):
    dl.download("camera/front/clip.mp4", to="./out/")

Or with an absolute path, no context needed:

python
dl.download(
    "/session-100/camera/front/clip.mp4",
    project="robotics@alice",
    to="./out/clip.mp4",
)

If to= ends with a / or is an existing directory, the file lands inside it with its original filename. Otherwise to= is the exact output path.

A whole folder, recursive

Pass a folder path — dl.download recognizes the kind is folder (not a file) and streams every descendant leaf, preserving relative paths:

python
with dl.Prefix(project="robotics@alice", prefix="/session-100"):
    dl.download("camera", to="./camera-dl/")

Result:

./camera-dl/
├── front/clip.mp4
└── rear/clip.mp4

An entire episode

Same function, pass the episode path:

python
dl.download("/session-100", project="robotics@alice", to="./session-100-dl/")

Every file across every sub-folder of the episode is downloaded with its full structure under to=.

By node ID

If you already have an ID (from a previous dl.upload response, a lookup_node call, or the preview UI), pass it directly. The SDK detects a 24-char hex string and skips path resolution:

python
dl.download("69e7264a1234567890abcdef", to="./out/")

Works for any kind — files, folders, episodes.

A whole bindr

Bindrs need a separate function because they can mix files and folders from anywhere:

python
dl.download_bindr(
    "training-set",
    project="robotics@alice",
    to="./train/",
)

Each member becomes a top-level entry under to=. Folder members keep their internal structure; file members land directly.

Best practices

  • Pick to= for the unit you're pulling. A single file → use a filename or directory. A folder → use a directory. The SDK creates to= if it doesn't exist.
  • Don't pre-flatten with absolute paths in your code. Let the SDK rebuild the tree under to= — that way the output mirrors what's in DreamLake.
  • Bytes flow direct from S3. The download URL is presigned and short-lived; the bytes never traverse the BSS server. This means big files don't compete for server bandwidth.
  • Resume isn't built into the high-level API yet. If a multi-gigabyte folder download is interrupted, re-run — already-downloaded files are overwritten cheaply, but partial files restart from zero.

What you can do next

  • Bindrs — curate exactly what you want to download
  • Upload an Episode — get data in so you have something to pull back