Renaming of Balancing Authority to Region

Renaming of Balancing Authority to Region through all code and comments.  This will also need updating through documentation.

Author: vaughanknight

src/CarbonAware.DataSources/CarbonAware.DataSources.WattTime/src/Client/IWattTimeClient.cs

@@ -11,90 +11,90 @@ internal interface IWattTimeClient
     public const string NamedAuthenticationClient = "WattTimeAuthenticationClient";
 
     /// <summary>
-    /// Async method to get observed emission data for a given balancing authority and time period.
+    /// Async method to get observed emission data for a given region and time period.
     /// </summary>
-    /// <param name="balancingAuthorityAbbreviation">Balancing authority abbreviation</param>
+    /// <param name="regionAbbreviation">Region abbreviation</param>
     /// <param name="startTime">Start time of the time period</param>
     /// <param name="endTime">End time of the time period</param>
     /// <returns>An <see cref="Task{IEnumerable}{GridEmissionDataPoint}"/> which contains all emissions data points in a period.</returns>
     /// <exception cref="WattTimeClientException">Can be thrown when errors occur connecting to WattTime client.  See the WattTimeClientException class for documentation of expected status codes.</exception>
-    Task<GridEmissionsDataResponse> GetDataAsync(string balancingAuthorityAbbreviation, DateTimeOffset startTime, DateTimeOffset endTime);
+    Task<GridEmissionsDataResponse> GetDataAsync(string regionAbbreviation, DateTimeOffset startTime, DateTimeOffset endTime);
 
     /// <summary>
-    /// Async method to get observed emission data for a given balancing authority and time period.
+    /// Async method to get observed emission data for a given region and time period.
     /// </summary>
-    /// <param name="balancingAuthority">Balancing authority</param>
+    /// <param name="region">Region</param>
     /// <param name="startTime">Start time of the time period</param>
     /// <param name="endTime">End time of the time period</param>
     /// <returns>An <see cref="Task{IEnumerable}{GridEmissionDataPoint}"/> which contains all emissions data points in a period.</returns>
     /// <exception cref="WattTimeClientException">Can be thrown when errors occur connecting to WattTime client.  See the WattTimeClientException class for documentation of expected status codes.</exception>
-    Task<GridEmissionsDataResponse> GetDataAsync(RegionResponse balancingAuthority, DateTimeOffset startTime, DateTimeOffset endTime);
+    Task<GridEmissionsDataResponse> GetDataAsync(RegionResponse region, DateTimeOffset startTime, DateTimeOffset endTime);
 
     /// <summary>
-    /// Async method to get the most recent 24 hour forecasted emission data for a given balancing authority.
+    /// Async method to get the most recent 24 hour forecasted emission data for a given region.
     /// </summary>
-    /// <param name="balancingAuthorityAbbreviation">Balancing authority abbreviation</param>
+    /// <param name="regionAbbreviation">region abbreviation</param>
     /// <returns>An <see cref="Task{Forecast}"/> which contains forecasted emissions data points.</returns>
     /// <exception cref="WattTimeClientException">Can be thrown when errors occur connecting to WattTime client.  See the WattTimeClientException class for documentation of expected status codes.</exception>
-    Task<ForecastEmissionsDataResponse> GetCurrentForecastAsync(string balancingAuthorityAbbreviation);
+    Task<ForecastEmissionsDataResponse> GetCurrentForecastAsync(string regionAbbreviation);
 
     /// <summary>
-    /// Async method to get the most recent 24 hour forecasted emission data for a given balancing authority.
+    /// Async method to get the most recent 24 hour forecasted emission data for a given region.
     /// </summary>
-    /// <param name="balancingAuthority">Balancing authority</param>
+    /// <param name="region">region</param>
     /// <returns>An <see cref="Task{Forecast}"/> which contains forecasted emissions data points.</returns>
     /// <exception cref="WattTimeClientException">Can be thrown when errors occur connecting to WattTime client.  See the WattTimeClientException class for documentation of expected status codes.</exception>
-    Task<ForecastEmissionsDataResponse> GetCurrentForecastAsync(RegionResponse balancingAuthority);
+    Task<ForecastEmissionsDataResponse> GetCurrentForecastAsync(RegionResponse region);
 
     /// <summary>
-    /// Async method to get generated forecast at requested time and balancing authority.
+    /// Async method to get generated forecast at requested time and region.
     /// </summary>
