Python Virtual Environments Explained — Setup, Usage and Best Practices

import sys
import site

# This script shows you WHERE Python is currently looking for packages.
# Run this BEFORE creating a virtual environment to see the global setup.
# Then run it again AFTER activating one — the paths will be completely different.

print("=== Python Executable Location ===")
# This tells you WHICH python binary is currently running this script
print(f"Python binary: {sys.executable}")

print("\n=== Where Python Looks for Installed Packages ===")
# sys.path is the list of folders Python searches when you write 'import something'
for index, path in enumerate(sys.path):
    print(f"  [{index}] {path}")

print("\n=== Site-packages Directory (where pip installs things) ===")
# site.getsitepackages() returns the folders where pip drops installed libraries
for packages_dir in site.getsitepackages():
    print(f"  {packages_dir}")

# ── STEP 1: Create a project folder and move into it ──────────────────────────
mkdir my_weather_app
cd my_weather_app

# ── STEP 2: Create the virtual environment ────────────────────────────────────
# 'python -m venv' tells Python to run the built-in venv module
# '.venv' is the name of the folder that will hold the environment
# Using a dot prefix (.venv) keeps it hidden from casual 'ls' listings
python -m venv .venv

# You'll now see a .venv folder. Peek inside — it's just files:
# .venv/
#   bin/          ← Python binary and activation scripts (Mac/Linux)
#   lib/          ← Where pip will install packages FOR THIS PROJECT ONLY
#   pyvenv.cfg    ← Config file pointing back to the original Python

# ── STEP 3: Activate the environment ──────────────────────────────────────────

# On macOS / Linux:
source .venv/bin/activate

# On Windows (Command Prompt):
# .venv\Scripts\activate.bat

# On Windows (PowerShell):
# .venv\Scripts\Activate.ps1

# ── STEP 4: Confirm the environment is active ─────────────────────────────────
# Your prompt should now show (.venv) at the start, like:
# (.venv) user@machine:~/my_weather_app$

# Double-check by asking WHICH python is active:
which python          # Mac/Linux
# Should print: /path/to/my_weather_app/.venv/bin/python
# (NOT /usr/local/bin/python3 — that's the global one)

# ── STEP 5: Install a package INSIDE the environment ──────────────────────────
# This installs 'requests' ONLY for this project, not globally
pip install requests

# ── STEP 6: Deactivate when you're done working ───────────────────────────────
deactivate
# Prompt returns to normal — you're back in the global environment

# ── SCENARIO: You've built your weather app. Time to share it. ────────────────

# Make sure the virtual environment is active first:
source .venv/bin/activate

# Install the packages the app actually needs:
pip install requests==2.31.0
pip install python-dotenv==1.0.0

# ── STEP 1: Freeze the environment into a requirements file ───────────────────
# 'pip freeze' lists EVERY installed package with its exact version
# '>' redirects that output into a file called requirements.txt
pip freeze > requirements.txt

# Let's see what that file looks like:
cat requirements.txt

# ── STEP 2: Simulate what a teammate would do on their machine ────────────────
# They clone your repo, then:
mkdir colleagues_machine_simulation
cd colleagues_machine_simulation
python -m venv .venv
source .venv/bin/activate

# One command installs EVERYTHING, at EXACTLY the same versions:
# '-r' means 'read from this file'
pip install -r ../requirements.txt

# ── STEP 3: Verify they got the same setup ────────────────────────────────────
pip list

# fetch_weather.py
# Run this INSIDE an active virtual environment where 'requests' is installed.
# Setup commands (run in terminal first):
#   python -m venv .venv
#   source .venv/bin/activate          (Mac/Linux)
#   pip install requests==2.31.0
#   pip freeze > requirements.txt
#   python fetch_weather.py

import requests  # Only available because we installed it in our virtual environment
import sys

# Open-Meteo is a free weather API — no API key needed, perfect for learning
WEATHER_API_BASE_URL = "https://api.open-meteo.com/v1/forecast"

# Coordinates for London, UK — change these to your city
LATITUDE = 51.5074
LONGITUDE = -0.1278
CITY_NAME = "London"

def fetch_current_temperature(latitude: float, longitude: float) -> dict:
    """
    Calls the Open-Meteo API and returns the current temperature data.
    Returns a dict with 'temperature' and 'unit' keys, or raises on failure.
    """
    # Build the query parameters the API expects
    query_params = {
        "latitude": latitude,
        "longitude": longitude,
        "current_weather": True,   # Ask for current conditions, not a forecast
        "temperature_unit": "celsius"
    }

    # requests.get() makes an HTTP GET request — this is why we installed 'requests'
    api_response = requests.get(WEATHER_API_BASE_URL, params=query_params, timeout=10)

    # Raise an exception immediately if the server returned an error status (4xx, 5xx)
    api_response.raise_for_status()

    # .json() parses the response body from a raw string into a Python dictionary
    weather_data = api_response.json()

    current_conditions = weather_data["current_weather"]
    return {
        "temperature": current_conditions["temperature"],
        "unit": "°C",
        "wind_speed_kmh": current_conditions["windspeed"]
    }


def display_weather_report(city: str, weather: dict) -> None:
    """Prints a clean, readable weather summary to the terminal."""
    print("\n" + "=" * 40)
    print(f"  Current Weather — {city}")
    print("=" * 40)
    print(f"  Temperature : {weather['temperature']}{weather['unit']}")
    print(f"  Wind Speed  : {weather['wind_speed_kmh']} km/h")
    print("=" * 40 + "\n")


if __name__ == "__main__":
    print(f"Fetching weather for {CITY_NAME}...")

    try:
        current_weather = fetch_current_temperature(LATITUDE, LONGITUDE)
        display_weather_report(CITY_NAME, current_weather)
    except requests.exceptions.ConnectionError:
        print("ERROR: No internet connection. Check your network and try again.")
        sys.exit(1)
    except requests.exceptions.HTTPError as http_err:
        print(f"ERROR: The weather API returned an error: {http_err}")
        sys.exit(1)