windborne 1.1.0__py3-none-any.whl → 1.1.2__py3-none-any.whl

windborne/api_request.py

@@ -199,8 +199,7 @@ def make_api_request(url, params=None, as_json=True, retry_counter=0):
                     mission_id = url.split('/missions/')[1].split('/')[0]
                     print(f"Mission ID provided: {mission_id}")
                     print(f"No mission found with id: {mission_id}")
-                    return None
-
+            return None
         elif http_err.response.status_code == 502:
             print(f"Temporary connection failure; sleeping for {2**retry_counter}s before retrying")
             print(f"Underlying error: 502 Bad Gateway")

windborne/cli.py

@@ -139,7 +139,7 @@ def main():
     points_parser.add_argument('-mh','--min-hour', type=int, help='Minimum forecast hour')
     points_parser.add_argument('-xh','--max-hour', type=int, help='Maximum forecast hour')
     points_parser.add_argument('-i', '--init-time', help='Initialization time')
-    points_parser.add_argument('output_file', help='Output file')
+    points_parser.add_argument('output_file', nargs='?', help='Output file')
 
     # GRIDDED FORECASTS
     ####################################################################################################################
@@ -210,9 +210,9 @@ def main():
     ####################################################################################################################
 
     # Tropical Cyclones Command
-    cyclones_parser = subparsers.add_parser('cyclones', help='Get tropical cyclone forecasts')
-    cyclones_parser.add_argument('-b', '--basin',  help='Optional: filter tropical cyclones on basin[ NA, EP, WP, NI, SI, AU, SP]')
-    cyclones_parser.add_argument('args', nargs='*',
+    tropical_cyclones_parser = subparsers.add_parser('tropical_cyclones', help='Get tropical cyclone forecasts')
+    tropical_cyclones_parser.add_argument('-b', '--basin',  help='Optional: filter tropical cyclones on basin[ NA, EP, WP, NI, SI, AU, SP]')
+    tropical_cyclones_parser.add_argument('args', nargs='*',
                                  help='[optional: initialization time (YYYYMMDDHH, YYYY-MM-DDTHH, or YYYY-MM-DDTHH:mm:ss)] output_file')
 
     # Initialization Times Command
@@ -365,12 +365,13 @@ def main():
             )
 
     elif args.command == 'flying-missions':
-        get_flying_missions(from_cli=True, output_file=args.output)
+        get_flying_missions(output_file=args.output, print_results=(not args.output))
 
     elif args.command == 'launch-site':
         get_mission_launch_site(
             mission_id=args.mission_id,
-            output_file=args.output
+            output_file=args.output,
+            print_result=(not args.output)
         )
 
     elif args.command == 'predict-path':
@@ -395,15 +396,12 @@ def main():
             min_forecast_hour=min_forecast_hour,
             max_forecast_hour=max_forecast_hour,
             initialization_time=initialization_time,
-            output_file=args.output_file
+            output_file=args.output_file,
+            print_response=(not args.output_file)
         )
 
     elif args.command == 'init_times':
-        if get_initialization_times():
-            print("Available initialization times for point forecasts:\n")
-            pprint(get_initialization_times())
-        else:
-            print("We can't currently display available initialization times for point forecasts:\n")
+        get_initialization_times(print_response=True)
 
     elif args.command == 'grid_temp_2m':
         # Parse grid_temp_2m arguments
@@ -588,39 +586,28 @@ def main():
             print("Too many arguments")
             print("\nUsage: windborne hist_500hpa_wind_v initialization_time forecast_hour output_file")
 
-    elif args.command == 'cyclones':
+    elif args.command == 'tropical_cyclones':
         # Parse cyclones arguments
-        basin_name = 'ALL basins'
+        basin_name = 'all basins'
         if args.basin:
             basin_name = f"{args.basin} basin"
-            print(f"Checking for tropical cyclones only within {args.basin} basin\n")
 
         if len(args.args) == 0:
