Appendix B: Environment Setup Guide

This appendix walks you through setting up a complete Python development environment from scratch. If you followed the installation instructions in Chapter 2, you may already have some or all of this in place — skim to the parts you need.

B.1 Python Installation

Which Version?

This textbook requires Python 3.12 or later. Features used in this book that require 3.10+ include match/case statements (Ch. 4) and improved error messages. We recommend installing the latest stable release (3.12.x or 3.13.x at time of writing).

Windows

1. Download the installer. Go to python.org/downloads and click the yellow "Download Python 3.1x.x" button. This downloads a .exe installer.

2. Run the installer. Double-click the downloaded file. On the first screen, check the box that says "Add python.exe to PATH" — this is critical and the single most common source of problems when students skip it.

3. Choose "Install Now" for default settings, or "Customize installation" if you want to change the install location. The defaults are fine for this course.

4. Verify the installation. Open a terminal (see B.3 below) and type: python --version You should see something like Python 3.12.2. If you see an error or the wrong version, see the Troubleshooting section (B.7).

On some Windows systems, you may need to use python3 instead of python. If python --version opens the Microsoft Store or shows Python 2, try: python3 --version

5. Verify pip. pip is Python's package installer and should be included automatically: python -m pip --version You should see something like pip 24.0 from ....

macOS

1. Check for an existing installation. Open Terminal (Applications > Utilities > Terminal) and type: python3 --version macOS may ship with an older Python or none at all. Even if a version is present, install a current one.

2. Option A: Official installer (recommended for beginners). Go to python.org/downloads/macos and download the macOS installer (.pkg file). Double-click it and follow the wizard. This is the simplest path.

3. Option B: Homebrew (recommended if you already use Homebrew). If you have Homebrew installed: brew install python@3.12 Homebrew installs Python as python3 and pip as pip3.

4. Verify the installation: python3 --version pip3 --version

5. Important: On macOS, always use python3 and pip3, not python and pip, unless you've set up an alias. The bare python command may point to a legacy Python 2 installation or may not exist.

Linux (Ubuntu/Debian)

1. Update your package list: sudo apt update

2. Install Python 3.12+: sudo apt install python3.12 python3.12-venv python3-pip If Python 3.12 is not available in your distribution's repositories, add the deadsnakes PPA: sudo add-apt-repository ppa:deadsnakes/ppa sudo apt update sudo apt install python3.12 python3.12-venv python3.12-distutils

3. Verify: python3.12 --version

4. Make it the default (optional). If you want python3 to point to 3.12: sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.12 1

Linux (Fedora/RHEL)

sudo dnf install python3.12
python3.12 --version

Verifying Your Installation — All Platforms

After installation, open a terminal and confirm three things:

python3 --version       # Should show 3.12.x or later
python3 -m pip --version  # Should show pip and a Python 3.12 path
python3 -c "print('Hello from Python!')"

If the last command prints Hello from Python!, you are ready for Chapter 2.

B.2 VS Code Installation

Visual Studio Code (VS Code) is a free, lightweight code editor that works on all three platforms. It is the recommended editor for this textbook.

Installing VS Code

1. Go to code.visualstudio.com and download the installer for your operating system.
2. Run the installer with default settings.
3. Launch VS Code after installation.

Installing the Python Extension

1. Open VS Code.
2. Click the Extensions icon in the left sidebar (it looks like four small squares) or press Ctrl+Shift+X (Windows/Linux) / Cmd+Shift+X (macOS).
3. Search for "Python" and install the extension published by Microsoft (it should be the first result, with millions of installs).
4. This extension provides syntax highlighting, code completion (IntelliSense), linting, debugging, and a built-in terminal.

Configuring VS Code for Python

After installing the extension:

1. Select the Python interpreter. Press Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (macOS) to open the Command Palette. Type "Python: Select Interpreter" and choose the Python 3.12+ installation you just set up.

2. Enable auto-save (optional but recommended). Go to File > Preferences > Settings, search for "auto save", and set it to "afterDelay" with a 1000ms delay. This prevents the "I forgot to save before running" problem.

3. Set the default terminal. On Windows, VS Code may default to PowerShell. If you prefer Git Bash or Command Prompt, open Settings and search for "terminal default profile windows."

Recommended Additional Extensions

B.3 Terminal / Command Line Basics

