darksky.agent module

class darksky.agent.Darksky(performance_mode=True, **kwargs)

Bases: volttron.platform.agent.base_weather.BaseWeatherAgent

The Darksky agent requires having an API key to interact with the remote API. The agent offers a performance_mode configuration option which allows users to limit the amount of data returned by the API.

*Powered by Dark Sky*

create_forecast_entry(service, location, timestamp, forecast_start)

Helper method used for removing extraneous data from a forecast request response based on request time :param service: weather agent service endpoint :param location: request location dictionary :param timestamp: timestamp for the forecast request. If None, the default forecast result of

are returned - a minute-by-minute forecast for the next hour (where available), or an hour-by-hour forecast for the next 48 hours, or a day-by-day forecast for the next week

Returns

(the last time stamp for which forecast is returned, filtered Dark Sky forecast response)

format_multientry_response(location, response, service, timezone)

Used to extract the data not used by the RPC method, and store it in the cache, helping to limit the number of API calls used to obtain data :param location: location dictionary to include with cached data :param response: Darksky forecast response :param service: :param timezone: timezone string extracted from Darksky response :return: formatted response data by service

generate_response_error(url, response_code)

raises a descriptive runtime error based on the response code returned by a service. :param url: actual url used for requesting data from Darksky :param response_code: Http response code returned by a service following a request

get_api_calls_interval()

Returns

Returns a datetime object representing the time period for API

calls to expire as well as a number representing the number of API calls alloted during the period

get_api_description(service_name)

Provides a human-readable description of the various endpoints provided by the agent :param service_name: requested service endpoint :return: Human-readable description string

get_daily_forecast(locations, days=7)

RPC method for getting time series forecast weather data by full day. :param locations: list of location dictionaries from the RPC call :param days: Number of minutes of weather data to be returned :return: List of daily forecast weather dictionaries

get_darksky_data(service, location, timestamp=None)

Generic method called by the current and forecast service endpoint methods to fetch a forecast request from the Darksky API. If performance mode is set to True, the url adds exclusions for the services provided by the API that were not requested. :param service: requested service endpoint :param location: location dictionary for building url :param timestamp: timestamp of a record if this request is for the Time Machine end point :return: Darksky forecast request response

get_generation_time_for_service(service)

Calculates generation time of forecast request response. “Next-hour minutely forecast data is updated every five minutes. Hourly and daily forecast data are updated every hour.” (https://darksky.net/dev/docs/faq#data-update) :param service: requested weather agent service endpoint :return: Datetime object representing the timestamp when the weather was forecasted

get_hourly_forecast(locations, hours=48)

Overload of get_hourly_forecast method of base weather agent - sets default hours to 48 as this is the quantity provided by a Dark Sky forecast request :param locations: ist of location dictionaries from the RPC call :param hours: Number of hours of weather data to be returned :return: Dark Sky forecast data by the hour

get_minutely_forecast(locations, minutes=60)

RPC method for getting time series forecast weather data minute by minute. Dark Sky does not provide more than 1 hour into the future of minutely forecast data. :param locations: list of location dictionaries from the RPC call :param minutes: Number of minutes of weather data to be returned :return: List of minutely forecast weather dictionaries

get_point_name_defs_file()

Constructs the point name mapping dict from the mapping csv. :return: dictionary containing a mapping of service point names to standard point names with optional

get_update_interval(service_name)

Indicates the interval between remote API updates :param service_name: requested service endpoint :return: datetime timedelta representing the time interval

get_version()

Provides the current version of the agent. :return: current version number in string format.

query_current_weather(location)

Retrieve data from the Darksky API, return formatted current data and store forecast data in cache :param location: location dictionary requested by the user :return: Timestamp and data for current data from the Darksky API

query_forecast_service(service, location, quantity, forecast_start)

Generic method for requesting forecast data from the various RPC forecast methods. If the user requests a number of records to return greater than the default for the forecast request(7 daily records) additional API calls will be made to the Dark Sky Time Machine endpoint. If the number of API calls required to fulfill the additional records is greater than the amount of available API calls, the user will receive only the records returned by the forecast request. :param service: forecast service type of weather data to return :param location: location dictionary requested during the RPC call :param quantity: number of records to return, used to generate Time Machine requests after the forecast request :param forecast_start: forecast results that are prior to this

timestamp will be filtered by base weather agent

Returns

Timestamp and data returned by the Darksky weather API response

validate_location(service_name, location)

Indicates whether the location dictionary provided matches the format required by the remote weather API :param service_name: name of the remote API service :param location: location dictionary to provide in the remote API url :return: True if the location matches the required format else False

darksky.agent.darksky(config_path, **kwargs)

Parses the Agent configuration and returns an instance of the agent created using that configuration.

Parameters

config_path (str) – Path to a configuration file.

Returns

Darksky

Return type

Darksky

darksky.agent.main()

Main method called to start the agent.