src/nominatim_db/data/place_name.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 Data class for a single name of a place.
   9 """
  10 from typing import Optional, Dict, Mapping
  11
  12 class PlaceName:
  13     """ Each name and address part of a place is encapsulated in an object of
  14         this class. It saves not only the name proper but also describes the
  15         kind of name with two properties:
  16
  17         * `kind` describes the name of the OSM key used without any suffixes
  18           (i.e. the part after the colon removed)
  19         * `suffix` contains the suffix of the OSM tag, if any. The suffix
  20           is the part of the key after the first colon.
  21
  22         In addition to that, a name may have arbitrary additional attributes.
  23         How attributes are used, depends on the sanitizers and token analysers.
  24         The exception is the 'analyzer' attribute. This attribute determines
  25         which token analysis module will be used to finalize the treatment of
  26         names.
  27     """
  28
  29     def __init__(self, name: str, kind: str, suffix: Optional[str]):
  30         self.name = name
  31         self.kind = kind
  32         self.suffix = suffix
  33         self.attr: Dict[str, str] = {}
  34
  35
  36     def __repr__(self) -> str:
  37         return f"PlaceName(name={self.name!r},kind={self.kind!r},suffix={self.suffix!r})"
  38
  39
  40     def clone(self, name: Optional[str] = None,
  41               kind: Optional[str] = None,
  42               suffix: Optional[str] = None,
  43               attr: Optional[Mapping[str, str]] = None) -> 'PlaceName':
  44         """ Create a deep copy of the place name, optionally with the
  45             given parameters replaced. In the attribute list only the given
  46             keys are updated. The list is not replaced completely.
  47             In particular, the function cannot to be used to remove an
  48             attribute from a place name.
  49         """
  50         newobj = PlaceName(name or self.name,
  51                            kind or self.kind,
  52                            suffix or self.suffix)
  53
  54         newobj.attr.update(self.attr)
  55         if attr:
  56             newobj.attr.update(attr)
  57
  58         return newobj
  59
  60
  61     def set_attr(self, key: str, value: str) -> None:
  62         """ Add the given property to the name. If the property was already
  63             set, then the value is overwritten.
  64         """
  65         self.attr[key] = value
  66
  67
  68     def get_attr(self, key: str, default: Optional[str] = None) -> Optional[str]:
  69         """ Return the given property or the value of 'default' if it
  70             is not set.
  71         """
  72         return self.attr.get(key, default)
  73
  74
  75     def has_attr(self, key: str) -> bool:
  76         """ Check if the given attribute is set.
  77         """
  78         return key in self.attr