nominatim/tokenizer/sanitizers/config.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 Configuration for Sanitizers.
   9 """
  10 from typing import Sequence, Optional, Pattern, Callable, Any, TYPE_CHECKING
  11 from collections import UserDict
  12 import re
  13
  14 from nominatim.errors import UsageError
  15
  16 # working around missing generics in Python < 3.8
  17 # See https://github.com/python/typing/issues/60#issuecomment-869757075
  18 if TYPE_CHECKING:
  19     _BaseUserDict = UserDict[str, Any]
  20 else:
  21     _BaseUserDict = UserDict
  22
  23 class SanitizerConfig(_BaseUserDict):
  24     """ The `SanitizerConfig` class is a read-only dictionary
  25         with configuration options for the sanitizer.
  26         In addition to the usual dictionary functions, the class provides
  27         accessors to standard sanitizer options that are used by many of the
  28         sanitizers.
  29     """
  30
  31     def get_string_list(self, param: str, default: Sequence[str] = tuple()) -> Sequence[str]:
  32         """ Extract a configuration parameter as a string list.
  33
  34             Arguments:
  35                 param: Name of the configuration parameter.
  36                 default: Value to return, when the parameter is missing.
  37
  38             Returns:
  39                 If the parameter value is a simple string, it is returned as a
  40                 one-item list. If the parameter value does not exist, the given
  41                 default is returned. If the parameter value is a list, it is
  42                 checked to contain only strings before being returned.
  43         """
  44         values = self.data.get(param, None)
  45
  46         if values is None:
  47             return None if default is None else list(default)
  48
  49         if isinstance(values, str):
  50             return [values] if values else []
  51
  52         if not isinstance(values, (list, tuple)):
  53             raise UsageError(f"Parameter '{param}' must be string or list of strings.")
  54
  55         if any(not isinstance(value, str) for value in values):
  56             raise UsageError(f"Parameter '{param}' must be string or list of strings.")
  57
  58         return values
  59
  60
  61     def get_bool(self, param: str, default: Optional[bool] = None) -> bool:
  62         """ Extract a configuration parameter as a boolean.
  63
  64             Arguments:
  65                 param: Name of the configuration parameter. The parameter must
  66                        contain one of the yaml boolean values or an
  67                        UsageError will be raised.
  68                 default: Value to return, when the parameter is missing.
  69                          When set to `None`, the parameter must be defined.
  70
  71             Returns:
  72                 Boolean value of the given parameter.
  73         """
  74         value = self.data.get(param, default)
  75
  76         if not isinstance(value, bool):
  77             raise UsageError(f"Parameter '{param}' must be a boolean value ('yes' or 'no'.")
  78
  79         return value
  80
  81
  82     def get_delimiter(self, default: str = ',;') -> Pattern[str]:
  83         """ Return the 'delimiters' parameter in the configuration as a
  84             compiled regular expression that can be used to split strings on
  85             these delimiters.
  86
  87             Arguments:
  88                 default: Delimiters to be used when 'delimiters' parameter
  89                          is not explicitly configured.
  90
  91             Returns:
  92                 A regular expression pattern which can be used to
  93                 split a string. The regular expression makes sure that the
  94                 resulting names are stripped and that repeated delimiters
  95                 are ignored. It may still create empty fields on occasion. The
  96                 code needs to filter those.
  97         """
  98         delimiter_set = set(self.data.get('delimiters', default))
  99         if not delimiter_set:
 100             raise UsageError("Empty 'delimiter' parameter not allowed for sanitizer.")
 101
 102         return re.compile('\\s*[{}]+\\s*'.format(''.join('\\' + d for d in delimiter_set)))
 103
 104
 105     def get_filter_kind(self, *default: str) -> Callable[[str], bool]:
 106         """ Return a filter function for the name kind from the 'filter-kind'
 107             config parameter.
 108
 109             If the 'filter-kind' parameter is empty, the filter lets all items
 110             pass. If the parameter is a string, it is interpreted as a single
 111             regular expression that must match the full kind string.
 112             If the parameter is a list then
 113             any of the regular expressions in the list must match to pass.
 114
 115             Arguments:
 116                 default: Filters to be used, when the 'filter-kind' parameter
 117                          is not specified. If omitted then the default is to
 118                          let all names pass.
 119
 120             Returns:
 121                 A filter function which takes a name string and returns
 122                 True when the item passes the filter.
 123         """
 124         filters = self.get_string_list('filter-kind', default)
 125
 126         if not filters:
 127             return lambda _: True
 128
 129         regexes = [re.compile(regex) for regex in filters]
 130
 131         return lambda name: any(regex.fullmatch(name) for regex in regexes)