pyowm.commons package

Submodules

pyowm.commons.cityids

pyowm.commons.cityidregistry module

class pyowm.commons.cityidregistry.CityIDRegistry(sqlite_db_path: str)

Bases: object

MATCHINGS = {'exact': 'SELECT city_id, name, country, state, lat, lon FROM city WHERE name=?', 'like': 'SELECT city_id, name, country, state, lat, lon FROM city WHERE name LIKE ?'}

geopoints_for(city_name, country=None, state=None, matching='like')

Returns a list of pyowm.utils.geo.Point objects corresponding to the int IDs and relative toponyms and 2-chars country of the cities matching the provided city name. The rule for identifying matchings is according to the provided matching parameter value. If country is provided, the search is restricted to the cities of the specified country. :param city_name: the string toponym of the city to search :param country: two character str representing the country where to search for the city. Defaults to None, which means: search in all countries. :param state: two character str representing the state where to search for the city. Defaults to None. When not None also state must be specified :param matching: str. Default is nocase. Possible values: exact - literal, case-sensitive matching like - matches cities whose name contains, as a substring, the string fed to the function, case-insensitive, :raises ValueError if the value for matching is unknown :return: list of pyowm.utils.geo.Point objects

classmethod get_instance()

Factory method returning the default city ID registry :return: a CityIDRegistry instance

ids_for(city_name, country=None, state=None, matching='like')

Returns a list of tuples in the form (city_id, name, country, state, lat, lon ) The rule for querying follows the provided matching parameter value. If country is provided, the search is restricted to the cities of the specified country, and an even stricter search when state is provided as well :param city_name: the string toponym of the city to search :param country: two character str representing the country where to search for the city. Defaults to None, which means: search in all countries. :param state: two character str representing the state where to search for the city. Defaults to None. When not None also state must be specified :param matching: str. Default is like. Possible values: exact - literal, case-sensitive matching like - matches cities whose name contains, as a substring, the string fed to the function, case-insensitive, :raises ValueError if the value for matching is unknown :return: list of tuples

locations_for(city_name, country=None, state=None, matching='like')

Returns a list of Location objects The rule for querying follows the provided matching parameter value. If country is provided, the search is restricted to the cities of the specified country, and an even stricter search when state is provided as well :param city_name: the string toponym of the city to search :param country: two character str representing the country where to search for the city. Defaults to None, which means: search in all countries. :param state: two character str representing the state where to search for the city. Defaults to None. When not None also state must be specified :param matching: str. Default is like. Possible values: exact - literal, case-sensitive matching like - matches cities whose name contains, as a substring, the string fed to the function, case-insensitive, :raises ValueError if the value for matching is unknown :return: list of Location objects

pyowm.commons.databoxes module

class pyowm.commons.databoxes.ImageType(name, mime_type)

Bases: object

Databox class representing an image type

Parameters:

• name (str) – the image type name

• mime_type (str) – the image type MIME type

class pyowm.commons.databoxes.Satellite(name, symbol)

Bases: object

Databox class representing a satellite

Parameters:

• name (str) – the satellite

• symbol (str) – the short name of the satellite

class pyowm.commons.databoxes.SubscriptionType(name, subdomain, is_paid)

Bases: object

Databox class representing a type of subscription to OpenWeatherMap web APIs

Parameters:

• name (str) – the name of the subscription

• subdomain (str) – the root API subdomain associated to the subscription

• is_paid (bool) – tells if the subscription plan is paid

pyowm.commons.enums module

class pyowm.commons.enums.ImageTypeEnum

Bases: object

Allowed image types on OWM APIs

GEOTIFF = <pyowm.commons.databoxes.ImageType - name=GEOTIFF mime=image/tiff>

PNG = <pyowm.commons.databoxes.ImageType - name=PNG mime=image/png>

classmethod items()

All values for this enum :return: list of pyowm.commons.enums.ImageType

classmethod lookup_by_mime_type(mime_type)

classmethod lookup_by_name(name)

class pyowm.commons.enums.SubscriptionTypeEnum

Bases: object

Allowed OpenWeatherMap subscription types

DEVELOPER = <pyowm.commons.databoxes.SubscriptionType - name=developer subdomain=api paid=True>

ENTERPRISE = <pyowm.commons.databoxes.SubscriptionType - name=enterprise subdomain=api paid=True>

FREE = <pyowm.commons.databoxes.SubscriptionType - name=free subdomain=api paid=False>

PROFESSIONAL = <pyowm.commons.databoxes.SubscriptionType - name=professional subdomain=api paid=True>

STARTUP = <pyowm.commons.databoxes.SubscriptionType - name=startup subdomain=api paid=True>

classmethod items()

All values for this enum :return: list of pyowm.commons.enums.SubscriptionType

classmethod lookup_by_name(name)

pyowm.commons.exceptions module

exception pyowm.commons.exceptions.APIRequestError

Bases: PyOWMError

Error class that represents network/infrastructural failures when invoking OWM Weather API, in example due to network errors.

exception pyowm.commons.exceptions.APIResponseError

Bases: PyOWMError

Generic base class for exceptions representing HTTP error status codes in OWM Weather API responses

exception pyowm.commons.exceptions.BadGatewayError

Bases: APIRequestError

