Python on your own computer

Where the academy's Python runs

Every code cell in this course runs in your browser, using a version of Python compiled to run inside web pages. That's why it starts instantly and can't harm your computer. It's also why some things only work on a real computer: reading files from your disk, sending real email, running a web server for other people, or using a package that needs your operating system.

import platform
import sys

print("Python", platform.python_version())
print("running on:", sys.platform)
print("in a virtual environment:", sys.prefix != sys.base_prefix)

sys.platform says "emscripten" here, the toolkit that turns programs into code a web page can run. On your computer it will say "darwin" (a Mac), "win32" (Windows) or "linux". The last line asks whether Python is running inside a virtual environment, which you'll create below.

import sys
print(sys.prefix != sys.base_prefix)

Step 1: install Python and an editor

Python. Install a current version, 3.12 or newer:

• Windows: download the installer from python.org. On its first screen, tick "Add python.exe to PATH". Afterwards, the py command starts Python in any terminal.
• macOS: the installer from python.org works well. If you already use Homebrew, brew install python does the same. Type python3, not python.
• Linux: Python is usually already there. Install the pieces for virtual environments too, for example sudo apt install python3 python3-venv on Ubuntu.

Then open a terminal (Terminal on a Mac, PowerShell on Windows) and check:

python3 --version     # macOS and Linux
py --version          # Windows

An editor. Install Visual Studio Code (free) and, inside it, the Python extension from Microsoft. It adds running, debugging, tests and error highlighting. Other good editors work too, such as PyCharm. The steps below use VS Code.

Step 2: a project folder

Make a folder called trail-tools and open it in VS Code with File, then Open Folder. Create these four files in it.

shop_math.py, the code:

def with_tax(price, rate=0.08):
    return round(price * (1 + rate), 2)


def bulk_price(price, qty):
    discount = 0.1 if qty >= 10 else 0
    return round(price * qty * (1 - discount), 2)

test_shop_math.py, its tests:

from shop_math import bulk_price, with_tax


def test_with_tax():
    assert with_tax(100) == 108.0


def test_bulk_discount_starts_at_ten():
    assert bulk_price(5, 9) == 45.0
    assert bulk_price(5, 10) == 45.0

requirements.txt, the packages the project needs:

pytest>=8

selfcheck.py, which checks the whole setup:

import hashlib
import platform
import subprocess
import sys

version = platform.python_version()
in_venv = sys.prefix != sys.base_prefix
run = subprocess.run([sys.executable, "-m", "pytest", "-q"], capture_output=True, text=True)
passed = run.returncode == 0
fields = f"python={version} venv={'yes' if in_venv else 'no'} tests={'passed' if passed else 'failed'}"
code = hashlib.sha256(fields.encode()).hexdigest()[:8]
print(f"SETUP-CHECK {fields} code={code}")
print((run.stdout.strip().splitlines() or ["pytest printed nothing"])[-1])

Step 3: a virtual environment

A virtual environment is a folder holding its own copy of Python's package list, so each project gets exactly the packages it needs, without clashing with other projects. The packages lesson explained why; here's how. In VS Code's terminal (Terminal, then New Terminal), inside trail-tools:

# macOS and Linux
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

# Windows (PowerShell)
py -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt

After activating, the prompt starts with (.venv), and python means the environment's Python on every system. pip install -r requirements.txt installs everything the file lists. Then tell VS Code to use it: open the Command Palette (Ctrl+Shift+P, or Cmd+Shift+P on a Mac), run Python: Select Interpreter, and pick the one inside .venv.

Writing python -m pip instead of plain pip makes sure packages go into the Python you're actually running. That one habit prevents the most common "but I installed it!" mystery.

Step 4: run, debug and test

Run the self-check from the activated terminal:

python selfcheck.py

It prints a line starting with SETUP-CHECK, and then pytest's summary. Keep that output: the exercise below checks it.

Debug. Open shop_math.py, click in the margin to the left of the discount = ... line to set a breakpoint (a red dot), then open test_shop_math.py and use the Testing panel's "Debug Test" on test_bulk_discount_starts_at_ten. The program stops on your line. Hover over qty to see its value, and use Step Over (F10) to move one line at a time. It's the step-through view from the debugging lesson, on your own code. Typing breakpoint() on a line does the same thing in any terminal.

Test. python -m pytest -q finds every test_*.py file, runs every test_ function in it, and prints a dot for each pass. Change >= 10 to > 10 in shop_math.py and run it again: one test fails, and pytest shows which values disagreed. Put it back before the self-check.

When something goes wrong

Almost everyone hits one of these once:

• "python3: command not found" or "'python' is not recognized". Python isn't on the terminal's PATH. On Windows, rerun the installer and tick "Add python.exe to PATH", or use py. Then close and reopen the terminal, because terminals read PATH when they start.
• PowerShell won't run Activate.ps1. Windows blocks scripts by default. Run Set-ExecutionPolicy -Scope CurrentUser RemoteSigned once, then activate again.
• "No module named pytest" after installing it. You installed into a different Python. Check that the prompt shows (.venv), then run python -m pip install -r requirements.txt again.
• VS Code underlines an import that works in the terminal. VS Code is using a different interpreter. Run "Python: Select Interpreter" and choose .venv.
• selfcheck says venv=no. You ran it with the system Python. Activate the environment first.

Add .venv/ to a .gitignore file when you put the project in git. The environment can always be rebuilt from requirements.txt, so it never belongs in version control.

import hashlib
import platform
import sys

version = platform.python_version()
in_venv = sys.prefix != sys.base_prefix
passed = True  # here we pretend pytest passed
fields = f"python={version} venv={'yes' if in_venv else 'no'} tests={'passed' if passed else 'failed'}"
code = hashlib.sha256(fields.encode()).hexdigest()[:8]
print(f"SETUP-CHECK {fields} code={code}")

typo = fields.replace("venv=no", "venv=yes")
print("changing one field changes the code:", hashlib.sha256(typo.encode()).hexdigest()[:8])