Computing Policy

Using the CS 307 Tech Stack

This document will guide you through setting up and using your machine for success in CS 307.

We understand that you have a setup that you have used in previous courses. However, you are still required to follow this guide to avoid issues that would otherwise arise.

Setup

The CS 307 technology stack has three core elements:

  • IDE – Visual Studio Code (VSCode)
  • Python Management – uv
  • Report Generation – Quarto

Update Your Operating System

Before you start, you should probably be sure operating system (OS) is reasonably updated. However, don’t let this step hold you back, just realize that if your aren’t up-to-date, things could go wrong. In this past, we’ve discovered that some students have not applied operating system updates in years! This is terrible from a security perspective, but could also prevent some software from operating properly.

Before applying OS updates, make sure you can be plugged into power and without access to your machine for up to an hour. Also, as there is a small chance that things go wrong during updates, be sure you have any and all important files backed-up. You have a backup plan, right?

Install VSCode

First, you’ll need to install Visual Studio Code, which we will usually abbreviate as VSCode.

If you have previously downloaded VSCode, no-need to re-install. However, if any updates are available, we recommend applying them.

On macOS, it is important that you properly install VSCode. We have often found that students do not do so correctly, mostly because Microsoft distributes VSCode in a somewhat odd manner compared to other macOS software.

After downloading VSCode, you must place it in your Applications folder. To check if that was the case for an existing installation, open VSCode, then right click its icon in your Dock. Select Options > Show in Finder. If installed correctly, this will open your Applications folder.

If not, you should quit VSCode. Be sure to quit, not simply close the window. Then, delete anything related to VSCode from your Downloads folder. Next, re-download VSCode. Take the file that is downloaded, and drag it to your Applications folder. Open that file from the Applications folder to launch VSCode.

Create CS 307 Directory

Create a directory (folder) for CS 307. You can create it anywhere you’d like, but your Desktop is fine. You can name it anything you want, but something like cs307 is recommended.

Next, open this folder in VSCode. There are various ways to do so, but selecting File > Open Folder... is the most straightforward.

You will use this folder to collect all things CS 307. Opening a folder rather than an individual file will provide several advantages when working in VSCode for CS 307. All instructions in CS 307 will assume that you are working inside this directory when using VSCode for CS 307.

Install uv

Rather than install Python, we will install uv. You must install uv even if you have previously installed Python.

The installation instructions are slightly different for macOS and Windows.

In VSCode, open a terminal and run the following command:

curl -LsSf https://astral.sh/uv/install.sh | sh

In VSCode, open a terminal. Verify that the terminal is using the powershell shell. Run the following command:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

With either OS, after installing uv, restart your terminal. The easiest way to do so is to fully quit then reopen VSCode. When you relaunch VSCode, be sure to also reopen your CS 307 folder if VSCode does not do so automatically. We wil always assume you have this folder open when running commands in the future.

Setup Python

We will manage Python through uv. As a result, no need to install Python! Thankfully, uv will automatically take care of that for us.

Create a Virtual Environment

To ensure that you use the correct version of Python and Python packages, we will create a virtual environment.

To streamline this process, we have created a pyproject.toml specific to CS 307. Download this file, and place it in your CS 307 directory.

With that file in your directory, simply run the following in a VSCode terminal:

uv sync --compile-bytecode

This will install Python, and all necessary packages for CS 307!

If you use version control such as git, together with GitHub, be sure to add .venv to your .gitignore. The .venv folder contains an entire Python installation, which would be annoying to check-in to version control and push to GitHub.

With a virtual environment created, you should optionally activate it. This step is not strictly necessary, but will help avoid conflicts with conda.1

Run the following command:

source .venv/bin/activate

Run the following command:

.venv\Scripts\activate

To verify that the packages have installed correctly, run:

uv pip freeze

If installed correctly, you’ll see a list of packages and their versions.

Install VSCode Extensions

Install two VSCode Extensions:

Many incorrectly assume that Jupyter is a Python specific tool. Very much not the case.

“Project Jupyter’s name is a reference to the three core programming languages supported by Jupyter, which are Julia, Python and R.”

Install Quarto

Use of Quarto is required to properly render lab reports in CS 307. To use Quarto together with Jupyter and VSCode, you’ll need to install both Quarto CLI, as well as the Quarto VSCode Extension.

Check Jupyter

Now, let’s test that everything is working properly.

Create a new Jupyter Notebook in VSCode. In the top right, click Select Kernel. If you see .venv (Python 3.12.*), select it! If not, chose Select Another Kernel, then Python Environments..., then .venv (Python 3.13.*).

Now, place the following in a Python cell and run it:

from sklearn.datasets import load_wine
from sklearn.model_selection import train_test_split
from sklearn.ensemble import RandomForestClassifier
from sklearn.metrics import accuracy_score

wine = load_wine()
X, y = wine.data, wine.target
X_train, X_test, y_train, y_test = train_test_split(
    X,
    y,
    test_size=0.5,
    random_state=42,
)
clf = RandomForestClassifier(
    n_estimators=5,
    random_state=42,
)
clf.fit(X_train, y_train)
y_pred = clf.predict(X_test)
accuracy = accuracy_score(y_test, y_pred)
print(f"Accuracy: {accuracy:.4f}")
Accuracy: 0.8652

If your output matches the above, you’re all set!

Check Quarto

Save the notebook you were just working on as something like temp.ipynb. We’ll delete it when we are done. Now we need to render it, using Quarto, not Jupyter.

To do so, in a terminal, run:

uv run quarto preview temp.ipynb

Replace temp.ipynb with the name of whatever file you want to render.

Do not use Jupyter’s Export. This uses Jupyter, not Quarto. Doing so on labs will not be accepted.

Notice that a file named temp.html was created. You should see it in the Explorer panel. If VSCode did not do so automatically, open this file in a web browser to see the result.

To finish up, clean up your folder by deleting:

  • temp.ipynb
  • temp.html
  • temp_files

Footnotes

  1. It may be helpful to disable conda first, with conda deactivate.↩︎