windborne 1.2.3__tar.gz → 1.2.5__tar.gz

{windborne-1.2.3 → windborne-1.2.5}/PKG-INFO

@@ -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.3 → windborne-1.2.5}/README.md

@@ -13,3 +13,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.3 → windborne-1.2.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "windborne"
-version = "1.2.3"
+version = "1.2.5"
 description = "A Python library for interacting with WindBorne Data and Forecasts API"
 readme = {file = "README.md", content-type = "text/markdown"}
 authors = [

{windborne-1.2.3 → windborne-1.2.5}/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-1.2.5/windborne/api_request.py

@@ -0,0 +1,187 @@
+import jwt
+import time
+import requests
+import re
+import os
+
+def is_valid_uuid_v4(client_id):
+    return re.fullmatch(r"[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}", client_id) is not None
+
+
+def is_valid_client_id_format(client_id):
+    return re.fullmatch(r"[a-z0-9_]+", client_id) is not None
+
+
+def get_api_credentials():
+    client_id = os.getenv('WB_CLIENT_ID')
+    api_key = os.getenv('WB_API_KEY')
+    
+    return client_id, api_key
+
+
+def verify_api_credentials(client_id, api_key):
+    if not client_id and not api_key:
+        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:
+        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:
+        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]:
+        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):
+        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)):
+        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:
+            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
+        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
+VERIFIED_WB_API_KEY = None
+
+def get_verified_api_credentials():
+    global VERIFIED_WB_CLIENT_ID, VERIFIED_WB_API_KEY
+
+    if VERIFIED_WB_CLIENT_ID is None or VERIFIED_WB_API_KEY is None:
+        VERIFIED_WB_CLIENT_ID, VERIFIED_WB_API_KEY = get_api_credentials()
+        verify_api_credentials(VERIFIED_WB_CLIENT_ID, VERIFIED_WB_API_KEY)
+
+    return VERIFIED_WB_CLIENT_ID, VERIFIED_WB_API_KEY
+
+
+def make_api_request(url, params=None, as_json=True, retry_counter=0):
+    """
+    Make an authenticated request to the WindBorne API.
+
+    This uses a JWT under the hood
+    While basic auth is supported, this method reduces the odds of an improper configuration accidentally leaking the keys
+
+    :param url: The URL to make the request to
+    :param params: The parameters to pass to the request
+    :param as_json: Whether to return the response as JSON or as a requests.Response object
+    :param retry_counter: The number of times the request has been retried
+    :return:
+    """
+    if retry_counter >= 5:
+        raise ConnectionError("Max retries to API reached.")
+
+    client_id, api_key = get_verified_api_credentials()
+
+    if is_valid_uuid_v4(client_id):
+        token_id = client_id
+        client_id = 'api_token'
+
+        signed_token = jwt.encode({
+            'client_id': client_id,
+            'iat': int(time.time()),
+            'token_id': token_id
+        }, api_key, algorithm='HS256')
+    else:
+        signed_token = jwt.encode({
+            'client_id': client_id,
+            'iat': int(time.time()),
+        }, api_key, algorithm='HS256')
+
+    try:
+        if params:
+            response = requests.get(url, auth=(client_id, signed_token), params=params)
+        else:
+            response = requests.get(url, auth=(client_id, signed_token))
+
+        response.raise_for_status()
+
+        if as_json:
+            return response.json()
+        else:
+            return response
+
+    except requests.exceptions.HTTPError as http_err:
+        if http_err.response.status_code == 403:
+            print("--------------------------------------")
+            print("We couldn't authenticate your request.")
+            print("--------------------------------------")
+            print("You likely don't have permission to access this resource.\n")
+            print("For questions, email data@windbornesystems.com.")
+        elif http_err.response.status_code in [404, 400]:
+            print("-------------------------------------------------------")
+            print("Our server couldn't find the information you requested.")
+            print("-------------------------------------------------------")
+            print(f"URL: {url}")
+            print(f"Error: {http_err.response.status_code}")
+            print("-------------------------------------------------------")
+            if params:
+                print("\nParameters provided:")
+                for key, value in params.items():
+                    print(f"  {key}: {value}")
+            else:
+                if 'missions/' in url:
+                    mission_id = url.split('/missions/')[1].split('/')[0]
+                    print(f"Mission ID provided: {mission_id}")
+                    print(f"No mission found with id: {mission_id}")
+            print("-------------------------------------------------------")
+            print("Response text:")
+            print(http_err.response.text)
+            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")
+            time.sleep(2**retry_counter)
+            return make_api_request(url, params, as_json, retry_counter + 1)
+        else:
+            # 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}")
+        time.sleep(2**retry_counter)
+        return make_api_request(url, params, as_json, retry_counter + 1)
+    except requests.exceptions.Timeout as timeout_err:
+        print(f"Temporary connection failure; sleeping for {2**retry_counter}s before retrying")
+        print(f"Underlying error: \n\n{timeout_err}")
+        time.sleep(2**retry_counter)
+        return make_api_request(url, params, as_json, retry_counter + 1)
+    except requests.exceptions.RequestException as req_err:
+        print(f"An error occurred\n\n{req_err}")

