data: add a new field, locale_catalog.phone_format (#130)

docs/user_guide/structure_of_the_yaml_input_file.md

@@ -49,17 +49,18 @@ cv:
   name: John Doe
   location: Your Location
   email: youremail@yourdomain.com
-  phone: +905419999999
+  phone: +905419999999 # (1)!
   website: https://example.com/
   social_networks:
-    - network: LinkedIn # (1)!
+    - network: LinkedIn # (2)!
       username: yourusername
     - network: GitHub 
       username: yourusername
   ...
 ```
 
-1.  The available social networks are: {{available_social_networks}}.
+1.  If you want to change the phone number formatting in the output, see the `locale_catalog` field's `phone_number_format` key.
+2.  The available social networks are: {{available_social_networks}}.
 
 None of the values above are required. You can omit any or all of them, and RenderCV will adapt to your input. These generic fields are used in the header of the CV.
 
@@ -287,12 +288,13 @@ design:
 
 ## "`locale_catalog`" field
 
-This field is what makes RenderCV a multilingual tool. RenderCV uses some English strings to render PDFs. For example, it takes the dates in ISO format (`2020-01-01`) and converts them into human-friendly strings (`"Jan 2020"`). However, you can override these strings for your own language or needs with the `locale_catalog` field.
+This field is what makes RenderCV a multilingual tool. RenderCV uses some English strings to render PDFs. For example, it takes the dates in ISO format (`2020-01-01`) and converts them into human-friendly strings (`"Jan 2020"`). However, you can override these strings for your own language or needs with the `locale_catalog` field. Also, you can change the phone number formatting with the `phone_number_format` key.
 
 Here is an example:
 
 ```yaml
 locale_catalog:
+  phone_number_format: national # (1)!
   abbreviations_for_months: # translation of the month abbreviations
     - Jan
     - Feb
@@ -326,3 +328,5 @@ locale_catalog:
   present: present  # translation of the word "present"
   to: to            # translation of the word "to"
 ```
+
+1. The available phone number formats are: `national`, `international`, and `E164`.

rendercv/data/models/computers.py

@@ -8,9 +8,41 @@ import re
 from datetime import date as Date
 from typing import Optional
 
+import phonenumbers
+
 from .locale_catalog import locale_catalog
 
 
+def format_phone_number(phone_number: str) -> str:
+    """Format a phone number to the format specified in the `locale_catalog` dictionary.
+
+    Example:
+        ```python
+        format_phone_number("+17034800500")
+        ```
+        returns
+        ```python
+        "(703) 480-0500"
+        ```
+
+    Args:
+        phone_number (str): The phone number to format.
+
+    Returns:
+        str: The formatted phone number.
+    """
+
+    format = locale_catalog["phone_format"].upper()  # type: ignore
+
+    phonenumbers.PhoneNumberFormat.E164
+
+    parsed_number = phonenumbers.parse(phone_number, None)
+    formatted_number = phonenumbers.format_number(
+        parsed_number, getattr(phonenumbers.PhoneNumberFormat, format)
+    )
+    return formatted_number
+
+
 def format_date(date: Date, use_full_name: bool = False) -> str:
     """Formats a `Date` object to a string in the following format: "Jan 2021". The
     month names are taken from the `locale_catalog` dictionary from the

rendercv/data/models/curriculum_vitae.py

@@ -401,7 +401,7 @@ class CurriculumVitae(RenderCVBaseModelWithExtraKeys):
     phone: Optional[pydantic_phone_numbers.PhoneNumber] = pydantic.Field(
         default=None,
         title="Phone",
-        description="The phone number of the person.",
+        description="The phone number of the person, including the country code.",
     )
     website: Optional[pydantic.HttpUrl] = pydantic.Field(
         default=None,
@@ -455,11 +455,11 @@ class CurriculumVitae(RenderCVBaseModelWithExtraKeys):
             )
 
         if self.phone is not None:
-            phone_placeholder = self.phone.replace("tel:", "").replace("-", " ")
+            phone_placeholder = computers.format_phone_number(self.phone)
             connections.append(
                 {
                     "latex_icon": "\\faPhone*",
-                    "url": f"{self.phone}",
+                    "url": self.phone,
                     "clean_url": phone_placeholder,
                     "placeholder": phone_placeholder,
                 }

rendercv/data/models/locale_catalog.py

@@ -3,7 +3,7 @@ The `rendercv.models.locale_catalog` module contains the data model of the
 `locale_catalog` field of the input file.
 """
 
-from typing import Annotated, Optional
+from typing import Annotated, Literal, Optional
 
 import annotated_types as at
 import pydantic
@@ -16,6 +16,18 @@ class LocaleCatalog(RenderCVBaseModelWithoutExtraKeys):
     updates the `locale_catalog` dictionary.
     """
 
+    phone_format: Optional[Literal["national", "international", "E164"]] = (
+        pydantic.Field(
+            default="national",
+            title="Phone Number Format",
+            description=(
+                "If 'national', phone numbers are formatted without the country code."
+                " If 'international', phone numbers are formatted with the country"
+                " code. The default value is 'national'."
+            ),
+            validate_default=True,  # To initialize the locale catalog with the default
+        )
+    )
     month: Optional[str] = pydantic.Field(
         default="month",
         title='Translation of "Month"',
@@ -109,6 +121,7 @@ class LocaleCatalog(RenderCVBaseModelWithoutExtraKeys):
         "abbreviations_for_months",
         "to",
         "full_names_of_months",
+        "phone_format",
     )
     @classmethod
     def update_translations(cls, value: str, info: pydantic.ValidationInfo) -> str:

tests/test_data.py

@@ -697,6 +697,7 @@ def test_locale_catalog():
             "11",
             "12",
         ],
+        phone_format="international",
     )
 
     assert locale_catalog.locale_catalog == data_model.locale_catalog.model_dump()