From eef7ea89189fe4cfd8e0919915a377127f9dfad1 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, 74 insertions(+), 21 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..fafa2e14 --- /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-phone-number-extension`. diff --git a/docs/reference.rst b/docs/reference.rst index 2bd30109..571bf460 100644 --- a/docs/reference.rst +++ b/docs/reference.rst @@ -355,31 +355,47 @@ Validates: Settings ======== -.. setting:: PHONENUMBER_DB_FORMAT +.. _settings-phone-number-extension: -``PHONENUMBER_DB_FORMAT`` -------------------------- +.. rubric:: Phone number extensions -Store phone numbers strings in the specified format. +.. warning:: -Default: ``"E164"``. + By default, the library uses `E.164, the international public + telecommunication numbering plan `_, + which **does not support phone numbers extensions**. -Choices: + Set **both** :setting:`PHONENUMBER_DB_FORMAT` and + :setting:`PHONENUMBER_DEFAULT_FORMAT` to an extension-compatible format to + handle phone numbers extensions. -- ``"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`). +.. _settings-format-choices: -.. setting:: PHONENUMBER_DEFAULT_REGION +Phone number format choices +--------------------------- -``PHONENUMBER_DEFAULT_REGION`` ------------------------------- ++---------------------+---------------+------------+-----------------------------------------------------------------+ +| Setting value | International | Extensions | Notes | ++=====================+===============+============+=================================================================+ +| ``"E164"`` | ✓ | ❌ | 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` | ++---------------------+---------------+------------+-----------------------------------------------------------------+ -`ISO-3166-1 `_ -two-letter country code indicating how to interpret regional phone numbers. +.. setting:: PHONENUMBER_DB_FORMAT -Default: ``None``. +``PHONENUMBER_DB_FORMAT`` +------------------------- + +Store phone numbers strings in the specified format in the database. + +Default: ``"E164"``. + +See :ref:`settings-format-choices`. .. setting:: PHONENUMBER_DEFAULT_FORMAT @@ -390,9 +406,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``.