windborne 1.2.3__py3-none-any.whl → 1.2.5__py3-none-any.whl

windborne/__init__.py

@@ -39,7 +39,9 @@ from .forecasts_api import (
     get_historical_500hpa_geopotential,
     get_historical_500hpa_wind_u, get_historical_500hpa_wind_v,
 
-    get_tropical_cyclones
+    get_tropical_cyclones,
+
+    get_population_weighted_hdd
 )
 
 # Define what should be available when users import *
@@ -82,5 +84,7 @@ __all__ = [
     "get_historical_500hpa_geopotential",
     "get_historical_500hpa_wind_u",
     "get_historical_500hpa_wind_v",
-    "get_tropical_cyclones"
+    "get_tropical_cyclones",
+
+    "get_population_weighted_hdd"
 ]

windborne/api_request.py

@@ -21,99 +21,62 @@ def get_api_credentials():
 
 def verify_api_credentials(client_id, api_key):
     if not client_id and not api_key:
-        print("To access the WindBorne API, set your Client ID and API key by setting the environment variables WB_CLIENT_ID and WB_API_KEY.")
-        print("--------------------------------------")
-        print("You may refer to https://windbornesystems.com/docs/api/cli#introduction\n"
-              "for instructions on how to set your credentials as environment variables for CLI and Code usage\n\n"
-              "and to https://windbornesystems.com/docs/api/pip_data#introduction\n"
-              "for instruction on how to set your credentials for code usage.")
-        print("--------------------------------------")
-        print("To get an API key, email data@windbornesystems.com.")
-        exit(80)
+        raise ValueError(
+            "To access the WindBorne API, set your Client ID and API key by setting the environment variables WB_CLIENT_ID and WB_API_KEY. "
+            "For instructions, refer to https://windbornesystems.com/docs/api/cli#introduction or https://windbornesystems.com/docs/api/pip_data#introduction. "
+            "To get an API key, email data@windbornesystems.com."
+        )
 
     if not client_id:
-        print("To access the WindBorne API, you need to set your Client ID by setting the environment variable WB_CLIENT_ID.")
-        print("--------------------------------------")
-        print("You may refer to https://windbornesystems.com/docs/api/cli#introduction\n"
-              "for instructions on how to set your credentials as environment variables for CLI and Code usage\n\n"
-              "and to https://windbornesystems.com/docs/api/pip_data#introduction\n"
-              "for instruction on how to set your credentials for code usage.")
-        print("--------------------------------------")
-        print("To get an API key, email data@windbornesystems.com.")
-        exit(90)
+        raise ValueError(
+            "To access the WindBorne API, you need to set your Client ID by setting the environment variable WB_CLIENT_ID. "
+            "For instructions, refer to https://windbornesystems.com/docs/api/cli#introduction or https://windbornesystems.com/docs/api/pip_data#introduction. "
+            "To get an API key, email data@windbornesystems.com."
+        )
 
     if not api_key:
-        print("To access the WindBorne API, you need to set your API key by setting the environment variable WB_API_KEY.")
-        print("--------------------------------------")
-        print("You may refer to https://windbornesystems.com/docs/api/cli#introduction\n"
-              "for instructions on how to set your credentials as environment variables for CLI and Code usage\n\n"
-              "and to https://windbornesystems.com/docs/api/pip_data#introduction\n"
-              "for instruction on how to set your credentials for code usage.")
-        print("--------------------------------------")
-        print("To get an API key, email data@windbornesystems.com.")
-        exit(91)
+        raise ValueError(
+            "To access the WindBorne API, you need to set your API key by setting the environment variable WB_API_KEY. "
+            "For instructions, refer to https://windbornesystems.com/docs/api/cli#introduction or https://windbornesystems.com/docs/api/pip_data#introduction. "
+            "To get an API key, email data@windbornesystems.com."
+        )
 
     if len(client_id) in [32, 35] and len(api_key) not in [32, 35]:
-        print("Your Client ID and API Key are likely swapped.")
-        print("--------------------------------------")
-        print("Swap them or modify them accordingly to get access to WindBorne API.")
-        print("--------------------------------------")
-        print("You may refer to https://windbornesystems.com/docs/api/cli#introduction\n"
-              "for instructions on how to set your credentials as environment variables for CLI and Code usage\n\n"
-              "and to https://windbornesystems.com/docs/api/pip_data#introduction\n"
-              "for instruction on how to set your credentials for code usage.")
-        print("--------------------------------------")
-        print(f"Current Client ID: {client_id}")
-        print(f"Current API Key: {api_key}")
-        exit(95)
+        raise ValueError(
+            f"Your Client ID and API Key are likely swapped. Current Client ID: {client_id}, Current API Key: {api_key}. "
+            "Swap them or modify them accordingly to get access to WindBorne API. "
+            "For instructions, refer to https://windbornesystems.com/docs/api/cli#introduction or https://windbornesystems.com/docs/api/pip_data#introduction."
+        )
 
     # Validate WB_CLIENT_ID format
     if is_valid_uuid_v4(client_id):
