Merge branch 'main' into 562-types

.github/workflows/check.yml

@@ -22,10 +22,10 @@ jobs:
       TOXENV: ${{ matrix.tox-environment }}
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
 
       - name: Install dependencies
         run: python -m pip install tox

.github/workflows/release.yml

@@ -8,15 +8,22 @@ jobs:
     name: Build distribution files
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: "3.x"
 
       - name: Install dependencies
-        run: pip install --user build setuptools twine wheel
+        run: pip install --user build django setuptools twine wheel
+
+      - name: Install gettext
+        run: sudo apt-get install gettext
+
+      - name: Compile messages
+        run: django-admin compilemessages
+        working-directory: phonenumber_field
 
       - name: Build package
         run: python -m build
@@ -25,7 +32,7 @@ jobs:
         run: twine check --strict dist/*
 
       - name: Upload distributions to GitHub
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: dist
           path: dist/
@@ -42,7 +49,7 @@ jobs:
       id-token: write
     steps:
       - name: Download distributions
-        uses: actions/download-artifact@v3
+        uses: actions/download-artifact@v4
         with:
           name: dist
           path: dist/

.github/workflows/test.yml

@@ -17,15 +17,24 @@ jobs:
           - 3.9
           - '3.10'
           - '3.11'
+          - '3.12'
         tox-environment:
           - dj32
           - dj41
           - dj42
+          - dj50
         include:
           - python-version: '3.10'
             tox-environment: djmain
           - python-version: '3.11'
             tox-environment: djmain
+          - python-version: '3.12'
+            tox-environment: djmain
+        exclude:
+          - python-version: '3.8'
+            tox-environment: dj50
+          - python-version: '3.9'
+            tox-environment: dj50
 
     env:
       COVERALLS_FLAG_NAME: Python ${{ matrix.python-version }} / ${{ matrix.tox-environment }}
@@ -40,10 +49,10 @@ jobs:
           sudo apt-get update
           sudo apt-get install -y gettext
 
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
 
@@ -69,7 +78,7 @@ jobs:
 
     steps:
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
 
       - name: Install coveralls
         run: python -m pip install coveralls

.gitignore

@@ -39,6 +39,8 @@ share/
 .coverage*
 # Written by setuptools_scm.
 phonenumber_field/version.py
+# Generated automatically during the release process
+phonenumber_field/locale/*/LC_MESSAGES/django.mo
 # python virtualenv
 .venv/
 venv/

MANIFEST.in

@@ -1,3 +1,3 @@
 exclude .gitignore
-exclude check-translations
 prune .github
