pyowm.utils package

Submodules

pyowm.utils.config module

pyowm.utils.config.get_config_from(path_to_file)

Loads configuration data from the supplied file and returns it.

Parameters:

path_to_file (str) – path to the configuration file

Returns:

the configuration dict

Raises:

ConfigurationNotFoundError when the supplied filepath is not a regular file; ConfigurationParseError when the supplied file cannot be parsed

pyowm.utils.config.get_default_config()

Returns the default PyOWM configuration.

Returns:

the configuration dict

pyowm.utils.config.get_default_config_for_proxy(http_url, https_url)

Returns the PyOWM configuration to be used behind a proxy server

Parameters:

• http_url (str) – URL connection string for HTTP protocol

• https_url (str) – URL connection string for HTTPS protocol

Returns:

the configuration dict

pyowm.utils.config.get_default_config_for_subscription_type(name)

Returns the PyOWM configuration for a specific OWM API Plan subscription type

Parameters:

name (str) – name of the subscription type

Returns:

the configuration dict

pyowm.utils.decorators module

pyowm.utils.decorators.deprecated(will_be=None, on_version=None, name=None)

Function decorator that warns about deprecation upon function invocation. :param will_be: str representing the target action on the deprecated function :param on_version: tuple representing a SW version :param name: name of the entity to be deprecated (useful when decorating __init__ methods so you can specify the deprecated class name) :return: callable

pyowm.utils.geo module

class pyowm.utils.geo.Geometry

Bases: object

Abstract parent class for geotypes

geojson()

