nominatim/tokenizer/sanitizers/base.py

   1 # SPDX-License-Identifier: GPL-2.0-only
   2 #
   3 # This file is part of Nominatim. (https://nominatim.org)
   4 #
   5 # Copyright (C) 2022 by the Nominatim developer community.
   6 # For a full list of authors see the git log.
   7 """
   8 Common data types and protocols for sanitizers.
   9 """
  10 from typing import Optional, Dict, List, Mapping, Callable
  11
  12 from nominatim.tokenizer.sanitizers.config import SanitizerConfig
  13 from nominatim.data.place_info import PlaceInfo
  14 from nominatim.typing import Protocol, Final
  15
  16 class PlaceName:
  17     """ A searchable name for a place together with properties.
  18         Every name object saves the name proper and two basic properties:
  19         * 'kind' describes the name of the OSM key used without any suffixes
  20           (i.e. the part after the colon removed)
  21         * 'suffix' contains the suffix of the OSM tag, if any. The suffix
  22           is the part of the key after the first colon.
  23         In addition to that, the name may have arbitrary additional attributes.
  24         Which attributes are used, depends on the token analyser.
  25     """
  26
  27     def __init__(self, name: str, kind: str, suffix: Optional[str]):
  28         self.name = name
  29         self.kind = kind
  30         self.suffix = suffix
  31         self.attr: Dict[str, str] = {}
  32
  33
  34     def __repr__(self) -> str:
  35         return f"PlaceName(name='{self.name}',kind='{self.kind}',suffix='{self.suffix}')"
  36
  37
  38     def clone(self, name: Optional[str] = None,
  39               kind: Optional[str] = None,
  40               suffix: Optional[str] = None,
  41               attr: Optional[Mapping[str, str]] = None) -> 'PlaceName':
  42         """ Create a deep copy of the place name, optionally with the
  43             given parameters replaced. In the attribute list only the given
  44             keys are updated. The list is not replaced completely.
  45             In particular, the function cannot to be used to remove an
  46             attribute from a place name.
  47         """
  48         newobj = PlaceName(name or self.name,
  49                            kind or self.kind,
  50                            suffix or self.suffix)
  51
  52         newobj.attr.update(self.attr)
  53         if attr:
  54             newobj.attr.update(attr)
  55
  56         return newobj
  57
  58
  59     def set_attr(self, key: str, value: str) -> None:
  60         """ Add the given property to the name. If the property was already
  61             set, then the value is overwritten.
  62         """
  63         self.attr[key] = value
  64
  65
  66     def get_attr(self, key: str, default: Optional[str] = None) -> Optional[str]:
  67         """ Return the given property or the value of 'default' if it
  68             is not set.
  69         """
  70         return self.attr.get(key, default)
  71
  72
  73     def has_attr(self, key: str) -> bool:
  74         """ Check if the given attribute is set.
  75         """
  76         return key in self.attr
  77
  78
  79 class ProcessInfo:
  80     """ Container class for information handed into to handler functions.
  81         The 'names' and 'address' members are mutable. A handler must change
  82         them by either modifying the lists place or replacing the old content
  83         with a new list.
  84     """
  85
  86     def __init__(self, place: PlaceInfo):
  87         self.place: Final = place
  88         self.names = self._convert_name_dict(place.name)
  89         self.address = self._convert_name_dict(place.address)
  90
  91
  92     @staticmethod
  93     def _convert_name_dict(names: Optional[Mapping[str, str]]) -> List[PlaceName]:
  94         """ Convert a dictionary of names into a list of PlaceNames.
  95             The dictionary key is split into the primary part of the key
  96             and the suffix (the part after an optional colon).
  97         """
  98         out = []
  99
 100         if names:
 101             for key, value in names.items():
 102                 parts = key.split(':', 1)
 103                 out.append(PlaceName(value.strip(),
 104                                      parts[0].strip(),
 105                                      parts[1].strip() if len(parts) > 1 else None))
 106
 107         return out
 108
 109
 110 class SanitizerHandler(Protocol):
 111     """ Protocol for sanitizer modules.
 112     """
 113
 114     def create(self, config: SanitizerConfig) -> Callable[[ProcessInfo], None]:
 115         """
 116         A sanitizer must define a single function `create`. It takes the
 117         dictionary with the configuration information for the sanitizer and
 118         returns a function that transforms name and address.
 119         """