-        print("Personal API tokens are not yet supported.")
-        print("--------------------------------------")
-        print("You will need to get a globally-authorizing API key.")
-        print("For questions, email data@windbornesystems.com.")
-        exit(1)
+        raise NotImplementedError(
+            "Personal API tokens are not yet supported. "
+            "You will need to get a globally-authorizing API key. "
+            "For questions, email data@windbornesystems.com."
+        )
 
     if not (is_valid_uuid_v4(client_id) or is_valid_client_id_format(client_id)):
-        print("Your Client ID is misformatted.")
-        print("--------------------------------------")
-        print("It should either be a valid UUID v4 or consist of only lowercase letters, digits, and underscores ([a-z0-9_]).")
-        print("--------------------------------------")
-        print("You may refer to https://windbornesystems.com/docs/api/cli#introduction\n"
-              "for instructions on how to set your credentials as environment variables for CLI and Code usage\n\n"
-              "and to https://windbornesystems.com/docs/api/pip_data#introduction\n"
-              "for instruction on how to set your credentials for code usage.")
-        print("--------------------------------------")
-        print(f"Current Client ID: {client_id}")
-        exit(92)
+        raise ValueError(
+            f"Your Client ID is misformatted: {client_id}. "
+            "It should either be a valid UUID v4 or consist of only lowercase letters, digits, and underscores ([a-z0-9_]). "
+            "For instructions, refer to https://windbornesystems.com/docs/api/cli#introduction or https://windbornesystems.com/docs/api/pip_data#introduction."
+        )
 
     # Validate WB_API_KEY for both newer and older formats
     if api_key.startswith("wb_"):
         if len(api_key) != 35:
-            print("Your API key is misformatted.")
-            print("--------------------------------------")
-            print("API keys starting with 'wb_' must be 35 characters long (including the 'wb_' prefix).")
-            print("--------------------------------------")
-            print("You may refer to https://windbornesystems.com/docs/api/cli#introduction\n"
-                  "for instructions on how to set your credentials as environment variables for CLI and Code usage\n\n"
-                  "and to https://windbornesystems.com/docs/api/pip_data#introduction\n"
-                  "for instruction on how to set your credentials for code usage.")
-            print("--------------------------------------")
-            print(f"Current API key: {api_key}")
-            exit(93)
+            raise ValueError(
+                f"Your API key is misformatted: {api_key}. "
+                "API keys starting with 'wb_' must be 35 characters long (including the 'wb_' prefix). "
+                "For instructions, refer to https://windbornesystems.com/docs/api/cli#introduction or https://windbornesystems.com/docs/api/pip_data#introduction."
+            )
     elif len(api_key) != 32:  # For early tokens
-        print("Your API key is misformatted.")
-        print("--------------------------------------")
-        print("API keys created in 2023 or earlier must be exactly 32 characters long.")
-        print("--------------------------------------")
-        print("You may refer to https://windbornesystems.com/docs/api/cli#introduction\n"
-              "for instructions on how to set your credentials as environment variables for CLI and Code usage\n\n"
-              "and to https://windbornesystems.com/docs/api/pip_data#introduction\n"
-              "for instruction on how to set your credentials for code usage.")
-        print("--------------------------------------")
-        print(f"Current API key: {api_key}")
-        exit(94)
+        raise ValueError(
+            f"Your API key is misformatted: {api_key}. "
+            "API keys created in 2023 or earlier must be exactly 32 characters long. "
+            "For instructions, refer to https://windbornesystems.com/docs/api/cli#introduction or https://windbornesystems.com/docs/api/pip_data#introduction."
+        )
 
 
 VERIFIED_WB_CLIENT_ID = None
