GWeather.Location

Fields

None

Methods

class detect_nearest_city_finish (result)
class get_world ()
class new_detached (name, icao, latitude, longitude)
  deserialize (serialized)
  detect_nearest_city (lat, lon, cancellable, callback, *user_data)
  equal (two)
  find_by_country_code (country_code)
  find_by_station_code (station_code)
  find_nearest_city (lat, lon)
  find_nearest_city_full (lat, lon, func, *user_data)
  free_timezones (zones)
  get_children ()
  get_city_name ()
  get_code ()
  get_coords ()
  get_country ()
  get_country_name ()
  get_distance (loc2)
  get_english_name ()
  get_level ()
  get_name ()
  get_parent ()
  get_sort_name ()
  get_timezone ()
  get_timezone_str ()
  get_timezones ()
  has_coords ()
  ref ()
  serialize ()
  unref ()

Details

class GWeather.Location

A GWeather.Location represents a “location” of some type known to libgweather; anything from a single weather station to the entire world. See GWeather.LocationLevel for information about how the hierarchy of locations works.

classmethod detect_nearest_city_finish(result)
Parameters:result (Gio.AsyncResult) –
Raises:GLib.Error
Return type:GWeather.Location
classmethod get_world()
Returns:a GWeather.LocationLevel.WORLD location, or None if Locations.xml could not be found or could not be parsed. The return value is owned by libgweather and should not be modified or freed.
Return type:GWeather.Location or None

Obtains the shared GWeather.Location of type GWeather.LocationLevel.WORLD, representing a hierarchy containing all of the locations from Locations.xml.

classmethod new_detached(name, icao, latitude, longitude)
Parameters:
  • name (str) – the user visible location name
  • icao (str or None) – the ICAO code of the location
  • latitude (float) – the latitude of the location
  • longitude (float) – the longitude of the location
Return type:

GWeather.Location

Construct a new location from the given data, supplementing any missing information from the static database.

deserialize(serialized)
Parameters:serialized (GLib.Variant) – the GLib.Variant representing the GWeather.Location
Returns:the deserialized location.
Return type:GWeather.Location

This call undoes the effect of GWeather.Location.serialize(), that is, it turns a GLib.Variant into a GWeather.Location. The conversion happens in the context of self (i.e, for a city or weather station, the resulting location will be attached to a administrative division, country and region as appropriate).

detect_nearest_city(lat, lon, cancellable, callback, *user_data)
Parameters:

Initializes geocode reversing to find place for (lat, lon) coordinates. Calls the callback function passed by user when the result is ready.

self must be at most a GWeather.LocationLevel.ADM1 location. This restriction may be lifted in a future version.

New in version 3.12.

equal(two)
Parameters:two (GWeather.Location) – another GWeather.Location
Returns:True if the two locations represent the same place as far as libgweather can tell, and False otherwise.
Return type:bool

Compares two GWeather.Location and sees if they represent the same place. It is only legal to call this for cities, weather stations or detached locations. Note that this function only checks for geographical characteristics, such as coordinates and METAR code. It is still possible that the two locations belong to different worlds (in which case care must be taken when passing them GWeather.LocationEntry and GWeather.Info), or if one is them is detached it could have a custom name.

find_by_country_code(country_code)
Parameters:country_code (str) – a country code
Returns:a country level GWeather.Location, or None.
Return type:GWeather.Location

Retrieves the country identified by the specified ISO 3166 code, if present in the database.

find_by_station_code(station_code)
Parameters:station_code (str) – a 4 letter METAR code
Returns:a weather station level GWeather.Location for station_code, or None if none exists in the database.
Return type:GWeather.Location

Retrieves the weather station identifier by station_code. Note that multiple instances of the same weather station can exist in the database, and this function will return any of them, so this not usually what you want.

See GWeather.Location.deserialize() to recover a stored GWeather.Location.

find_nearest_city(lat, lon)
Parameters:
  • lat (float) – Latitude, in degrees
  • lon (float) – Longitude, in degrees
Returns:

the city closest to (lat, lon), in the region or administrative district of self.

Return type:

GWeather.Location

Finds the nearest city to the passed latitude and longitude, among the descendants of self.

self must be at most a GWeather.LocationLevel.ADM1 location. This restriction may be lifted in a future version.

Note that this function does not check if (lat, lon) fall inside self, or are in the same region and timezone as the return value.

New in version 3.12.

find_nearest_city_full(lat, lon, func, *user_data)
Parameters:
  • lat (float) – Latitude, in degrees
  • lon (float) – Longitude, in degrees
  • func (GWeather.FilterFunc or None) – returns true to continue check for the location and false to filter the location out
  • user_data (object or None) – for customization
