Merge pull request #156 from unicef/feature/phone-number-field

Feature/phone number field

Author: domdinicola

pyproject.toml

@@ -50,6 +50,7 @@ dependencies = [
   "numpy>=2.3",
   "openpyxl>=3.1.5",
   "pandas>=2.3",
+  "phonenumbers>=9.0.8",
   "pillow>=11.2.1",
   "pre-commit>=4.2",
   "psycopg2-binary>=2.9.9",

src/country_workspace/contrib/hope/apps.py

@@ -2,6 +2,7 @@
 
 from .geo import Admin1Choice, Admin2Choice, Admin3Choice, Admin4Choice, CountryChoice
 from .lookups import FinancialInstitutionChoice
+from .phone_numbers import PhoneNumberField
 
 
 class Config(AppConfig):
@@ -21,6 +22,7 @@ def ready(self) -> None:
         field_registry.register(Admin3Choice)
         field_registry.register(Admin4Choice)
         field_registry.register(FinancialInstitutionChoice)
+        field_registry.register(PhoneNumberField)
 
         from country_workspace.contrib.hope.validators import FullHouseholdValidator
         from country_workspace.validators.registry import beneficiary_validator_registry

src/country_workspace/contrib/hope/phone_numbers.py

@@ -0,0 +1,13 @@
+from django import forms
+
+from country_workspace.validators.phone_number import is_right_phone_number_format
+
+
+class PhoneNumberField(forms.CharField):
+    def clean(self, value: str) -> str:
+        value = super().clean(value)
+
+        if value and not is_right_phone_number_format(value):
+            raise forms.ValidationError("Invalid phone number")
+
+        return value

src/country_workspace/validators/phone_number.py

@@ -0,0 +1,24 @@
+import phonenumbers
+
+from typing import Any
+
+
+def is_right_phone_number_format(phone_number: str | Any) -> bool:
+    # from phonenumbers.parse method description:
+    # This method will throw a NumberParseException if the number is not
+    # considered to be a possible number.
+    #
+    # so if `parse` does not throw, we may assume it's ok
+    if not isinstance(phone_number, str):  # pragma: no cover
+        phone_number = str(phone_number)
+
+    phone_number = phone_number.strip()
+    if phone_number.startswith("00"):
+        phone_number = f"+{phone_number[2:]}"
+
+    try:
+        phonenumbers.parse(phone_number)
+    except phonenumbers.NumberParseException:
+        return False
+
+    return True

src/country_workspace/versioning/scripts/0012_add_phone_number_field.py

@@ -0,0 +1,32 @@
+from concurrency.utils import fqn
+from hope_flex_fields.models import FieldDefinition
+from hope_flex_fields.registry import field_registry
+from hope_flex_fields.utils import get_kwargs_from_field_class, get_common_attrs
+from packaging.version import Version
+
+from country_workspace.contrib.hope.phone_numbers import PhoneNumberField
+
+_script_for_version = Version("0.1.0")
+
+PHONE_NUMBER_FIELD = "phone_number"
+
+
+def forward() -> None:
+    field_registry.register(PhoneNumberField)
+    FieldDefinition.objects.get_or_create(
+        name=PhoneNumberField.__name__,
+        field_type=fqn(PhoneNumberField),
+        defaults={"attrs": get_kwargs_from_field_class(PhoneNumberField, get_common_attrs())},
+    )
+
+
+def backward() -> None:
+    FieldDefinition.objects.filter(
+        name=PhoneNumberField.__name__,
+        field_type=fqn(PhoneNumberField),
+    ).delete()
+
+
+class Scripts:
+    requires = []
+    operations = [(forward, backward)]

tests/contrib/hope/test_phone_numbers.py

@@ -0,0 +1,113 @@
+import pytest
+from django.core.exceptions import ValidationError
+
+from country_workspace.contrib.hope.phone_numbers import PhoneNumberField
+
+
+def test_valid_international_format_with_plus():
+    field = PhoneNumberField()
+
+    valid_numbers = [
+        "+12345678901",  # US number (10 digits)
+        "+442071234567",  # UK number
+        "+33123456789",  # French number
+        "+61412345678",  # Australian number
+        "+123456789012345",  # Long international number
+    ]
+
+    for number in valid_numbers:
+        result = field.clean(number)
+        assert result == number
+
+
+def test_valid_international_format_with_00_prefix():
+    field = PhoneNumberField()
+
+    valid_numbers = [
+        "0012345678901",  # US number with 00
+        "00442071234567",  # UK number with 00
+        "0033123456789",  # French number with 00
+    ]
+
+    for number in valid_numbers:
+        result = field.clean(number)
+        assert result == number
+
+
+def test_empty_value():
+    field = PhoneNumberField(required=False)
+
+    result = field.clean("")
+    assert result == ""
+
+    result = field.clean(None)
+    assert result == ""
+
+
+def test_whitespace_handling():
+    field = PhoneNumberField()
+
+    result = field.clean("  +12345678901  ")
+    assert result == "+12345678901"
+
+    result = field.clean("+1 234 567 8901")
+    assert result == "+1 234 567 8901"
+
+
+def test_invalid_phone_numbers():
+    field = PhoneNumberField()
+
+    invalid_numbers = [
+        "123",
+        "+",
+        "+99",
+    ]
+
+    for number in invalid_numbers:
+        with pytest.raises(ValidationError, match="Invalid phone number"):
+            field.clean(number)
+
+
+def test_edge_cases():
+    field = PhoneNumberField()
+
+    with pytest.raises(ValidationError, match="Invalid phone number"):
+        field.clean("1")
+
+    with pytest.raises(ValidationError, match="Invalid phone number"):
+        field.clean("0000000000")
+
+    with pytest.raises(ValidationError, match="Invalid phone number"):
+        field.clean("123abc456")
+
+
+def test_required_field_validation():
+    field = PhoneNumberField(required=True)
+
+    with pytest.raises(ValidationError):
+        field.clean("")
+
+    with pytest.raises(ValidationError):
+        field.clean(None)
+
+
+def test_field_inheritance():
+    field = PhoneNumberField(max_length=20)
+
+    long_number = "123456789012345678901234567890"
+    with pytest.raises(ValidationError):
+        field.clean(long_number)
+
+    valid_number = "+12345678901"
+    result = field.clean(valid_number)
+    assert result == valid_number
+
+
+def test_00_prefix_conversion_logic():
+    field = PhoneNumberField()
+
+    result = field.clean("0012345678901")
+    assert result == "0012345678901"
+
+    result = field.clean("00 123 456 7890")
+    assert result == "00 123 456 7890"