-            print("Loading tropical cyclones for our latest available initialization time\n")
-            if get_tropical_cyclones(basin=args.basin):
-                print(f"Found {len(get_tropical_cyclones())} cyclone(s)\n")
-                pprint(get_tropical_cyclones(basin=args.basin))
-                return
-            else:
-                print("There are no active tropical cyclones for our latest available initialization time.")
+            get_tropical_cyclones(basin=args.basin, print_response=True)
+            return
         elif len(args.args) == 1:
             if '.' in args.args[0]:
                 # Save tcs with the latest available initialization time in filename
                 get_tropical_cyclones(basin=args.basin, output_file=args.args[0])
             else:
                 # Display tcs for selected initialization time
-                if get_tropical_cyclones(initialization_time=args.args[0], basin=args.basin):
-                    print(f"Loading tropical cyclones for initialization time {args.args[0]}\n")
-                    print(f"Found {len(get_tropical_cyclones(initialization_time=args.args[0]))} cyclone(s)\n")
-                    pprint(get_tropical_cyclones(initialization_time=args.args[0], basin=args.basin))
-                else:
-                    print(f"No active tropical cyclones for {basin_name} and {args.args[0]} initialization time.")
+                get_tropical_cyclones(initialization_time=args.args[0], basin=args.basin, print_response=True)
         elif len(args.args) == 2:
             print(f"Saving tropical cyclones for initialization time {args.args[0]} and {basin_name}\n")
             get_tropical_cyclones(initialization_time=args.args[0], basin=args.basin, output_file=args.args[1])
         else:
             print("Error: Too many arguments")
-            print("Usage: windborne cyclones [initialization_time] output_file")
+            print("Usage: windborne tropical_cyclones [initialization_time] output_file")
 
     else:
         parser.print_help()

windborne/data_api.py

@@ -6,7 +6,7 @@ import json
 
 from .api_request import make_api_request
 from .observation_formatting import format_little_r, convert_to_netcdf
-from .utils import to_unix_timestamp, save_arbitrary_response
+from .utils import to_unix_timestamp, save_arbitrary_response, print_table
 
 DATA_API_BASE_URL = "https://sensor-data.windbornesystems.com/api/v1"
 
