src/nominatim_db/cli.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 Command-line interface to the Nominatim functions for import, update,
   9 database administration and querying.
  10 """
  11 from typing import Optional, Any
  12 import importlib
  13 import logging
  14 import os
  15 import sys
  16 import argparse
  17 import asyncio
  18 from pathlib import Path
  19
  20 from .config import Configuration
  21 from .errors import UsageError
  22 from .tools.exec_utils import run_php_server
  23 from . import clicmd
  24 from . import version
  25 from .clicmd.args import NominatimArgs, Subcommand
  26
  27 LOG = logging.getLogger()
  28
  29 class CommandlineParser:
  30     """ Wraps some of the common functions for parsing the command line
  31         and setting up subcommands.
  32     """
  33     def __init__(self, prog: str, description: Optional[str]):
  34         self.parser = argparse.ArgumentParser(
  35             prog=prog,
  36             description=description,
  37             formatter_class=argparse.RawDescriptionHelpFormatter)
  38
  39         self.subs = self.parser.add_subparsers(title='available commands',
  40                                                dest='subcommand')
  41
  42         # Global arguments that only work if no sub-command given
  43         self.parser.add_argument('--version', action='store_true',
  44                                  help='Print Nominatim version and exit')
  45
  46         # Arguments added to every sub-command
  47         self.default_args = argparse.ArgumentParser(add_help=False)
  48         group = self.default_args.add_argument_group('Default arguments')
  49         group.add_argument('-h', '--help', action='help',
  50                            help='Show this help message and exit')
  51         group.add_argument('-q', '--quiet', action='store_const', const=0,
  52                            dest='verbose', default=1,
  53                            help='Print only error messages')
  54         group.add_argument('-v', '--verbose', action='count', default=1,
  55                            help='Increase verboseness of output')
  56         group.add_argument('--project-dir', metavar='DIR', default='.',
  57                            help='Base directory of the Nominatim installation (default:.)')
  58         group.add_argument('-j', '--threads', metavar='NUM', type=int,
  59                            help='Number of parallel threads to use')
  60
  61
  62     def nominatim_version_text(self) -> str:
  63         """ Program name and version number as string
  64         """
  65         text = f'Nominatim version {version.NOMINATIM_VERSION!s}'
  66         if version.GIT_COMMIT_HASH is not None:
  67             text += f' ({version.GIT_COMMIT_HASH})'
  68         return text
  69
  70
  71     def add_subcommand(self, name: str, cmd: Subcommand) -> None:
  72         """ Add a subcommand to the parser. The subcommand must be a class
  73             with a function add_args() that adds the parameters for the
  74             subcommand and a run() function that executes the command.
  75         """
  76         assert cmd.__doc__ is not None
  77
  78         parser = self.subs.add_parser(name, parents=[self.default_args],
  79                                       help=cmd.__doc__.split('\n', 1)[0],
  80                                       description=cmd.__doc__,
  81                                       formatter_class=argparse.RawDescriptionHelpFormatter,
  82                                       add_help=False)
  83         parser.set_defaults(command=cmd)
  84         cmd.add_args(parser)
  85
  86
  87     def run(self, **kwargs: Any) -> int:
  88         """ Parse the command line arguments of the program and execute the
  89             appropriate subcommand.
  90         """
  91         args = NominatimArgs()
  92         try:
  93             self.parser.parse_args(args=kwargs.get('cli_args'), namespace=args)
  94         except SystemExit:
  95             return 1
  96
  97         if args.version:
  98             print(self.nominatim_version_text())
  99             return 0
 100
 101         if args.subcommand is None:
 102             self.parser.print_help()
 103             return 1
 104
 105         args.project_dir = Path(args.project_dir).resolve()
 106
 107         if 'cli_args' not in kwargs:
 108             logging.basicConfig(stream=sys.stderr,
 109                                 format='%(asctime)s: %(message)s',
 110                                 datefmt='%Y-%m-%d %H:%M:%S',
 111                                 level=max(4 - args.verbose, 1) * 10)
 112
 113         args.config = Configuration(args.project_dir,
 114                                     environ=kwargs.get('environ', os.environ))
 115         args.config.set_libdirs(module=kwargs['module_dir'],
 116                                 osm2pgsql=kwargs['osm2pgsql_path'])
 117
 118         log = logging.getLogger()
 119         log.warning('Using project directory: %s', str(args.project_dir))
 120
 121         try:
 122             return args.command.run(args)
 123         except UsageError as exception:
 124             if log.isEnabledFor(logging.DEBUG):
 125                 raise # use Python's exception printing
 126             log.fatal('FATAL: %s', exception)
 127
 128         # If we get here, then execution has failed in some way.
 129         return 1
 130
 131
 132 # Subcommand classes
 133 #
 134 # Each class needs to implement two functions: add_args() adds the CLI parameters
 135 # for the subfunction, run() executes the subcommand.
 136 #
 137 # The class documentation doubles as the help text for the command. The
 138 # first line is also used in the summary when calling the program without
 139 # a subcommand.
 140 #
 141 # No need to document the functions each time.
 142 # pylint: disable=C0111
 143 class AdminServe:
 144     """\
 145     Start a simple web server for serving the API.
 146
 147     This command starts a built-in webserver to serve the website
 148     from the current project directory. This webserver is only suitable
 149     for testing and development. Do not use it in production setups!
 150
 151     There are different webservers available. The default 'php' engine
 152     runs the classic PHP frontend. The other engines are Python servers
 153     which run the new Python frontend code. This is highly experimental
 154     at the moment and may not include the full API.
 155
 156     By the default, the webserver can be accessed at: http://127.0.0.1:8088
 157     """
 158
 159     def add_args(self, parser: argparse.ArgumentParser) -> None:
 160         group = parser.add_argument_group('Server arguments')
 161         group.add_argument('--server', default='127.0.0.1:8088',
 162                            help='The address the server will listen to.')
 163         group.add_argument('--engine', default='falcon',
 164                            choices=('php', 'falcon', 'starlette'),
 165                            help='Webserver framework to run. (default: falcon)')
 166
 167
 168     def run(self, args: NominatimArgs) -> int:
 169         if args.engine == 'php':
 170             if args.config.lib_dir.php is None:
 171                 raise UsageError("PHP frontend not configured.")
 172             run_php_server(args.server, args.project_dir / 'website')
 173         else:
 174             asyncio.run(self.run_uvicorn(args))
 175
 176         return 0
 177
 178
 179     async def run_uvicorn(self, args: NominatimArgs) -> None:
 180         import uvicorn # pylint: disable=import-outside-toplevel
 181
 182         server_info = args.server.split(':', 1)
 183         host = server_info[0]
 184         if len(server_info) > 1:
 185             if not server_info[1].isdigit():
 186                 raise UsageError('Invalid format for --server parameter. Use <host>:<port>')
 187             port = int(server_info[1])
 188         else:
 189             port = 8088
 190
 191         server_module = importlib.import_module(f'nominatim_api.server.{args.engine}.server')
 192
 193         app = server_module.get_application(args.project_dir)
 194
 195         config = uvicorn.Config(app, host=host, port=port)
 196         server = uvicorn.Server(config)
 197         await server.serve()
 198
 199
 200 def get_set_parser() -> CommandlineParser:
 201     """\
 202     Initializes the parser and adds various subcommands for
 203     nominatim cli.
 204     """
 205     parser = CommandlineParser('nominatim', nominatim.__doc__)
 206
 207     parser.add_subcommand('import', clicmd.SetupAll())
 208     parser.add_subcommand('freeze', clicmd.SetupFreeze())
 209     parser.add_subcommand('replication', clicmd.UpdateReplication())
 210
 211     parser.add_subcommand('special-phrases', clicmd.ImportSpecialPhrases())
 212
 213     parser.add_subcommand('add-data', clicmd.UpdateAddData())
 214     parser.add_subcommand('index', clicmd.UpdateIndex())
 215     parser.add_subcommand('refresh', clicmd.UpdateRefresh())
 216
 217     parser.add_subcommand('admin', clicmd.AdminFuncs())
 218
 219     try:
 220         exportcmd = importlib.import_module('nominatim_db.clicmd.export')
 221         apicmd = importlib.import_module('nominatim_db.clicmd.api')
 222         convertcmd = importlib.import_module('nominatim_db.clicmd.convert')
 223
 224         parser.add_subcommand('export', exportcmd.QueryExport())
 225         parser.add_subcommand('convert', convertcmd.ConvertDB())
 226         parser.add_subcommand('serve', AdminServe())
 227
 228         parser.add_subcommand('search', apicmd.APISearch())
 229         parser.add_subcommand('reverse', apicmd.APIReverse())
 230         parser.add_subcommand('lookup', apicmd.APILookup())
 231         parser.add_subcommand('details', apicmd.APIDetails())
 232         parser.add_subcommand('status', apicmd.APIStatus())
 233     except ModuleNotFoundError as ex:
 234         if not ex.name or 'nominatim_api' not in ex.name: # pylint: disable=E1135
 235             raise ex
 236
 237         parser.parser.epilog = \
 238             '\n\nNominatim API package not found. The following commands are not available:'\
 239             '\n    export, convert, serve, search, reverse, lookup, details, status'\
 240             "\n\nRun 'pip install nominatim-api' to install the package."
 241
 242
 243     return parser
 244
 245
 246 def nominatim(**kwargs: Any) -> int:
 247     """\
 248     Command-line tools for importing, updating, administrating and
 249     querying the Nominatim database.
 250     """
 251     return get_set_parser().run(**kwargs)