feat: find close matches to state name in license generators

Author: Pythonian

.github/workflows/testpypi.yml

@@ -35,7 +35,7 @@ def degree(self, degree_type: str | None = None) -> dict:
         Note:
             - Degree type options: undergraduate, masters, doctorate
 
-        Example:
+        Examples:
             .. code-block:: python
 
                 >>> from fakernaija import Naija
@@ -67,7 +67,7 @@ def degree_name(self, degree_type: str | None = None) -> str:
         Note:
             - Degree type options: undergraduate, masters, doctorate
 
-        Example:
+        Examples:
             .. code-block:: python
 
                 >>> from fakernaija import Naija
@@ -102,7 +102,7 @@ def degree_abbr(self, degree_type: str | None = None) -> str:
         Note:
             - Degree type options: undergraduate, masters, doctorate
 
-        Example:
+        Examples:
             .. code-block:: python
 
                 >>> from fakernaija import Naija

fakernaija/mixins/degree.py

@@ -40,7 +40,7 @@ def email(
             - Gender options: male, female
             - Tribe options: yoruba, igbo, hausa, edo, fulani, ijaw
 
-        Example:
+        Examples:
             .. code-block:: python
 
                 >>> from fakernaija import Naija
@@ -65,6 +65,10 @@ def email(
                 >>> print(f"Random email with tribe filter: {email}")
                 Random email with tribe filter: ugochi.maduike@gmail.com
 
+                >>> email = naija.email(domain="edu.ng")
+                >>> print(f"Random email with domain filter: {email}")
+                Random email with domain filter: maduike.ugochi1999@edu.ng
+
                 >>> email = naija.email(gender="female")
                 >>> print(f"Random email with gender filter: {email}")
                 Random email with gender filter: ugochi.maduike@gmail.com

fakernaija/mixins/email.py

@@ -11,10 +11,10 @@ def __init__(self) -> None:
         self.license_plate_provider = LicensePlateProvider()
 
     def license_plate(self, state: str | None = None) -> str:
-        """Generate a random license plate.
+        """Generate a random license plate number.
 
         Args:
-            state (str | None, optional): The state to generate the license plate for.
+            state (str | None, optional): The state to generate the license plate number from.
 
         Returns:
             str: The generated license plate.
@@ -46,4 +46,8 @@ def license_plate(self, state: str | None = None) -> str:
                 >>> print(f"Random license plate number from a specific state: {license_plate}")
                 Random license plate number from a specific state: EZA-352CC
         """
-        return self.license_plate_provider.generate_license_plate(state=state)
+        try:
+            return self.license_plate_provider.generate_license_plate(state=state)
+        except ValueError as e:
+            msg = f"Invalid state name: {state}. {e!s}"
+            raise ValueError(msg) from e

fakernaija/mixins/license_plate.py

@@ -204,7 +204,7 @@ def prefix(
             - Gender options: male, female
             - Title options: traditional, professional
 
-        Example:
+        Examples:
             .. code-block:: python
 
                 >>> from fakernaija import Naija

fakernaija/mixins/name.py

@@ -36,7 +36,7 @@ def phone_number(
                 - airtel: 0802, 0808, 0812, 0708, 0701, 0901, 0902, 0907
                 - etisalat: 0809, 0817, 0818, 0908, 0909
 
-        Example:
+        Examples:
             .. code-block:: python
 
                 >>> from fakernaija import Naija

fakernaija/mixins/phonenumber.py

@@ -229,7 +229,7 @@ def state_postal_code(self, state: str | None = None) -> str:
         Note:
             - State options: 36 states in Nigeria + FCT.
 
-        Example:
+        Examples:
             .. code-block:: python
 
                 >>> from fakernaija import Naija

fakernaija/mixins/state.py

@@ -1,11 +1,15 @@
 """LicensePlateProvider."""
 
+import difflib
 import random
 from pathlib import Path
 
 from fakernaija.providers.state import StateProvider
 from fakernaija.utils import load_json, normalize_input
 
+DIGIT_COUNT = 3
+LETTER_COUNT = 2
+
 
 class LicensePlateProvider:
     """Provider class to generate Nigerian license plates."""
@@ -38,6 +42,9 @@ def generate_license_plate(self, state: str | None = None) -> str:
 
         Returns:
             str: A randomly generated Nigerian license plate.
+
+        Raises:
+            ValueError: If the state name is invalid.
         """
         state = normalize_input(state)
 
@@ -46,7 +53,14 @@ def generate_license_plate(self, state: str | None = None) -> str:
             # Map lowercase state names to original case
             state_dict = {s.lower(): s for s in self.state_names}
             if state.lower() not in state_dict:
-                msg = f"Invalid state name: {state}. Valid states are: {', '.join(self.state_names)}"
+                # Find close matches to the input state name
+                suggestions = difflib.get_close_matches(
+                    state, self.state_names, n=3, cutoff=0.6
+                )
+                if suggestions:
+                    msg = f"Invalid state name: {state}. Did you mean: {', '.join(suggestions)}?"
+                else:
+                    msg = f"Invalid state name: {state}. Valid states are: {', '.join(self.state_names)}"
                 raise ValueError(msg)
             # Use the correctly cased state name to access LGA codes
             state_name = state_dict[state.lower()]
@@ -56,6 +70,6 @@ def generate_license_plate(self, state: str | None = None) -> str:
             all_lgas = [code for codes in self.lga_codes.values() for code in codes]
             lga_code = random.choice(all_lgas)
 
-        digits = "".join(random.choices("0123456789", k=3))
-        letters = "".join(random.choices("ABCDEFGHIJKLMNOPQRSTUVWXYZ", k=2))
+        digits = "".join(random.choices("0123456789", k=DIGIT_COUNT))
+        letters = "".join(random.choices("ABCDEFGHIJKLMNOPQRSTUVWXYZ", k=LETTER_COUNT))
         return f"{lga_code}-{digits}{letters}"

fakernaija/providers/license_plate.py

@@ -3,6 +3,7 @@
 import csv
 import json
 import random
+import unicodedata
 from collections.abc import Callable
 from pathlib import Path
 from typing import Any
@@ -106,6 +107,18 @@ def normalize_input(value: str | None) -> str | None:
     Returns:
         str | None: The normalized value or None if the input is None.
     """
+    if value is None:
+        return None
+
+    # Normalize and strip whitespace
+    value = value.strip()
+
+    # Remove accents
+    value = (
+        unicodedata.normalize("NFKD", value).encode("ascii", "ignore").decode("ascii")
+    )
+
+    # Convert to lowercase
     return value.lower() if value else None