Week 4 Assignment

📝 Overview

In this assignment, you'll build a command-line Weather Assistant that fetches live weather data from the internet and saves it to your computer. This project ties together everything from Week 4:

• Environment Variables: Storing your API key securely outside your code
• HTTP Requests: Calling the OpenWeatherMap API with the requests library
• JSON: Parsing API responses and saving data to files
• File I/O: Reading and writing persistent data between program runs
• Dictionaries: Navigating nested API response data
• Exception Handling: Gracefully handling missing files, bad cities, and network errors

⚙️ Setup: Get Your API Key

This project uses a real, free weather API. Before you can run the program you need a key:

1. Go to openweathermap.org/api and create a free account
2. Copy your API key from the dashboard (it may take a few minutes to activate)
3. Set it as an environment variable in your terminal — do not paste it into your code:

   # Mac / Linux
   export OPENWEATHER_API_KEY="your_key_here"
   
   # Windows (Command Prompt)
   set OPENWEATHER_API_KEY=your_key_here

4. Run your program from the same terminal window where you set the variable

🎯 Learning Objectives

By completing this assignment, you'll be able to:

1. Read secrets from environment variables instead of hard-coding them
2. Make HTTP GET requests and pass query parameters
3. Parse and navigate nested JSON / dictionary responses
4. Read and write JSON files to persist data between runs
5. Handle common runtime errors without crashing the program
6. Design a menu-driven command-line application

📋 Requirements

Your Weather Assistant must support all of the following menu options:

1. Get weather for a city — prompt for a city name, call the API, display temperature, condition, humidity, and wind speed, then save the result to history
2. Add city to favorites — save the city name to cities.json; do not allow duplicates
3. Remove city from favorites — remove from cities.json; handle the case where the city is not in the list
4. Get weather for all favorites — loop through every saved city, fetch, display, and save to history
5. View weather history — read weather_history.json and show the 10 most recent entries
6. Show favorite cities — print the current favorites list
7. Quit — exit the program cleanly

Your program must also:

• Exit with a clear message if OPENWEATHER_API_KEY is not set
• Handle an invalid city name without crashing (API returns a 404)
• Handle a missing internet connection without crashing
• Handle invalid menu input (letters instead of numbers) without crashing
• Persist favorites and history between program runs using JSON files

🚀 Suggested Function Structure

The scaffolding file has 15 TODO items covering these functions:

• load_api_key() — read key from environment, exit if missing
• load_cities() — read favorites from cities.json
• save_cities(cities) — write favorites list back to file
• add_city(cities, city_name) — add with duplicate check
• remove_city(cities, city_name) — remove with not-found check
• get_weather(city_name, api_key) — call the API, return JSON or None
• display_weather(city_name, data) — format and print the result
• save_weather_history(city_name, data) — append entry with timestamp
• show_history() — print the last 10 entries
• show_favorites(cities) — print numbered favorites list
• get_weather_for_favorites(cities, api_key) — loop and fetch all
• show_menu() — print the numbered menu
• main() — menu loop and option dispatch

📁 Files in Your Assignment

• weather_assistant.py — your main program with TODO markers to guide you
• cheat_sheet.py — reference patterns for environment variables, JSON, requests, and exception handling

💡 Tips for Success

1. Install requests first: run pip install requests in your terminal
2. Build incrementally: get get_weather() working and printing data before building the rest
3. Print the raw response first: call print(data) on the API result to see the full dictionary structure before you start extracting values
4. Test error cases early: try an invalid city name and disconnect your Wi-Fi to make sure your exception handling works
5. Check your JSON files: open cities.json and weather_history.json in VS Code after running the program to verify they look correct

🎮 Example Session

--- Weather Assistant ---
1. Get weather for a city
2. Add city to favorites
3. Remove city from favorites
4. Get weather for all favorites
5. View weather history
6. Show favorite cities
7. Quit

Choose an option: 1
Enter city name: London

--- Weather for London ---
Temperature : 54°F
Condition   : overcast clouds
Humidity    : 81%
Wind Speed  : 9.2 mph

Choose an option: 2
Enter city name to add: London
London added to favorites!

Choose an option: 5
Recent weather history:
  2026-02-22 14:35 | London      | 54°F | overcast clouds