pyowm.utils package

Submodules

pyowm.utils.geo module

pyowm.utils.temputils module

Module containing utility functions for temperature and wind units conversion

pyowm.utils.temputils.kelvin_dict_to(d, target_temperature_unit)

Converts all the values in a dict from Kelvin temperatures to the specified temperature format.

Parameters:

• d (dict) – the dictionary containing Kelvin temperature values
• target_temperature_unit (str) – the target temperature unit, may be: ‘celsius’ or ‘fahrenheit’

Returns:

a dict with the same keys as the input dict and converted temperature values as values

Raises:

ValueError when unknown target temperature units are provided

pyowm.utils.temputils.kelvin_to_celsius(kelvintemp)

Converts a numeric temperature from Kelvin degrees to Celsius degrees

Parameters:kelvintemp (int/long/float) – the Kelvin temperature Returns:the float Celsius temperature Raises:TypeError when bad argument types are provided

pyowm.utils.temputils.kelvin_to_fahrenheit(kelvintemp)

Converts a numeric temperature from Kelvin degrees to Fahrenheit degrees

Parameters:kelvintemp (int/long/float) – the Kelvin temperature Returns:the float Fahrenheit temperature Raises:TypeError when bad argument types are provided

pyowm.utils.temputils.metric_wind_dict_to_imperial(d)

Converts all the wind values in a dict from meters/sec (metric measurement system) to miles/hour (imperial measurement system) .

Parameters:d (dict) – the dictionary containing metric values Returns:a dict with the same keys as the input dict and values converted to miles/hour

pyowm.utils.timeformatutils module

Module containing utility functions for time formats conversion

class pyowm.utils.timeformatutils.UTC

Bases: datetime.tzinfo

dst(dt)

datetime -> DST offset in minutes east of UTC.

tzname(dt)

datetime -> string name of time zone.

utcoffset(dt)

datetime -> timedelta showing offset from UTC, negative values indicating West of UTC

pyowm.utils.timeformatutils.timeformat(timeobject, timeformat)

Formats the specified time object to the target format type.

Parameters:

• timeobject (int, datetime.datetime or ISO8601-formatted string with pattern YYYY-MM-DD HH:MM:SS+00) – the object conveying the time value
• timeformat (str) – the target format for the time conversion. May be: ‘unix’ (outputs an int UNIXtime), ‘date’ (outputs a datetime.datetime object) or ‘iso’ (outputs an ISO8601-formatted string with pattern YYYY-MM-DD HH:MM:SS+00)

Returns:

the formatted time

Raises:

ValueError when unknown timeformat switches are provided or when negative time values are provided

pyowm.utils.timeformatutils.to_ISO8601(timeobject)

Returns the ISO8601-formatted string corresponding to the time value conveyed by the specified object, which can be either a UNIXtime, a datetime.datetime object or an ISO8601-formatted string in the format YYYY-MM-DD HH:MM:SS+00`.

Parameters:timeobject (int, datetime.datetime or ISO8601-formatted string) – the object conveying the time value Returns:an ISO8601-formatted string with pattern YYYY-MM-DD HH:MM:SS+00` Raises:TypeError when bad argument types are provided, ValueError when negative UNIXtimes are provided

pyowm.utils.timeformatutils.to_UNIXtime(timeobject)

Returns the UNIXtime corresponding to the time value conveyed by the specified object, which can be either a UNIXtime, a datetime.datetime object or an ISO8601-formatted string in the format YYYY-MM-DD HH:MM:SS+00`.

Parameters:timeobject (int, datetime.datetime or ISO8601-formatted string) – the object conveying the time value Returns:an int UNIXtime Raises:TypeError when bad argument types are provided, ValueError when negative UNIXtimes are provided

pyowm.utils.timeformatutils.to_date(timeobject)

Returns the datetime.datetime object corresponding to the time value conveyed by the specified object, which can be either a UNIXtime, a datetime.datetime object or an ISO8601-formatted string in the format YYYY-MM-DD HH:MM:SS+00`.

Parameters:timeobject (int, datetime.datetime or ISO8601-formatted string) – the object conveying the time value Returns:a datetime.datetime object Raises:TypeError when bad argument types are provided, ValueError when negative UNIXtimes are provided

pyowm.utils.timeutils module

Module containing utility functions for time values generation/management

pyowm.utils.timeutils.last_hour(date=None)