@@ -143,8 +106,7 @@ def make_api_request(url, params=None, as_json=True, retry_counter=0):
     :return:
     """
     if retry_counter >= 5:
-        print("Max retries to API reached. Exiting.")
-        exit(1)
+        raise ConnectionError("Max retries to API reached.")
 
     client_id, api_key = get_verified_api_credentials()
 
@@ -209,12 +171,8 @@ def make_api_request(url, params=None, as_json=True, retry_counter=0):
             time.sleep(2**retry_counter)
             return make_api_request(url, params, as_json, retry_counter + 1)
         else:
-            print(f"Unrecoverable HTTP error occurred \n\n{http_err}")
-            if params:
-                print("\nParameters provided:")
-                for key, value in params.items():
-                    print(f"  {key}: {value}")
-            exit(1)
+            # Re-raise the HTTP error instead of exiting
+            raise http_err
     except requests.exceptions.ConnectionError as conn_err:
         print(f"Temporary connection failure; sleeping for {2**retry_counter}s before retrying")
         print(f"Underlying error: \n\n{conn_err}")

windborne/cli.py

@@ -23,7 +23,8 @@ from . import (
     get_generation_times,
     get_full_gridded_forecast,
     get_gridded_forecast,
-    get_tropical_cyclones
+    get_tropical_cyclones,
+    get_population_weighted_hdd
 
 )
 
@@ -226,6 +227,14 @@ def main():
     tropical_cyclones_parser.add_argument('args', nargs='*',
                                  help='[optional: initialization time (YYYYMMDDHH, YYYY-MM-DDTHH, or YYYY-MM-DDTHH:mm:ss)] output_file')
 
+    # Population Weighted HDD Command
+    hdd_parser = subparsers.add_parser('hdd', help='Get population weighted heating degree days (HDD) forecasts')
+    hdd_parser.add_argument('initialization_time', help='Initialization time (YYYYMMDDHH, YYYY-MM-DDTHH, or YYYY-MM-DDTHH:mm:ss)')
+    hdd_parser.add_argument('-i', '--intracycle', action='store_true', help='Use the intracycle forecast')
+    hdd_parser.add_argument('-e', '--ens-member', help='Ensemble member (eg 1 or mean)')
+    hdd_parser.add_argument('-m', '--external-model', help='External model (eg gfs, ifs, hrrr, aifs)')
+    hdd_parser.add_argument('-o', '--output', help='Output file (supports .csv and .json formats)')
+
     # Initialization Times Command
     initialization_times_parser = subparsers.add_parser('init_times', help='Get available initialization times for point forecasts')
     initialization_times_parser.add_argument('-i', '--intracycle', action='store_true', help='Use the intracycle forecast')
@@ -527,6 +536,17 @@ def main():
             print("Error: Too many arguments")
             print("Usage: windborne tropical_cyclones [initialization_time] output_file")
 
+    elif args.command == 'hdd':
+        # Handle population weighted HDD
+        get_population_weighted_hdd(
+            initialization_time=args.initialization_time, 
+            intracycle=args.intracycle,
+            ens_member=args.ens_member,
+            external_model=args.external_model,
+            output_file=args.output,
+            print_response=(not args.output)
+        )
+
     else:
         parser.print_help()
 

windborne/forecasts_api.py

@@ -389,3 +389,41 @@ def download_and_save_output(output_file, response, silent=False):
         if not silent:
             print(f"Error processing the file: {e}")
         return False
+
+def get_population_weighted_hdd(initialization_time, intracycle=False, ens_member=None, external_model=None, output_file=None, print_response=False):
+    """
+    Get population weighted HDD data from the API.
+    """
+    params = {
+        "initialization_time": initialization_time,
+        "intracycle": intracycle,
+        "ens_member": ens_member,
+        "external_model": external_model
+    }
+    response = make_api_request(f"{FORECASTS_API_BASE_URL}/hdd", params=params, as_json=True)
+    
+    if output_file:
+        if output_file.endswith('.csv'):
+            import csv
+
+            # save as csv, with a row for each region, and a column for each date, sorted alphabetically by region
+            regions = sorted(response['hdd'].keys())
+            dates = response['dates']
+            data = [[response['hdd'][region][dates[i]] for region in regions] for i in range(len(dates))]  
+
+            with open(output_file, 'w') as f:
+                writer = csv.writer(f)
+                writer.writerow(['Region'] + dates)
+
+                for region in regions:
+                    writer.writerow([region] + [response['hdd'][region][date] for date in dates])
+    
+    if print_response:
+        dates = response['dates']
+        print(response['hdd']['Alabama'])
+        for region in sorted(response['hdd'].keys()):
+            print(f"{region}:")
+            for i in range(len(dates)):
+                print(f"  {dates[i]}: {response['hdd'][region][dates[i]]}")
+    
+    return response

{windborne-1.2.3.dist-info → windborne-1.2.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: windborne
-Version: 1.2.3
+Version: 1.2.5
 Summary: A Python library for interacting with WindBorne Data and Forecasts API
 Author-email: WindBorne Systems <data@windbornesystems.com>
 Classifier: Programming Language :: Python :: 3
@@ -29,3 +29,5 @@ Run `windborne --help` for more information.
 
 ## Further information and help request
 If you encounter issues or have questions, please ask your WindBorne Systems contact or email data@windbornesystems.com.
+
+For development of this package, see [README_dev.md](README_dev.md)

windborne-1.2.5.dist-info/RECORD

@@ -0,0 +1,13 @@
+windborne/__init__.py,sha256=tbcmwRlhTZAZCzOBeGSuaiOArA1OK-j94ZvEQN910eE,2172
+windborne/api_request.py,sha256=moFKZFKMrHCINtve6ZfQYgrGgd6tXQffVGuNkZzprV4,8508
+windborne/cli.py,sha256=qcETAJ0KXEmdJaIVrZqC7X742K9cNo6cS3racth1IGs,30353
+windborne/data_api.py,sha256=sYZkcQog8RuLErfdLLa4gC8fRkAoPGNKKQJ8i6o-LTQ,33826
+windborne/forecasts_api.py,sha256=kWpUPSzuepZ0G_mwtKgts2lmxlZAzcT7UB7kzurQ6D4,18558
+windborne/observation_formatting.py,sha256=c739aaun6aaYhXl5VI-SRGR-TDS355_0Bfu1t6McoiM,14993
+windborne/track_formatting.py,sha256=LaLfTyjpWoOtHmReJPLViY0MKm_iPL_5I2OB_lNvGGA,10054
+windborne/utils.py,sha256=H8gvZ4Lrr0UmLl25iMZs6NsZliCY_73Ved_rBIqxJg4,7240
+windborne-1.2.5.dist-info/METADATA,sha256=j22__ATrIramyQnlHMxQf7bY2ds1ITdfiDs4v4ZTWlY,1304
+windborne-1.2.5.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+windborne-1.2.5.dist-info/entry_points.txt,sha256=j_YrqdCDrCd7p5MIwQ2BYwNXEi95VNANzLRJmcXEg1U,49
+windborne-1.2.5.dist-info/top_level.txt,sha256=PE9Lauriu5S5REf7JKhXprufZ_V5RiZ_TnfnrLGJrmE,10
+windborne-1.2.5.dist-info/RECORD,,

windborne-1.2.3.dist-info/RECORD

@@ -1,13 +0,0 @@
-windborne/__init__.py,sha256=dslI8_5Wozr96w7c0E7_HEpYIHt9YaTLo3ADF2yapSk,2102
-windborne/api_request.py,sha256=wh8-LANzB62eJt699Zk3YHv4pIzwa1DIhiTJdWRp-To,11264
-windborne/cli.py,sha256=TzEZtfzOgMgPU11ARgJ6O3YZFV3TcXPPYOabHBKb01Y,29247
-windborne/data_api.py,sha256=sYZkcQog8RuLErfdLLa4gC8fRkAoPGNKKQJ8i6o-LTQ,33826
-windborne/forecasts_api.py,sha256=mg7rJkBUE9xSyKIx4RMN0-RIZBdqqSz7Jp5JqFg8DhI,17053
-windborne/observation_formatting.py,sha256=c739aaun6aaYhXl5VI-SRGR-TDS355_0Bfu1t6McoiM,14993
-windborne/track_formatting.py,sha256=LaLfTyjpWoOtHmReJPLViY0MKm_iPL_5I2OB_lNvGGA,10054
-windborne/utils.py,sha256=H8gvZ4Lrr0UmLl25iMZs6NsZliCY_73Ved_rBIqxJg4,7240
-windborne-1.2.3.dist-info/METADATA,sha256=UvrhPEAgHC8C7kZ0o0Ii8qqOWVZCa3HEw72M7QfqLkI,1235
-windborne-1.2.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-windborne-1.2.3.dist-info/entry_points.txt,sha256=j_YrqdCDrCd7p5MIwQ2BYwNXEi95VNANzLRJmcXEg1U,49
-windborne-1.2.3.dist-info/top_level.txt,sha256=PE9Lauriu5S5REf7JKhXprufZ_V5RiZ_TnfnrLGJrmE,10
-windborne-1.2.3.dist-info/RECORD,,