Code cleanup/refactor, docstrings

src/api.py

@@ -50,7 +50,8 @@ def default_location():
 
 def get_uv(lat, long, decimal, unit="imperial"):
     """
-    Get UV at coordinates
+    Get UV at coordinates (lat, long)
+    Calling the API here: https://open-meteo.com/en/docs
     """
     # Setup the Open-Meteo API client with cache and retry on error
     cache_session = requests_cache.CachedSession(".cache", expire_after=3600)
@@ -81,6 +82,7 @@ def get_uv(lat, long, decimal, unit="imperial"):
 def ocean_information(lat, long, decimal, unit="imperial"):
     """
     Get Ocean Data at coordinates
+    API: https://open-meteo.com/en/docs/marine-weather-api
     """
     # Setup the Open-Meteo API client with cache and retry on error
     cache_session = requests_cache.CachedSession(".cache", expire_after=3600)
@@ -119,6 +121,7 @@ def ocean_information(lat, long, decimal, unit="imperial"):
 def forecast(lat, long, decimal, days=0):
     """
     Number of forecast days. Max is 7
+    API: https://open-meteo.com/en/docs/marine-weather-api
     """
     # Setup the Open-Meteo API client with cache and retry on error
     cache_session = requests_cache.CachedSession(".cache", expire_after=3600)
@@ -169,35 +172,43 @@ def forecast(lat, long, decimal, days=0):
     ]
 
 
-def gather_data(lat, long, ocean):
+def gather_data(lat, long, arguments):
     """
-    Calls APIs though python files
+    Calls APIs though python files,
+    returns all the ocean data(height, period...)
+    in a dictionary (ocean_data_dict)
     """
-    ocean_data = ocean_information(lat, long, ocean["decimal"], ocean["unit"])
-    uv_index = get_uv(lat, long, ocean["decimal"], ocean["unit"])
+    lat, long = float(lat), float(long)
+    ocean_data = ocean_information(
+        lat, long, arguments["decimal"], arguments["unit"]
+    )
+    uv_index = get_uv(lat, long, arguments["decimal"], arguments["unit"])
 
-    ocean["ocean_data"] = ocean_data
-    ocean["uv_index"] = uv_index
-    spot_forecast = forecast(lat, long, ocean["decimal"], 7)
-    json_forecast = helper.forecast_to_json(spot_forecast, ocean["decimal"])
+    arguments["ocean_data"] = ocean_data
+    arguments["uv_index"] = uv_index
+    spot_forecast = forecast(lat, long, arguments["decimal"], 7)
+    json_forecast = helper.forecast_to_json(
+        spot_forecast, arguments["decimal"]
+    )
 
-    data_dict = {
+    ocean_data_dict = {
         "Lat": lat,
         "Long": long,
-        "Location": ocean["city"],
+        "Location": arguments["city"],
         "Height": ocean_data[0],
         "Direction": ocean_data[1],
         "Period": ocean_data[2],
         "UV Index": uv_index,
         "Forecast": json_forecast,
-        "Unit": ocean["unit"],
+        "Unit": arguments["unit"],
     }
-    return data_dict
+    return ocean_data_dict
 
 
 def seperate_args_and_get_location(args):
     """
-    Gets user's coordinates from either the argument(location=) or, if none,
+    Gets user's coordinates from either
+    the argument(location=) or, if none,
     the default coordinates(default_location())
     """
     coordinates = get_coordinates(args)

src/cli.py

@@ -25,31 +25,28 @@ def run(lat=0, long=0):
     #  return coordinates, lat, long, city
     location = api.seperate_args_and_get_location(args)
 
+    # Set location returns: city, lat, long
     set_location = helper.set_location(location)
     city = set_location[0]
 
     # Check if lat and long are set to defaults(no argumentes passed in main())
     if lat == 0 and long == 0:
         lat, long = set_location[1], set_location[2]
 
-    # Sets ocean = dictionary with
+    # Sets arguments = dictionary with all the CLI args(show_wave, city, ect.)
     arguments = helper.arguments_dictionary(lat, long, city, args)
-    # Updates the ocean dict with the valeus from the arguments
-    arguments = helper.set_output_values(args, arguments)
 
-    lat = float(lat)
-    long = float(long)
-    # Makes calls to the apis(ocean, UV) and returns the values
-    data_dict = api.gather_data(lat, long, arguments)
+    # Makes calls to the apis(ocean, UV) and returns the values in a dictionary
+    ocean_data_dict = api.gather_data(lat, long, arguments)
 
     # Non-JSON output
     if arguments["json_output"] == 0:
-        helper.print_outputs(city, data_dict, arguments, gpt_prompt, gpt_info)
-        return data_dict
-    # JSON Output
+        helper.print_outputs(
+            city, ocean_data_dict, arguments, gpt_prompt, gpt_info
+        )
     else:
-        json_output = helper.json_output(data_dict)
-        return json_output
+        # print the output in json format!
+        helper.json_output(ocean_data_dict)
 
 
 if __name__ == "__main__":

src/helper.py

@@ -34,6 +34,40 @@ def arguments_dictionary(lat, long, city, args):
         "color": get_color(args),
         "gpt": 0,
     }
