Merge remote-tracking branch 'upstream/master'

[nominatim.git] / nominatim / data / place_info.py

diff --git a/nominatim/data/place_info.py b/nominatim/data/place_info.py
index 96912a61e36176900f7b557fd0e70a838af58784..91e77a588514ca4c2cd457d95286ca49883dd7e0 100644 (file)
--- a/nominatim/data/place_info.py
+++ b/nominatim/data/place_info.py
@@ -8,11 +8,11 @@
 Wrapper around place information the indexer gets from the database and hands to
 the tokenizer.
 """
-from typing import Optional, Mapping, Any
+from typing import Optional, Mapping, Any, Tuple
 
 class PlaceInfo:
-    """ Data class containing all information the tokenizer gets about a
-        place it should process the names for.
+    """ This data class contains all information the tokenizer can access
+        about a place.
     """
 
     def __init__(self, info: Mapping[str, Any]) -> None:
@@ -21,16 +21,25 @@ class PlaceInfo:
 
     @property
     def name(self) -> Optional[Mapping[str, str]]:
-        """ A dictionary with the names of the place or None if the place
-            has no names.
+        """ A dictionary with the names of the place. Keys and values represent
+            the full key and value of the corresponding OSM tag. Which tags
+            are saved as names is determined by the import style.
+            The property may be None if the place has no names.
         """
         return self._info.get('name')
 
 
     @property
     def address(self) -> Optional[Mapping[str, str]]:
-        """ A dictionary with the address elements of the place
-            or None if no address information is available.
+        """ A dictionary with the address elements of the place. They key
+            usually corresponds to the suffix part of the key of an OSM
+            'addr:*' or 'isin:*' tag. There are also some special keys like
+            `country` or `country_code` which merge OSM keys that contain
+            the same information. See [Import Styles][1] for details.
+
+            The property may be None if the place has no address information.
+
+            [1]: ../customize/Import-Styles.md
         """
         return self._info.get('address')
 
@@ -38,28 +47,39 @@ class PlaceInfo:
     @property
     def country_code(self) -> Optional[str]:
         """ The country code of the country the place is in. Guaranteed
-            to be a two-letter lower-case string or None, if no country
-            could be found.
+            to be a two-letter lower-case string. If the place is not inside
+            any country, the property is set to None.
         """
         return self._info.get('country_code')
 
 
     @property
     def rank_address(self) -> int:
-        """ The computed rank address before rank correction.
+        """ The [rank address][1] before any rank correction is applied.
+
+            [1]: ../customize/Ranking.md#address-rank
         """
         return self._info.get('rank_address', 0)
 
 
+    @property
+    def centroid(self) -> Optional[Tuple[float, float]]:
+        """ A center point of the place in WGS84. May be None when the
+            geometry of the place is unknown.
+        """
+        x, y = self._info.get('centroid_x'), self._info.get('centroid_y')
+        return None if x is None or y is None else (x, y)
+
+
     def is_a(self, key: str, value: str) -> bool:
-        """ Check if the place's primary tag corresponds to the given
+        """ Set to True when the place's primary tag corresponds to the given
             key and value.
         """
         return self._info.get('class') == key and self._info.get('type') == value
 
 
     def is_country(self) -> bool:
-        """ Check if the place is a valid country boundary.
+        """ Set to True when the place is a valid country boundary.
         """
         return self.rank_address == 4 \
                and self.is_a('boundary', 'administrative') \