Gives the datetime.datetime object corresponding to the last hour before now or before the specified datetime.datetime object.

Parameters:date (datetime.datetime object) – the date you want an hour to be subtracted from (if left None, the current date and time will be used) Returns:a datetime.datetime object

pyowm.utils.timeutils.last_month(date=None)

Gives the datetime.datetime object corresponding to the last month before now or before the specified datetime.datetime object. A month corresponds to 30 days.

Parameters:date (datetime.datetime object) – the date you want a month to be subtracted from (if left None, the current date and time will be used) Returns:a datetime.datetime object

pyowm.utils.timeutils.last_three_hours(date=None)

Gives the datetime.datetime object corresponding to last three hours before now or before the specified datetime.datetime object.

Parameters:date (datetime.datetime object) – the date you want three hours to be subtracted from (if left None, the current date and time will be used) Returns:a datetime.datetime object

pyowm.utils.timeutils.last_week(date=None)

Gives the datetime.datetime object corresponding to the last week before now or before the specified datetime.datetime object. A week corresponds to 7 days.

Parameters:date (datetime.datetime object) – the date you want a week to be subtracted from (if left None, the current date and time will be used) Returns:a datetime.datetime object

pyowm.utils.timeutils.last_year(date=None)

Gives the datetime.datetime object corresponding to the last year before now or before the specified datetime.datetime object. A year corresponds to 365 days.

Parameters:date (datetime.datetime object) – the date you want a year to be subtracted from (if left None, the current date and time will be used) Returns:a datetime.datetime object

pyowm.utils.timeutils.millis_offset_between_epochs(reference_epoch, target_epoch)

Calculates the signed milliseconds delta between the reference unix epoch and the provided target unix epoch :param reference_epoch: the unix epoch that the millis offset has to be calculated with respect to :type reference_epoch: int :param target_epoch: the unix epoch for which the millis offset has to be calculated :type target_epoch: int :return: int

pyowm.utils.timeutils.next_hour(date=None)

Gives the datetime.datetime object corresponding to the next hour from now or from the specified datetime.datetime object.

Parameters:date (datetime.datetime object) – the date you want an hour to be added (if left None, the current date and time will be used) Returns:a datetime.datetime object

pyowm.utils.timeutils.next_month(date=None)

Gives the datetime.datetime object corresponding to the next month after now or after the specified datetime.datetime object. A month corresponds to 30 days.

Parameters:date (datetime.datetime object) – the date you want a month to be added to (if left None, the current date and time will be used) Returns:a datetime.datetime object

pyowm.utils.timeutils.next_three_hours(date=None)

Gives the datetime.datetime object corresponding to the next three hours from now or from the specified datetime.datetime object.

Parameters:date (datetime.datetime object) – the date you want three hours to be added (if left None, the current date and time will be used) Returns:a datetime.datetime object

pyowm.utils.timeutils.next_week(date=None)

Gives the datetime.datetime object corresponding to the next week from now or from the specified datetime.datetime object. A week corresponds to 7 days.

Parameters:date (datetime.datetime object) – the date you want a week to be added (if left None, the current date and time will be used) Returns:a datetime.datetime object

pyowm.utils.timeutils.next_year(date=None)

Gives the datetime.datetime object corresponding to the next year after now or after the specified datetime.datetime object. A month corresponds to 30 days.

Parameters:date (datetime.datetime object) – the date you want a year to be added to (if left None, the current date and time will be used) Returns:a datetime.datetime object

pyowm.utils.timeutils.now(timeformat='date')

Returns the current time in the specified timeformat.

Parameters:timeformat (str) – 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) Returns:the current time value Raises:ValueError when unknown timeformat switches are provided or when negative time values are provided

pyowm.utils.timeutils.tomorrow(hour=None, minute=None)

Gives the datetime.datetime object corresponding to tomorrow. The default value for optional parameters is the current value of hour and minute. I.e: when called without specifying values for parameters, the resulting object will refer to the time = now + 24 hours; when called with only hour specified, the resulting object will refer to tomorrow at the specified hour and at the current minute.

Parameters:

• hour (int) – the hour for tomorrow, in the format 0-23 (defaults to None)
• minute (int) – the minute for tomorrow, in the format 0-59 (defaults to None)

Returns:

a datetime.datetime object

Raises:

ValueError when hour or minute have bad values

pyowm.utils.timeutils.yesterday(hour=None, minute=None)