-    /// <param name="region">Balancing authority abbreviation</param>
+    /// <param name="region">region abbreviation</param>
     /// <param name="requestedAt">The historical time used to fetch the most recent forecast generated as of that time.</param>
     /// <returns>An <see cref="Task{Forecast}"/> which contains forecasted emissions data points or null if no Forecast generated at the requested time.</returns>
     /// <exception cref="WattTimeClientException">Can be thrown when errors occur connecting to WattTime client.  See the WattTimeClientException class for documentation of expected status codes.</exception>
     Task<HistoricalForecastEmissionsDataResponse?> GetForecastOnDateAsync(string region, DateTimeOffset requestedAt);
 
     /// <summary>
-    /// Async method to get generated forecast at requested time and balancing authority.
+    /// Async method to get generated forecast at requested time and region.
     /// </summary>
-    /// <param name="balancingAuthority">Balancing authority</param>
+    /// <param name="region">region</param>
     /// <param name="requestedAt">The historical time used to fetch the most recent forecast generated as of that time.</param>
     /// <returns>An <see cref="Task{Forecast}"/> which contains forecasted emissions data points or null if no Forecast generated at the requested time.</returns>
     /// <exception cref="WattTimeClientException">Can be thrown when errors occur connecting to WattTime client.  See the WattTimeClientException class for documentation of expected status codes.</exception>
-    Task<HistoricalForecastEmissionsDataResponse?> GetForecastOnDateAsync(RegionResponse balancingAuthority, DateTimeOffset requestedAt);
+    Task<HistoricalForecastEmissionsDataResponse?> GetForecastOnDateAsync(RegionResponse region, DateTimeOffset requestedAt);
 
     /// <summary>
-    /// Async method to get the balancing authority for a given location.
+    /// Async method to get the region for a given location.
     /// </summary>
     /// <param name="latitude">Latitude of the location</param>
     /// <param name="longitude">Longitude of the location</param>
-    /// <returns>An <see cref="Task{BalancingAuthority}"/> which contains the balancing authority details.</returns>
+    /// <returns>An <see cref="Task{region}"/> which contains the region details.</returns>
     /// <exception cref="WattTimeClientException">Can be thrown when errors occur connecting to WattTime client.  See the WattTimeClientException class for documentation of expected status codes.</exception>
     Task<RegionResponse> GetRegionAsync(string latitude, string longitude);
 
     /// <summary>
-    /// Async method to get the balancing authority abbreviation for a given location.
+    /// Async method to get the region abbreviation for a given location.
     /// </summary>
     /// <param name="latitude">Latitude of the location</param>
     /// <param name="longitude">Longitude of the location</param>
-    /// <returns>A string which contains the balancing authority details.</returns>
+    /// <returns>A string which contains the region details.</returns>
     /// <exception cref="WattTimeClientException">Can be thrown when errors occur connecting to WattTime client.  See the WattTimeClientException class for documentation of expected status codes.</exception>
-    Task<string?> GetBalancingAuthorityAbbreviationAsync(string latitude, string longitude);
+    Task<string?> GetRegionAbbreviationAsync(string latitude, string longitude);
 
     /// <summary>
-    /// Async method to get binary data (representing a zip file) of the historical emissions data for the given balancing authority.
+    /// Async method to get binary data (representing a zip file) of the historical emissions data for the given region.
     /// </summary>
-    /// <param name="balancingAuthorityAbbreviation">Balancing authority abbreviation</param>
+    /// <param name="regionAbbreviation">region abbreviation</param>
     /// <returns>An <see cref="Task{Stream}"/> which contains the binary data stream of the .zip file.</returns>
     /// <exception cref="WattTimeClientException">Can be thrown when errors occur connecting to WattTime client.  See the WattTimeClientException class for documentation of expected status codes.</exception>
-    Task<Stream> GetHistoricalDataAsync(string balancingAuthorityAbbreviation);
+    Task<Stream> GetHistoricalDataAsync(string regionAbbreviation);
 
     /// <summary>
-    /// Async method to get binary data (representing a zip file) of the historical emissions data for the given balancing authority.
+    /// Async method to get binary data (representing a zip file) of the historical emissions data for the given region.
     /// </summary>
