oxen.remote_repo

get_repo

def get_repo(name: str, host: str = "hub.oxen.ai", scheme: str = "https")

Get a RemoteRepo object for the specified name. For example ‘ox/CatDogBBox’. Arguments:

name - str Name of the repository in the format ‘namespace/repo_name’.
host - str The host to connect to. Defaults to ‘hub.oxen.ai’

Returns: RemoteRepo

create_repo

def create_repo(name: str,
                description="",
                is_public: bool = True,
                host: str = "hub.oxen.ai",
                scheme: str = "https",
                files: List[Tuple[str, str]] = [])

Create a new repository on the remote server. Arguments:

name - str Name of the repository in the format ‘namespace/repo_name’.
description - str Description of the repository. Only applicable to OxenHub.
is_public - bool Whether the repository is public or private. Only applicable to OxenHub.
host - str The host to connect to. Defaults to ‘hub.oxen.ai’
scheme - str The scheme to use for the remote url. Default: ‘https’
files - List[Tuple[str, str]] A list of tuples containing the path to the file and the contents of the file that you would like to seed the repository with.

Returns: RemoteRepo

RemoteRepo Objects

class RemoteRepo()

The RemoteRepo class allows you to interact with an Oxen repository without downloading the data locally.

Examples

Add & Commit Files

Adding and committing a file to a remote workspace.

from oxen import RemoteRepo

repo = RemoteRepo("ox/CatDogBBox")
repo.add("/path/to/image.png")
status = repo.status()
print(status.added_files())
repo.commit("Adding my image to the remote workspace.")

Downloading Specific Files

Grab a specific file revision and load it into pandas.

from oxen import RemoteRepo
import pandas as pd

# Connect to the remote repo
repo = RemoteRepo("ox/CatDogBBox")
# Specify the version of the file you want to download
branch = repo.get_branch("my-pets")
# Download takes a file or directory a commit id
repo.download("annotations", revision=branch.commit_id)
# Once you have the data locally, use whatever library you want to explore the data
df = pd.read_csv("annotations/train.csv")
print(df.head())

init

def __init__(repo_id: str,
             host: str = "hub.oxen.ai",
             revision: str = "main",
             scheme: str = "https")

Create a new RemoteRepo object to interact with. Arguments:

repo_id - str Name of the repository in the format ‘namespace/repo_name’. For example ‘ox/chatbot’
host - str The host to connect to. Defaults to ‘hub.oxen.ai’
revision - str The branch name or commit id to checkout. Defaults to ‘main’
scheme - str The scheme to use for the remote url. Default: ‘https’

create

def create(empty: bool = False, is_public: bool = False)

Will create the repo on the remote server. Arguments:

empty - bool Whether to create an empty repo or not. Default: False
is_public - bool Whether the repository is public or private. Default: False

exists

def exists() -> bool

Checks if this remote repo exists on the server.

delete

def delete()

Delete this remote repo from the server.

checkout

def checkout(revision: str, create=False)

Switches the remote repo to the specified revision. Arguments:

revision - str The name of the branch or commit id to checkout.
create - bool Whether to create a new branch if it doesn’t exist. Default: False

ls

def ls(directory: Optional[str] = None,
       page_num: int = 1,
       page_size: int = 100)

Lists the contents of a directory in the remote repo. Arguments:

directory - str The directory to list. If None, will list the root directory.
page_num - int The page number to return. Default: 1
page_size - int The number of items to return per page. Default: 100

scan

def scan(directory: Optional[str] = None, page_size: int = 100)

Generator over the contents of a directory in the remote repo Arguments:

directory - str The directory to list. If None, will list the root directory
page_size - int The number of items to return per page. Default: 100

download

def download(src: str,
             dst: Optional[str] = None,
             revision: Optional[str] = None)

Download a file or directory from the remote repo. Arguments:

src - str The path to the remote file
dst - str | None The path to the local file. If None, will download to the same path as src
revision - str | None The branch or commit id to download. Defaults to self.revision

download_zip

def download_zip(src: str,
                 dst: Optional[str] = None,
                 revision: Optional[str] = None)

Download the contents of a directory as a zip file Arguments:

src - str The path to the remote dir to download files from. This must be a directory
dst - str | None The path to the local file. If None, will download to {src}.zip
revision - str | None The branch or commit id to download. Defaults to self.revision

get_file

def get_file(src: str, revision: Optional[str] = None)

Get a file from the remote repo. Arguments:

src - str The path to the remote file
revision - str | None The branch or commit id to download. Defaults to self.revision

create_workspace

def create_workspace(branch: Optional[str] = None,
                     workspace_name: Optional[str] = None)

Create a new workspace in the remote repo. If the workspace already exists, it will just be returned. Arguments:

branch - str | None The branch to create the workspace on. Defaults to self.revision
workspace_name - str | None The named workspace to use when adding the file. If None, will create a temporary workspace

Returns: Workspace

delete_workspace

def delete_workspace()

Delete the current workspace in the remote repo.

add

def add(src: str,
        dst: Optional[str] = "",
        branch: Optional[str] = None,
        workspace_name: Optional[str] = None)

Stage a file to a workspace in the remote repo. Arguments:

src - str The path to the local file to upload
dst - str | None The directory to upload the file to. If None, will upload to the root directory.
branch - str | None The branch to upload the file to. Defaults to self.revision
workspace_name - str | None The named workspace to use when adding the file. If None, will create a temporary workspace

Returns: Workspace

status

def status()

Get the status of the workspace.

commit

def commit(message: str, branch: Optional[str] = None)

Commit the workspace to the remote repo. Arguments:

message - str The message to commit with
branch - str | None The branch to commit to. Defaults to the branch the workspace was created on.

delete_file

def delete_file(path: str,
                commit_message: Optional[str] = None,
                branch: Optional[str] = None)

Delete from the remote repo. This can be used with a committed file or dir Arguments:

path - str The path to the remote file to remove
commit_message - str | None The message to commit with. Defaults to “Removed ''”
branch - str | None The branch to remove the file from. Defaults to self.revision

upload

def upload(src: str,
           commit_message: str,
           file_name: Optional[str] = None,
           dst_dir: Optional[str] = "",
           branch: Optional[str] = None)

Upload a file to the remote repo. Arguments:

src - str The path to the local file to upload
commit_message - str The message to commit with. Defaults to “Uploaded ''”
file_name - str | None The name of the file to upload. If None, will use the name of the file in src
dst_dir - str | None The directory to upload the file to. If None, will upload to the root directory.
branch - str | None The branch to upload the file to. Defaults to self.revision

metadata

def metadata(path: str)

Get the metadata for a file in the remote repo.

file_exists

def file_exists(path: str, revision: Optional[str] = None)

Check if a file exists in the remote repo. Arguments:

path - str The path to the file to check
revision - str The revision to check against, defaults to self.revision

file_has_changes

def file_has_changes(local_path: str,
                     remote_path: str = None,
                     revision: str = None)

Check if a local file has changed compared to a remote revision Arguments:

local_path - str The local path to the file to check
remote_path - str The remote path to the file to check, will default to local_path if not provided
revision - str The revision to check against, defaults to self.revision

log

def log(revision: Optional[str] = None,
        path: Optional[str] = None,
        page_num: int = 1,
        page_size: int = 10)

Get the commit history for a remote repo Arguments:

revision - str | None The revision to get the commit history for. Defaults to self.revision
path - str | None The path to the file to get the commit history for. Defaults to None, which will return the commit history for the entire repo
page_num - int The page number to return. Defaults to 1
page_size - int The number of items to return per page. Defaults to 10

branch_exists

def branch_exists(name: str) -> bool

Check if a branch exists in the remote repo. Arguments:

name - str The name of the branch to check

branch

def branch()

Get the current branch for a remote repo

branches

def branches()

List all branches for a remote repo

list_workspaces

def list_workspaces()

List all workspaces for a remote repo

get_branch

def get_branch(branch: str)

Return a branch by name on this repo, if exists Arguments:

branch - str The name of the branch to return

create_branch

def create_branch(branch: str)

Return a branch by name on this repo, creating it from the currently checked out branch if it doesn’t exist Arguments:

branch - str The name to assign to the created branch

delete_branch

def delete_branch(branch: str)

Delete a branch from the remote repo. Arguments:

branch - str The name of the branch to delete

create_checkout_branch

def create_checkout_branch(branch: str)

Create a new branch from the currently checked out branch, and switch to it Arguments:

branch - str The name to assign to the created branch

merge

def merge(base_branch: str, head_branch: str)

Merge the head branch into the base branch on the remote repo. Arguments:

base_branch - str The base branch to merge into
head_branch - str The head branch to merge

mergeable

def mergeable(base_branch: str, head_branch: str)

Check if a branch is mergeable into another branch. Arguments:

base_branch - str The target branch to merge into
head_branch - str The source branch to merge from

diff

def diff(base: str | PyCommit, head: str | PyCommit, path: str)

Get the diff between two refs on the remote repo. Arguments:

base - str The base ref to diff (branch or commit)
head - str The head ref to diff (branch or commit)
path - str The path to the file to diff

namespace

@property
def namespace() -> str

The namespace for the repo.

name

@property
def name() -> str

The name of the repo.

identifier

@property
def identifier()

The namespace/name of the repo.

url

@property
def url() -> str

The remote url for the repo.

revision

@property
def revision() -> str

The branch or commit id for the repo

repo_uuid

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

The identifier the server addresses this repo by, or None from a server that reports no identity. Raises if the repo does not exist yet.

storage_backend

@property
def storage_backend() -> str

Where the server keeps this repo’s version files, “local” or “s3”. Raises if the repo does not exist yet.

​oxen.remote_repo

​get_repo

​create_repo

​RemoteRepo Objects

​Examples

​Add & Commit Files

​Downloading Specific Files

​__init__

​create

​exists

​delete

​checkout

​ls

​scan

​download

​download_zip

​get_file

​create_workspace

​delete_workspace

​add

​status

​commit

​delete_file

​upload

​metadata

​file_exists

​file_has_changes

​log

​branch_exists

​branch

​branches

​list_workspaces

​get_branch

​create_branch

​delete_branch

​create_checkout_branch

​merge

​mergeable

​diff

​namespace

​name

​identifier

​url

​revision

​repo_uuid

​storage_backend