The terminal is a text-based interface for interacting with your computer. You will use it to run Python scripts, manage files, install packages, and use Git.

Opening a Terminal

Essential Terminal Commands

These commands work on macOS and Linux. On Windows Command Prompt, some differ — the Windows equivalent is noted in parentheses.

Navigating with the Terminal

A typical workflow for this course:

# Create a course folder
mkdir cs1
cd cs1

# Create a folder for Chapter 3 exercises
mkdir ch03
cd ch03

# Create a Python file
touch tip_calculator.py

# Open the current folder in VS Code
code .

Running Python from the Terminal

# Run a script
python3 my_script.py

# Start the interactive REPL
python3

# Run a one-liner
python3 -c "print(2 ** 10)"

# Run a module
python3 -m pytest

# Check installed packages
python3 -m pip list

On Windows, replace python3 with python if that is how your installation is configured.

B.4 Creating and Running .py Files

Method 1: VS Code (Recommended)

1. Open VS Code.
2. Open a folder: File > Open Folder > select your project folder.
3. Create a new file: File > New File, or click the new-file icon in the Explorer panel.
4. Save it with a .py extension (e.g., hello.py).
5. Write your code.
6. Run it by clicking the play button (triangle) in the top-right corner, or press F5 for the debugger.

Method 2: Terminal

1. Create or navigate to your project folder.
2. Create the file: bash touch hello.py
3. Edit it with any text editor (or use VS Code: code hello.py).
4. Run it: bash python3 hello.py

File Naming Rules

• Use lowercase letters and underscores: grade_calculator.py
• Do not use spaces in filenames: my script.py will cause problems.
• Do not name your file the same as a Python module: do NOT name a file random.py, math.py, string.py, test.py, or csv.py. This will shadow the standard library module and cause confusing import errors.
• Start with a letter, not a number: 3_variables.py is a bad name. Use ch03_variables.py instead.

B.5 Virtual Environments

A virtual environment is an isolated Python installation that keeps each project's dependencies separate. This becomes important starting in Chapter 12 and is essential by Chapter 23.

Creating a Virtual Environment

# Navigate to your project folder
cd my_project

# Create the virtual environment
python3 -m venv venv

This creates a venv/ folder inside your project directory containing a private copy of the Python interpreter and pip.

Activating the Virtual Environment

When activated, your terminal prompt changes to show (venv) at the beginning:

(venv) $ python --version
Python 3.12.2

Installing Packages in a Virtual Environment

Once activated, use pip normally:

pip install requests
pip install pytest
pip install rich

Packages installed here are isolated from your system Python and from other virtual environments.

Saving and Restoring Dependencies

# Save current packages to a file
pip freeze > requirements.txt

# Install all packages from the file (on a different machine or fresh venv)
pip install -r requirements.txt

Deactivating

deactivate

VS Code and Virtual Environments

VS Code can detect virtual environments automatically. If it doesn't, press Ctrl+Shift+P / Cmd+Shift+P, type "Python: Select Interpreter", and choose the interpreter inside your venv/ folder.

Best Practices

• Create one virtual environment per project.
• Add venv/ to your .gitignore file — never commit the virtual environment to version control.
• Always use requirements.txt to track dependencies.
• If something feels broken, delete the venv/ folder and recreate it. Virtual environments are disposable.

B.6 Project Folder Structure

By mid-semester (around Chapter 12), your projects should follow this general structure:

my_project/
    venv/                    # virtual environment (not committed to git)
    src/                     # your source code
        __init__.py
        main.py
        models.py
        utils.py
    tests/                   # your tests
        test_models.py
        test_utils.py
    data/                    # data files
        input.csv
    requirements.txt         # package dependencies
    README.md                # project description
    .gitignore               # files to exclude from git

For early chapters (1-10), a flat structure is fine:

ch03/
    tip_calculator.py
    grade_calculator.py
    exercises.py

B.7 Troubleshooting

"python" Is Not Recognized (Windows)

Symptom: Typing python in the terminal gives 'python' is not recognized as an internal or external command or opens the Microsoft Store.

Cause: Python is not on your system PATH.

