feat: add suggestion for wrongly set names/id (#23)

docs/source/conf.py

@@ -27,7 +27,7 @@
     "sphinx.ext.autosectionlabel",
     "sphinx_copybutton",
     "sphinx_design",
-    "sphinx-favicon",
+    "sphinx_favicon",
     "jupyter_sphinx",
 ]
 templates_path = ["_templates"]

docs/source/usage.rst

@@ -252,6 +252,16 @@ I now know that the code is "SGP.1_1" for the Central province so I can run my i
 
     m
 
+Suggestion
+----------
+
+If you make an error when writing the name of your input, the error message will suggest 5 potential candidates in the existing names of the GADM dataset:
 
 
+.. jupyter-execute::
+    :raises: ValueError
+
+    import pygadm
+
+    gdf = pygadm.get_items(name="Franc")
 

pygadm/__init__.py

@@ -8,11 +8,13 @@
 
 import json
 import warnings
+from difflib import get_close_matches
 from itertools import product
 from pathlib import Path
 from typing import List, Union
 
 import geopandas as gpd
+import numpy as np
 import pandas as pd
 
 __version__ = "0.2.0"
@@ -155,7 +157,17 @@ def get_names(name: str = "", admin: str = "", content_level: int = -1) -> pd.Da
     )
 
     if not is_in.any().any():
-        raise Exception(f'The requested "{id}" is not part of GADM')
+        # find the 5 closest names/id
+        columns = [df[column.format(i)].dropna().str.lower().values for i in range(6)]
+        ids = np.unique(np.concatenate(columns))
+        close_ids = get_close_matches(id.lower(), ids, n=5)
+        if is_name is True:
+            close_ids = [i.capitalize() for i in close_ids]
+        else:
+            close_ids = [i.upper() for i in close_ids]
+        raise ValueError(
+            f'The requested "{id}" is not part of GADM. The closest matches are: {", ".join(close_ids)}.'
+        )
 
     # Get the iso_3 of the associated country of the identifed area and the associated level
     line = is_in[~((~is_in).all(axis=1))].idxmax(1)

tests/test_get_names.py

@@ -70,3 +70,10 @@ def test_duplication():
     # italy is also a level 4 province of Bangladesh: BGD.5.4.6.6_1
     df = pygadm.get_names(name="Italy")
     assert df.GID_0.to_list() == ["ITA"]
+
+
+def test_suggestions():
+    """Test that when a wrong name is given 5 options are proposed in the error message."""
+    expected_error = 'The requested "Franc" is not part of GADM. The closest matches are: Francs, Franco, France, Franca, Francon.'
+    with pytest.raises(ValueError, match=expected_error):
+        pygadm.get_names(name="Franc")