-    /// <param name="balancingAuthority">Balancing authority</param>
+    /// <param name="region">region</param>
     /// <returns>An <see cref="Task{Stream}"/> which contains the data Stream of the .zip file.</returns>
     /// <exception cref="WattTimeClientException">Can be thrown when errors occur connecting to WattTime client.  See the WattTimeClientException class for documentation of expected status codes.</exception>
-    Task<Stream> GetHistoricalDataAsync(RegionResponse balancingAuthority);
+    Task<Stream> GetHistoricalDataAsync(RegionResponse region);
 }

src/CarbonAware.DataSources/CarbonAware.DataSources.WattTime/src/Client/WattTimeClient.cs

@@ -88,7 +88,7 @@ public Task<GridEmissionsDataResponse> GetDataAsync(RegionResponse region, DateT
     public async Task<ForecastEmissionsDataResponse> GetCurrentForecastAsync(string region)
     {
 
-        _log.LogInformation("Requesting current forecast from balancing authority {balancingAuthority}", region);
+        _log.LogInformation("Requesting current forecast from region: {region}", region);
 
         var parameters = new Dictionary<string, string>()
         {
@@ -109,15 +109,15 @@ public async Task<ForecastEmissionsDataResponse> GetCurrentForecastAsync(string
     }
 
     /// <inheritdoc/>
-    public Task<ForecastEmissionsDataResponse> GetCurrentForecastAsync(RegionResponse balancingAuthority)
+    public Task<ForecastEmissionsDataResponse> GetCurrentForecastAsync(RegionResponse region)
     {
-        return this.GetCurrentForecastAsync(balancingAuthority.Region);
+        return this.GetCurrentForecastAsync(region.Region);
     }
 
     /// <inheritdoc/>
     public async Task<HistoricalForecastEmissionsDataResponse?> GetForecastOnDateAsync(string region, DateTimeOffset requestedAt)
     {
-        _log.LogInformation($"Requesting forecast from balancingAuthority {region} generated at {requestedAt}.");
+        _log.LogInformation($"Requesting forecast from region {region} generated at {requestedAt}.");
 
         var parameters = new Dictionary<string, string>()
         {
@@ -147,24 +147,24 @@ public Task<ForecastEmissionsDataResponse> GetCurrentForecastAsync(RegionRespons
     /// <inheritdoc/>
     public async Task<RegionResponse> GetRegionAsync(string latitude, string longitude)
     {
-        _log.LogInformation("Requesting balancing authority for lattitude {lattitude} and longitude {longitude}", latitude, longitude);
-        return await GetBalancingAuthorityFromCacheAsync(latitude, longitude);
+        _log.LogInformation("Requesting region for lattitude {lattitude} and longitude {longitude}", latitude, longitude);
+        return await GetRegionFromCacheAsync(latitude, longitude);
     }
 
     /// <inheritdoc/>
-    public async Task<string?> GetBalancingAuthorityAbbreviationAsync(string latitude, string longitude)
+    public async Task<string?> GetRegionAbbreviationAsync(string latitude, string longitude)
     {
         return (await this.GetRegionAsync(latitude, longitude))?.Region;
     }
 
     /// <inheritdoc/>
-    public async Task<Stream> GetHistoricalDataAsync(string balancingAuthorityAbbreviation)
+    public async Task<Stream> GetHistoricalDataAsync(string regionAbbreviation)
     {
-        _log.LogInformation("Requesting historical data for balancing authority {balancingAuthority}", balancingAuthorityAbbreviation);
+        _log.LogInformation("Requesting historical data for region {regionAbbreviation}", regionAbbreviation);
 
         var parameters = new Dictionary<string, string>()
         {
-            { QueryStrings.Region, balancingAuthorityAbbreviation }
+            { QueryStrings.Region, regionAbbreviation }
         };
 
         var url = BuildUrlWithQueryString(Paths.Historical, parameters);
@@ -179,9 +179,9 @@ public async Task<Stream> GetHistoricalDataAsync(string balancingAuthorityAbbrev
     }
 
     /// <inheritdoc/>
-    public Task<Stream> GetHistoricalDataAsync(RegionResponse balancingAuthority)
+    public Task<Stream> GetHistoricalDataAsync(RegionResponse region)
     {
-        return this.GetHistoricalDataAsync(balancingAuthority.Region);
+        return this.GetHistoricalDataAsync(region.Region);
     }
 
     private async Task<HttpResponseMessage> GetAsyncWithAuthRetry(string uriPath)
@@ -293,10 +293,10 @@ private string BuildUrlWithQueryString(string url, IDictionary<string, string> q
         return result;
     }
 
-    private async Task<RegionResponse> GetBalancingAuthorityFromCacheAsync(string latitude, string longitude)
+    private async Task<RegionResponse> GetRegionFromCacheAsync(string latitude, string longitude)
     {
         var key = new Tuple<string, string>(latitude, longitude);
-        var balancingAuthority = await this._memoryCache.GetOrCreateAsync(key, async entry =>
+        var region = await this._memoryCache.GetOrCreateAsync(key, async entry =>
         {
             var parameters = new Dictionary<string, string>()
             {
@@ -312,11 +312,11 @@ private async Task<RegionResponse> GetBalancingAuthorityFromCacheAsync(string la
                 { QueryStrings.SignalType, SignalTypes.co2_moer }
             };
             var result = await this.MakeRequestGetStreamAsync(Paths.RegionFromLocation, parameters, tags);
-            var baValue = await JsonSerializer.DeserializeAsync<RegionResponse>(result, _options) ?? throw new WattTimeClientException($"Error getting Balancing Authority for latitude {latitude} and longitude {longitude}");
-            entry.AbsoluteExpirationRelativeToNow = TimeSpan.FromSeconds(_configuration.BalancingAuthorityCacheTTL);
-            entry.Value = baValue;
-            return baValue;
+            var regionResponse = await JsonSerializer.DeserializeAsync<RegionResponse>(result, _options) ?? throw new WattTimeClientException($"Error getting Region for latitude {latitude} and longitude {longitude}");
+            entry.AbsoluteExpirationRelativeToNow = TimeSpan.FromSeconds(_configuration.RegionCacheTTL);
+            entry.Value = regionResponse;
+            return regionResponse;
         });
-        return balancingAuthority;
+        return region;
     }
 }

src/CarbonAware.DataSources/CarbonAware.DataSources.WattTime/src/Client/WattTimeClientHttpException.cs

@@ -22,7 +22,7 @@ public WattTimeClientHttpException(string message, HttpResponseMessage response)
     /// Gets the status code for the exception.  See remarks for the status codes that can be returned.
     /// </summary>
     /// <remarks>
-    /// 400:  Returned when the lattitude/longitude provided aren't associated with a known balancing authority.
+    /// 400:  Returned when the lattitude/longitude provided aren't associated with a known region.
     /// 401:  Returned when no authorization header is passed.  You should not expect to receive this status code.
     /// 403:  Returned when an invalid username or password is used for login.  Please check your configuration and verify your account when this error is received.
     /// 429:  Returned when the number of requests has exceeded the WattTime rate limit, currently at 3,000 per rolling 5 minute window.  For current limits, see https://www.watttime.org/api-documentation/#restrictions

src/CarbonAware.DataSources/CarbonAware.DataSources.WattTime/src/Configuration/WattTimeClientConfiguration.cs

@@ -32,10 +32,10 @@ internal class WattTimeClientConfiguration
     public string AuthenticationBaseUrl { get; set; } = "https://api.watttime.org/";
 
     /// <summary>
-    /// Gets or sets the cached expiration time (in seconds) for a BalancingAuthority instance.
+    /// Gets or sets the cached expiration time (in seconds) for a Region instance.
     /// It defaults to 86400 secs.
     /// </summary>
-    public int BalancingAuthorityCacheTTL { get; set; } = 86400;
+    public int RegionCacheTTL { get; set; } = 86400;
 
     /// <summary>
     /// Validate that this object is properly configured.

src/CarbonAware.DataSources/CarbonAware.DataSources.WattTime/src/Model/GridEmissionDataPoint.cs

@@ -3,7 +3,7 @@
 namespace CarbonAware.DataSources.WattTime.Model;
 
 /// <summary>
-/// An object describing the emissions for a given time period and balancing authority.
+/// An object describing the emissions for a given time period and region.
 /// </summary>
 [Serializable]
 internal record GridEmissionDataPoint

src/CarbonAware.DataSources/CarbonAware.DataSources.WattTime/src/Model/RegionResponse.cs

@@ -3,7 +3,7 @@
 namespace CarbonAware.DataSources.WattTime.Model;
 
 /// <summary>
-/// The details of the balancing authority (BA) serving a particular location.
+/// The details of the region serving a particular location.
 /// </summary>
 [Serializable]
 internal record RegionResponse