+    # Updates the arguments dict with the values from the CLI args
+    arguments = set_output_values(args, arguments)
+    return arguments
+
+
+def set_output_values(args, arguments):
+    """
+    Takes a list of command line arguments(args)
+    and sets the appropritate values
+    in the arguments dictionary(show_wave = 1, etc).
+    Returns the arguments dict with the updated CLI args
+    """
+    if "hide_wave" in args or "hw" in args:
+        arguments["show_wave"] = 0
+    if "show_large_wave" in args or "slw" in args:
+        arguments["show_large_wave"] = 1
+    if "hide_uv" in args or "huv" in args:
+        arguments["show_uv"] = 0
+    if "hide_height" in args or "hh" in args:
+        arguments["show_height"] = 0
+    if "hide_direction" in args or "hdir" in args:
+        arguments["show_direction"] = 0
+    if "hide_period" in args or "hp" in args:
+        arguments["show_period"] = 0
+    if "hide_location" in args or "hl" in args:
+        arguments["show_city"] = 0
+    if "hide_date" in args or "hdate" in args:
+        arguments["show_date"] = 0
+    if "metric" in args or "m" in args:
+        arguments["unit"] = "metric"
+    if "json" in args or "j" in args:
+        arguments["json_output"] = 1
+    if "gpt" in args or "g" in args:
+        arguments["gpt"] = 1
     return arguments
 
 
@@ -72,9 +106,9 @@ def print_location(city, show_city):
         print("\n")
 
 
-def print_output(ocean_data_dict):
+def print_ocean_data(ocean_data_dict):
     """
-    Prints output
+    Prints ocean data(height, wave direction, period, etc)
     """
     if int(ocean_data_dict["show_uv"]) == 1:
         print("UV index: ", ocean_data_dict["uv_index"])
@@ -140,37 +174,6 @@ def round_decimal(round_list, decimal):
     return rounded_list
 
 
-def set_output_values(args, ocean):
-    """
-    Takes a list of command line arguments(args)
-    and sets the appropritate values
-    in the ocean dictionary(show_wave = 1, etc)
-    """
-    if "hide_wave" in args or "hw" in args:
-        ocean["show_wave"] = 0
-    if "show_large_wave" in args or "slw" in args:
-        ocean["show_large_wave"] = 1
-    if "hide_uv" in args or "huv" in args:
-        ocean["show_uv"] = 0
-    if "hide_height" in args or "hh" in args:
-        ocean["show_height"] = 0
-    if "hide_direction" in args or "hdir" in args:
-        ocean["show_direction"] = 0
-    if "hide_period" in args or "hp" in args:
-        ocean["show_period"] = 0
-    if "hide_location" in args or "hl" in args:
-        ocean["show_city"] = 0
-    if "hide_date" in args or "hdate" in args:
-        ocean["show_date"] = 0
-    if "metric" in args or "m" in args:
-        ocean["unit"] = "metric"
-    if "json" in args or "j" in args:
-        ocean["json_output"] = 1
-    if "gpt" in args or "g" in args:
-        ocean["gpt"] = 1
-    return ocean
-
-
 def json_output(data_dict):
     """
     If JSON=TRUE in .args, we print and return the JSON data
@@ -192,21 +195,25 @@ def print_outputs(city, data_dict, arguments, gpt_prompt, gpt_info):
         print(data_dict["Lat"], data_dict["Long"])
         print("No ocean data at this location.")
     else:
+        # Location is found, print details
         print_location(arguments["city"], arguments["show_city"])
         art.print_wave(
             arguments["show_wave"],
             arguments["show_large_wave"],
             arguments["color"],
         )
-        print_output(arguments)
+        # Prints(Height: <>, Period: <>, etc.)
+        print_ocean_data(arguments)
     print("\n")
     forecast = api.forecast(
         data_dict["Lat"],
         data_dict["Long"],
         arguments["decimal"],
         arguments["forecast_days"],
     )
+    # Prints the forecast(if activated in CLI args)
     print_forecast(arguments, forecast)
+    # Checks if GPT in args, prints GPT response if True
     if arguments["gpt"] == 1:
         gpt_response = print_gpt(data_dict, gpt_prompt, gpt_info)
         print(gpt_response)
@@ -244,7 +251,7 @@ def forecast_to_json(data, decimal):
 def surf_summary(surf_data):
     """
     Outputs a simple summary of the surf data.
-    Useful for the GPT
+    Useed by the GPT as input
     """
     location = surf_data["Location"]
     height = surf_data["Height"]