Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.oxen.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
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

​
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
Returns: Workspace

​
status

def status()
Get the status of the workspace.

​
commit

def commit(message: str)
Commit the workspace to the remote repo.

​
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
  • 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: 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()
Get the commit history for a remote repo

​
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

​
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

​
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