From e631500974a1ff12ba7eb286ea45b5c284c19f60 Mon Sep 17 00:00:00 2001
From: mkrausse-ggtx <131683556+mkrausse-ggtx@users.noreply.github.com>
Date: Tue, 19 Dec 2023 14:56:23 -0800
Subject: [PATCH] Add utility method to format phone numbers (#928)

* added a utility method to format phone numbers

* updated to return none when number is invalid

* clarified docstring and cleaned

---------

Co-authored-by: mattkrausse <106627640+mattkrausse@users.noreply.github.com>
---
 parsons/utilities/format_phone_number.py      | 34 +++++++++++++++++++
 .../test_format_phone_number.py               | 34 +++++++++++++++++++
 2 files changed, 68 insertions(+)
 create mode 100644 parsons/utilities/format_phone_number.py
 create mode 100644 test/test_utilities/test_format_phone_number.py

diff --git a/parsons/utilities/format_phone_number.py b/parsons/utilities/format_phone_number.py
new file mode 100644
index 0000000000..670bd3e5e4
--- /dev/null
+++ b/parsons/utilities/format_phone_number.py
@@ -0,0 +1,34 @@
+import re
+
+
+def format_phone_number(phone_number, country_code="1"):
+    """
+    Formats a phone number in E.164 format, which is the international standard for phone numbers.
+    Example: Converts "555-555-5555" -> "+15555555555"
+
+    `Args:`
+        phone_number (str):
+            The phone number to be formatted.
+        country_code (str):
+            The country code to be used as a prefix.
+        Defaults to "1" (United States).
+
+    `Returns:`
+        str:
+            The formatted phone number in E.164 format.
+    """
+    # Remove non-numeric characters and leading zeros
+    digits = re.sub(r"[^\d]", "", phone_number.lstrip("0"))
+
+    # Check if the phone number is valid
+    if len(digits) < 10:
+        return None
+
+    # Handle country code prefix
+    if not digits.startswith(country_code):
+        digits = country_code + digits
+
+    # Format the phone number in E.164 format
+    formatted_number = "+" + digits
+
+    return formatted_number
diff --git a/test/test_utilities/test_format_phone_number.py b/test/test_utilities/test_format_phone_number.py
new file mode 100644
index 0000000000..5a9a9f1143
--- /dev/null
+++ b/test/test_utilities/test_format_phone_number.py
@@ -0,0 +1,34 @@
+import unittest
+from parsons.utilities.format_phone_number import format_phone_number
+
+
+class TestFormatPhoneNumber(unittest.TestCase):
+    def test_format_phone_number_local_us_number(self):
+        phone_number = "555-123-4567"
+        expected_result = "+15551234567"
+        self.assertEqual(
+            format_phone_number(
+                phone_number,
+            ),
+            expected_result,
+        )
+
+    def test_format_phone_number_us_number_with_leading_1(self):
+        phone_number = "15551234567"
+        expected_result = "+15551234567"
+        self.assertEqual(format_phone_number(phone_number), expected_result)
+
+    def test_format_phone_number_international_number(self):
+        phone_number = "+441234567890"
+        expected_result = "+441234567890"
+        self.assertEqual(
+            format_phone_number(phone_number, country_code="44"), expected_result
+        )
+
+    def test_format_phone_number_invalid_length(self):
+        phone_number = "12345"
+        self.assertIsNone(format_phone_number(phone_number))
+
+
+if __name__ == "__main__":
+    unittest.main()