+include phonenumber_field/locale/*/LC_MESSAGES/django.mo

docs/index.rst

@@ -44,4 +44,5 @@ your ``settings.py`` file :external+django:setting:`INSTALLED_APPS`:
    :maxdepth: 2
    :caption: Contents:
 
+   phonenumbers
    reference

docs/phonenumbers.rst

@@ -0,0 +1,31 @@
+Handling phone numbers
+======================
+
+`Google’s libphonenumber “Falsehoods Programmers Believe About Phone Numbers”
+<https://github.com/google/libphonenumber/blob/master/FALSEHOODS.md>`_ are
+worth keeping in mind, especially since this library relies heavily on
+`libphonenumber <https://github.com/google/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
+<https://en.wikipedia.org/wiki/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`.

docs/reference.rst

@@ -143,7 +143,7 @@ Usage
       Enter a valid phone number (e.g. (506) 234-5678) or a number with an international call prefix.
      </li>
     </ul>
-    <input id="id_number" name="number" required="" type="tel" value="invalid"/>
+    <input aria-invalid="true" id="id_number" name="number" required="" type="tel" value="invalid"/>
    </div>
 
 .. note:: Because the PhoneNumberField specifies a region, the example number
@@ -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 <https://en.wikipedia.org/wiki/E.164>`_,
+    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 <https://en.wikipedia.org/wiki/ISO_3166-1#Current_codes>`_
-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`.
+
+.. setting:: PHONENUMBER_DEFAULT_REGION
+
+``PHONENUMBER_DEFAULT_REGION``
+------------------------------
+
+`ISO-3166-1 <https://en.wikipedia.org/wiki/ISO_3166-1#Current_codes>`_
+two-letter country code indicating how to interpret regional phone numbers.
 
-- ``"E164"`` (no support of phone extensions),
-- ``"INTERNATIONAL"``,
-- ``"RFC3966"``,
-- ``"NATIONAL"`` (discouraged, fails to represent international phone numbers).
+Default: ``None``.

docs/requirements.txt

@@ -1,3 +1,4 @@
 django
 djangorestframework
 phonenumberslite
+sphinx-rtd-theme

phonenumber_field/locale/it/LC_MESSAGES/django.po

@@ -1,45 +1,47 @@
-# Copyright (C) 2013-2018
-# This file is distributed under the same license as the PACKAGE package.
-#
-# Francesco Facconi <francesco@immediatic.it>, 2013-2017.
-# Paolo Melchiorre <paolo@melchiorre.org>, 2018.
-msgid ""
-msgstr ""
-"Project-Id-Version: \n"
-"Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2019-05-28 13:04-0700\n"
-"PO-Revision-Date: 2018-02-28 20:23+0100\n"
-"Last-Translator: Paolo Melchiorre <paolo@melchiorre.org>\n"
-"Language-Team: Italian <paolo@melchiorre.org>\n"
-"Language: it\n"
-"MIME-Version: 1.0\n"
-"Content-Type: text/plain; charset=UTF-8\n"
-"Content-Transfer-Encoding: 8bit\n"
-"Plural-Forms: nplurals=2; plural=(n > 1);\n"
-"X-Generator: Poedit 2.0.4\n"
-
-#: formfields.py:27
-#, python-brace-format
-msgid ""
-"Enter a valid phone number (e.g. {example_number}) or a number with an "
-"international call prefix."
-msgstr ""
-
-#. Translators: {example_number} is an international phone number.
-#: formfields.py:33
-#, fuzzy, python-brace-format
-#| msgid "Enter a valid phone number."
-msgid "Enter a valid phone number (e.g. {example_number})."
-msgstr "Inserire un numero di telefono valido."
-
-#: modelfields.py:51
-msgid "Phone number"
-msgstr "Numero di telefono"
-
-#: serializerfields.py:9
-msgid "Enter a valid phone number."
-msgstr "Inserire un numero di telefono valido."
-
-#: validators.py:11
-msgid "The phone number entered is not valid."
-msgstr "Il numero di telefono inserito non è valido."
+# Copyright (C) 2013-2018
+# This file is distributed under the same license as the PACKAGE package.
+#
+# Francesco Facconi <francesco@immediatic.it>, 2013-2017.
+# Paolo Melchiorre <paolo@melchiorre.org>, 2018.
+# Ruggero Fabbiano <ruggero_fabbiano@outlook.com>, 2023.
+msgid ""
+msgstr ""
+"Project-Id-Version: \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2023-12-28 15:43+0100\n"
+"PO-Revision-Date: 2018-02-28 20:23+0100\n"
+"Last-Translator: Paolo Melchiorre <paolo@melchiorre.org>\n"
+"Language-Team: Italian <paolo@melchiorre.org>\n"
+"Language: it\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Plural-Forms: nplurals=2; plural=(n > 1);\n"
+"X-Generator: Poedit 2.0.4\n"
+
+#: .\formfields.py:43
+#, python-brace-format
+msgid ""
+"Enter a valid phone number (e.g. {example_number}) or a number with an "
+"international call prefix."
+msgstr ""
+"Inserisci un numero di telefono valido (esempio: {example_number}) o un "
+"numero con un prefisso internazionale."
+
+#. Translators: {example_number} is an international phone number.
+#: .\formfields.py:49
+#, python-brace-format
+msgid "Enter a valid phone number (e.g. {example_number})."
+msgstr "Inserisci un numero di telefono valido (esempio: {example_number})."
+
+#: .\modelfields.py:53
+msgid "Phone number"
+msgstr "Numero di telefono"
+
+#: .\serializerfields.py:10
+msgid "Enter a valid phone number."
+msgstr "Inserisci un numero di telefono valido."
+
+#: .\validators.py:11
+msgid "The phone number entered is not valid."
+msgstr "Il numero di telefono inserito non è valido."