src/nominatim_db/tokenizer/sanitizers/config.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 Configuration for Sanitizers.
   9 """
  10 from typing import Sequence, Union, Optional, Pattern, Callable, Any, TYPE_CHECKING
  11 from collections import UserDict
  12 import re
  13
  14 from ...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
  24 class SanitizerConfig(_BaseUserDict):
  25     """ The `SanitizerConfig` class is a read-only dictionary
  26         with configuration options for the sanitizer.
  27         In addition to the usual dictionary functions, the class provides
  28         accessors to standard sanitizer options that are used by many of the
  29         sanitizers.
  30     """
  31
  32     def get_string_list(self, param: str, default: Sequence[str] = tuple()) -> Sequence[str]:
  33         """ Extract a configuration parameter as a string list.
  34
  35             Arguments:
  36                 param: Name of the configuration parameter.
  37                 default: Takes a tuple or list of strings which will
  38                          be returned if the parameter is missing in the
  39                          sanitizer configuration.
  40                          Note that if this default parameter is not
  41                          provided then an empty list is returned.
  42
  43             Returns:
  44                 If the parameter value is a simple string, it is returned as a
  45                     one-item list. If the parameter value does not exist, the given
  46                     default is returned. If the parameter value is a list, it is
  47                     checked to contain only strings before being returned.
  48         """
  49         values = self.data.get(param, None)
  50
  51         if values is None:
  52             return list(default)
  53
  54         if isinstance(values, str):
  55             return [values] if values else []
  56
  57         if not isinstance(values, (list, tuple)):
  58             raise UsageError(f"Parameter '{param}' must be string or list of strings.")
  59
  60         if any(not isinstance(value, str) for value in values):
  61             raise UsageError(f"Parameter '{param}' must be string or list of strings.")
  62
  63         return values
  64
  65     def get_bool(self, param: str, default: Optional[bool] = None) -> bool:
  66         """ Extract a configuration parameter as a boolean.
  67
  68             Arguments:
  69                 param: Name of the configuration parameter. The parameter must
  70                        contain one of the yaml boolean values or an
  71                        UsageError will be raised.
  72                 default: Value to return, when the parameter is missing.
  73                          When set to `None`, the parameter must be defined.
  74
  75             Returns:
  76                 Boolean value of the given parameter.
  77         """
  78         value = self.data.get(param, default)
  79
  80         if not isinstance(value, bool):
  81             raise UsageError(f"Parameter '{param}' must be a boolean value ('yes' or 'no').")
  82
  83         return value
  84
  85     def get_delimiter(self, default: str = ',;') -> Pattern[str]:
  86         """ Return the 'delimiters' parameter in the configuration as a
  87             compiled regular expression that can be used to split strings on
  88             these delimiters.
  89
  90             Arguments:
  91                 default: Delimiters to be used when 'delimiters' parameter
  92                          is not explicitly configured.
  93
  94             Returns:
  95                 A regular expression pattern which can be used to
  96                     split a string. The regular expression makes sure that the
  97                     resulting names are stripped and that repeated delimiters
  98                     are ignored. It may still create empty fields on occasion. The
  99                     code needs to filter those.
 100         """
 101         delimiter_set = set(self.data.get('delimiters', default))
 102         if not delimiter_set:
 103             raise UsageError("Empty 'delimiter' parameter not allowed for sanitizer.")
 104
 105         return re.compile('\\s*[{}]+\\s*'.format(''.join('\\' + d for d in delimiter_set)))
 106
 107     def get_filter(self, param: str, default: Union[str, Sequence[str]] = 'PASS_ALL'
 108                    ) -> Callable[[str], bool]:
 109         """ Returns a filter function for the given parameter of the sanitizer
 110             configuration.
 111
 112             The value provided for the parameter in sanitizer configuration
 113             should be a string or list of strings, where each string is a regular
 114             expression. These regular expressions will later be used by the
 115             filter function to filter strings.
 116
 117             Arguments:
 118                 param: The parameter for which the filter function
 119                        will be created.
 120                 default: Defines the behaviour of filter function if
 121                          parameter is missing in the sanitizer configuration.
 122                          Takes a string(PASS_ALL or FAIL_ALL) or a list of strings.
 123                          Any other value of string or an empty list is not allowed,
 124                          and will raise a ValueError. If the value is PASS_ALL, the filter
 125                          function will let all strings to pass, if the value is FAIL_ALL,
 126                          filter function will let no strings to pass.
 127                          If value provided is a list of strings each string
 128                          is treated as a regular expression. In this case these regular
 129                          expressions will be used by the filter function.
 130                          By default allow filter function to let all strings pass.
 131
 132             Returns:
 133                 A filter function that takes a target string as the argument and
 134                     returns True if it fully matches any of the regular expressions
 135                     otherwise returns False.
 136         """
 137         filters = self.get_string_list(param) or default
 138
 139         if filters == 'PASS_ALL':
 140             return lambda _: True
 141         if filters == 'FAIL_ALL':
 142             return lambda _: False
 143
 144         if filters and isinstance(filters, (list, tuple)):
 145             regexes = [re.compile(regex) for regex in filters]
 146             return lambda target: any(regex.fullmatch(target) for regex in regexes)
 147
 148         raise ValueError("Default parameter must be a non-empty list or a string value \
 149                           ('PASS_ALL' or 'FAIL_ALL').")