# E190BO — Setting Up Your Laptop

You will build **one Python environment now and reuse it for the whole semester.**
Budget ten minutes.
Doing this in Lab 0, with an instructor in the room, is far cheaper than doing it at 11pm before an assignment is due.

---

## Step 1 — Make your course folder

Everything you download for this course goes in **one folder in your home directory**: `e190bo`.
Create it, with a subfolder for this lab:

**macOS / Linux**
```bash
mkdir -p ~/e190bo/lab0 && cd ~/e190bo
```

**Windows (PowerShell)**
```powershell
mkdir -Force ~\e190bo\lab0 ; cd ~\e190bo
```

From now on: **every file you download from the course website goes in `~/e190bo/`**, in a subfolder for that assignment.
Keep each assignment's files together — notebooks expect to find their data files sitting next to them.

Download `requirements.txt` and `check_env.ipynb` into `~/e190bo/` itself (not a subfolder).

## Step 2 — Get Python 3.13

**This class runs Python 3.13.** Not 3.12, not 3.14 — 3.13, for everyone.
When the whole class runs one version, an error you hit is an error your classmates and instructor can reproduce.
That is worth more to you than being on the newest release.

Check whether you already have it:

```bash
python3.13 --version     # macOS/Linux
py -3.13 --version       # Windows
```

If that prints `Python 3.13.x`, you are done with this step.

If it says "command not found", install it:

