From cdb381887700c5039d978f63939467555e24ab66 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20Freitag?= Date: Wed, 15 Nov 2023 22:01:29 +0100 Subject: [PATCH] Document phone number extension handling --- docs/index.rst | 1 + docs/phonenumbers.rst | 31 +++++++++++++++++++++ docs/reference.rst | 63 ++++++++++++++++++++++++++++++------------- 3 files changed, 77 insertions(+), 18 deletions(-) create mode 100644 docs/phonenumbers.rst diff --git a/docs/index.rst b/docs/index.rst index b8911d44..0be81b25 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -44,4 +44,5 @@ your ``settings.py`` file :external+django:setting:`INSTALLED_APPS`: :maxdepth: 2 :caption: Contents: + phonenumbers reference diff --git a/docs/phonenumbers.rst b/docs/phonenumbers.rst new file mode 100644 index 00000000..01c10e00 --- /dev/null +++ b/docs/phonenumbers.rst @@ -0,0 +1,31 @@ +Handling phone numbers +====================== + +`Google’s libphonenumber “Falsehoods Programmers Believe About Phone Numbers” +`_ are +worth keeping in mind, especially since this library relies heavily on +`libphonenumber `_. + +About phone numbers extensions +------------------------------ + +An extension is an additional phone line added to an existing phone system, +making it possible to reach a specific employee or department within an +organization. An extension is defined in the following manner: + +.. doctest:: extensions + + >>> import phonenumbers + >>> phonenumbers.parse("+1 604-401-1234 ext. 987") + PhoneNumber(country_code=1, national_number=6044011234, extension='987', italian_leading_zero=None, number_of_leading_zeros=None, country_code_source=0, preferred_domestic_carrier_code=None) + >>> phonenumbers.parse("+1 604-401-1234,987") + PhoneNumber(country_code=1, national_number=6044011234, extension='987', italian_leading_zero=None, number_of_leading_zeros=None, country_code_source=0, preferred_domestic_carrier_code=None) + +The library primarily focuses on public phone numbers, its default format and +database representation are using `E.164 +`_, which has no support for extensions. + +Projects that need to handle phone number extensions must set **both** +:setting:`PHONENUMBER_DEFAULT_FORMAT` and :setting:`PHONENUMBER_DB_FORMAT` to +an extension-compatible format, as described in +:ref:`settings-format-choices`. diff --git a/docs/reference.rst b/docs/reference.rst index 8cae44e6..6f597abc 100644 --- a/docs/reference.rst +++ b/docs/reference.rst @@ -355,31 +355,53 @@ Validates: Settings ======== +.. _settings-format-choices: + +Phone number format choices +--------------------------- + ++------------------------+---------------+------------+-----------------------------------------------------------------+ +| Setting value | International | Extensions | Notes | ++========================+===============+============+=================================================================+ +| ``"E164"`` *(default)* | ✓ | ❌ | https://en.wikipedia.org/wiki/E.164 | ++------------------------+---------------+------------+-----------------------------------------------------------------+ +| ``"INTERNATIONAL"`` | ✓ | ✓ | https://en.wikipedia.org/wiki/E.123#Telephone_number | ++------------------------+---------------+------------+-----------------------------------------------------------------+ +| ``"RFC3966"`` | ✓ | ✓ | https://www.rfc-editor.org/rfc/rfc3966.html | ++------------------------+---------------+------------+-----------------------------------------------------------------+ +| ``"NATIONAL"`` | ❌ | ✓ | **DISCOURAGED**, requires :setting:`PHONENUMBER_DEFAULT_REGION` | ++------------------------+---------------+------------+-----------------------------------------------------------------+ + +.. warning:: + + By default, the library uses `E.164, the international public + telecommunication numbering plan `_, + which **does not support phone numbers extensions**. Set **both** + :setting:`PHONENUMBER_DB_FORMAT` and :setting:`PHONENUMBER_DEFAULT_FORMAT` + to an extension-compatible format to handle phone numbers extensions. + .. setting:: PHONENUMBER_DB_FORMAT ``PHONENUMBER_DB_FORMAT`` ------------------------- -Store phone numbers strings in the specified format. +Store phone numbers strings in the specified format in the database. Default: ``"E164"``. -Choices: +See :ref:`settings-format-choices`. -- ``"E164"`` (public international numbers), -- ``"INTERNATIONAL"`` (international numbers, possibly with phone extensions), -- ``"RFC3966"`` (international numbers, possibly with phone extensions), -- ``"NATIONAL"`` (discouraged, requires :setting:`PHONENUMBER_DEFAULT_REGION`). +.. warning:: **Data loss may occur when changing the DB format.** -.. setting:: PHONENUMBER_DEFAULT_REGION + Phone numbers stored in the database are parsed every time they are loaded + from the database. -``PHONENUMBER_DEFAULT_REGION`` ------------------------------- + When switching from a format that can represent extensions to a format that + cannot, the **extension information is definitely lost**. -`ISO-3166-1 `_ -two-letter country code indicating how to interpret regional phone numbers. - -Default: ``None``. + When using :setting:`PHONENUMBER_DB_FORMAT`\ ``="NATIONAL"``, changing the + :setting:`PHONENUMBER_DEFAULT_REGION` will cause phone numbers stored in the + database to be interpreted differently, resulting in data corruption. .. setting:: PHONENUMBER_DEFAULT_FORMAT @@ -390,9 +412,14 @@ String formatting of phone numbers. Default: ``"E164"``. -Choices: +See :ref:`settings-format-choices`. -- ``"E164"`` (no support of phone extensions), -- ``"INTERNATIONAL"``, -- ``"RFC3966"``, -- ``"NATIONAL"`` (discouraged, fails to represent international phone numbers). +.. setting:: PHONENUMBER_DEFAULT_REGION + +``PHONENUMBER_DEFAULT_REGION`` +------------------------------ + +`ISO-3166-1 `_ +two-letter country code indicating how to interpret regional phone numbers. + +Default: ``None``.