291 lines
9.4 KiB
Markdown
291 lines
9.4 KiB
Markdown
# Instrument Control for QPS Optics Lab
|
|
|
|
|
|
### General rules
|
|
Please use initials and kebab case when opening a branch. For example if your name is John Doe, name your branch jd-branch-name.
|
|
|
|
# Python Environments with `uv` — Lab Repo Guide (Written by Claude AI)
|
|
|
|
---
|
|
|
|
## Installing `uv`
|
|
|
|
`uv` is a modern Python package and environment manager — much faster than `pip` and handles everything in one tool (environments, dependencies, Python versions). Install it with:
|
|
|
|
**macOS / Linux:**
|
|
```bash
|
|
curl -LsSf https://astral.sh/uv/install.sh | sh
|
|
```
|
|
|
|
**Windows:**
|
|
```powershell
|
|
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.sh | iex"
|
|
```
|
|
|
|
After installing, restart your terminal and verify it worked:
|
|
```bash
|
|
uv --version
|
|
```
|
|
|
|
---
|
|
|
|
## If you have other Python installations on your machine
|
|
|
|
If you installed Python previously (via `python.org`, `brew`, `conda`, `pyenv`, etc.), those installations still exist and your terminal may default to one of them. This is fine — `uv` does not conflict with them. However, to avoid confusion:
|
|
|
|
- **Do not use `pip install` globally anymore.** It installs packages into your system Python, which creates a mess over time. Use `uv add` inside a project instead (see below).
|
|
- **Check what Python your terminal defaults to** at any time with `which python` or `python --version`. This tells you what runs when you type `python` without using `uv`.
|
|
- **`uv` manages its own Python versions independently.** When you pin a project to Python 3.12, `uv` will download and use that version for the project regardless of what Python is installed system-wide. You don't need to uninstall anything.
|
|
|
|
If you want to see all Python versions `uv` knows about:
|
|
```bash
|
|
uv python list
|
|
```
|
|
|
|
---
|
|
|
|
## Philosophy
|
|
|
|
Each project subfolder gets its own fully isolated environment — its own packages, its own Python version. Nothing bleeds between projects.
|
|
|
|
You always stay at the **repo root** for Git operations and use `--project` to point `uv` at the right subfolder. This way `git push`, `git pull`, and `git status` always work from one place.
|
|
|
|
```
|
|
INSTRUMENT-CONTROL/
|
|
├── .gitignore
|
|
├── README.md
|
|
├── your-project-folder/
|
|
│ ├── pyproject.toml ← declares your dependencies (commit this)
|
|
│ ├── uv.lock ← locks exact versions (commit this)
|
|
│ ├── .python-version ← pins the Python version (commit this)
|
|
│ └── .venv/ ← the actual environment (gitignore this)
|
|
└── ptis-analysis/
|
|
├── pyproject.toml
|
|
├── uv.lock
|
|
├── .python-version
|
|
└── .venv/
|
|
```
|
|
|
|
---
|
|
|
|
## Which Python version to use
|
|
|
|
Use **Python 3.12** for all new projects.
|
|
|
|
Python 3.9 reached end-of-life in October 2025 and no longer receives security patches. Python 3.12 is fully supported by the entire scientific stack (numpy, scipy, matplotlib, pyvisa, etc.) and has meaningful performance improvements. Avoid the absolute latest release (e.g. 3.14) as some libraries take a few months to catch up.
|
|
|
|
Pick one version and stick to it across all projects unless you have a specific reason not to — it makes debugging much simpler.
|
|
|
|
---
|
|
|
|
## Setting up a new project
|
|
|
|
From the **repo root**, run:
|
|
|
|
```bash
|
|
uv init --python 3.12 your-project-folder
|
|
```
|
|
|
|
This creates the following inside `your-project-folder/`:
|
|
- `pyproject.toml` — the project's metadata and dependency list
|
|
- `uv.lock` — a locked snapshot of the full dependency tree (including sub-dependencies)
|
|
- `.python-version` — a one-line file that just says `3.12`
|
|
|
|
The `.venv/` folder doesn't exist yet — it gets created the first time you add a package or run something.
|
|
|
|
---
|
|
|
|
## Adding packages
|
|
|
|
```bash
|
|
uv --project your-project-folder add numpy matplotlib scipy
|
|
```
|
|
|
|
This does three things at once: updates `pyproject.toml` with the new dependencies, resolves the full dependency tree into `uv.lock`, and installs everything into `.venv/`. You never need to manually `pip install` anything.
|
|
|
|
---
|
|
|
|
## Running a script
|
|
|
|
```bash
|
|
uv --project your-project-folder run python your-project-folder/measure.py
|
|
```
|
|
|
|
`uv run` automatically uses the project's environment — no need to activate anything first for one-off script runs.
|
|
|
|
---
|
|
|
|
## Running Jupyter
|
|
|
|
First add Jupyter to the project:
|
|
```bash
|
|
uv --project your-project-folder add jupyter
|
|
```
|
|
|
|
Then activate the environment and launch:
|
|
```bash
|
|
source your-project-folder/.venv/bin/activate
|
|
jupyter lab
|
|
```
|
|
|
|
You need to activate here (rather than use `uv run`) because Jupyter is an interactive session, not a one-off command. After activating, your terminal prompt will change to show `(.venv)` — this means all `python`, `jupyter`, and other commands will use the project's environment until you run `deactivate`.
|
|
|
|
Create or open any `.ipynb` file inside `your-project-folder/` and it will have access to all the project's packages. Before committing notebooks, clear the outputs (`Kernel → Restart & Clear Output`) to keep your Git diffs clean.
|
|
|
|
---
|
|
|
|
## Checking the Python version
|
|
|
|
To confirm which Python a project is using:
|
|
```bash
|
|
uv --project your-project-folder run python --version
|
|
|
|
# or just read the pin file directly:
|
|
cat your-project-folder/.python-version
|
|
```
|
|
|
|
To change it:
|
|
```bash
|
|
uv --project your-project-folder python pin 3.12
|
|
```
|
|
|
|
---
|
|
|
|
## The full daily workflow
|
|
|
|
```bash
|
|
# Pull latest changes
|
|
git pull
|
|
|
|
# Add a new package
|
|
uv --project your-project-folder add pyvisa
|
|
|
|
# Run your script
|
|
uv --project your-project-folder run python your-project-folder/measure.py
|
|
|
|
# Commit the updated dependency files
|
|
git add your-project-folder/pyproject.toml your-project-folder/uv.lock
|
|
git commit -m "add pyvisa dependency"
|
|
git push
|
|
```
|
|
|
|
---
|
|
|
|
## Syncing after a clone or pull
|
|
|
|
The `.venv/` folder is gitignored, so it doesn't exist on a fresh clone. `uv sync` recreates it from `uv.lock`:
|
|
|
|
```bash
|
|
uv --project your-project-folder sync
|
|
```
|
|
|
|
You need this in two situations:
|
|
1. **Fresh clone on a new machine** — `.venv/` doesn't exist yet
|
|
2. **After a `git pull`** where someone else added a dependency — your `.venv/` is now out of date
|
|
|
|
If you're the one adding packages with `uv add`, you never need to sync — it handles installation automatically.
|
|
|
|
> **Mental model:** `uv.lock` is the source of truth that lives in Git. `.venv/` is a local build of it. `uv sync` = "rebuild `.venv/` from `uv.lock`."
|
|
|
|
---
|
|
|
|
## Why `.venv/` is not committed
|
|
|
|
`.venv/` contains compiled binaries and symlinks built specifically for your OS and CPU. If you pushed it and pulled it on a different machine, it simply wouldn't work. It's also hundreds of MB — Git isn't designed for that.
|
|
|
|
`pyproject.toml` and `uv.lock` together are everything needed to recreate the exact same environment anywhere:
|
|
|
|
| File | Commit? | Why |
|
|
|---|---|---|
|
|
| `pyproject.toml` | ✅ Yes | Declares your dependencies |
|
|
| `uv.lock` | ✅ Yes | Locks exact versions — guarantees reproducibility |
|
|
| `.python-version` | ✅ Yes | Pins the Python version |
|
|
| `.venv/` | ❌ No | Local build artifact — regenerated from the above |
|
|
|
|
---
|
|
|
|
## Quick reference
|
|
|
|
| Task | Command |
|
|
|---|---|
|
|
| Create new project | `uv init --python 3.12 <project>` |
|
|
| Add a package | `uv --project <project> add <package>` |
|
|
| Run a script | `uv --project <project> run python <script>` |
|
|
| Activate interactively | `source <project>/.venv/bin/activate` |
|
|
| Deactivate | `deactivate` |
|
|
| Sync after clone/pull | `uv --project <project> sync` |
|
|
| Check Python version | `uv --project <project> run python --version` |
|
|
| Pin Python version | `uv --project <project> python pin 3.12` |
|
|
| List available Pythons | `uv python list` |
|
|
|
|
---
|
|
|
|
---
|
|
|
|
# `.gitignore` — Only read this if you are setting up a new repo
|
|
|
|
The `.gitignore` file tells Git which files to never track. It lives at the repo root and covers all subfolders. You only need to set this up once per repo.
|
|
|
|
## Why you need it
|
|
|
|
Without a `.gitignore`, Git will try to track everything — including `.venv/`, which contains thousands of compiled files you never want in version control (see above). VS Code's source control badge will show thousands of "changes" that aren't really changes, making it impossible to see what's actually going on.
|
|
|
|
## The `.gitignore` for this repo
|
|
|
|
Create a file called `.gitignore` at the repo root (next to your project folders, not inside them) with this content:
|
|
|
|
```gitignore
|
|
# uv environments
|
|
**/.venv/
|
|
.uv-cache/
|
|
|
|
# Python
|
|
__pycache__/
|
|
*.py[cod]
|
|
*.pyo
|
|
*.pyd
|
|
|
|
# Jupyter
|
|
.ipynb_checkpoints/
|
|
**/.ipynb_checkpoints/
|
|
|
|
# OS files
|
|
.DS_Store
|
|
Thumbs.db
|
|
|
|
# Editor
|
|
.vscode/settings.json
|
|
.idea/
|
|
*.swp
|
|
*.swo
|
|
|
|
# Measurement data (uncomment if needed)
|
|
# *.csv
|
|
# *.dat
|
|
# *.hdf5
|
|
# *.h5
|
|
```
|
|
|
|
The `**/.venv/` pattern uses a wildcard so it catches `.venv/` inside *any* subfolder automatically — you don't need to update it when you add a new project.
|
|
|
|
## Committing the `.gitignore`
|
|
|
|
Yes, the `.gitignore` itself should be committed:
|
|
|
|
```bash
|
|
git add .gitignore
|
|
git commit -m "add .gitignore"
|
|
```
|
|
|
|
It's not sensitive or machine-specific — committing it means any collaborator or future clone automatically gets the same rules.
|
|
|
|
## If Git is already tracking `.venv/`
|
|
|
|
If you set up the `.gitignore` after Git already started tracking `.venv/`, the file won't be automatically un-tracked — `.gitignore` only prevents *new* files from being added. To fix this:
|
|
|
|
```bash
|
|
git rm -r --cached your-project-folder/.venv/
|
|
git commit -m "untrack .venv"
|
|
```
|
|
|
|
The `--cached` flag removes it from Git tracking only — the actual folder stays on disk and your environment keeps working. |