Skip to main content

Volumes

Manage code and data volumes, and read and write their data files.

Access it as client.volumes on a Strongly client, or the same path on AsyncStrongly with await. All methods exist on both with identical signatures.

Quick start​

from strongly import Strongly

client = Strongly()

# List (auto-paginates as you iterate)  # filters: scope, project_id, sort
for volume in client.volumes.list():
    print(volume.id)

Methods​

Core​

list​

list(*, scope: str | None = None, project_id: str | None = None, sort: str | None = None, limit: int | None = None) -> SyncPaginator[Volume]

List the volumes you can use, newest first.

Parameters

  • scope (str | None, optional): Only volumes with this stored scope: "local" (projects' own volumes) or "shared".
  • project_id (str | None, optional): Only the volumes of this project.
  • sort (str | None, optional): The order, as comma-separated wire field names, each prefixed with - for descending (for example "name"). The API's default is "-createdAt".
  • limit (int | None, optional): The most volumes to return; None returns every one.

Returns

  • SyncPaginator[Volume]: The volumes, fetched a page at a time.

create​

create(*, name: str, filesystem_type: str | None = None, repo_url: str | None = None, branch: str | None = None, ssh_key_id: str | None = None, scope: str | None = None, project_id: str | None = None, description: str | None = None) -> CreatedVolume

Create a volume in your organization.

A shared volume (scope="shared") is the usual kind to create: it holds data only, so pass no code arguments (code is refused for it). A project's own volume, with its code, is created with its project.

Parameters

  • name (str): The volume's name, unique among your volumes of the same scope. It is lowercased, and characters other than letters, digits, ., _ and - become -.
  • filesystem_type (str | None, optional): For a project's (local) volume only: where its code half lives, "strongly" (a platform-managed repository) or "github".
  • repo_url (str | None, optional): The GitHub repository's SSH URL (required for "github").
  • branch (str | None, optional): The code half's branch. The API's default is "main".
  • ssh_key_id (str | None, optional): For "github": one of your GitHub SSH keys (Users.github_ssh_keys).
  • scope (str | None, optional): "shared" or "local". The API's default is "local".
  • project_id (str | None, optional): The project a local volume belongs to.
  • description (str | None, optional): What the volume holds.

Returns

  • CreatedVolume: The new volume's id, normalized name and scope.

Raises

  • ConflictError: You already have a volume of this scope with this name (error_code duplicate).
  • PermissionDeniedError: You have no organization, or a governance policy blocks the volume.

retrieve​

retrieve(volume_id: str) -> Volume

Retrieve a volume you can use.

Parameters

  • volume_id (str): The volume's id.

Returns

  • Volume: The volume.

Raises

  • NotFoundError: There is no such volume, or you cannot use it.

delete​

delete(volume_id: str) -> None

Delete a volume, its code and its data (its owner, or an admin).

The volume is also detached from every workspace and job.

Parameters

  • volume_id (str): The volume's id.

Raises

  • NotFoundError: There is no such volume.
  • PermissionDeniedError: You may not delete it.

Other​

code_diff​

code_diff(volume_id: str, *, head: str, base: str | None = None, path: str | None = None) -> dict[str, Any]

Show the changes between two commits or branches of a volume's code half.

Parameters

  • volume_id (str): The volume's ID.
  • head (str): The commit or branch to show.
  • base (str | None, optional): What to compare it with; head's parent when omitted.
  • path (str | None, optional): Only this file or folder.

code_history​

code_history(volume_id: str, *, ref: str, path: str | None = None, count: int | None = None) -> dict[str, Any]

List the commits of a branch of a volume's code half, newest first.

Parameters

  • volume_id (str): The volume's ID.
  • ref (str): The branch or commit.
  • path (str | None, optional): Only commits that touched this file or folder.
  • count (int | None, optional): How many commits; the platform returns 50 when omitted.

create_code_branch​

create_code_branch(volume_id: str, name: str, *, from_ref: str | None = None) -> dict[str, Any]

Create a branch in a volume's code half.

Parameters

  • volume_id (str): The volume's ID.
  • name (str): The new branch's name.
  • from_ref (str | None, optional): The branch or commit to start it from; the default branch when omitted.

delete_code_file​

delete_code_file(volume_id: str, path: str, *, branch: str | None = None, message: str | None = None) -> dict[str, Any]

Delete a file of a volume's code half, as a commit.

Parameters

  • volume_id (str): The volume's ID.
  • path (str): The file's path.
  • branch (str | None, optional): The branch to commit to; the default branch when omitted.
  • message (str | None, optional): The commit message.

delete_data_file​

delete_data_file(volume_id: str, path: str, *, message: str | None = None) -> DataFileWrite

Delete one data file; the deletion is a new version in its history.

Parameters

  • volume_id (str): The volume's id.
  • path (str): The file's path within the data half.
  • message (str | None, optional): A note for the file's history.

Returns

  • DataFileWrite: The version that deleted the file.

deletion_impact​

deletion_impact(volume_id: str) -> dict[str, Any]

Before deleting a volume: whether it can be, and what still mounts or uses it.

Parameters

  • volume_id (str): The volume's ID.

download_data​

download_data(volume_id: str, dest: str) -> int

Copy every file of a volume's data half, at its latest version, into a directory.

Parameters

  • volume_id (str): The volume's id.
  • dest (str): The local directory; each file is written to dest/<path> (directories are created as needed).

Returns

  • int: How many files were written.

list_available_shared​

list_available_shared(*, project_id: str | None = None, search: str | None = None, sort: str | None = None, limit: int | None = None) -> SyncPaginator[AvailableSharedVolume]

List the shared volumes you may mount in a workspace or job (shared_volume_ids).

Parameters

  • project_id (str | None, optional): The project the workspace or job is in; its own volume is left out.
  • search (str | None, optional): Only volumes whose name contains this.
  • sort (str | None, optional): name (the default), createdAt or updatedAt; prefix - for descending.
  • limit (int | None, optional): The most volumes to return; all of them when omitted.

list_code_branches​

list_code_branches(volume_id: str) -> dict[str, Any]

List the branches of a volume's code half.

Parameters

  • volume_id (str): The volume's ID.

list_code_files​

list_code_files(volume_id: str, *, ref: str | None = None, path: str | None = None) -> dict[str, Any]

List one folder of a volume's code half.

Parameters

  • volume_id (str): The volume's ID.
  • ref (str | None, optional): A branch or commit; the default branch when omitted.
  • path (str | None, optional): The folder; the top when omitted.

list_data_file_versions​

list_data_file_versions(volume_id: str, path: str) -> list[DataFileVersion]

List one data file's versions, newest first.

Parameters

  • volume_id (str): The volume's id.
  • path (str): The file's path within the data half.

Returns

  • list[DataFileVersion]: The file's versions (empty for a path that was never written).

list_data_files​

list_data_files(volume_id: str) -> list[DataFile]

List the files in a volume's data half, each at its current version.

Parameters

  • volume_id (str): The volume's id.

Returns

  • list[DataFile]: The files, sorted by path; deleted files are not listed.

read_code_file​

read_code_file(volume_id: str, path: str, *, ref: str) -> dict[str, Any]

Read a file of a volume's code half at a branch or commit.

Parameters

  • volume_id (str): The volume's ID.
  • path (str): The file's path.
  • ref (str): The branch or commit.

read_data_file​

read_data_file(volume_id: str, path: str, *, version: int | None = None) -> bytes

Return one data file's content.

Parameters

  • volume_id (str): The volume's id.
  • path (str): The file's path within the data half.
  • version (int | None, optional): The file version to read. The API's default is the latest.

Returns

  • bytes: The file's bytes.

read_data_text​

read_data_text(volume_id: str, path: str, *, version: int | None = None, encoding: str = "utf-8") -> str

Return one data file's content as text.

Parameters

  • volume_id (str): The volume's id.
  • path (str): The file's path within the data half.
  • version (int | None, optional): The file version to read. The API's default is the latest.
  • encoding (str, optional): How the bytes are decoded ("utf-8" unless given).

Returns

  • str: The decoded text.

upload_data​

upload_data(volume_id: str, src: str, *, message: str | None = None) -> int

Write every file under a local directory into a volume's data half.

Each file is written to its path relative to src.

Parameters

  • volume_id (str): The volume's id.
  • src (str): The local directory.
  • message (str | None, optional): A note for each file's history.

Returns

  • int: How many files were written.

Raises

  • NotADirectoryError: src is not a directory.

write_code_file​

write_code_file(volume_id: str, path: str, *, content: str, branch: str | None = None, message: str | None = None) -> dict[str, Any]

Write a whole file of a volume's code half, as a commit.

Parameters

  • volume_id (str): The volume's ID.
  • path (str): The file's path.
  • content (str): The file's whole content (text).
  • branch (str | None, optional): The branch to commit to; the default branch when omitted.
  • message (str | None, optional): The commit message.

write_data_file​

write_data_file(volume_id: str, path: str, data: str | bytes, *, message: str | None = None) -> DataFileWrite

Write one data file, committing a new version of it.

Writing the content the file already has commits nothing.

Parameters

  • volume_id (str): The volume's id.
  • path (str): The file's path within the data half.
  • data (str | bytes): The content: text, or bytes for a binary file.
  • message (str | None, optional): A note for the file's history.

Returns

  • DataFileWrite: The file's version after the write, and whether it changed.

Raises

  • TypeError: data is neither str nor bytes.
  • NotFoundError: There is no such volume, or you may not write to it.