oxen.workspace

Workspace Objects

class Workspace()

The Workspace class allows you to interact with an Oxen workspace without downloading the data locally. Workspaces can be created off a branch and is tied to the commit id of the branch at the time of creation. You can commit a Workspace back to the same branch if the branch has not advanced, otherwise you will have to commit to a new branch and merge.

Examples

Adding Files to a Workspace

Create a workspace from a branch.

from oxen import RemoteRepo
from oxen import Workspace

# Connect to the remote repo
repo = RemoteRepo("ox/CatDogBBox")

# Create the workspace
workspace = Workspace(repo, "my-branch")

# Add a file to the workspace
failed_to_upload = workspace.add("my-image.png", raise_on_failure=False)
assert len(failed_to_upload) == 0

# Or raise an exception if any files fail to upload
workspace.add("my-image-final-final.png")

# Print the status of the workspace
status = workspace.status()
print(status.added_files())

# Commit the workspace
workspace.commit("Adding my images to the workspace.")

init

def __init__(repo: "RemoteRepo",
             branch: str,
             workspace_id: Optional[str] = None,
             workspace_name: Optional[str] = None,
             path: Optional[str] = None) -> None

Create a new Workspace. Arguments:

repo - PyRemoteRepo The remote repo to create the workspace from.
branch - str The branch name to create the workspace from. The workspace will be tied to the commit id of the branch at the time of creation.
workspace_id - Optional[str] The workspace id to create the workspace from. If left empty, will create a unique workspace id.
workspace_name - Optional[str] The name of the workspace. If left empty, the workspace will have no name.
path - Optional[str] The path to the workspace. If left empty, the workspace will be created in the root of the remote repo.

id

@property
def id()

Get the id of the workspace.

name

@property
def name()

Get the name of the workspace.

branch

@property
def branch()

Get the branch that the workspace is tied to.

commit_id

@property
def commit_id() -> str

Get the commit id of the workspace.

created_at

@property
def created_at() -> Optional[str]

Get the RFC 3339 time the workspace was created, or None for a workspace created before the server recorded it.

repo

@property
def repo() -> "RemoteRepo"

Get the remote repo that the workspace is tied to.

status

def status(path: str = "")

Get the status of the workspace. Arguments:

path - str The path to check the status of.

add

def add(src: str | Iterable[str] | Path | Iterable[Path],
        dst: str = "",
        raise_on_failure: bool = True) -> list[PyErrorFileInfo]

Add files to the workspace. Accepts a single file, a single directory, or multiple of either. Recursively walks directories to add all accessible files. Preserves relative path to destination when adding multiple files from a directory. Arguments:

src - str | Iterable[str] | Path | Iterable[Path] The path(s) to the local file(s) to be staged.
dst - str The path in the remote repo where the file(s) will be added.
raise_on_failure - bool Whether to raise an exception if any files fail to upload. By default, raises an exception. Set to False to return a list of failed file paths instead.

Returns: A list of PyErrorFileInfo for files that failed to upload. An empty list means all files were uploaded successfully. Each entry has .hash, .path, and .error attributes. Raises: ValueError if the provided input is not a valid filepath, an invalid directory, or it points to an empty directory, or is a collection of empty directories.

add_files

def add_files(base_dir: str | Path,
              paths: Iterable[str] | Iterable[Path],
              raise_on_failure: bool = True) -> list[PyErrorFileInfo]

A workspace add that preserves relative paths of files that share a common base. Unlike add, which places files into a flat destination directory, this method uses each file’s path relative to the supplied base directory as its staging path on the server. The base_dir serves as a stand-in for the root of the remote repository. The key use of add_files is to import a large file tree into an existing repository. For example, a file at repo/data/images/cat.jpg will be staged as data/images/cat.jpg. Arguments:

base_dir - str | Path The base directory: all added files share this as an ancestor.
paths - Iterable[str] | Iterable[Path] The file paths to add. Can be absolute or relative to the base directory. Each path must point to an existing file.
raise_on_failure - bool Whether to raise an exception if any files fail to upload. By default, raises an exception. Set to False to return a list of failed file paths instead.

PyOxenError - If no valid file paths are provided.

add_bytes

def add_bytes(src: str, buf: bytes, dst: str = "") -> None

Adds from a memory buffer to the workspace Arguments:

src - str The relative path to be used as the entry’s name in the workspace
buf - bytes The memory buffer to be read from for this entry
dst - str The path in the remote repo where the file will be added

rm

def rm(path: str) -> None

Unstage a file that was previously added to the workspace. Despite the name, this does not stage a deletion of a file in the base repo. Prefer unstage, which does the same thing through the non-deprecated endpoint. Arguments:

path - str The path to the staged file to unstage

unstage

def unstage(path: str) -> None

Unstage a file that was previously added to the workspace, without touching the base repo. Arguments:

path - str The path to the staged file to unstage

commit

def commit(message: str, branch_name: Optional[str] = None) -> PyCommit

Commit the workspace to a branch Arguments:

message - str The message to commit with
branch_name - Optional[str] The name of the branch to commit to. If left empty, will commit to the branch the workspace was created from.

delete

def delete() -> None

Delete the workspace

Get Started

Developer Tools

Workspace

oxen.workspace

Workspace Objects

Examples

Adding Files to a Workspace

init

id

name

branch

commit_id

created_at

repo

status

add

add_files

add_bytes

rm

unstage

commit

delete

​oxen.workspace

​Workspace Objects

​Examples

​Adding Files to a Workspace

​__init__

​id

​name

​branch

​commit_id

​created_at

​repo

​status

​add

​add_files

​add_bytes

​rm

​unstage

​commit

​delete

oxen.workspace

Workspace Objects

Examples

Adding Files to a Workspace

init

id

name

branch

commit_id

created_at

repo

status

add

add_files

add_bytes

rm

unstage

commit

delete