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 87ecb731b9ee8e989c5069ecd9ae3c54161676f0..1bfd512c38e169e318373ff61a04aab3cd122f4f 100644 (file)
--- a/nominatim/data/place_info.py
+++ b/nominatim/data/place_info.py
@@ -8,66 +8,78 @@
 Wrapper around place information the indexer gets from the database and hands to
 the tokenizer.
 """
 Wrapper around place information the indexer gets from the database and hands to
 the tokenizer.
 """

-
-import psycopg2.extras
+from typing import Optional, Mapping, Any, Tuple

 
 class PlaceInfo:
 
 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):
+    def __init__(self, info: Mapping[str, Any]) -> None:

         self._info = info
 
 
         self._info = info
 
 

-    def analyze(self, analyzer):
-        """ Process this place with the given tokenizer and return the
-            result in psycopg2-compatible Json.
-        """
-        return psycopg2.extras.Json(analyzer.process_place(self))
-
-

     @property
     @property

-    def name(self):
-        """ A dictionary with the names of the place or None if the place
-            has no names.
+    def name(self) -> Optional[Mapping[str, str]]:
+        """ 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
         """
         return self._info.get('name')
 
 
     @property

-    def address(self):
-        """ A dictionary with the address elements of the place
-            or None if no address information is available.
+    def address(self) -> Optional[Mapping[str, str]]:
+        """ 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')
 
 
     @property
         """
         return self._info.get('address')
 
 
     @property

-    def country_code(self):
+    def country_code(self) -> Optional[str]:

         """ The country code of the country the place is in. Guaranteed
         """ 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
         """
         return self._info.get('country_code')
 
 
     @property

-    def rank_address(self):
-        """ The computed rank address before rank correction.
+    def rank_address(self) -> int:
+        """ The [rank address][1] before ant 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.

         """
         """

-        return self._info.get('rank_address')
+        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, value):
-        """ Check if the place's primary tag corresponds to the given
+    def is_a(self, key: str, value: str) -> bool:
+        """ 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
 
 
             key and value.
         """
         return self._info.get('class') == key and self._info.get('type') == value
 
 

-    def is_country(self):
-        """ Check if the place is a valid country boundary.
+    def is_country(self) -> bool:
+        """ Set to True when the place is a valid country boundary.

         """
         return self.rank_address == 4 \
                and self.is_a('boundary', 'administrative') \
         """
         return self.rank_address == 4 \
                and self.is_a('boundary', 'administrative') \