Gives the datetime.datetime object corresponding to yesterday. The default value for optional parameters is the current value of hour and minute. I.e: when called without specifying values for parameters, the resulting object will refer to the time = now - 24 hours; when called with only hour specified, the resulting object will refer to yesterday at the specified hour and at the current minute.

Parameters:

• hour (int) – the hour for yesterday, in the format 0-23 (defaults to None)
• minute (int) – the minute for yesterday, in the format 0-59 (defaults to None)

Returns:

a datetime.datetime object

Raises:

ValueError when hour or minute have bad values

pyowm.utils.weatherutils module

Module containing search and filter utilities for Weather objects lists management

pyowm.utils.weatherutils.any_status_is(weather_list, status, weather_code_registry)

Checks if the weather status code of any of the Weather objects in the provided list corresponds to the detailed status indicated. The lookup is performed against the provided WeatherCodeRegistry object.

Parameters:

• weathers (list) – a list of Weather objects
• status (str) – a string indicating a detailed weather status
• weather_code_registry (WeatherCodeRegistry) – a WeatherCodeRegistry object

Returns:

True if the check is positive, False otherwise

pyowm.utils.weatherutils.filter_by_status(weather_list, status, weather_code_registry)

Filters out from the provided list of Weather objects a sublist of items having a status corresponding to the provided one. The lookup is performed against the provided WeatherCodeRegistry object.

Parameters:

• weathers (list) – a list of Weather objects
• status (str) – a string indicating a detailed weather status
• weather_code_registry (WeatherCodeRegistry) – a WeatherCodeRegistry object

Returns:

True if the check is positive, False otherwise

pyowm.utils.weatherutils.find_closest_weather(weathers_list, unixtime)

Extracts from the provided list of Weather objects the item which is closest in time to the provided UNIXtime.

Parameters:

• weathers_list (list) – a list of Weather objects
• unixtime (int) – a UNIX time

Returns:

the Weather object which is closest in time or None if the list is empty

pyowm.utils.weatherutils.is_in_coverage(unixtime, weathers_list)

Checks if the supplied UNIX time is contained into the time range (coverage) defined by the most ancient and most recent Weather objects in the supplied list

Parameters:

• unixtime (int) – the UNIX time to be searched in the time range
• weathers_list (list) – the list of Weather objects to be scanned for global time coverage

Returns:

True if the UNIX time is contained into the time range, False otherwise

pyowm.utils.weatherutils.status_is(weather, status, weather_code_registry)

Checks if the weather status code of a Weather object corresponds to the detailed status indicated. The lookup is performed against the provided WeatherCodeRegistry object.

Parameters:

• weather (Weather) – the Weather object whose status code is to be checked
• status (str) – a string indicating a detailed weather status
• weather_code_registry (WeatherCodeRegistry) – a WeatherCodeRegistry object

Returns:

True if the check is positive, False otherwise

pyowm.utils.xmlutils module

Module containing utility functions for generating XML strings

pyowm.utils.xmlutils.DOM_node_to_XML(tree, xml_declaration=True)

Prints a DOM tree to its Unicode representation.

Parameters:

• tree (an xml.etree.ElementTree.Element object) – the input DOM tree
• xml_declaration (bool) – if True (default) prints a leading XML declaration line

Returns:

Unicode object

pyowm.utils.xmlutils.annotate_with_XMLNS(tree, prefix, URI)

Annotates the provided DOM tree with XMLNS attributes and adds XMLNS prefixes to the tags of the tree nodes.

Parameters:

• tree (an xml.etree.ElementTree.ElementTree or xml.etree.ElementTree.Element object) – the input DOM tree
• prefix (str) – XMLNS prefix for tree nodes’ tags
• URI (str) – the URI for the XMLNS definition file

pyowm.utils.xmlutils.create_DOM_node_from_dict(d, name, parent_node)

Dumps dict data to an xml.etree.ElementTree.SubElement DOM subtree object and attaches it to the specified DOM parent node. The created subtree object is named after the specified name. If the supplied dict is None no DOM node is created for it as well as no DOM subnodes are generated for eventual None values found inside the dict

Parameters:

• d (dict) – the input dictionary
• name (str) – the name for the DOM subtree to be created
• parent_node (xml.etree.ElementTree.Element or derivative objects) – the parent DOM node the newly created subtree must be attached to

Returns:

xml.etree.ElementTree.SubElementTree object

Module contents