Error class that represents 502 errors - i.e when upstream backend cannot communicate with API gateways.

exception pyowm.commons.exceptions.ConfigurationError

Bases: PyOWMError

Generic base class for configuration related errors

exception pyowm.commons.exceptions.ConfigurationNotFoundError

Bases: ConfigurationError

Raised when configuration source file is not available

exception pyowm.commons.exceptions.ConfigurationParseError

Bases: ConfigurationError

Raised on failures in parsing configuration data

exception pyowm.commons.exceptions.InvalidSSLCertificateError

Bases: APIRequestError

Error class that represents failure in verifying the SSL certificate provided by the OWM API

exception pyowm.commons.exceptions.NotFoundError

Bases: APIResponseError

Error class that represents the situation when an entity is not found.

exception pyowm.commons.exceptions.ParseAPIResponseError

Bases: PyOWMError

Error class that represents failures when parsing payload data in HTTP responses sent by the OWM Weather API.

exception pyowm.commons.exceptions.PyOWMError

Bases: Exception

Generic base class for PyOWM exceptions

exception pyowm.commons.exceptions.TimeoutError

Bases: APIRequestError

Error class that represents response timeout conditions

exception pyowm.commons.exceptions.UnauthorizedError

Bases: APIResponseError

Error class that represents the situation when an entity cannot be retrieved due to user subscription insufficient capabilities.

pyowm.commons.http_client module

class pyowm.commons.http_client.HttpClient(api_key, config, root_uri, admits_subdomains=True)

Bases: object

An HTTP client encapsulating some config data and abstarcting away data raw retrieval

Parameters:

• api_key (str) – the OWM API key

• config (dict) – the configuration dictionary (if not provided, a default one will be used)

• root_uri (str) – the root URI of the API endpoint

• admits_subdomains (bool) – if the root URI of the API endpoint admits subdomains based on the subcription type (default: True)

classmethod check_status_code(status_code, payload)

delete(path, params=None, data=None, headers=None)

get_geotiff(path, params=None, headers=None)

get_json(path, params=None, headers=None)

get_png(path, params=None, headers=None)

post(path, params=None, data=None, headers=None)

put(path, params=None, data=None, headers=None)

class pyowm.commons.http_client.HttpRequestBuilder(root_uri_token, api_key, config, has_subdomains=True)

Bases: object

URL_TEMPLATE_WITHOUT_SUBDOMAINS = '{}://{}/{}'

A stateful HTTP URL, params and headers builder with a fluent interface

URL_TEMPLATE_WITH_SUBDOMAINS = '{}://{}.{}/{}'

build()

with_api_key()

with_header(key, value)

with_headers(headers)

with_language()

with_path(path_uri_token)

with_query_params(query_params)

pyowm.commons.image module

class pyowm.commons.image.Image(data, image_type=None)

Bases: object

Wrapper class for a generic image

Parameters:

• data (bytes) – raw image data

• image_type (pyowm.commons.databoxes.ImageType or None) – the type of the image, if known

classmethod load(path_to_file)

Loads the image data from a file on disk and tries to guess the image MIME type

Parameters:

path_to_file (str) – path to the source file

Returns:

a pyowm.image.Image instance

persist(path_to_file)

Saves the image to disk on a file

Parameters:

path_to_file (str) – path to the target file

Returns:

None

pyowm.commons.tile module

class pyowm.commons.tile.Tile(x, y, zoom, map_layer, image)

Bases: object

Wrapper class for an image tile :param x: horizontal tile number in OWM tile reference system :type x: int :param y: vertical tile number in OWM tile reference system :type y: int :param zoom: zoom level for the tile :type zoom: int :param map_layer: the name of the OWM map layer this tile belongs to :type map_layer: str :param image: raw image data :type image: pyowm.commons.image.Image instance

bounding_polygon()

Returns the bounding box polygon for this tile

Returns:

pywom.utils.geo.Polygon instance

classmethod geoocoords_to_tile_coords(lon, lat, zoom)

Calculates the tile numbers corresponding to the specified geocoordinates at the specified zoom level Coordinates shall be provided in degrees and using the Mercator Projection (http://en.wikipedia.org/wiki/Mercator_projection)

Parameters:

• lon (int or float) – longitude

• lat (int or float) – latitude

• zoom (int) – zoom level

Returns:

a tuple (x, y) containing the tile-coordinates

persist(path_to_file)

Saves the tile to disk on a file

Parameters:

path_to_file (str) – path to the target file

Returns:

None

classmethod tile_coords_for_point(geopoint, zoom)

Returns the coordinates of the tile containing the specified geopoint at the specified zoom level

Parameters:

• geopoint (pywom.utils.geo.Point) – the input geopoint instance

• zoom (int) – zoom level

Returns:

a tuple (x, y) containing the tile-coordinates

classmethod tile_coords_to_bbox(x, y, zoom)

Calculates the lon/lat estrema of the bounding box corresponding to specific tile coordinates. Output coordinates are in degrees and in the Mercator Projection (http://en.wikipedia.org/wiki/Mercator_projection)

Parameters:

• x – the x tile coordinates

• y – the y tile coordinates

• zoom – the zoom level

Returns:

tuple with (lon_left, lat_bottom, lon_right, lat_top)

Module contents