Returns:

the city closest to (lat, lon), in the region or administrative district of self with validation of filter function.

Return type:

GWeather.Location

Finds the nearest city to the passed latitude and longitude, among the descendants of self.

Supports the use of own filter function to filter out locations. Geocoding should be done on the application side if needed.

self must be at most a GWeather.LocationLevel.ADM1 location. This restriction may be lifted in a future version.

New in version 3.12.

free_timezones(zones)
Parameters:zones (GWeather.Timezone) – an array returned from GWeather.Location.get_timezones()

Frees the array of timezones returned by GWeather.Location.get_timezones().

get_children()
Returns:self’s children. (May be empty, but will not be None.)
Return type:[GWeather.Location]

Gets an array of self’s children; this is owned by self and will not remain valid if self is freed.

get_city_name()
Returns:self’s city name, or None
Return type:str or None

For a GWeather.LocationLevel.CITY or GWeather.LocationLevel.DETACHED location, this is equivalent to GWeather.Location.get_name(). For a GWeather.LocationLevel.WEATHER_STATION location, it is equivalent to calling GWeather.Location.get_name() on the location’s parent. For other locations it will return None.

get_code()
Returns:self’s METAR station code, or None
Return type:str or None

Gets the METAR station code associated with a GWeather.LocationLevel.WEATHER_STATION location.

get_coords()
Returns:
latitude:on return will contain self’s latitude
longitude:on return will contain self’s longitude
Return type:(latitude: float, longitude: float)

Gets self’s coordinates; you must check GWeather.Location.has_coords() before calling this.

get_country()
Returns:self’s country code (or None if self is a region- or world-level location)
Return type:str or None

Gets the ISO 3166 country code of self (or None if self is a region- or world-level location)

get_country_name()
Returns:self’s country name, or None
Return type:str or None

Gets the country name of loc. For a GWeather.LocationLevel.COUNTRY location, this is equivalent to GWeather.Location.get_name(). For a GWeather.LocationLevel.REGION and GWeather.LocationLevel.WORLD location it will return None. For other locations it will find the parent GWeather.LocationLevel.COUNTRY and return its name.

get_distance(loc2)
Parameters:loc2 (GWeather.Location) – a second GWeather.Location
Returns:the distance between self and loc2.
Return type:float

Determines the distance in kilometers between self and loc2.

get_english_name()
Returns:self’s English name
Return type:str

Gets self’s English name.

New in version 3.36.

get_level()
Returns:self’s level
Return type:GWeather.LocationLevel

Gets self’s level, from GWeather.LocationLevel.WORLD, to GWeather.LocationLevel.WEATHER_STATION.

get_name()
Returns:self’s name
Return type:str

Gets self’s name, localized into the current language.

get_parent()
Returns:self’s parent, or None if self is a GWeather.LocationLevel.WORLD node.
Return type:GWeather.Location or None

Gets self’s parent location.

get_sort_name()
Returns:self’s sort name
Return type:str

Gets self’s “sort name”, which is the name after having GLib.utf8_normalize() (with GLib.NormalizeMode.ALL) and GLib.utf8_casefold() called on it. You can use this to sort locations, or to comparing user input against a location name.

get_timezone()
Returns:self’s timezone, or None
Return type:GWeather.Timezone or None

Gets the timezone associated with self, if known.

The timezone is owned either by self or by one of its parents. FIXME.

get_timezone_str()
Returns:self’s timezone as a string, or None
Return type:str or None

Gets the timezone associated with self, if known, as a string.

The timezone string is owned either by self or by one of its parents, do not free it.

get_timezones()
Returns:an array of timezones. May be empty but will not be None.
Return type:[GWeather.Timezone]

Gets an array of all timezones associated with any location under self. You can use GWeather.Location.free_timezones() to free this array.

has_coords()
Returns:True if self has valid latitude and longitude.
Return type:bool

Checks if self has valid latitude and longitude.

ref()
Returns:self
Return type:GWeather.Location

Adds 1 to self’s reference count.

serialize()
Returns:the serialization of location.
Return type:GLib.Variant

Transforms a GWeather.Location into a GLib.Variant, in a way that calling GWeather.Location.deserialize() will hold an equivalent GWeather.Location. The resulting variant can then be stored into Gio.Settings or on disk. This call is only valid for cities, weather stations and detached locations. The format of the resulting GLib.Variant is private to libgweather, and it is subject to change. You should use the “v” format in Gio.Settings, to ensure maximum compatibility with future versions of the library.

unref()

Subtracts 1 from self’s reference count, and frees it if the reference count reaches 0.