{windborne-1.2.3 → windborne-1.2.5}/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-1.2.3 → windborne-1.2.5}/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 → windborne-1.2.5}/windborne.egg-info/PKG-INFO

@@ -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.3/windborne/api_request.py

@@ -1,229 +0,0 @@
-import jwt
-import time
-import requests
-import re
-import os
-
-def is_valid_uuid_v4(client_id):
-    return re.fullmatch(r"[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}", client_id) is not None
-
-
-def is_valid_client_id_format(client_id):
-    return re.fullmatch(r"[a-z0-9_]+", client_id) is not None
-
-
-def get_api_credentials():
-    client_id = os.getenv('WB_CLIENT_ID')
-    api_key = os.getenv('WB_API_KEY')
-    
-    return client_id, api_key
-
-
-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)
-
-    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)
-
-    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)
-
-    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)
-
-    # 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)
-
-    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)
-
-    # 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)
-    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)
-
-
-VERIFIED_WB_CLIENT_ID = None
-VERIFIED_WB_API_KEY = None
-
-def get_verified_api_credentials():
-    global VERIFIED_WB_CLIENT_ID, VERIFIED_WB_API_KEY
-
-    if VERIFIED_WB_CLIENT_ID is None or VERIFIED_WB_API_KEY is None:
-        VERIFIED_WB_CLIENT_ID, VERIFIED_WB_API_KEY = get_api_credentials()
-        verify_api_credentials(VERIFIED_WB_CLIENT_ID, VERIFIED_WB_API_KEY)
-
-    return VERIFIED_WB_CLIENT_ID, VERIFIED_WB_API_KEY
-
-
-def make_api_request(url, params=None, as_json=True, retry_counter=0):
-    """
-    Make an authenticated request to the WindBorne API.
-
-    This uses a JWT under the hood
-    While basic auth is supported, this method reduces the odds of an improper configuration accidentally leaking the keys
-
-    :param url: The URL to make the request to
-    :param params: The parameters to pass to the request
-    :param as_json: Whether to return the response as JSON or as a requests.Response object
-    :param retry_counter: The number of times the request has been retried
-    :return:
-    """
-    if retry_counter >= 5:
-        print("Max retries to API reached. Exiting.")
-        exit(1)
-
-    client_id, api_key = get_verified_api_credentials()
-
-    if is_valid_uuid_v4(client_id):
-        token_id = client_id
-        client_id = 'api_token'
-
-        signed_token = jwt.encode({
-            'client_id': client_id,
-            'iat': int(time.time()),
-            'token_id': token_id
-        }, api_key, algorithm='HS256')
-    else:
-        signed_token = jwt.encode({
-            'client_id': client_id,
-            'iat': int(time.time()),
-        }, api_key, algorithm='HS256')
-
-    try:
-        if params:
-            response = requests.get(url, auth=(client_id, signed_token), params=params)
-        else:
-            response = requests.get(url, auth=(client_id, signed_token))
-
-        response.raise_for_status()
-
-        if as_json:
-            return response.json()
-        else:
-            return response
-
-    except requests.exceptions.HTTPError as http_err:
-        if http_err.response.status_code == 403:
-            print("--------------------------------------")
-            print("We couldn't authenticate your request.")
-            print("--------------------------------------")
-            print("You likely don't have permission to access this resource.\n")
-            print("For questions, email data@windbornesystems.com.")
-        elif http_err.response.status_code in [404, 400]:
-            print("-------------------------------------------------------")
-            print("Our server couldn't find the information you requested.")
-            print("-------------------------------------------------------")
-            print(f"URL: {url}")
-            print(f"Error: {http_err.response.status_code}")
-            print("-------------------------------------------------------")
-            if params:
-                print("\nParameters provided:")
-                for key, value in params.items():
-                    print(f"  {key}: {value}")
-            else:
-                if 'missions/' in url:
-                    mission_id = url.split('/missions/')[1].split('/')[0]
-                    print(f"Mission ID provided: {mission_id}")
-                    print(f"No mission found with id: {mission_id}")
-            print("-------------------------------------------------------")
-            print("Response text:")
-            print(http_err.response.text)
-            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")
-            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)
-    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}")
-        time.sleep(2**retry_counter)
-        return make_api_request(url, params, as_json, retry_counter + 1)
-    except requests.exceptions.Timeout as timeout_err:
-        print(f"Temporary connection failure; sleeping for {2**retry_counter}s before retrying")
-        print(f"Underlying error: \n\n{timeout_err}")
-        time.sleep(2**retry_counter)
-        return make_api_request(url, params, as_json, retry_counter + 1)
-    except requests.exceptions.RequestException as req_err:
-        print(f"An error occurred\n\n{req_err}")