Merge pull request #235 from realpython/weather-app

Add tutorial code for Weather App SbSP

Author: KateFinegan

weather-app/README.md

@@ -0,0 +1,69 @@
+# Weather CLI
+
+> See the world's weather 🌤 at home through your CLI window.
+
+View weather and temperature information for different cities around the world right inside your CLI:
+
+![CLI interactions using the weather CLI app](weather.gif)
+
+Follow the tutorial to [Build This Weather CLI App with Python](https://realpython.com/build-a-python-weather-app-cli/) using only modules from Python's standard library.
+
+## Requirements
+
+To run this CLI app, you need a modern installation of [Python](https://www.python.org/) >= 3.6.
+
+**Note:** This app was developed on macOS for the [Zsh](https://www.zsh.org) shell. Your mileage with some of the color display and emojis may vary depending on your setup. On Windows, [PowerShell](https://docs.microsoft.com/en-us/powershell/) on [Windows Terminal](https://github.com/microsoft/terminal) displays the formatting reasonably well.
+
+You also need an [API key for OpenWeather's API](https://openweathermap.org/appid). After signing up and generating your API key, add it to the `secrets.ini` config file:
+
+```
+[openweathermap]
+api_key = <YOUR-OPENWEATHERAPP-API-KEY>
+```
+
+**Note:** Make sure that `secrets.ini` is not tracked by your version control system, to avoid leaking your API key to the public.
+
+For more information on the OpenWeather API used in this CLI app, check out the [documentation on the city name endpoint](https://openweathermap.org/current#name).
+
+## Usage example
+
+Once you're set up, you can call the weather CLI by running:
+
+```bash
+$ python weather.py <CITY_NAME> [-i]
+```
+
+For example, to get the current weather in Vienna, Austria, you can run the following command:
+
+```bash
+$ python weather.py Vienna
+```
+
+To display the temperature in Fahrenheit, you can add the optional `-i` or `--imperial` flag.
+
+_For more examples and usage, please refer to the [associated Real Python tutorial](https://realpython.com/build-a-python-weather-app-cli/)._
+
+## Development setup
+
+To run and continue development on this CLI project, you need to have **Python>=3.6** installed on your system.
+
+## Release History
+
+- 0.1.0
+    - The first proper release
+
+## Meta
+
+Martin Breuss – [@martinbreuss](https://twitter.com/martinbreuss) – [email protected]
+
+Distributed under the [MIT License](https://opensource.org/licenses/MIT).
+
+[https://github.com/martin-martin](https://github.com/martin-martin/)
+
+## Contributing
+
+1. Fork it (<https://github.com/realpython/materials/fork>)
+2. Create your feature branch (`git checkout -b feature/fooBar`)
+3. Commit your changes (`git commit -am 'Add some fooBar'`)
+4. Push to the branch (`git push origin feature/fooBar`)
+5. Create a new Pull Request

weather-app/source_code_final/.gitignore

@@ -0,0 +1 @@
+secrets.ini

weather-app/source_code_final/style.py

@@ -0,0 +1,18 @@
+import sys
+
+
+PADDING = 20
+
+RED = "\033[1;31m"
+BLUE = "\033[1;34m"
+CYAN = "\033[1;36m"
+GREEN = "\033[0;32m"
+YELLOW = "\033[33m"
+WHITE = "\033[37m"
+
+REVERSE = "\033[;7m"
+RESET = "\033[0m"
+
+
+def change_color(color):
+    sys.stdout.write(color)

weather-app/source_code_final/weather.py

@@ -0,0 +1,167 @@
+import argparse
+import json
+import sys
+from configparser import ConfigParser
+from urllib import error, parse, request
+
+import style
+
+BASE_WEATHER_API_URL = "http://api.openweathermap.org/data/2.5/weather"
+
+# Weather Condition Codes
+# https://openweathermap.org/weather-conditions#Weather-Condition-Codes-2
+THUNDERSTORM = range(200, 300)
+DRIZZLE = range(300, 400)
+RAIN = range(500, 600)
+SNOW = range(600, 700)
+ATMOSPHERE = range(700, 800)
+CLEAR = range(800, 801)
+CLOUDY = range(801, 900)
+
+
+def read_user_cli_args():
+    """Handles the CLI user interactions.
+
+    Returns:
+        argparse.Namespace: Populated namespace object
+    """
+    parser = argparse.ArgumentParser(
+        description="gets weather and temperature information for a city"
+    )
+    parser.add_argument(
+        "City", metavar="city", nargs="+", type=str, help="enter the city name"
+    )
+    parser.add_argument(
+        "-i",
+        "--imperial",
+        action="store_true",
+        help="display the temperature in imperial units",
+    )
+    return parser.parse_args()
+
+
+def build_weather_query(city_input, imperial=False):
+    """Builds the URL for an API request to OpenWeather's Weather API.
+
+    Args:
+        city_input (List[str]): Name of a city as collected by argparse
+        imperial (bool): Whether or not to use imperial units for temperature
+
+    Returns:
+        str: URL formatted for a call to OpenWeather's city name endpoint
+    """
+    api_key = _get_api_key()
+    city_name = " ".join(city_input)
+    url_encoded_city_name = parse.quote_plus(city_name)
+    units = "imperial" if imperial else "metric"
+    url = (
+        f"{BASE_WEATHER_API_URL}?q={url_encoded_city_name}"
+        f"&units={units}&appid={api_key}"
+    )
+    return url
+
+
+def _get_api_key():
+    """Fetch the API key from your configuration file.
+
+    Expects a configuration file named "secrets.ini" with structure:
+
+        [openweather]
+        api_key=<YOUR-OPENWEATHER-API-KEY>
+    """
+    config = ConfigParser()
+    config.read("secrets.ini")
+    return config["openweather"]["api_key"]
+
+
+def get_weather_data(query_url):
+    """Makes an API request to a URL and returns the data as a Python object.
+
+    Args:
+        query_url (str): URL formatted for OpenWeather's city name endpoint
+
+    Returns:
+        dict: Weather information for a specific city
+    """
+    try:
+        response = request.urlopen(query_url)
+    except error.HTTPError as http_error:
+        if http_error.code == 401:  # 401 - Unauthorized
+            sys.exit("Access denied. Check your API key.")
+        elif http_error.code == 404:  # 404 - Not Found
+            sys.exit("Can't find weather data for this city.")
+        else:
+            sys.exit(f"Something went wrong... ({http_error.code})")
+
+    data = response.read()
+
+    try:
+        return json.loads(data)
+    except json.JSONDecodeError:
+        sys.exit("Couldn't read the server response.")
+
+
+def display_weather_info(weather_data, imperial=False):
+    """Prints formatted weather information about a city.
+
+    Args:
+        weather_data (dict): API response from OpenWeather by city name
+        imperial (bool): Whether or not to use imperial units for temperature
+
+    More information at https://openweathermap.org/current#name
+    """
+    city = weather_data["name"]
+    weather_id = weather_data["weather"][0]["id"]
+    weather_description = weather_data["weather"][0]["description"]
+    temperature = weather_data["main"]["temp"]
+
+    style.change_color(style.REVERSE)
+    print(f"{city:^{style.PADDING}}", end="")
+    style.change_color(style.RESET)
+
+    weather_symbol, color = _select_weather_display_params(weather_id)
+    style.change_color(color)
+
+    print(f"\t{weather_symbol}", end=" ")
+    print(
+        f"\t{weather_description.capitalize():^{style.PADDING}}",
+        end=" ",
+    )
+    style.change_color(style.RESET)
+
+    print(f"({temperature}°{'F' if imperial else 'C'})")
+
+
+def _select_weather_display_params(weather_id):
+    """Selects a weather symbol and a display color for a weather state.
+
+    Args:
+        weather_id (int): Weather condition code from the OpenWeather API
+
+    Returns:
+        tuple[str]: Contains a weather symbol and a display color
+    """
+    if weather_id in THUNDERSTORM:
+        display_params = ("💥", style.RED)
+    elif weather_id in DRIZZLE:
+        display_params = ("💧", style.CYAN)
+    elif weather_id in RAIN:
+        display_params = ("💦", style.BLUE)
+    elif weather_id in SNOW:
+        display_params = ("⛄️", style.WHITE)
+    elif weather_id in ATMOSPHERE:
+        display_params = ("🌀", style.BLUE)
+    elif weather_id in CLEAR:
+        display_params = ("🔆", style.YELLOW)
+    elif weather_id in CLOUDY:
+        display_params = ("💨", style.WHITE)
+    else:  # In case the API adds new weather codes
+        display_params = ("🌈", style.RESET)
+    return display_params
+
+
+if __name__ == "__main__":
+    user_args = read_user_cli_args()
+    query_url = build_weather_query(user_args.City, user_args.imperial)
+    weather_data = get_weather_data(query_url)
+    display_weather_info(weather_data, user_args.imperial)

weather-app/source_code_step_1/README.md

@@ -0,0 +1,3 @@
+There is no code here!
+
+This step is all about obtaining your API key.

weather-app/source_code_step_2/.gitignore

@@ -0,0 +1 @@
+secrets.ini

weather-app/source_code_step_2/weather.py

@@ -0,0 +1,14 @@
+from configparser import ConfigParser
+
+
+def _get_api_key():
+    """Fetch the API key from your configuration file.
+
+    Expects a configuration file named "secrets.ini" with structure:
+
+        [openweather]
+        api_key=<YOUR-OPENWEATHER-API-KEY>
+    """
+    config = ConfigParser()
+    config.read("secrets.ini")
+    return config["openweather"]["api_key"]

weather-app/source_code_step_3/.gitignore

@@ -0,0 +1 @@
+secrets.ini

weather-app/source_code_step_3/weather.py

@@ -0,0 +1,41 @@
+import argparse
+from configparser import ConfigParser
+
+
+def read_user_cli_args():
+    """Handles the CLI user interactions.
+
+    Returns:
+        argparse.Namespace: Populated namespace object
+    """
+    parser = argparse.ArgumentParser(
+        description="gets weather and temperature information for a city"
+    )
+    parser.add_argument(
+        "City", metavar="city", nargs="+", type=str, help="enter the city name"
+    )
+    parser.add_argument(
+        "-i",
+        "--imperial",
+        action="store_true",
+        help="display the temperature in imperial units",
+    )
+    return parser.parse_args()
+
+
+def _get_api_key():
+    """Fetch the API key from your configuration file.
+
+    Expects a configuration file named "secrets.ini" with structure:
+
+        [openweather]
+        api_key=<YOUR-OPENWEATHER-API-KEY>
+    """
+    config = ConfigParser()
+    config.read("secrets.ini")
+    return config["openweather"]["api_key"]
+
+
+if __name__ == "__main__":
+    user_args = read_user_cli_args()
+    print(user_args.City, user_args.imperial)

weather-app/source_code_step_4/.gitignore

@@ -0,0 +1 @@
+secrets.ini