@@ -257,6 +257,9 @@ def get_observations_core(api_args, csv_headers, get_page, start_time=None, end_
     For example, for 6-hour buckets centered on 00 UTC, the start time should be 21 UTC of the previous day.
 
     Args:
+        api_args (dict): Arguments to pass to the API endpoint.
+        csv_headers (list): Headers for CSV files.
+        get_page (callable): Function to fetch a page of observations.
         start_time (str): A date string, supporting formats YYYY-MM-DD HH:MM:SS, YYYY-MM-DD_HH:MM and ISO strings,
                           representing the starting time of fetching data.
         end_time (str): Optional. A date string, supporting formats YYYY-MM-DD HH:MM:SS, YYYY-MM-DD_HH:MM and ISO strings,
@@ -531,7 +534,7 @@ def poll_super_observations(**kwargs):
 # ------------
 # METADATA
 # ------------
-def get_flying_missions(from_cli=None, output_file=None):
+def get_flying_missions(output_file=None, print_results=False):
     """
     Retrieves a list of currently flying missions.
     In CLI mode, displays missions in a formatted table.
@@ -539,6 +542,7 @@ def get_flying_missions(from_cli=None, output_file=None):
     Args:
         output_file (str): Optional path to save the response data.
                            If provided, saves the data in CSV or JSON format.
+        print_results (bool): Whether to print the results in the CLI.
 
     Returns:
         dict: The API response containing list of flying missions.
@@ -549,35 +553,47 @@ def get_flying_missions(from_cli=None, output_file=None):
     flying_missions = flying_missions_response.get("missions", [])
 
     # Display currently flying missions only if we are in cli and we don't save info in file
-    if flying_missions and from_cli and not output_file:
-        print("Currently flying missions:\n")
-
-        # Define headers and data
-        headers = ["Index", "Mission ID", "Mission Name"]
-        rows = [
-            [str(i), mission.get("id", "N/A"), mission.get("name", "Unnamed Mission")]
-            for i, mission in enumerate(flying_missions, start=1)
-        ]
-
-        # Kinda overkill | but it's a good practice if we ever change missions naming convention
-        # Calculate column widths
-        col_widths = [max(len(cell) for cell in col) + 2 for col in zip(headers, *rows)]
-
-        # Display table
-        print("".join(f"{headers[i]:<{col_widths[i]}}" for i in range(len(headers))))
-        print("".join("-" * col_width for col_width in col_widths))
-        for row in rows:
-            print("".join(f"{row[i]:<{col_widths[i]}}" for i in range(len(row))))
+    if print_results:
+        if flying_missions:
+            print("Currently flying missions:\n")
+
+            # Define headers and data
+            headers = ["Index", "Mission ID", "Mission Name"]
+            rows = [
+                [str(i), mission.get("id", "N/A"), mission.get("name", "Unnamed Mission")]
+                for i, mission in enumerate(flying_missions, start=1)
+            ]
+
+            # Kinda overkill | but it's a good practice if we ever change missions naming convention
+            # Calculate column widths
+            col_widths = [max(len(cell) for cell in col) + 2 for col in zip(headers, *rows)]
+
+            # Display table
+            print("".join(f"{headers[i]:<{col_widths[i]}}" for i in range(len(headers))))
+            print("".join("-" * col_width for col_width in col_widths))
+            for row in rows:
+                print("".join(f"{row[i]:<{col_widths[i]}}" for i in range(len(row))))
+        else:
+            print("No missions are currently flying.")
 
     if output_file:
         save_arbitrary_response(output_file, flying_missions_response, csv_data_key='missions')
     
-    return flying_missions_response
+    return flying_missions
 
 
-def get_mission_launch_site(mission_id=None, output_file=None):
+def get_mission_launch_site(mission_id=None, output_file=None, print_result=False):
     """
     Retrieves launch site information for a specified mission.
+
+    Args:
+        mission_id (str): The ID of the mission to fetch the launch site for.
+        output_file (str): Optional path to save the response data.
+                           If provided, saves the data in CSV format.
+        print_result (bool): Whether to print the results in the CLI.
+
+    Returns:
+        dict: The API response containing the launch site information.
     """
     if not mission_id:
         print("Must provide mission ID")
@@ -586,7 +602,7 @@ def get_mission_launch_site(mission_id=None, output_file=None):
     url = f"{DATA_API_BASE_URL}/missions/{mission_id}/launch_site.json"
     response = make_api_request(url)
 
-    if response and not output_file:
+    if response and print_result:
         launch_site = response.get('launch_site')
         if isinstance(launch_site, dict):
             print("Mission launch site\n")
@@ -599,7 +615,7 @@ def get_mission_launch_site(mission_id=None, output_file=None):
     if output_file:
         save_arbitrary_response(output_file, response, csv_data_key='launch_site')
 
-    return response
+    return response.get('launch_site')
 
 def get_predicted_path(mission_id=None, output_file=None):
     """
@@ -612,7 +628,7 @@ def get_predicted_path(mission_id=None, output_file=None):
                                If provided, saves the data in CSV format.
 
         Returns:
-            dict: The API response containing the predicted flight path data.
+            list: The API response containing the predicted flight path data.
     """
     if not mission_id:
         print("To get the predicted flight path for a given mission you must provide a mission ID.")
@@ -629,22 +645,7 @@ def get_predicted_path(mission_id=None, output_file=None):
         if flying_missions:
             print("\nCurrently flying missions:\n")
 
-            # Define headers and data
-            headers = ["Index", "Mission ID", "Mission Name"]
-            rows = [
-                [str(i), mission.get("id", "N/A"), mission.get("name", "Unnamed Mission")]
-                for i, mission in enumerate(flying_missions, start=1)
-            ]
-
-            # Kinda overkill | but it's a good practice if we ever change missions naming convention
-            # Calculate column widths
-            col_widths = [max(len(cell) for cell in col) + 2 for col in zip(headers, *rows)]
-
-            # Display table
-            print("".join(f"{headers[i]:<{col_widths[i]}}" for i in range(len(headers))))
-            print("".join("-" * col_width for col_width in col_widths))
-            for row in rows:
-                print("".join(f"{row[i]:<{col_widths[i]}}" for i in range(len(row))))
+            print_table(flying_missions, keys=['i', 'id', 'name'], headers=['Index', 'Mission ID', 'Mission Name'])
         else:
             print("No missions are currently flying.")
         return
@@ -655,4 +656,4 @@ def get_predicted_path(mission_id=None, output_file=None):
     if output_file:
         save_arbitrary_response(output_file, response, csv_data_key='prediction')
     
-    return response
+    return response.get('prediction')

windborne/forecasts_api.py

@@ -1,8 +1,10 @@
 import requests
+import json
 
 from .utils import (
     parse_time,
-    save_arbitrary_response
+    save_arbitrary_response,
+    print_table
 )
 
 from .api_request import (
@@ -24,7 +26,7 @@ TCS_SUPPORTED_FORMATS = ('.csv', '.json', '.geojson', '.gpx', '.kml', 'little_r'
 
 
 # Point forecasts
-def get_point_forecasts(coordinates, min_forecast_time=None, max_forecast_time=None, min_forecast_hour=None, max_forecast_hour=None, initialization_time=None, output_file=None):
+def get_point_forecasts(coordinates, min_forecast_time=None, max_forecast_time=None, min_forecast_hour=None, max_forecast_hour=None, initialization_time=None, output_file=None, print_response=False):
     """
     Get point forecasts from the API.
 
@@ -38,6 +40,7 @@ def get_point_forecasts(coordinates, min_forecast_time=None, max_forecast_time=N
         initialization_time (str, optional): Initialization time in ISO 8601 format (YYYY-MM-DDTHH:00:00)
         output_file (str, optional): Path to save the response data
                                       Supported formats: .json, .csv
+        print_response (bool, optional): Whether to print the response data
     """
 
     # coordinates should be formatted as a semi-colon separated list of latitude,longitude tuples, eg 37,-121;40.3,-100
@@ -91,13 +94,25 @@ def get_point_forecasts(coordinates, min_forecast_time=None, max_forecast_time=N
         initialization_time = parse_time(initialization_time,init_time_flag=True)
         params["initialization_time"] = initialization_time
 
-    print("Generating point forecast...")
+    if print_response:
+        print("Generating point forecast...")
 
     response = make_api_request(f"{FORECASTS_API_BASE_URL}/points", params=params)
 
     if output_file:
         save_arbitrary_response(output_file, response, csv_data_key='forecasts')
 
+    if print_response:
+        unformatted_coordinates = formatted_coordinates.split(';')
+
+        keys = ['time', 'temperature_2m', 'dewpoint_2m', 'wind_u_10m', 'wind_v_10m', 'precipitation', 'pressure_msl']
+        headers = ['Time', '2m Temperature (°C)', '2m Dewpoint (°C)', 'Wind U (m/s)', 'Wind V (m/s)', 'Precipitation (mm)', 'MSL Pressure (hPa)']
+
+        for i in range(len(response['forecasts'])):
+            latitude, longitude = unformatted_coordinates[i].split(',')
+            print(f"\nForecast for ({latitude}, {longitude})")
+            print_table(response['forecasts'][i], keys=keys, headers=headers)
+
     return response
 
 
@@ -126,6 +141,9 @@ def get_gridded_forecast(time, variable, output_file=None):
 
     response = make_api_request(f"{FORECASTS_GRIDDED_URL}/{variable}", params=params, as_json=False)
 
+    if response is None:
+        return None
+
     if output_file:
         print(f"Output URL found; downloading to {output_file}...")
         download_and_save_output(output_file, response)
@@ -181,6 +199,9 @@ def get_historical_output(initialization_time, forecast_hour, variable, output_f
 
     response = make_api_request(f"{FORECASTS_HISTORICAL_URL}/{variable}", params=params, as_json=False)
 
+    if response is None:
+        return None
+
     if output_file:
         print(f"Output URL found; downloading to {output_file}...")
         download_and_save_output(output_file, response)
@@ -201,7 +222,7 @@ def get_historical_500hpa_wind_v(initialization_time, forecast_hour, output_file
     return get_historical_output(initialization_time, forecast_hour, "500/wind_v", output_file)
 
 
-def get_tropical_cyclones(initialization_time=None, basin=None, output_file=None):
+def get_tropical_cyclones(initialization_time=None, basin=None, output_file=None, print_response=False):
     """
     Get tropical cyclone data from the API.
 
@@ -209,8 +230,10 @@ def get_tropical_cyclones(initialization_time=None, basin=None, output_file=None
         initialization_time (str): Date in either ISO 8601 format (YYYY-MM-DDTHH:00:00)
                                  or compact format (YYYYMMDDHH)
                                  where HH must be 00, 06, 12, or 18
+        basin (str, optional): Basin code (e.g., 'NA', 'EP', 'WP', 'NI', 'SI', 'AU', 'SP')
         output_file (str, optional): Path to save the response data
                                       Supported formats: .json, .csv, .gpx, .geojson, .kml, .little_r
+        print_response (bool, optional): Whether to print the response data
 
     Returns:
         dict: API response data or None if there's an error
@@ -221,7 +244,6 @@ def get_tropical_cyclones(initialization_time=None, basin=None, output_file=None
         initialization_time_parsed = parse_time(initialization_time, init_time_flag=True)
         params["initialization_time"] = initialization_time_parsed
     else:
-        # Madee this for our displaying message when no active tcs found
         initialization_time = 'latest'
 
     if basin:
@@ -286,10 +308,19 @@ def get_tropical_cyclones(initialization_time=None, basin=None, output_file=None
         elif output_file.lower().endswith('.little_r'):
             save_track_as_little_r(output_file, response)
 
+    if print_response:
+        if len(response) == 0:
+            print("No tropical cyclones for initialization time:", initialization_time)
+        else:
+            print("Tropical Cyclones for initialization time:", initialization_time)
+            for cyclone_id, tracks in response.items():
+                print(f"\nCyclone ID: {cyclone_id}")
+                print_table(tracks, keys=['time', 'latitude', 'longitude'], headers=['Time', 'Latitude', 'Longitude'])
+
     return response
 
 
-def get_initialization_times():
+def get_initialization_times(print_response=False):
     """
     Get available WeatherMesh initialization times (also known as cycle times).
 
@@ -298,6 +329,12 @@ def get_initialization_times():
 
     response = make_api_request(f"{FORECASTS_API_BASE_URL}/initialization_times.json")
 
+    if print_response:
+        print("Latest initialization time:", response['latest'])
+        print("Available initialization times:")
+        for time in response['available']:
+            print(f" - {time}")
+
     return response
 
 

windborne/utils.py

@@ -46,7 +46,7 @@ def to_unix_timestamp(date_string):
 
 # Supported date format
 # Compact format YYYYMMDDHH
-def parse_time(time, init_time_flag=None):
+def parse_time(time, init_time_flag=None, require_past=False):
     """
     Parse and validate initialization time with support for multiple formats.
     Returns validated initialization time in ISO format, or None if invalid.
@@ -78,10 +78,9 @@ def parse_time(time, init_time_flag=None):
                 print("  - Initialization time hour must be 00, 06, 12, or 18")
                 exit(2)
 
-        if parsed_date > datetime.now():
-            print(f"How would it be to live in {parsed_date} ?\n")
-            print("Looks like you are coming from the future!\n")
-            exit(1111)
+        if require_past and parsed_date > datetime.now():
+            print(f"Invalid date: {time} -- cannot be in the future")
+            exit(2)
 
         return parsed_date.strftime('%Y-%m-%dT%H:00:00')
 
@@ -158,3 +157,33 @@ def save_arbitrary_response(output_file, response, csv_data_key=None):
     else:
         print("Unsupported file format. Please use either .json or .csv.")
         exit(4)
+
+
+def print_table(data, keys=None, headers=None):
+    if len(data) == 0:
+        print("No data found")
+        return
+
+    if keys is None:
+        keys = list(data[0].keys())
+
+    if headers is None:
+        headers = keys
+
+    # headers = ["Index", "Mission ID", "Mission Name"]
+    rows = [
+        [
+            str(value.get(key)) if key != 'i' else str(i)
+            for key in keys
+        ]
+        for i, value in enumerate(data, start=1)
+    ]
+
+    # Calculate column widths
+    col_widths = [max(len(cell) for cell in col) + 2 for col in zip(headers, *rows)]
+
+    # Display table
+    print("".join(f"{headers[i]:<{col_widths[i]}}" for i in range(len(headers))))
+    print("".join("-" * col_width for col_width in col_widths))
+    for row in rows:
+        print("".join(f"{row[i]:<{col_widths[i]}}" for i in range(len(row))))

{windborne-1.1.0.dist-info → windborne-1.1.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: windborne
-Version: 1.1.0
+Version: 1.1.2
 Summary: A Python library for interacting with WindBorne Data and Forecasts API
 Author-email: WindBorne Systems <data@windbornesystems.com>
 Classifier: Programming Language :: Python :: 3

windborne-1.1.2.dist-info/RECORD

@@ -0,0 +1,13 @@
+windborne/__init__.py,sha256=0bPtPzBG3djZMVfyUNhapiEqCSyN8SSDsm_eCZ4kwhc,1783
+windborne/api_request.py,sha256=zh1TaaZAaRfAXp2NYMja75fKeduWLfao02JRRFVpQCA,11108
+windborne/cli.py,sha256=XvI9a9mO921a_LpI1ojN9Rn_x3sYq3XTkmUUT37wg4g,34835
+windborne/cyclone_formatting.py,sha256=0S8S_PflRGm6ftUlyR2aGGyX6IRn0hbUTEWptu7f8Q8,7886
+windborne/data_api.py,sha256=qVA0UGcnkBGYe8TFgqgFlFjZYCsS4ly1IL97tSpgKgI,29751
+windborne/forecasts_api.py,sha256=QzdayDr3MaswsFibOdBoo6SCdRY86eE2E7kWqn-Jc1Y,15479
+windborne/observation_formatting.py,sha256=c739aaun6aaYhXl5VI-SRGR-TDS355_0Bfu1t6McoiM,14993
+windborne/utils.py,sha256=H8gvZ4Lrr0UmLl25iMZs6NsZliCY_73Ved_rBIqxJg4,7240
+windborne-1.1.2.dist-info/METADATA,sha256=NR1lkRL5m-j3UoWVj_2ti14bSrIXZLtCbwS4DfUvko0,1235
+windborne-1.1.2.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
+windborne-1.1.2.dist-info/entry_points.txt,sha256=j_YrqdCDrCd7p5MIwQ2BYwNXEi95VNANzLRJmcXEg1U,49
+windborne-1.1.2.dist-info/top_level.txt,sha256=PE9Lauriu5S5REf7JKhXprufZ_V5RiZ_TnfnrLGJrmE,10
+windborne-1.1.2.dist-info/RECORD,,

windborne-1.1.0.dist-info/RECORD

@@ -1,13 +0,0 @@
-windborne/__init__.py,sha256=0bPtPzBG3djZMVfyUNhapiEqCSyN8SSDsm_eCZ4kwhc,1783
-windborne/api_request.py,sha256=J7kcCC3xiISHnrTLxMkFQCEu8rg8UntYvFfP5wkLabQ,11117
-windborne/cli.py,sha256=JqIjVXwZr_x9kuHYlXm45XYvl7NJBBckn-R69qne2Q8,35745
-windborne/cyclone_formatting.py,sha256=0S8S_PflRGm6ftUlyR2aGGyX6IRn0hbUTEWptu7f8Q8,7886
-windborne/data_api.py,sha256=rAcXUunz1lGOtxx59ID5Ki4thdGbtCl-aAw0DeVuouo,29645
-windborne/forecasts_api.py,sha256=-IM78Dr10rV-CKVqRWXpptJPe7Hh64DNMO3P3zVgvuQ,13790
-windborne/observation_formatting.py,sha256=c739aaun6aaYhXl5VI-SRGR-TDS355_0Bfu1t6McoiM,14993
-windborne/utils.py,sha256=AJhvdwtfDrV0NQyN_I5JxXr6K3UgFlPCwUGqApe-c2E,6431
-windborne-1.1.0.dist-info/METADATA,sha256=2LBcuwXPOXfguHSqGFqQtg2GgGi6adNtjyENNUF3swQ,1235
-windborne-1.1.0.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
-windborne-1.1.0.dist-info/entry_points.txt,sha256=j_YrqdCDrCd7p5MIwQ2BYwNXEi95VNANzLRJmcXEg1U,49
-windborne-1.1.0.dist-info/top_level.txt,sha256=PE9Lauriu5S5REf7JKhXprufZ_V5RiZ_TnfnrLGJrmE,10
-windborne-1.1.0.dist-info/RECORD,,