> ## 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. # 🐍 Python > Learn how to get started with the oxenai python package. ## Install ``` pip install oxenai ``` ## Clone Repository Clone a repository from the [Oxen Hub](https://oxen.ai) or a your own [oxen-server](/getting-started/oxen-server). Detailed documentation for the [clone](/python-api/clone) method can be found in the [API Documentation](/python-api). ```python theme={null} import oxen oxen.clone("ox/SpanishToEnglish") ``` This will create a directory called `SpanishToEnglish` in your current working directory and download the latest version of the repository. ### Private Repositories Not all repositories are public. If you are trying to clone a private repository, you will need to [configure auth](/python-api/auth) before you can clone. If you try to clone a repository you do not have access to, and you have not configured auth, you will see the following error: ```bash theme={null} ValueError: oxen authentication token not found, obtain one from your administrator and configure with: oxen config --auth ``` ### Obtain Auth Token Before you can push to a remote repository, you must have permissions to do so. Permissions are handled through an `auth_token` that is passed in with the request. You can obtain an `auth_token` by creating an account on [Oxen.ai](https://oxen.ai) and going to your profile. Oxen.ai authentication key ### Set Auth Token To set your auth token, you can either set it through the command line interface or directly in python. ```python Python theme={null} from oxen.auth import config_auth config_auth("YOUR_AUTH_TOKEN") ``` ```bash CLI theme={null} oxen config --auth 'hub.oxen.ai' YOUR_AUTH_TOKEN ``` This will write the auth token to a file in `~/.config/oxen/auth_config.toml` for future use. If you set up your own [oxen-server](/getting-started/oxen-server) you can generate custom auth tokens there. ## Setup User In order for Oxen to know who is committing and where to sync to by default, you must call [config\_user](/python-api/user) and pass in the name and email you would like to use in your commit messages. ```python theme={null} from oxen.user import config_user config_user("YOUR NAME", "YOUR EMAIL") ``` This will save a file in `~/.config/oxen/user_config.toml` that contains your user configuration. ## Initialize Local Repository If you are creating a new repository from scratch, you can initialize it with the [init](/python-api/init) method. We will be using a fictional repository called `CatsVsDogs` for this example. ```python theme={null} import oxen import os # Create an empty directory named CatsVsDogs directory = "CatsVsDogs" os.makedirs(directory) # Initialize the Oxen Repository repo = oxen.init(directory) ``` This will create a `.oxen` directory to keep track of changes as you make them. ## Load Existing Repository Use the [repo](/python-api/repo) class to interact with a repository that has already been initialized. ```python theme={null} from oxen import Repo # Load the repository from the CatsVsDogs directory repo = Repo("CatsVsDogs") # Check the status of the repository print(repo.status()) ``` ## Add Files Now let's create a README.md file and [add](/python-api/repo#add) it to the local staging area. This will not commit the changes to the repository, but it will prepare them to be committed. ```python theme={null} # ... continue from previous example # Create a README.md file filename = os.path.join(repo.path, "README.md") with open(filename, "w") as f: f.write("# Cats vs. Dogs\n\nWhich is it? We will be using machine learning to find out!") # Add the README.md file to the staging area repo.add(filename) # Confirm that the file has been staged print(repo.status()) ``` ## Commit Changes Now that we have added the README.md file to the staging area, we can commit the changes to the repository. ```python theme={null} # ... continue from previous example # Commit the changes to the repository repo.commit("Adding README.md") ``` ## Diff Changes Oxen.ai has powerful diff tools built in that allow you to see the changes to files between commits, branches, and more. ```python theme={null} result = oxen.diff("README.md") print(result.get()) ``` To learn more about diffs checkout the [diff](/concepts/diffs) documentation or the [Python API Documentation](/python-api/diff/diff). ## Push To Remote It's one thing to version your data locally, but where the real power comes in is when you can share your data with others. Oxen repositories can be pushed to a remote repository hosted on [Oxen Hub](https://oxen.ai) or your own [oxen-server](/getting-started/oxen-server). There are a few steps when pushing to a remote for the first time. 1. [Create Remote](/python-api/remote_repo#create_repo) 2. [Point Local to Remote](/python-api/repo#set_remote) 3. [Push Changes](/python-api/repo#push) ### Create Remote Before you can push to a remote repository, you must create it. This can be done with the [create\_repo](/python-api/remote_repo#create_repo) method. ```python theme={null} from oxen.remote_repo import create_repo # Create a remote repository remote_name = "MyNamespace/CatsVsDogs" remote_repo = create_repo(remote_name) ``` ### Point Local to Remote Now that we have created the remote repository, we need to point our local repository to sync to it. This can be done with the [set\_remote](/python-api/repo#set_remote) method. ```python theme={null} from oxen import Repo # Load the local repository repo = Repo("CatsVsDogs") # Point the local repository to the remote repo.set_remote("origin", remote_repo.url()) ``` ### Push Changes Now that we have created the remote repository and pointed our local repository to it, we can [push](/python-api/repo#push) our changes to the remote repository. ```python theme={null} # Push the changes to the remote repository repo.push() ``` ### Full Push Example The end to end workflow from scratch looks like this: ```python theme={null} from oxen import Repo from oxen.remote_repo import create_repo from oxen.auth import config_auth # 0. Load the local repository repo = Repo("CatsVsDogs") # 1. Configure Authentication config_auth("YOUR_AUTH_TOKEN") # 2. Create a remote repository remote_name = "MyNamespace/CatsVsDogs" repo = create_repo(remote_name) # 3. Point the local repository to the remote repo.set_remote("origin", repo.url) # 4. Push the changes to the remote repository repo.push() ``` ## Pull Data Now that we have pushed our changes to the remote repository, we can [pull](/python-api/repo#pull) them down to another machine. ```python theme={null} import oxen import os repo_path = "CatsVsDogs" if os.path.exists(repo_path): # if you already have a local copy of the repository, you can load it repo = oxen.Repo(repo_path) else: # if you don't have a local copy of the repository, you can clone it repo = oxen.clone("ox/CatsVsDogs") # Pull the latest changes from the remote repository repo.pull() ``` ## OxenFS (fsspec Integration) OxenFS allows you to conveniently read and write files through a Pythonic file interface. ```python theme={null} import oxen fs = oxen.OxenFS("openai", "gsm8k") with fs.open("gsm8k_test.parquet") as f: content = f.read() ``` It also integrates directly with third-party libraries like Pandas like this: ```python theme={null} df = pd.read_parquet("oxen://openai:gsm8k@main/gsm8k_test.parquet") ``` See the full documentation for [OxenFS](/python-api/oxen_fs). ## Branching Branching is a powerful feature of Oxen that allows you to create a named version of your data without affecting the original version. This is useful when you want to experiment with your changes affecting the original version. ### Create Branch To create a new branch, use the [Repo.checkout](/python-api/repo#checkout) method. ```python theme={null} from oxen import Repo repo = Repo("CatsVsDogs") repo.checkout("add-dogs", create=True) ``` This both creates the branch and checks it out (the command line equivalent of `oxen checkout -b add-dogs`). ### List Branches To list all of the branches in a repository, use the [Repo.branches](/python-api/repo#branches) method. ```python theme={null} from oxen import Repo repo = Repo("CatsVsDogs") print(repo.branches()) ``` Output: ``` [Branch(name=add-dogs, commit_id=3168391af834ac18), Branch(name=main, commit_id=3168391af834ac18)] ``` As you can see there should be a `main` branch and a `add-dogs` branch, each tied to a commit id. The commit ids will be the same at this point, because the branches have not diverged in content. ## Next Steps Now that you have learned the basics of Oxen, the rest of the workflow is very similar to git. You can dive deeper into the [API Documentation](/python-api) to learn more about the methods available to you.