nominatim/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 Nominatim configuration accessor.
   9 """
  10 from typing import Dict, Any, List, Mapping, Optional
  11 import importlib.util
  12 import logging
  13 import os
  14 import sys
  15 from pathlib import Path
  16 import json
  17 import yaml
  18
  19 from dotenv import dotenv_values
  20 from psycopg2.extensions import parse_dsn
  21
  22 from nominatim.typing import StrPath
  23 from nominatim.errors import UsageError
  24 import nominatim.paths
  25
  26 LOG = logging.getLogger()
  27 CONFIG_CACHE : Dict[str, Any] = {}
  28
  29 def flatten_config_list(content: Any, section: str = '') -> List[Any]:
  30     """ Flatten YAML configuration lists that contain include sections
  31         which are lists themselves.
  32     """
  33     if not content:
  34         return []
  35
  36     if not isinstance(content, list):
  37         raise UsageError(f"List expected in section '{section}'.")
  38
  39     output = []
  40     for ele in content:
  41         if isinstance(ele, list):
  42             output.extend(flatten_config_list(ele, section))
  43         else:
  44             output.append(ele)
  45
  46     return output
  47
  48
  49 class Configuration:
  50     """ The `Configuration` class wraps access to the local configuration
  51         options as described in the [Configuration page](../customize/Settings.md).
  52
  53         Nominatim uses dotenv to configure the software. Configuration options
  54         are resolved in the following order:
  55
  56         * from the OS environment (or the dictionary given in `environ`)
  57         * from the .env file in the project directory of the installation
  58         * from the default installation in the configuration directory
  59
  60         All Nominatim configuration options are prefixed with 'NOMINATIM_' to
  61         avoid conflicts with other environment variables. All settings can
  62         be accessed as properties of the class under the same name as the
  63         setting but with the `NOMINATIM_` prefix removed. In addition, there
  64         are accessor functions that convert the setting values to types
  65         other than string.
  66     """
  67
  68     def __init__(self, project_dir: Optional[Path],
  69                  environ: Optional[Mapping[str, str]] = None) -> None:
  70         self.environ = environ or os.environ
  71         self.project_dir = project_dir
  72         self.config_dir = nominatim.paths.CONFIG_DIR
  73         self._config = dotenv_values(str(self.config_dir / 'env.defaults'))
  74         if self.project_dir is not None and (self.project_dir / '.env').is_file():
  75             self.project_dir = self.project_dir.resolve()
  76             self._config.update(dotenv_values(str(self.project_dir / '.env')))
  77
  78         class _LibDirs:
  79             module: Path
  80             osm2pgsql: Path
  81             php = nominatim.paths.PHPLIB_DIR
  82             sql = nominatim.paths.SQLLIB_DIR
  83             data = nominatim.paths.DATA_DIR
  84
  85         self.lib_dir = _LibDirs()
  86         self._private_plugins: Dict[str, object] = {}
  87
  88
  89     def set_libdirs(self, **kwargs: StrPath) -> None:
  90         """ Set paths to library functions and data.
  91         """
  92         for key, value in kwargs.items():
  93             setattr(self.lib_dir, key, Path(value))
  94
  95
  96     def __getattr__(self, name: str) -> str:
  97         name = 'NOMINATIM_' + name
  98
  99         if name in self.environ:
 100             return self.environ[name]
 101
 102         return self._config[name] or ''
 103
 104
 105     def get_bool(self, name: str) -> bool:
 106         """ Return the given configuration parameter as a boolean.
 107             Values of '1', 'yes' and 'true' are accepted as truthy values,
 108             everything else is interpreted as false.
 109
 110             Parameters:
 111               name: Name of the configuration parameter with the NOMINATIM_
 112                 prefix removed.
 113
 114             Returns:
 115               `True` for values of '1', 'yes' and 'true', `False` otherwise.
 116         """
 117         return getattr(self, name).lower() in ('1', 'yes', 'true')
 118
 119
 120     def get_int(self, name: str) -> int:
 121         """ Return the given configuration parameter as an int.
 122
 123             Parameters:
 124               name: Name of the configuration parameter with the NOMINATIM_
 125                 prefix removed.
 126
 127             Returns:
 128               The configuration value converted to int.
 129
 130             Raises:
 131               ValueError: when the value is not a number.
 132         """
 133         try:
 134             return int(getattr(self, name))
 135         except ValueError as exp:
 136             LOG.fatal("Invalid setting NOMINATIM_%s. Needs to be a number.", name)
 137             raise UsageError("Configuration error.") from exp
 138
 139
 140     def get_str_list(self, name: str) -> Optional[List[str]]:
 141         """ Return the given configuration parameter as a list of strings.
 142             The values are assumed to be given as a comma-sparated list and
 143             will be stripped before returning them. On empty values None
 144             is returned.
 145         """
 146         raw = getattr(self, name)
 147
 148         return [v.strip() for v in raw.split(',')] if raw else None
 149
 150
 151     def get_path(self, name: str) -> Optional[Path]:
 152         """ Return the given configuration parameter as a Path.
 153             If a relative path is configured, then the function converts this
 154             into an absolute path with the project directory as root path.
 155             If the configuration is unset, None is returned.
 156         """
 157         value = getattr(self, name)
 158         if not value:
 159             return None
 160
 161         cfgpath = Path(value)
 162
 163         if not cfgpath.is_absolute():
 164             assert self.project_dir is not None
 165             cfgpath = self.project_dir / cfgpath
 166
 167         return cfgpath.resolve()
 168
 169
 170     def get_libpq_dsn(self) -> str:
 171         """ Get configured database DSN converted into the key/value format
 172             understood by libpq and psycopg.
 173         """
 174         dsn = self.DATABASE_DSN
 175
 176         def quote_param(param: str) -> str:
 177             key, val = param.split('=')
 178             val = val.replace('\\', '\\\\').replace("'", "\\'")
 179             if ' ' in val:
 180                 val = "'" + val + "'"
 181             return key + '=' + val
 182
 183         if dsn.startswith('pgsql:'):
 184             # Old PHP DSN format. Convert before returning.
 185             return ' '.join([quote_param(p) for p in dsn[6:].split(';')])
 186
 187         return dsn
 188
 189
 190     def get_database_params(self) -> Mapping[str, str]:
 191         """ Get the configured parameters for the database connection
 192             as a mapping.
 193         """
 194         dsn = self.DATABASE_DSN
 195
 196         if dsn.startswith('pgsql:'):
 197             return dict((p.split('=', 1) for p in dsn[6:].split(';')))
 198
 199         return parse_dsn(dsn)
 200
 201
 202     def get_import_style_file(self) -> Path:
 203         """ Return the import style file as a path object. Translates the
 204             name of the standard styles automatically into a file in the
 205             config style.
 206         """
 207         style = getattr(self, 'IMPORT_STYLE')
 208
 209         if style in ('admin', 'street', 'address', 'full', 'extratags'):
 210             return self.config_dir / f'import-{style}.lua'
 211
 212         return self.find_config_file('', 'IMPORT_STYLE')
 213
 214
 215     def get_os_env(self) -> Dict[str, str]:
 216         """ Return a copy of the OS environment with the Nominatim configuration
 217             merged in.
 218         """
 219         env = {k: v for k, v in self._config.items() if v is not None}
 220         env.update(self.environ)
 221
 222         return env
 223
 224
 225     def load_sub_configuration(self, filename: StrPath,
 226                                config: Optional[str] = None) -> Any:
 227         """ Load additional configuration from a file. `filename` is the name
 228             of the configuration file. The file is first searched in the
 229             project directory and then in the global settings directory.
 230
 231             If `config` is set, then the name of the configuration file can
 232             be additionally given through a .env configuration option. When
 233             the option is set, then the file will be exclusively loaded as set:
 234             if the name is an absolute path, the file name is taken as is,
 235             if the name is relative, it is taken to be relative to the
 236             project directory.
 237
 238             The format of the file is determined from the filename suffix.
 239             Currently only files with extension '.yaml' are supported.
 240
 241             YAML files support a special '!include' construct. When the
 242             directive is given, the value is taken to be a filename, the file
 243             is loaded using this function and added at the position in the
 244             configuration tree.
 245         """
 246         configfile = self.find_config_file(filename, config)
 247
 248         if str(configfile) in CONFIG_CACHE:
 249             return CONFIG_CACHE[str(configfile)]
 250
 251         if configfile.suffix in ('.yaml', '.yml'):
 252             result = self._load_from_yaml(configfile)
 253         elif configfile.suffix == '.json':
 254             with configfile.open('r', encoding='utf-8') as cfg:
 255                 result = json.load(cfg)
 256         else:
 257             raise UsageError(f"Config file '{configfile}' has unknown format.")
 258
 259         CONFIG_CACHE[str(configfile)] = result
 260         return result
 261
 262
 263     def load_plugin_module(self, module_name: str, internal_path: str) -> Any:
 264         """ Load a Python module as a plugin.
 265
 266             The module_name may have three variants:
 267
 268             * A name without any '.' is assumed to be an internal module
 269               and will be searched relative to `internal_path`.
 270             * If the name ends in `.py`, module_name is assumed to be a
 271               file name relative to the project directory.
 272             * Any other name is assumed to be an absolute module name.
 273
 274             In either of the variants the module name must start with a letter.
 275         """
 276         if not module_name or not module_name[0].isidentifier():
 277             raise UsageError(f'Invalid module name {module_name}')
 278
 279         if '.' not in module_name:
 280             module_name = module_name.replace('-', '_')
 281             full_module = f'{internal_path}.{module_name}'
 282             return sys.modules.get(full_module) or importlib.import_module(full_module)
 283
 284         if module_name.endswith('.py'):
 285             if self.project_dir is None or not (self.project_dir / module_name).exists():
 286                 raise UsageError(f"Cannot find module '{module_name}' in project directory.")
 287
 288             if module_name in self._private_plugins:
 289                 return self._private_plugins[module_name]
 290
 291             file_path = str(self.project_dir / module_name)
 292             spec = importlib.util.spec_from_file_location(module_name, file_path)
 293             if spec:
 294                 module = importlib.util.module_from_spec(spec)
 295                 # Do not add to global modules because there is no standard
 296                 # module name that Python can resolve.
 297                 self._private_plugins[module_name] = module
 298                 assert spec.loader is not None
 299                 spec.loader.exec_module(module)
 300
 301                 return module
 302
 303         return sys.modules.get(module_name) or importlib.import_module(module_name)
 304
 305
 306     def find_config_file(self, filename: StrPath,
 307                          config: Optional[str] = None) -> Path:
 308         """ Resolve the location of a configuration file given a filename and
 309             an optional configuration option with the file name.
 310             Raises a UsageError when the file cannot be found or is not
 311             a regular file.
 312         """
 313         if config is not None:
 314             cfg_value = getattr(self, config)
 315             if cfg_value:
 316                 cfg_filename = Path(cfg_value)
 317
 318                 if cfg_filename.is_absolute():
 319                     cfg_filename = cfg_filename.resolve()
 320
 321                     if not cfg_filename.is_file():
 322                         LOG.fatal("Cannot find config file '%s'.", cfg_filename)
 323                         raise UsageError("Config file not found.")
 324
 325                     return cfg_filename
 326
 327                 filename = cfg_filename
 328
 329
 330         search_paths = [self.project_dir, self.config_dir]
 331         for path in search_paths:
 332             if path is not None and (path / filename).is_file():
 333                 return path / filename
 334
 335         LOG.fatal("Configuration file '%s' not found.\nDirectories searched: %s",
 336                   filename, search_paths)
 337         raise UsageError("Config file not found.")
 338
 339
 340     def _load_from_yaml(self, cfgfile: Path) -> Any:
 341         """ Load a YAML configuration file. This installs a special handler that
 342             allows to include other YAML files using the '!include' operator.
 343         """
 344         yaml.add_constructor('!include', self._yaml_include_representer,
 345                              Loader=yaml.SafeLoader)
 346         return yaml.safe_load(cfgfile.read_text(encoding='utf-8'))
 347
 348
 349     def _yaml_include_representer(self, loader: Any, node: yaml.Node) -> Any:
 350         """ Handler for the '!include' operator in YAML files.
 351
 352             When the filename is relative, then the file is first searched in the
 353             project directory and then in the global settings directory.
 354         """
 355         fname = loader.construct_scalar(node)
 356
 357         if Path(fname).is_absolute():
 358             configfile = Path(fname)
 359         else:
 360             configfile = self.find_config_file(loader.construct_scalar(node))
 361
 362         if configfile.suffix != '.yaml':
 363             LOG.fatal("Format error while reading '%s': only YAML format supported.",
 364                       configfile)
 365             raise UsageError("Cannot handle config file format.")
 366
 367         return yaml.safe_load(configfile.read_text(encoding='utf-8'))