Fixes (try in order): 1. Reinstall Python and make sure to check "Add python.exe to PATH" on the first screen of the installer. 2. Try python3 instead of python. 3. Try py — Windows has a Python Launcher that may work even when python doesn't. 4. Manually add Python to PATH: - Search for "Environment Variables" in the Start menu. - Click "Environment Variables..." - Under "User variables", find Path and click "Edit". - Add the path to your Python installation (typically C:\Users\YourName\AppData\Local\Programs\Python\Python312\ and the Scripts subdirectory). - Restart your terminal.

"Permission Denied" (macOS/Linux)

Symptom: Running a script gives Permission denied.

Fixes: - Use python3 my_script.py instead of ./my_script.py. - If you must run it directly: chmod +x my_script.py and add #!/usr/bin/env python3 as the first line.

Multiple Python Versions Installed

Symptom: python runs Python 2, or python3 runs an older version than expected.

Diagnosis:

which python3          # macOS/Linux: shows path
where python           # Windows: shows path(s)
python3 --version      # check version

Fixes: - On macOS/Linux: always use python3 explicitly, or create an alias in your shell config (~/.bashrc or ~/.zshrc): bash alias python=python3 alias pip=pip3 - On Windows: use the py launcher with a version flag: py -3.12 my_script.py

pip Install Fails

Symptom: pip install package_name gives an error.

Common causes and fixes: - Permission error: Use python3 -m pip install --user package_name or use a virtual environment (recommended). - pip not found: Use python3 -m pip install package_name instead. - SSL certificate error: Upgrade pip: python3 -m pip install --upgrade pip - Package not found: Check the spelling. Search pypi.org for the correct package name.

Import Errors After Installing a Package

Symptom: pip install requests succeeds, but import requests in your script gives ModuleNotFoundError.

Cause: The pip that installed the package and the Python that runs your script are different installations.

Fix: Install using the same Python:

python3 -m pip install requests
python3 my_script.py

Or use a virtual environment (the most reliable fix).

VS Code Uses the Wrong Python

Symptom: Code runs fine in the terminal but VS Code shows errors or uses a different Python version.

Fix: Press Ctrl+Shift+P / Cmd+Shift+P, type "Python: Select Interpreter", and choose the correct Python installation.

IndentationError in Code That Looks Fine

Symptom: Python raises IndentationError even though the code looks properly indented.

Cause: Your file mixes tabs and spaces. This is invisible to the human eye but Python treats them differently.

Fix: 1. In VS Code, go to Settings and search for "insert spaces". Make sure "Editor: Insert Spaces" is checked and "Editor: Tab Size" is set to 4. 2. To fix an existing file: select all code (Ctrl+A / Cmd+A), then use the Command Palette (Ctrl+Shift+P) and type "Convert Indentation to Spaces".

PowerShell Blocks Virtual Environment Activation (Windows)

Symptom: Running venv\Scripts\Activate.ps1 gives a "running scripts is disabled" error.

Fix: Run this command once in PowerShell (as administrator):

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Or use Command Prompt instead: venv\Scripts\activate (without the .ps1 extension).

"SyntaxError: invalid syntax" on Code That Works for Others

Possible causes: 1. Your Python version is too old for the syntax used. Check python3 --version. 2. You're running Python 2 instead of Python 3. Use python3 explicitly. 3. You named your file the same as a standard library module (e.g., string.py). 4. There's a syntax error on the previous line that Python reports on the next line. Check the line before the one Python highlights.

B.8 Getting Help

When you're stuck:

1. Read the error message carefully. Python's error messages have improved dramatically in recent versions. The traceback tells you the file, line number, and type of error.

2. Search the error message. Copy the last line of the traceback (e.g., TypeError: can only concatenate str (not "int") to str) and search for it. Someone has had this exact problem before.

3. Use the REPL. If you're unsure how something works, test it interactively: ``` python3

   "hello".split() ['hello'] ```

4. Check the official documentation. docs.python.org/3/ is comprehensive and well-written. The Library Reference and Tutorial sections are particularly useful.

5. Ask for help effectively. When asking an instructor, TA, or posting on a forum, include: - What you're trying to do (not just "it doesn't work") - The complete error message (copy-paste, don't paraphrase) - The relevant code (minimal — strip out unrelated parts) - What you've already tried

This guide was written for Python 3.12+ and VS Code as of 2025. Software installation procedures change over time; if these instructions don't match what you see, check the official websites for updated instructions.