File | Mixtrain Docs

from mixtrain import File

Overview

Use File for artifacts users need to access or download, such as reports, logs, model weights, and archives. For visual or audio media that should render inline in Mixtrain, use Image, Video, or Audio.

File("path/to/file") references a file in your Mixtrain workspace. File("https://...") references a public remote file. Use File.from_file("local.bin") for local files.

File, Image, Video, and Audio can download from Workspace path or URL (https://, gs://, s3://).

Constructor

File(
    url: str,
    *,
    content_type: str | None = None,
    filename: str | None = None,
)

Parameter	Type	Description
`url`	`str`	Workspace path or URL (https://, gs://, s3://)
`content_type`	`str \| None`	MIME type
`filename`	`str \| None`	Original filename

file = File(
    "gs://bucket/data.bin",
    content_type="application/octet-stream",
    filename="data.bin"
)

Properties

Property	Type	Description
`url`	`str`	Workspace path or remote URL
`content_type`	`str \| None`	MIME type
`filename`	`str \| None`	Original filename

Local Files

from_file()

Create a local file reference without uploading.

File.from_file(
    path: str,
    *,
    content_type: str | None = None,
    filename: str | None = None,
) -> File

file = File.from_file("model.bin")
saved = file.save("outputs/model.bin")

Methods

to_file()

Download the file to a local path. Results are cached — calling to_file() multiple times returns the same local path.

file.to_file(path: str | None = None) -> str

Parameter	Type	Description
`path`	`str \| None`	Optional save path. Auto-generates a temp file if not provided.

Returns: str — path to the downloaded file

# Auto-generated temp path
local_path = file.to_file()

# Specific path
file.to_file("/tmp/myfile.bin")

# Subsequent calls use cached path
same_path = file.to_file()  # No download, returns cached path

save()

Persist a local or external file into workspace storage and return a saved File.

file.save(
    path: str,
    *,
    timeout: float = 300.0,
    progress: bool = False,
) -> File

Parameter	Type	Description
`path`	`str`	Remote path in workspace storage
`timeout`	`float`	Timeout in seconds for the upload
`progress`	`bool`	Show a progress bar during upload

# Local file -> workspace
file = File.from_file("model.bin")
saved = file.save("outputs/model.bin")

# Public URL -> workspace
external = File("https://example.com/model.bin")
saved = external.save("outputs/model.bin")

delete()

Delete a workspace file.

File("outputs/model.bin").delete() -> bool

delete() works for workspace files.

Supported URL Schemes

The to_file() method handles multiple URL schemes:

Relative paths — Files in workspace storage (e.g., "outputs/model.bin")
gs://bucket/path — Google Cloud Storage (requires workspace secrets)
s3://bucket/path — S3/S3-compatible storage (requires workspace secrets)
https://... or http://... — Public URLs (no auth required)

Workspace Operations

list_workspace()

File.list_workspace(prefix: str = "", limit: int = 100) -> list[FileInfo]

List files in workspace storage.

iter_workspace()

File.iter_workspace(prefix: str = "", limit: int = 100) -> Iterator[FileInfo]

Iterate over all files in workspace storage with automatic pagination.

upload_dir()

Upload a local directory into workspace storage.

File.upload_dir(
    local_dir: str,
    remote_prefix: str = "",
    pattern: str = "**/*",
    *,
    timeout: float = 300.0,
    max_concurrency: int = 5,
    include_ignored: bool = False,
    progress: bool = False,
) -> UploadDirResult

Parameter	Type	Description
`local_dir`	`str`	Path to local directory
`remote_prefix`	`str`	Remote path prefix in workspace
`pattern`	`str`	Glob pattern for file matching
`timeout`	`float`	Timeout in seconds for the upload
`max_concurrency`	`int`	Maximum number of concurrent uploads
`include_ignored`	`bool`	Include files matched by `.mixtrainignore`
`progress`	`bool`	Show a progress bar during upload

Subtypes

Type	Methods	Use case
Image	`to_pil()`, `to_numpy()`	Image inputs and outputs
Video	`to_cv2()`, `to_frames()`	Video inputs and outputs
Audio	`to_numpy()`	Audio inputs and outputs

Storing and Retrieving Files

Use from_file() and save() for a single local file:

from mixtrain import File

saved = File.from_file("model.bin").save("outputs/model.bin")
local_path = saved.to_file()
saved.delete()

Use workspace class methods for collection operations:

from mixtrain import File

for info in File.list_workspace(prefix="outputs/"):
    print(info.path, info.size)

File.upload_dir("checkpoints/", remote_prefix="outputs/checkpoints/")

On this page