Returns a GeoJSON string representation of this geotype, compliant to RFC 7946 (https://tools.ietf.org/html/rfc7946) :return: str

to_dict()

Returns a dict representation of this geotype :return: dict

class pyowm.utils.geo.GeometryBuilder

Bases: object

classmethod build(the_dict)

Builds a pyowm.utils.geo.Geometry subtype based on the geoJSON geometry type specified on the input dictionary :param the_dict: a geoJSON compliant dict :return: a pyowm.utils.geo.Geometry subtype instance :raises ValueError if unable to the geometry type cannot be recognized

class pyowm.utils.geo.MultiPoint(list_of_tuples)

Bases: Geometry

A MultiPoint geotype. Represents a set of geographic points

Parameters:

list_of_tuples (list) – list of tuples, each one being the decimal (lon, lat) coordinates of a geopoint

Returns:

a MultiPoint instance

classmethod from_dict(the_dict)

Builds a MultiPoint instance out of a geoJSON compliant dict :param the_dict: the geoJSON dict :return: pyowm.utils.geo.MultiPoint instance

classmethod from_points(iterable_of_points)

Creates a MultiPoint from an iterable collection of pyowm.utils.geo.Point instances :param iterable_of_points: iterable whose items are pyowm.utils.geo.Point instances :type iterable_of_points: iterable :return: a MultiPoint instance

geojson()

Returns a GeoJSON string representation of this geotype, compliant to RFC 7946 (https://tools.ietf.org/html/rfc7946) :return: str

property latitudes

List of decimal latitudes of this MultiPoint instance :return: list of tuples

property longitudes

List of decimal longitudes of this MultiPoint instance :return: list of tuples

to_dict()

Returns a dict representation of this geotype :return: dict

class pyowm.utils.geo.MultiPolygon(iterable_of_list_of_lists)

Bases: Geometry

A MultiPolygon geotype. Each MultiPolygon represents a set of (also djsjoint) Polygons. Each MultiPolygon is composed by an iterable whose elements are the list of lists defining a Polygon geotype. Please refer to the pyowm.utils.geo.Point documentation for details

Parameters:

iterable_of_list_of_lists (iterable) – iterable whose elements are list of lists of tuples

Returns:

a MultiPolygon instance

Raises:

ValueError when last point and fist point do not coincide or when no points are specified at all

classmethod from_dict(the_dict)

Builds a MultiPolygoninstance out of a geoJSON compliant dict :param the_dict: the geoJSON dict :return: pyowm.utils.geo.MultiPolygon instance

classmethod from_polygons(iterable_of_polygons)

Creates a MultiPolygon instance out of an iterable of Polygon geotypes :param iterable_of_polygons: list of pyowm.utils.geo.Point instances :type iterable_of_polygons: iterable :returns: a MultiPolygon instance

geojson()

Returns a GeoJSON string representation of this geotype, compliant to RFC 7946 (https://tools.ietf.org/html/rfc7946) :return: str

to_dict()

Returns a dict representation of this geotype :return: dict

class pyowm.utils.geo.Point(lon, lat)

Bases: Geometry

A Point geotype. Represents a single geographic point

Parameters:

• lon (int of float) – decimal longitude for the geopoint

• lat (int of float) – decimal latitude for the geopoint

Returns:

a Point instance

Raises:

ValueError when negative values are provided

bounding_square_polygon(inscribed_circle_radius_km=10.0)

Returns a square polygon (bounding box) that circumscribes the circle having this geopoint as centre and having the specified radius in kilometers. The polygon’s points calculation is based on theory exposed by: http://janmatuschek.de/LatitudeLongitudeBoundingCoordinates by Jan Philip Matuschek, owner of the intellectual property of such material. In short: - locally to the geopoint, the Earth’s surface is approximated to a sphere with radius = Earth’s radius - the calculation works fine also when the bounding box contains the Earth’s poles and the 180 deg meridian

Parameters:

inscribed_circle_radius_km (int or float) – the radius of the inscribed circle, defaults to 10 kms

Returns:

a pyowm.utils.geo.Polygon instance

classmethod from_dict(the_dict)

Builds a Point instance out of a geoJSON compliant dict :param the_dict: the geoJSON dict :return: pyowm.utils.geo.Point instance

geojson()

Returns a GeoJSON string representation of this geotype, compliant to RFC 7946 (https://tools.ietf.org/html/rfc7946) :return: str

property lat

property lon

to_dict()

Returns a dict representation of this geotype :return: dict

class pyowm.utils.geo.Polygon(list_of_lists)

Bases: Geometry

A Polygon geotype. Each Polygon is made up by one or more lines: a line represents a set of connected geographic points and is conveyed by a list of points, the last one of which must coincide with the its very first one. As said, Polygons can be also made up by multiple lines (therefore, Polygons with “holes” are allowed) :param list_of_lists: list of lists, each sublist being a line and being composed by tuples - each one being the decimal (lon, lat) couple of a geopoint. The last point specified MUST coincide with the first one specified :type list_of_lists: list :returns: a MultiPoint instance :raises: ValueError when last point and fist point do not coincide or when no points are specified at all

classmethod from_dict(the_dict)

Builds a Polygon instance out of a geoJSON compliant dict :param the_dict: the geoJSON dict :return: pyowm.utils.geo.Polygon instance

classmethod from_points(list_of_lists)

Creates a Polygon instance out of a list of lists, each sublist being populated with pyowm.utils.geo.Point instances :param list_of_lists: list :type: list_of_lists: iterable_of_polygons :returns: a Polygon instance

geojson()

Returns a GeoJSON string representation of this geotype, compliant to RFC 7946 (https://tools.ietf.org/html/rfc7946) :return: str

property points

Returns the list of Point instances representing the points of the polygon :return: list of Point objects

to_dict()

Returns a dict representation of this geotype :return: dict

pyowm.utils.geo.assert_is_lat(val)

Checks it the given value is a feasible decimal latitude

Parameters:

val (int of float) – value to be checked

Returns:

None

Raises:

ValueError if value is out of latitude boundaries, AssertionError if type is wrong

pyowm.utils.geo.assert_is_lon(val)

Checks it the given value is a feasible decimal longitude

Parameters:

val (int of float) – value to be checked

Returns:

None

Raises:

ValueError if value is out of longitude boundaries, AssertionError if type is wrong

pyowm.utils.measurables module

pyowm.utils.measurables.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.measurables.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.measurables.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.measurables.metric_pressure_dict_to_inhg(d)

Converts all barometric pressure values in a dict to “inches of mercury.”

Parameters:

d (dict) – the dictionary containing metric values

Returns:

a dict with the same keys as the input dict and values converted to “Hg or inHg (inches of mercury)

Note what OWM says about pressure: “Atmospheric pressure [is given in hPa] (on the sea level, if there is no sea_level or grnd_level data)”

pyowm.utils.measurables.metric_wind_dict_to_beaufort(d)

Converts all the wind values in a dict from meters/sec to the corresponding Beaufort scale level (which is not an exact number but rather represents a range of wind speeds - see: https://en.wikipedia.org/wiki/Beaufort_scale). Conversion table: https://www.windfinder.com/wind/windspeed.htm

Parameters:

d (dict) – the dictionary containing metric values

Returns:

a dict with the same keys as the input dict and values converted to Beaufort level

pyowm.utils.measurables.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.measurables.metric_wind_dict_to_km_h(d)

Converts all the wind values in a dict from meters/sec to km/hour.

Parameters:

d (dict) – the dictionary containing metric values

Returns:

a dict with the same keys as the input dict and values converted to km/hour

pyowm.utils.measurables.metric_wind_dict_to_knots(d)

Converts all the wind values in a dict from meters/sec to knots

Parameters:

d (dict) – the dictionary containing metric values

Returns:

a dict with the same keys as the input dict and values converted to km/hour

pyowm.utils.measurables.visibility_distance_to(v, target_visibility_unit='kilometers')

Converts visibility distance (in meters) to kilometers or miles Defaults to kilometer conversion

Parameters:

• distance (int) – the value of visibility_distance

• target_visibility_unit (str) – the unit of conversion

Returns:

a converted value for visibility_distance (float)

pyowm.utils.formatting module

pyowm.utils.formatting.ISO8601_to_UNIXtime(iso)

Converts an ISO8601-formatted string in the format YYYY-MM-DD HH:MM:SS+00:00 to the correspondent UNIXtime

Parameters:

iso (string) – the ISO8601-formatted string

Returns:

an int UNIXtime

Raises:

TypeError when bad argument types are provided, ValueError when the ISO8601 string is badly formatted

class pyowm.utils.formatting.UTC

Bases: tzinfo

dst(dt)

datetime -> DST offset as timedelta positive 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.formatting.datetime_to_UNIXtime(date)

Converts a datetime.datetime object to its correspondent UNIXtime

Parameters:

date (datetime.datetime) – the datetime.datetime object

Returns:

an int UNIXtime

Raises:

TypeError when bad argument types are provided

pyowm.utils.formatting.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: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:00)

Returns:

the formatted time

Raises:

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

pyowm.utils.formatting.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: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:00`

Raises:

TypeError when bad argument types are provided, ValueError when negative UNIXtimes are provided

pyowm.utils.formatting.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: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.formatting.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: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.timestamps module

pyowm.utils.timestamps.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.timestamps.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.timestamps.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.timestamps.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.timestamps.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.timestamps.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.timestamps.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.timestamps.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.timestamps.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.timestamps.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.timestamps.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.timestamps.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.timestamps.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.timestamps.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.weather module

pyowm.utils.weather.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.weather.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.weather.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.weather.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.weather.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

Module contents