# Project Setup

This page walks through setting up a Python project and virtual environment using [uv](https://docs.astral.sh/uv/).
At any point, run `uv help <subcommand>` (e.g. `uv help init`) or consult the [uv CLI documentation](https://docs.astral.sh/uv/reference/cli/) for more information.

## Setting up a project

Navigate to the folder where you'd like to initialize the project and run the following command **from within that folder**.

```bash
uv init --python /bin/python3.12
```

This command will

- initialize a git repository in the folder if one doesn't already exist,
- create a `pyproject.toml` file storing information about the project and its dependencies,
- create a minimal `main.py` file, and
- create a blank `README.md`.

The `--python` flag specifies a particular version of Python.
Feel free to change this to another version or omit it entirely to use the default system Python.

Then, to create and activate the virtual environment, run

```bash
uv sync  # creates the venv -- only needs to be run the first time you set up the project
source .venv/bin/activate
```

## Installing dependencies

To add dependencies (i.e. install packages), use `uv add`:

```bash
uv add oi-tools polars  # ... and any other packages you may want
```

This will install the packages into your virtual environment _and_ record them in `pyproject.toml`.
No more manually managing a `requirements.txt` file!

## Adding other users to the project

For another person to use the virtual environment, have them go to the project folder and run `source .venv/bin/activate`.
They will then have access to exactly the same Python environment (same version of Python, same packages, same package versions, etc.).

For projects you use frequently, consider making shell aliases to automate these steps:

```bash
# in ~/.bashrc
alias venv="source .venv/bin/activate"
alias proj="cd /path/to/project && venv"
```

## Updating dependencies

```bash
uv sync --upgrade-package oi-tools  # upgrade a particular package
uv sync --upgrade  # upgrade all packages to their newest versions
```

Note that upgrading may break things. Make sure you have a clean git working tree so that you can revert `uv.lock` if needed.