def __init__(self, id, created_at, updated_at, external_id, name,
lon, lat, alt, rank):
assert id is not None
assert external_id is not None
assert lon is not None
assert lat is not None
if lon < -180.0 or lon > 180.0:
raise ValueError("'lon' value must be between -180 and 180")
self._lon = float(lon)
if lat < -90.0 or lat > 90.0:
raise ValueError("'lat' value must be between -90 and 90")
if alt is not None and alt < 0.0:
raise ValueError("'alt' value must not be negative")
self.id = id
self.created_at = created_at
if self.created_at is not None:
padded_created_at = self._format_micros(created_at)
t = dt.fromisoformat(padded_created_at.replace("Z", "+00:00"))
self.created_at = formatting.timeformat(t, 'unix')
self.updated_at = updated_at
if self.updated_at is not None:
padded_updated_at = self._format_micros(updated_at)
t = dt.fromisoformat(padded_updated_at.replace("Z", "+00:00"))
self.updated_at = formatting.timeformat(t, 'unix')
self.external_id = external_id
self.name = name
self.lon = lon
self.lat = lat
self.alt = alt
self.rank = rank
def uvindex_history_around_coords(self, lat, lon, start, end=None):
"""
Queries for UV index historical values in the
surroundings of the provided geocoordinates and in the specified
time frame. If the end of the time frame is not provided, that is
intended to be the current datetime.
:param lat: the location's latitude, must be between -90.0 and 90.0
:type lat: int/float
:param lon: the location's longitude, must be between -180.0 and 180.0
:type lon: int/float
:param start: the object conveying the time value for the start query boundary
:type start: int, ``datetime.datetime`` or ISO8601-formatted string
:param end: the object conveying the time value for the end query
boundary (defaults to ``None``, in which case the current datetime
will be used)
:type end: int, ``datetime.datetime`` or ISO8601-formatted string
:return: a list of *UVIndex* instances or empty list if data is not available
:raises: *ParseResponseException* when OWM UV Index API responses' data
cannot be parsed, *APICallException* when OWM UV Index API can not be
reached, *ValueError* for wrong input values
"""
geo.assert_is_lon(lon)
geo.assert_is_lat(lat)
assert start is not None
start = formatting.timeformat(start, 'unix')
if end is None:
end = timestamps.now(timeformat='unix')
else:
end = formatting.timeformat(end, 'unix')
params = {'lon': lon, 'lat': lat, 'start': start, 'end': end}
json_data = self.uv_client.get_uvi_history(params)
uvindex_list = [uvindex.UVIndex.from_dict(item) for item in json_data]
return uvindex_list
def test_timeformat(self):
unixtime = 1378459200
iso = "2013-09-06 09:20:00+00:00"
date = datetime(2013, 9, 6, 9, 20, 0, 0, timezone.utc)
self.assertEqual(unixtime, formatting.timeformat(unixtime, "unix"))
self.assertEqual(iso, formatting.timeformat(unixtime, "iso"))
self.assertEqual(date, formatting.timeformat(unixtime, "date"))
self.assertEqual(unixtime, formatting.timeformat(iso, "unix"))
self.assertEqual(iso, formatting.timeformat(iso, "iso"))
self.assertEqual(date, formatting.timeformat(iso, "date"))
self.assertEqual(unixtime, formatting.timeformat(date, "unix"))
self.assertEqual(iso, formatting.timeformat(date, "iso"))
self.assertEqual(date, formatting.timeformat(date, "date"))
def downloaded_on(self, timeformat='unix'):
"""Returns the UTC time telling when the satellite image was downloaded from the OWM Agro API
:param timeformat: the format for the time value. May be:
'*unix*' (default) for UNIX time
'*iso*' for ISO8601-formatted string in the format ``YYYY-MM-DD HH:MM:SS+00``
'*date* for ``datetime.datetime`` object instance
:type timeformat: str
:returns: an int or a str
"""
return formatting.timeformat(self._downloaded_on, timeformat)
def acquisition_time(self, timeformat='unix'):
"""Returns the UTC time telling when the image data was acquired by the satellite
:param timeformat: the format for the time value. May be:
'*unix*' (default) for UNIX time
'*iso*' for ISO8601-formatted string in the format ``YYYY-MM-DD HH:MM:SS+00``
'*date* for ``datetime.datetime`` object instance
:type timeformat: str
:returns: an int or a str
"""
return formatting.timeformat(self._acquisition_time, timeformat)
def issued_on(self, timeformat='unix'):
"""Returns the UTC time telling when the query was performed against the OWM Agro API
:param timeformat: the format for the time value. May be:
'*unix*' (default) for UNIX time
'*iso*' for ISO8601-formatted string in the format ``YYYY-MM-DD HH:MM:SS+00``
'*date* for ``datetime.datetime`` object instance
:type timeformat: str
:returns: an int or a str
"""
return formatting.timeformat(self.query_timestamp, timeformat)
def reference_time(self, timeformat='unix'):
"""Returns the UTC time telling when the soil data was measured
:param timeformat: the format for the time value. May be:
'*unix*' (default) for UNIX time
'*iso*' for ISO8601-formatted string in the format ``YYYY-MM-DD HH:MM:SS+00``
'*date* for ``datetime.datetime`` object instance
:type timeformat: str
:returns: an int or a str
"""
return formatting.timeformat(self._reference_time, timeformat)
def reference_time(self, timeformat='unix'):
"""Returns the GMT time telling when the weather was measured
:param timeformat: the format for the time value. May be:
'*unix*' (default) for UNIX time
'*iso*' for ISO8601-formatted string in the format ``YYYY-MM-DD HH:MM:SS+00``
'*date*' for ``datetime.datetime`` object instance
:type timeformat: str
:returns: an int or a str or a `datetime.datetime` object
:raises: ValueError when negative values are provided
"""
return formatting.timeformat(self.ref_time, timeformat)
def now(timeformat='date'):
"""
Returns the current time in the specified timeformat.
:param timeformat: the target format for the time conversion. May be:
'*date*' (default - outputs a ``datetime.datetime`` object), '*unix*'
(outputs a long UNIXtime) or '*iso*' (outputs an ISO8601-formatted
string with pattern ``YYYY-MM-DD HH:MM:SS+00``)
:type timeformat: str
:returns: the current time value
:raises: ValueError when unknown timeformat switches are provided or
when negative time values are provided
"""
return formatting.timeformat(datetime.now(timezone.utc), timeformat)
def reception_time(self, timeformat='unix'):
"""Returns the GMT time telling when the meteostation history data was
received from the OWM Weather API
:param timeformat: the format for the time value. May be:
'*unix*' (default) for UNIX time
'*iso*' for ISO8601-formatted string in the format ``YYYY-MM-DD HH:MM:SS+00``
'*date* for ``datetime.datetime`` object instance
:type timeformat: str
:returns: an int or a str
:raises: ValueError
"""
return formatting.timeformat(self.rec_time, timeformat)
def reception_time(self, timeformat='unix'):
"""
Returns the GMT time telling when the UV has been received from the API
:param timeformat: the format for the time value. May be:
'*unix*' (default) for UNIX time
'*iso*' for ISO8601-formatted string in the format ``YYYY-MM-DD HH:MM:SS+00``
'*date* for ``datetime.datetime`` object instance
:type timeformat: str
:returns: an int or a str
:raises: ValueError when negative values are provided
"""
return formatting.timeformat(self.rec_time, timeformat)
def end_time(self, timeformat='unix'):
"""
Returns the UTC end time of the weather alert event
:param timeformat: the format for the time value. May be:
'*unix*' (default) for UNIX time
'*iso*' for ISO8601-formatted string in the format ``YYYY-MM-DD HH:MM:SS+00``
'*date* for ``datetime.datetime`` object instance
:type timeformat: str
:returns: an int or a str
:raises: ValueError when negative values are provided
"""
return formatting.timeformat(self.end, timeformat)
def last_update_time(self, timeformat='unix'):
"""Returns the UTC time of the last update on this station's metadata
:param timeformat: the format for the time value. May be:
'*unix*' (default) for UNIX time, '*iso*' for ISO8601-formatted
string in the format ``YYYY-MM-DD HH:MM:SS+00`` or `date` for
a ``datetime.datetime`` object
:type timeformat: str
:returns: an int or a str or a ``datetime.datetime`` object or None
:raises: ValueError
"""
if self.updated_at is None:
return None
return formatting.timeformat(self.updated_at, timeformat)
def sunrise_time(self, timeformat='unix'):
"""Returns the GMT time of sunrise. Can be `None` in case of polar nights.
:param timeformat: the format for the time value. May be:
'*unix*' (default) for UNIX time
'*iso*' for ISO8601-formatted string in the format ``YYYY-MM-DD HH:MM:SS+00``
'*date*' for ``datetime.datetime`` object instance
:type timeformat: str
:returns: 'None`, an int, a str or a `datetime.datetime` object
:raises: ValueError
"""
if self.srise_time is None:
return None
return formatting.timeformat(self.srise_time, timeformat)
def air_quality_history_at_coords(self, lat, lon, start, end=None):
"""
Queries the OWM AirPollution API for available forecasted air quality indicators around the specified coordinates.
:param lat: the location's latitude, must be between -90.0 and 90.0
:type lat: int/float
:param lon: the location's longitude, must be between -180.0 and 180.0
:type lon: int/float
:param start: the object conveying the start value of the search time window
:type start: int, ``datetime.datetime`` or ISO8601-formatted string
:param end: the object conveying the end value of the search time window. Values in the future will be clipped
to the current timestamp. Defaults to the current UNIX timestamp.
:type end: int, ``datetime.datetime`` or ISO8601-formatted string
:return: a `list` of *AirStatus* instances or an empty `list` if data is not available
:raises: *ParseResponseException* when OWM AirPollution API responses' data
cannot be parsed, *APICallException* when OWM AirPollution API can not be
reached, *ValueError* for wrong input values
"""
geo.assert_is_lon(lon)
geo.assert_is_lat(lat)
now = timestamps.now(timeformat='unix')
assert start is not None
start = formatting.timeformat(start, 'unix')
if end is None:
end = now
else:
end = formatting.timeformat(end, 'unix')
if end > now:
end = now
params = {'lon': lon, 'lat': lat, 'start': start, 'end': end}
json_data = self.new_ap_client.get_historical_air_pollution(params)
try:
return airstatus.AirStatus.from_dict(json_data)
except:
return []
def creation_time(self, timeformat='unix'):
"""Returns the UTC time of creation of this aggregated measurement
:param timeformat: the format for the time value. May be:
'*unix*' (default) for UNIX time, '*iso*' for ISO8601-formatted
string in the format ``YYYY-MM-DD HH:MM:SS+00`` or `date` for
a ``datetime.datetime`` object
:type timeformat: str
:returns: an int or a str or a ``datetime.datetime`` object or None
:raises: ValueError
"""
if self.created_at is None:
return None
return formatting.timeformat(self.created_at, timeformat)
def when_ends(self, timeformat='unix'):
"""
Returns the GMT time of the end of the forecast coverage, which is the
time of the most recent *Weather* item in the forecast
:param timeformat: the format for the time value. May be:
'*unix*' (default) for UNIX time
'*iso*' for ISO8601-formatted string in the format ``YYYY-MM-DD HH:MM:SS+00``
'*date* for ``datetime.datetime`` object instance
:type timeformat: str
:returns: a long or a str
:raises: *ValueError* when invalid time format values are provided
"""
end_coverage = max([item.reference_time() for item in self.forecast])
return formatting.timeformat(end_coverage, timeformat)