utilities

General-purpose helpers shared across the forecast tool.

A grab-bag of small utilities used by the downloaders, processors, and notebooks:

• check_url_exists() — test whether a remote resource is reachable

• get_first_forecast_month() — derive the operational forecast month from a reference date

• get_date_range() — resolve the start/end dates for a CFS download, either automatically (from the database) or from manual input

• create_directory() — create a directory if it does not exist

• get_files() — list files in a directory matching a prefix or suffix

src.utilities.check_url_exists(url)

Check whether a URL exists and is reachable via a HEAD request.

Parameters:

url (str) – The full URL to be checked.

Returns:

True if the URL returns status code 200, False otherwise.

Return type:

bool

src.utilities.get_first_forecast_month(today=None)

Returns the first forecast month based on today’s date, then shifts backward by a specified number of months.

Rules

• If today’s day is before the 26th, use the current month.

• If today’s day is on or after the 26th, use the following month.

• Then subtract months_back months.

param today:

Reference date. Defaults to current date if None.

type today:

datetime, optional

returns:

Forecast month in ‘YYYY-MM’ format.

rtype:

str

src.utilities.get_date_range(db=None, auto='yes', start_date=None, end_date=None)

Determine the start and end dates for CFS CSV downloads, and return the date range.

Parameters:

• db (object, optional) – Database object with a get_next_run() method. Required if auto=’yes’.

• auto (str, default 'yes') – Whether to automatically fetch the next run date from the database (‘yes’ or ‘no’).

• start_date (str, optional) – Manual start date in format ‘MM-DD-YYYY’. Required if auto=’no’.

• end_date (str, optional) – Manual end date in format ‘MM-DD-YYYY’. Required if auto=’no’.

Returns:

(start_date: datetime, end_date: datetime, date_array: pd.DatetimeIndex)

Return type:

tuple

src.utilities.create_directory(directory)

Create a directory if it doesn’t already exist.

src.utilities.get_files(directory, affix, identifier)

List files in a directory whose names match a given prefix or suffix.

Parameters:

• directory (str) – Path to the directory to search.

• affix (str) – Which part of the filename to match against: 'prefix' or 'suffix'.

• identifier (str) – The prefix or suffix string to match.

Returns:

Full paths (directory joined with the filename) of all matching files. Empty if nothing matches.

Return type:

list of str