[IMP] phone_validation: add a tool to extract region information from number

In this commit we add a new tool function in 'phone_validation' tooling
module. This tool 'phone_get_region_data_for_number' returns

  * 'code': the region code from phonenumbers library, which is like 'BE' or
    'GB' and (should) be the uppercase version of odoo country code;
  * 'phone_code': the 'country_code' from phonenumbers library parsed object
    which is actually the phone code of the country (might not be unique
    e.g. 1 for US and CA);
  * 'national_number': the 'national_number' from phonenumbers library parsed
    object which is the number without the 'phone_code' prefix (e.g. for a
    belgian number +32485001122 it is 485001122).

This will be used in whatsapp (enterprise) to ease finding country (and
partners) based on an input number.

Task-3608129 (Whatsapp: Moultifix !)

X-original-commit: odoo/odoo@646aa8f369
Part-of: odoo/odoo#146398

addons/phone_validation/tests/test_phonenumbers.py

@@ -21,3 +21,26 @@ class TestPhonenumbers(BaseCase):
                 phone_validation.phone_format('0456998877', None, '32', force_format='E164'),
                 '+32456998877'
             )
+
+    def test_get_region_data_for_number(self):
+        for source, (exp_code, exp_national_number, exp_phone_code) in zip(
+            [
+                '+32456998877',  # all hail Philippe
+                '+1-613-555-0177',  # canada, same phone_code as US
+                '+1-202-555-0124',  # us, same phone_code as CA
+            ],
+            [
+                ('BE', '456998877', '32'),
+                ('CA', '6135550177', '1'),
+                ('US', '2025550124', '1'),
+            ],
+        ):
+            with self.subTest(source=source):
+                self.assertDictEqual(
+                    phone_validation.phone_get_region_data_for_number(source),
+                    {
+                        'code': exp_code,
+                        'national_number': exp_national_number,
+                        'phone_code': exp_phone_code,
+                    }
+                )

addons/phone_validation/tools/phone_validation.py

@@ -60,6 +60,21 @@ try:
             phone_fmt = phonenumbers.PhoneNumberFormat.NATIONAL
         return phonenumbers.format_number(phone_nbr, phone_fmt)
 
+    def phone_get_region_data_for_number(number):
+        try:
+            phone_obj = phone_parse(number, None)
+        except (phonenumbers.phonenumberutil.NumberParseException, UserError):
+            return {
+                'code': '',
+                'national_number': '',
+                'phone_code': '',
+            }
+        return {
+            'code': phonenumbers.phonenumberutil.region_code_for_number(phone_obj),
+            'national_number': str(phone_obj.national_number),
+            'phone_code': str(phone_obj.country_code),
+        }
+
 except ImportError:
 
     def phone_parse(number, country_code):
@@ -74,3 +89,10 @@ except ImportError:
             )
             _phonenumbers_lib_warning = True
         return number
+
+    def phone_get_region_code_for_number(number):
+        return {
+            'code': '',
+            'national_number': '',
+            'phone_code': '',
+        }