src/nominatim_db/data/place_info.py

   1 # SPDX-License-Identifier: GPL-3.0-or-later
   2 #
   3 # This file is part of Nominatim. (https://nominatim.org)
   4 #
   5 # Copyright (C) 2024 by the Nominatim developer community.
   6 # For a full list of authors see the git log.
   7 """
   8 Wrapper around place information the indexer gets from the database and hands to
   9 the tokenizer.
  10 """
  11 from typing import Optional, Mapping, Any, Tuple
  12
  13 class PlaceInfo:
  14     """ This data class contains all information the tokenizer can access
  15         about a place.
  16     """
  17
  18     def __init__(self, info: Mapping[str, Any]) -> None:
  19         self._info = info
  20
  21
  22     @property
  23     def name(self) -> Optional[Mapping[str, str]]:
  24         """ A dictionary with the names of the place. Keys and values represent
  25             the full key and value of the corresponding OSM tag. Which tags
  26             are saved as names is determined by the import style.
  27             The property may be None if the place has no names.
  28         """
  29         return self._info.get('name')
  30
  31
  32     @property
  33     def address(self) -> Optional[Mapping[str, str]]:
  34         """ A dictionary with the address elements of the place. They key
  35             usually corresponds to the suffix part of the key of an OSM
  36             'addr:*' or 'isin:*' tag. There are also some special keys like
  37             `country` or `country_code` which merge OSM keys that contain
  38             the same information. See [Import Styles][1] for details.
  39
  40             The property may be None if the place has no address information.
  41
  42             [1]: ../customize/Import-Styles.md
  43         """
  44         return self._info.get('address')
  45
  46
  47     @property
  48     def country_code(self) -> Optional[str]:
  49         """ The country code of the country the place is in. Guaranteed
  50             to be a two-letter lower-case string. If the place is not inside
  51             any country, the property is set to None.
  52         """
  53         return self._info.get('country_code')
  54
  55
  56     @property
  57     def rank_address(self) -> int:
  58         """ The [rank address][1] before any rank correction is applied.
  59
  60             [1]: ../customize/Ranking.md#address-rank
  61         """
  62         return self._info.get('rank_address', 0)
  63
  64
  65     @property
  66     def centroid(self) -> Optional[Tuple[float, float]]:
  67         """ A center point of the place in WGS84. May be None when the
  68             geometry of the place is unknown.
  69         """
  70         x, y = self._info.get('centroid_x'), self._info.get('centroid_y')
  71         return None if x is None or y is None else (x, y)
  72
  73
  74     def is_a(self, key: str, value: str) -> bool:
  75         """ Set to True when the place's primary tag corresponds to the given
  76             key and value.
  77         """
  78         return self._info.get('class') == key and self._info.get('type') == value
  79
  80
  81     def is_country(self) -> bool:
  82         """ Set to True when the place is a valid country boundary.
  83         """
  84         return self.rank_address == 4 \
  85                and self.is_a('boundary', 'administrative') \
  86                and self.country_code is not None