- **macOS** — from [python.org](https://www.python.org/downloads/), scroll **past** the big download button (it offers 3.14) to the release list and pick the newest **3.13.x**.
  Homebrew users can run `brew install python@3.13` instead.
- **Windows** — same: python.org, release list, newest **3.13.x** installer.

You do not need to remove any other Python you have.
Multiple versions coexist fine, which is exactly why the next step names 3.13 explicitly.

## Step 3 — Create the environment (once, all semester)

Run these from inside `~/e190bo`.

> **Type `python3.13`, not `python3`.**
> Plain `python3` means "whichever Python happens to be first on this laptop's PATH" — which differs from machine to machine, and is how you end up with a 3.14 environment that looks fine until something breaks oddly in week 6. Naming the version is the whole point of this step.

**macOS / Linux**
```bash
python3.13 -m venv .venv
source .venv/bin/activate
```

**Windows (PowerShell)**
```powershell
py -3.13 -m venv .venv
.venv\Scripts\Activate.ps1
```

Now **check what you got, before installing anything**:

```bash
python -VV
```

This must print `Python 3.13.x`.
If it prints any other version, delete the `.venv` folder and redo this step — do not continue, because everything after this inherits the mistake.

With 3.13 confirmed, install the packages and register the kernel:

```bash
pip install -r requirements.txt
python -m ipykernel install --user --name e190bo --display-name "Python (E190BO)"
```

That last line registers your environment with Jupyter under the name **Python (E190BO)**.
It is the step that makes the environment reusable — once registered, it shows up in the kernel list of every notebook you ever open, no matter what folder it is in.

## Step 4 — Verify

```bash
jupyter lab
```

Open `check_env.ipynb`, **set the kernel in the top-right corner to "Python (E190BO)"**, and run the single cell.
You want `ALL CHECKS PASSED`.

Show that output at your Lab 0 check-in.

---

## Every time you work on this course

```bash
cd ~/e190bo
source .venv/bin/activate        # Windows: .venv\Scripts\Activate.ps1
jupyter lab
```

Three lines, all semester.
You will know it worked when your shell prompt shows `(.venv)`.

Then in the Jupyter file browser, click into the assignment's folder and open the notebook.
**Always check that the kernel says "Python (E190BO)"** — this is the one thing worth building a habit around, because almost every confusing error in this course traces back to it.

## When a new package is added

Occasionally an assignment needs something new (`scipy`, say).
When that is announced:

1. Download the updated `requirements.txt` into `~/e190bo/`, replacing the old one.
2. Activate the environment and run `pip install -r requirements.txt` again.
3. Re-run `check_env.ipynb`.

Safe to run any time — it does nothing if you are already up to date.
You are still using the same environment; you are just adding to it.

## Your Glassroom API key (Lab 4 onward)

From Lab 4 on, notebooks call Claude through **Glassroom**, the course's AI platform.
Glassroom gives you an **API key**, a secret string starting with `sk-`.
Your notebooks send it to Glassroom's server, which forwards your requests to Claude.
Usage is billed to the course, so treat your key like a password.
If it leaks, tell an instructor so we can turn it off.

**Never paste your key into a notebook cell, even "just for a minute."**
Notebooks get submitted on Canvas and uploaded to chatbots, Jupyter keeps hidden checkpoint copies after you delete a line, and outputs can echo the key back.
Keys pushed to GitHub are found by automated scanners within minutes.

**How to store it** (the same on macOS and Windows):

1. In Glassroom, find the **Your API key** box and click **Copy** next to the key.
2. Run the first key cell of the Lab 4 notebook.
   Paste the key into the hidden box that appears, and press Enter.
3. **Double-check:** the notebook prints the start and end of the key it saved (like `sk-AbC1...wXyZ`).
   The start should match what Glassroom shows in the key box.
   Click **Show** in Glassroom to compare the end too.

The notebook saves the key in a file called `.env` in your course folder:

```
~/e190bo/
├── .env              <- your key lives here, and nowhere else
├── .venv/
├── requirements.txt
└── lab4/
    └── hw4.ipynb     <- reads the key from ../.env; the key never appears in the notebook
```

The notebook finds this file every time it runs, so you only need to paste the key once.

- **Replace the key** (wrong key, or a new one from Glassroom): run `save_api_key()` in any cell of the Lab 4 notebook.
- **Delete the key:**
  - macOS: `rm ~/e190bo/.env`
  - Windows (PowerShell): `Remove-Item ~\e190bo\.env`
- **Can't see `.env` in Finder?**
  On macOS, files whose names start with a dot are hidden.
  Press **Cmd + Shift + .** in Finder to show them.
  Windows Explorer shows it normally.
- **If you use git** for your course folder, add a line `.env` to your `.gitignore`.
- **On Colab**, the key is saved next to the notebook and disappears when the session ends.
  The notebook will ask for it again next time.
- **Already have your own Anthropic key?**
  Don't use it for this course.
  The notebooks deliberately send your Glassroom key to Glassroom, even if an `ANTHROPIC_API_KEY` is set on your laptop.

<details>
<summary>Optional, for experienced users: an environment variable instead of <code>.env</code></summary>

The notebooks also accept the key as an environment variable named `GLASSROOM_API_KEY`.
Glassroom's **Copy with key** button copies the macOS command for this (`export GLASSROOM_API_KEY=...`), but that only lasts until you close the terminal.
To make it permanent, set it once, then **open a new terminal** and start `jupyter lab` from it (programs only see variables that existed when they started):

- macOS (zsh): `read -s "k?Key: " && echo "export GLASSROOM_API_KEY=$k" >> ~/.zshrc` (`read -s` keeps the key out of your shell history)
- Windows (PowerShell): `[Environment]::SetEnvironmentVariable("GLASSROOM_API_KEY", (Read-Host "Key"), "User")`

If both are set, the environment variable wins over `.env`.
</details>

---

## If you see this error

**`ModuleNotFoundError: No module named 'numpy'`** (or pandas, or matplotlib) — almost always the wrong kernel, not a missing package.
Check the top-right corner of the notebook and switch it to **Python (E190BO)**.
If that kernel is not in the list, you skipped the `ipykernel install` line in Step 3; activate the environment and run it.

**`ModuleNotFoundError: No module named 'sklearn'`** — this one usually *is* a missing package.
`scikit-learn` was added to `requirements.txt` for Lab 2, after most people built their environment.
Follow "When a new package is added" above: download the current `requirements.txt`, then re-run `pip install -r requirements.txt` with the environment activated.

**`ModuleNotFoundError: No module named 'anthropic'`** (or `dotenv`, or `PackageNotFoundError` in the environment check) — `anthropic` and `python-dotenv` were added to `requirements.txt` for Lab 4. Follow "When a new package is added" above, then **restart the notebook's kernel**.
A kernel that was already running won't see new packages.

**"Glassroom rejected your key"** (an `AuthenticationError`) — the saved key is wrong or has been turned off.
Run `save_api_key()` in the Lab 4 notebook and paste the key from Glassroom's **Your API key** box.

**"Your key works, but it can't use the model"** — your key is fine, but Glassroom hasn't enabled that model for it.
Tell an instructor, and include the message the notebook printed.

**`RateLimitError`** — you sent too many requests in one minute.
The notebook already retries automatically; if it still fails, wait a minute and re-run the cell.

**`AssertionError: This kernel is running Python 3.x`** — either the notebook kernel is not **Python (E190BO)** (check the top-right corner), or your `.venv` was built by the wrong interpreter.
For the second: delete `.venv` and redo Step 3, typing `python3.13` rather than `python3`.

**`ERROR: No matching distribution found for numpy==2.1.3`** — your environment is on a Python version the pinned packages do not have builds for.
Confirm with `python -VV`; if it is not 3.13, rebuild per Step 3.

**`FileNotFoundError: testScores.csv`** — the data file is not in the same folder as the notebook.
Move it there.

**Plots do not appear** — make sure the plotting cell ends with `plt.show()`.
If they still do not render, add `%matplotlib inline` as the first line of the cell.

**Windows: `cannot be loaded because running scripts is disabled on this system`** — PowerShell is blocking the activation script.
Run this once, then retry:
```powershell
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
```

**Something is broken and you cannot work out why** — delete the `.venv` folder and redo Step 3. It takes about two minutes and costs you nothing, because everything the environment contains is specified in `requirements.txt`.
This is the whole reason we pin versions.
Do not spend an hour debugging an environment you can rebuild in two.

---

## Options

**Faster, if you want it:** [`uv`](https://docs.astral.sh/uv/) does Step 3 in seconds rather than minutes — `uv venv && uv pip install -r requirements.txt`.
Entirely optional; the route above is the default because it needs nothing installed first.

**If your setup breaks the night before a deadline:** upload the notebook and its data files to [Google Colab](https://colab.research.google.com) and work there.
Everything in this course runs on Colab unmodified.
Use it to stay unblocked, then come to office hours and we will fix your laptop properly.