improve error message on missing modules from nominatim_api

diff --git a/docs/customize/Result-Formatting.md b/docs/customize/Result-Formatting.md
index cd817afb82f471690a20482a339133fc7dcd1e1d..f3ac7f5a1ec1d600b90ece058fa6ae33b503df40 100644 (file)
--- a/docs/customize/Result-Formatting.md
+++ b/docs/customize/Result-Formatting.md
@@ -180,6 +180,26 @@ me@machine:planet-project$
 They will also emit full error messages when there is a problem with the
 code you need to debug.
 
+!!! danger
+    In some cases, when you make an error with your import statement, the
+    CLI will not give you an error but instead tell you, that the API
+    commands are no longer available:
+
+        me@machine: nominatim status
+        usage: nominatim [-h] [--version] {import,freeze,replication,special-phrases,add-data,index,refresh,admin} ...
+        nominatim: error: argument subcommand: invalid choice: 'status'
+
+    This happens because the CLI tool is meant to still work when the
+    nominatim-api package is not installed. Import errors involving
+    `nominatim_api` are interpreted as "package not installed".
+
+    Use the help command to find out which is the offending import that
+    could not be found:
+
+        me@machine: nominatim -h
+        ... [other help text] ...
+        Nominatim API package not found (was looking for module: nominatim_api.xxx).
+
 ## Reference
 
 ### FormatDispatcher

diff --git a/src/nominatim_db/cli.py b/src/nominatim_db/cli.py
index 88810df5a6f330c3df90997f780ef1b20e9c1c45..9fd439f8d0f33684e5429f31c7386f57f7625ae3 100644 (file)
--- a/src/nominatim_db/cli.py
+++ b/src/nominatim_db/cli.py
@@ -243,7 +243,8 @@ def get_set_parser() -> CommandlineParser:
             raise ex
 
         parser.parser.epilog = \
-            '\n\nNominatim API package not found. The following commands are not available:'\
+            f'\n\nNominatim API package not found (was looking for module: {ex.name}).'\
+            '\nThe following commands are not available:'\
             '\n    export, convert, serve, search, reverse, lookup, details, status'\
             "\n\nRun 'pip install nominatim-api' to install the package."